merged 2.0

CONTRIBUTING.md

@@ -0,0 +1,9 @@
+Contributing
+------------
+
+Symfony2 is an open source, community-driven project. If you'd like to contribute,
+please read the [Contributing Code][1] part of the documentation. If you're submitting
+a pull request, please follow the guidelines in the [Submitting a Patch][2] section.
+
+[1]: http://symfony.com/doc/current/contributing/code/index.html
+[2]: http://symfony.com/doc/current/contributing/code/patches.html#check-list

src/Symfony/Component/DependencyInjection/Compiler/AnalyzeServiceReferencesPass.php

@@ -116,7 +116,7 @@ class AnalyzeServiceReferencesPass implements RepeatablePassInterface
      *
      * @param string $id A full id or alias for a service definition.
      *
-     * @return Definition The definition related to the supplied id
+     * @return Definition|null The definition related to the supplied id
      */
     private function getDefinition($id)
     {

src/Symfony/Component/DependencyInjection/Compiler/InlineServiceDefinitionsPass.php

@@ -70,6 +70,8 @@ class InlineServiceDefinitionsPass implements RepeatablePassInterface
      *
      * @param ContainerBuilder $container The ContainerBuilder
      * @param array            $arguments An array of arguments
+     *
+     * @return array
      */
     private function inlineArguments(ContainerBuilder $container, array $arguments)
     {

src/Symfony/Component/DependencyInjection/Compiler/RepeatedPass.php

@@ -28,7 +28,8 @@ class RepeatedPass implements CompilerPassInterface
      * Constructor.
      *
      * @param array $passes An array of RepeatablePassInterface objects
-     * @throws InvalidArgumentException if a pass is not a RepeatablePassInterface instance
+     *
+     * @throws InvalidArgumentException when the passes don't implement RepeatablePassInterface
      */
     public function __construct(array $passes)
     {

src/Symfony/Component/DependencyInjection/Compiler/ReplaceAliasByActualDefinitionPass.php

@@ -97,6 +97,8 @@ class ReplaceAliasByActualDefinitionPass implements CompilerPassInterface
      * @param array  $arguments An array of Arguments
      * @param string $currentId The alias identifier
      * @param string $newId     The identifier the alias points to
+     *
+     * @return array
      */
     private function updateArgumentReferences(array $arguments, $currentId, $newId)
     {

src/Symfony/Component/DependencyInjection/Compiler/ResolveDefinitionTemplatesPass.php

@@ -58,6 +58,8 @@ class ResolveDefinitionTemplatesPass implements CompilerPassInterface
      * @param DefinitionDecorator $definition
      *
      * @return Definition
+     *
+     * @throws \RuntimeException When the definition is invalid
      */
     private function resolveDefinition($id, DefinitionDecorator $definition)
     {

src/Symfony/Component/DependencyInjection/Compiler/ResolveInvalidReferencesPass.php

@@ -71,6 +71,10 @@ class ResolveInvalidReferencesPass implements CompilerPassInterface
      *
      * @param array   $arguments    An array of Reference objects
      * @param Boolean $inMethodCall
+     *
+     * @return array
+     *
+     * @throws \RuntimeException When the config is invalid
      */
     private function processArguments(array $arguments, $inMethodCall = false)
     {

src/Symfony/Component/DependencyInjection/Compiler/ResolveParameterPlaceHoldersPass.php

@@ -25,6 +25,8 @@ class ResolveParameterPlaceHoldersPass implements CompilerPassInterface
      * Processes the ContainerBuilder to resolve parameter placeholders.
      *
      * @param ContainerBuilder $container
+     *
+     * @throws ParameterNotFoundException When an invalid parameter is referenced
      */
     public function process(ContainerBuilder $container)
     {

src/Symfony/Component/DependencyInjection/Compiler/ServiceReferenceGraph.php

@@ -37,6 +37,8 @@ class ServiceReferenceGraph
      * Checks if the graph has a specific node.
      *
      * @param string $id Id to check
+     *
+     * @return Boolean
      */
     public function hasNode($id)
     {

src/Symfony/Component/DependencyInjection/Container.php

@@ -180,6 +180,9 @@ class Container implements IntrospectableContainerInterface
      * @param object $service The service instance
      * @param string $scope   The scope of the service
      *
+     * @throws \RuntimeException When trying to set a service in an inactive scope
+     * @throws \InvalidArgumentException When trying to set a service in the prototype scope
+     *
      * @api
      */
     public function set($id, $service, $scope = self::SCOPE_CONTAINER)
@@ -229,6 +232,8 @@ class Container implements IntrospectableContainerInterface
      * @return object The associated service
      *
      * @throws InvalidArgumentException if the service is not defined
+     * @throws ServiceCircularReferenceException When a circular reference is detected
+     * @throws ServiceNotFoundException When the service is not defined
      *
      * @see Reference
      *
@@ -301,6 +306,9 @@ class Container implements IntrospectableContainerInterface
      *
      * @param string $name
      *
+     * @throws RuntimeException         When the parent scope is inactive
+     * @throws InvalidArgumentException When the scope does not exist
+     *
      * @api
      */
     public function enterScope($name)
@@ -384,6 +392,8 @@ class Container implements IntrospectableContainerInterface
      *
      * @param ScopeInterface $scope
      *
+     * @throws \InvalidArgumentException When the scope is invalid
+     *
      * @api
      */
     public function addScope(ScopeInterface $scope)

src/Symfony/Component/DependencyInjection/ContainerBuilder.php

@@ -62,6 +62,8 @@ class ContainerBuilder extends Container implements TaggedContainerInterface
      *
      * @return ExtensionInterface An extension instance
      *
+     * @throws \LogicException if the extension is not registered
+     *
      * @api
      */
     public function getExtension($name)
@@ -162,6 +164,8 @@ class ContainerBuilder extends Container implements TaggedContainerInterface
      * @return ContainerBuilder The current instance
      * @throws BadMethodCallException When this ContainerBuilder is frozen
      *
+     * @throws \LogicException if the container is frozen
+     *
      * @api
      */
     public function loadFromExtension($extension, array $values = array())
@@ -493,8 +497,11 @@ class ContainerBuilder extends Container implements TaggedContainerInterface
     /**
      * Sets an alias for an existing service.
      *
-     * @param string $alias The alias to create
+     * @param string        $alias The alias to create
-     * @param mixed  $id    The service to alias
+     * @param string|Alias  $id    The service to alias
+     *
+     * @throws \InvalidArgumentException if the id is not a string or an Alias
+     * @throws \InvalidArgumentException if the alias is for itself
      *
      * @api
      */
@@ -546,7 +553,7 @@ class ContainerBuilder extends Container implements TaggedContainerInterface
     /**
      * Gets all defined aliases.
      *
-     * @return array An array of aliases
+     * @return Alias[] An array of aliases
      *
      * @api
      */
@@ -625,7 +632,7 @@ class ContainerBuilder extends Container implements TaggedContainerInterface
     /**
      * Gets all service definitions.
      *
-     * @return array An array of Definition instances
+     * @return Definition[] An array of Definition instances
      *
      * @api
      */
@@ -640,6 +647,8 @@ class ContainerBuilder extends Container implements TaggedContainerInterface
      * @param string     $id         The service identifier
      * @param Definition $definition A Definition instance
      *
+     * @return Definition the service definition
+     *
      * @throws BadMethodCallException When this ContainerBuilder is frozen
      *
      * @api
@@ -721,9 +730,10 @@ class ContainerBuilder extends Container implements TaggedContainerInterface
      * @param Definition $definition A service definition instance
      * @param string     $id         The service identifier
      *
-     * @return object              The service described by the service definition
+     * @return object The service described by the service definition
      *
-     * @throws RuntimeException         When factory specification is incomplete or scope is inactive
+     * @throws RuntimeException When the scope is inactive
+     * @throws RuntimeException When the factory definition is incomplete
      * @throws InvalidArgumentException When configure callable is not callable
      */
     private function createService(Definition $definition, $id)

src/Symfony/Component/DependencyInjection/ContainerInterface.php

@@ -12,6 +12,8 @@
 namespace Symfony\Component\DependencyInjection;
 
 use Symfony\Component\DependencyInjection\Exception\InvalidArgumentException;
+use Symfony\Component\DependencyInjection\Exception\ServiceCircularReferenceException;
+use Symfony\Component\DependencyInjection\Exception\ServiceNotFoundException;
 
 /**
  * ContainerInterface is the interface implemented by service container classes.
@@ -49,6 +51,8 @@ interface ContainerInterface
      * @return object The associated service
      *
      * @throws InvalidArgumentException if the service is not defined
+     * @throws ServiceCircularReferenceException When a circular reference is detected
+     * @throws ServiceNotFoundException When the service is not defined
      *
      * @see Reference
      *

src/Symfony/Component/DependencyInjection/Definition.php

@@ -241,6 +241,8 @@ class Definition
      *
      * @return Definition The current instance
      *
+     * @throws \OutOfBoundsException When the replaced argument does not exist
+     *
      * @api
      */
     public function replaceArgument($index, $argument)
@@ -273,6 +275,8 @@ class Definition
      *
      * @return mixed The argument value
      *
+     * @throws \OutOfBoundsException When the argument does not exist
+     *
      * @api
      */
     public function getArgument($index)
@@ -628,7 +632,7 @@ class Definition
     /**
      * Sets a configurator to call after the service is fully initialized.
      *
-     * @param mixed $callable A PHP callable
+     * @param callable $callable A PHP callable
      *
      * @return Definition The current instance
      *
@@ -644,7 +648,7 @@ class Definition
     /**
      * Gets the configurator to call after the service is fully initialized.
      *
-     * @return mixed The PHP callable to call
+     * @return callable The PHP callable to call
      *
      * @api
      */

src/Symfony/Component/DependencyInjection/DefinitionDecorator.php

@@ -29,7 +29,7 @@ class DefinitionDecorator extends Definition
     /**
      * Constructor.
      *
-     * @param Definition $parent The Definition instance to decorate.
+     * @param string $parent The id of Definition instance to decorate.
      *
      * @api
      */
@@ -44,7 +44,7 @@ class DefinitionDecorator extends Definition
     /**
      * Returns the Definition being decorated.
      *
-     * @return Definition
+     * @return string
      *
      * @api
      */
@@ -159,6 +159,8 @@ class DefinitionDecorator extends Definition
      *
      * @return mixed The argument value
      *
+     * @throws \OutOfBoundsException When the argument does not exist
+     *
      * @api
      */
     public function getArgument($index)

src/Symfony/Component/DependencyInjection/Dumper/PhpDumper.php

@@ -186,6 +186,9 @@ class PhpDumper extends Dumper
      * @param Definition $definition
      *
      * @return string
+     *
+     * @throws \RuntimeException When the factory definition is incomplete
+     * @throws ServiceCircularReferenceException When a circular reference is detected
      */
     private function addServiceInlinedDefinitions($id, $definition)
     {

src/Symfony/Component/DependencyInjection/Dumper/XmlDumper.php

@@ -63,7 +63,7 @@ class XmlDumper extends Dumper
     /**
      * Adds parameters.
      *
-     * @param DOMElement $parent
+     * @param \DOMElement $parent
      */
     private function addParameters(\DOMElement $parent)
     {
@@ -84,8 +84,8 @@ class XmlDumper extends Dumper
     /**
      * Adds method calls.
      *
-     * @param array      $methodcalls
+     * @param array       $methodcalls
-     * @param DOMElement $parent
+     * @param \DOMElement $parent
      */
     private function addMethodCalls(array $methodcalls, \DOMElement $parent)
     {
@@ -102,9 +102,9 @@ class XmlDumper extends Dumper
     /**
      * Adds a service.
      *
-     * @param Definition $definition
+     * @param Definition  $definition
-     * @param string     $id
+     * @param string      $id
-     * @param DOMElement $parent
+     * @param \DOMElement $parent
      */
     private function addService($definition, $id, \DOMElement $parent)
     {
@@ -172,9 +172,9 @@ class XmlDumper extends Dumper
     /**
      * Adds a service alias.
      *
-     * @param string     $alias
+     * @param string      $alias
-     * @param string     $id
+     * @param string      $id
-     * @param DOMElement $parent
+     * @param \DOMElement $parent
      */
     private function addServiceAlias($alias, $id, \DOMElement $parent)
     {
@@ -190,7 +190,7 @@ class XmlDumper extends Dumper
     /**
      * Adds services.
      *
-     * @param DOMElement $parent
+     * @param \DOMElement $parent
      */
     private function addServices(\DOMElement $parent)
     {
@@ -213,10 +213,10 @@ class XmlDumper extends Dumper
     /**
      * Converts parameters.
      *
-     * @param array      $parameters
+     * @param array       $parameters
-     * @param string     $type
+     * @param string      $type
-     * @param DOMElement $parent
+     * @param \DOMElement $parent
-     * @param string     $keyAttribute
+     * @param string      $keyAttribute
      */
     private function convertParameters($parameters, $type, \DOMElement $parent, $keyAttribute = 'key')
     {
@@ -280,6 +280,10 @@ class XmlDumper extends Dumper
      * Converts php types to xml types.
      *
      * @param mixed $value Value to convert
+     *
+     * @return string
+     *
+     * @throws RuntimeException When trying to dump object or resource
      */
     public static function phpToXml($value)
     {

src/Symfony/Component/DependencyInjection/Dumper/YamlDumper.php

@@ -12,7 +12,10 @@
 namespace Symfony\Component\DependencyInjection\Dumper;
 
 use Symfony\Component\Yaml\Dumper as YmlDumper;
+use Symfony\Component\Yaml\Yaml;
+use Symfony\Component\DependencyInjection\Alias;
 use Symfony\Component\DependencyInjection\ContainerInterface;
+use Symfony\Component\DependencyInjection\Definition;
 use Symfony\Component\DependencyInjection\Parameter;
 use Symfony\Component\DependencyInjection\Reference;
 use Symfony\Component\DependencyInjection\Exception\RuntimeException;
@@ -135,7 +138,7 @@ class YamlDumper extends Dumper
      * Adds a service alias
      *
      * @param string $alias
-     * @param string $id
+     * @param Alias  $id
      *
      * @return string
      */
@@ -196,6 +199,8 @@ class YamlDumper extends Dumper
      *
      * @param mixed $value
      *
+     * @return mixed
+     *
      * @throws RuntimeException When trying to dump object or resource
      */
     private function dumpValue($value)

src/Symfony/Component/DependencyInjection/Loader/XmlFileLoader.php

@@ -200,7 +200,9 @@ class XmlFileLoader extends FileLoader
      *
      * @param string $file Path to a file
      *
-     * @throws InvalidArgumentException When loading of XML file returns error
+     * @return SimpleXMLElement
+     *
+     * @throws \InvalidArgumentException When loading of XML file returns error
      */
     private function parseFile($file)
     {
@@ -286,8 +288,8 @@ class XmlFileLoader extends FileLoader
     /**
      * Validates an XML document.
      *
-     * @param DOMDocument $dom
+     * @param \DOMDocument $dom
-     * @param string      $file
+     * @param string       $file
      */
     private function validate(\DOMDocument $dom, $file)
     {
@@ -302,7 +304,7 @@ class XmlFileLoader extends FileLoader
      * @param string       $file
      *
      * @throws RuntimeException         When extension references a non-existent XSD file
-     * @throws InvalidArgumentException When XML doesn't validate its XSD schema
+     * @throws InvalidArgumentException When xml doesn't validate its xsd schema
      */
     private function validateSchema(\DOMDocument $dom, $file)
     {
@@ -404,6 +406,8 @@ EOF
     /**
      * Returns an array of XML errors.
      *
+     * @param Boolean $internalErrors
+     *
      * @return array
      */
     private function getXmlErrors($internalErrors)

src/Symfony/Component/DependencyInjection/Loader/YamlFileLoader.php

@@ -119,6 +119,8 @@ class YamlFileLoader extends FileLoader
      * @param string $id
      * @param array  $service
      * @param string $file
+     *
+     * @throws InvalidArgumentException When tags are invalid
      */
     private function parseDefinition($id, $service, $file)
     {

src/Symfony/Component/DependencyInjection/ParameterBag/ParameterBag.php

@@ -84,7 +84,7 @@ class ParameterBag implements ParameterBagInterface
      *
      * @return mixed  The parameter value
      *
-     * @throws  ParameterNotFoundException if the parameter is not defined
+     * @throws ParameterNotFoundException if the parameter is not defined
      *
      * @api
      */

src/Symfony/Component/HttpKernel/Kernel.php

@@ -250,7 +250,7 @@ abstract class Kernel implements KernelInterface, TerminableInterface
     public function getBundle($name, $first = true)
     {
         if (!isset($this->bundleMap[$name])) {
-            throw new \InvalidArgumentException(sprintf('Bundle "%s" does not exist or it is not enabled. Maybe you forgot to add it in the registerBundles() function of your %s.php file?', $name, get_class($this)));
+            throw new \InvalidArgumentException(sprintf('Bundle "%s" does not exist or it is not enabled. Maybe you forgot to add it in the registerBundles() method of your %s.php file?', $name, get_class($this)));
         }
 
         if (true === $first) {

src/Symfony/Component/HttpKernel/Profiler/Profiler.php

@@ -168,7 +168,7 @@ class Profiler
         $profile = new Profile(uniqid());
         $profile->setTime(time());
         $profile->setUrl($request->getUri());
-        $profile->setIp($request->server->get('REMOTE_ADDR'));
+        $profile->setIp($request->getClientIp());
         $profile->setMethod($request->getMethod());
 
         $response->headers->set('X-Debug-Token', $profile->getToken());