Merge branch '2.1'

Conflicts:
	reference/configuration/security.rst

Author: weaverryan

book/controller.rst

@@ -493,6 +493,8 @@ that's responsible for generating the HTML (or other format) for the controller.
 The ``renderView()`` method renders a template and returns its content. The
 content from the template can be used to create a ``Response`` object::
 
+    use Symfony\Component\HttpFoundation\Response;
+
     $content = $this->renderView(
         'AcmeHelloBundle:Hello:index.html.twig',
         array('name' => $name)
@@ -705,6 +707,8 @@ The only requirement for a controller is to return a ``Response`` object. The
 abstraction around the HTTP response - the text-based message filled with HTTP
 headers and content that's sent back to the client::
 
+    use Symfony\Component\HttpFoundation\Response;
+
     // create a simple Response with a 200 status code (the default)
     $response = new Response('Hello '.$name, 200);
 

book/doctrine.rst

@@ -142,7 +142,7 @@ just a simple PHP class.
 .. tip::
 
     Once you learn the concepts behind Doctrine, you can have Doctrine create
-    this entity class for you:
+    simple entity classes for you:
 
     .. code-block:: bash
 
@@ -315,6 +315,12 @@ for the ``Product`` class. This is a safe command - you can run it over and
 over again: it only generates getters and setters that don't exist (i.e. it
 doesn't replace your existing methods).
 
+.. caution::
+
+    Keep in mind that Doctrine's entity generator produces simple getters/setters. 
+    You should check generated entities and adjust getter/setter logic to your own 
+    needs.
+
 .. sidebar:: More about ``doctrine:generate:entities``
 
     With the ``doctrine:generate:entities`` command you can:

book/forms.rst

@@ -205,6 +205,7 @@ user must be bound to the form. Add the following functionality to your
 controller::
 
     // ...
+    use Symfony\Component\HttpFoundation\Request;
 
     public function newAction(Request $request)
     {

book/from_flat_php_to_symfony2.rst

@@ -436,7 +436,7 @@ content:
             "symfony/symfony": "2.1.*"
         },
         "autoload": {
-            "files": ["model.php","controller.php"]
+            "files": ["model.php","controllers.php"]
         }
     }
     
@@ -462,7 +462,7 @@ the HTTP response being returned. Use them to improve the blog:
 
     <?php
     // index.php
-    require_once 'vendor/bootstrap.php';
+    require_once 'vendor/autoload.php';
 
     use Symfony\Component\HttpFoundation\Request;
     use Symfony\Component\HttpFoundation\Response;
@@ -582,7 +582,7 @@ them for you. Here's the same sample application, now built in Symfony2::
         }
     }
 
-The two controllers are still lightweight. Each uses the Doctrine ORM library
+The two controllers are still lightweight. Each uses the :doc:`Doctrine ORM library</book/doctrine>`
 to retrieve objects from the database and the ``Templating`` component to
 render a template and return a ``Response`` object. The list template is
 now quite a bit simpler:

book/http_cache.rst

@@ -310,6 +310,8 @@ its creation more manageable::
 
     // ...
 
+    use Symfony\Component\HttpFoundation\Response;
+
     $response = new Response();
 
     // mark the response as either public or private
@@ -650,6 +652,8 @@ Put another way, the less you do in your application to return a 304 response,
 the better. The ``Response::isNotModified()`` method does exactly that by
 exposing a simple and efficient pattern::
 
+    use Symfony\Component\HttpFoundation\Response;
+
     public function showAction($articleSlug)
     {
         // Get the minimum information to compute
@@ -1026,6 +1030,8 @@ Here is how you can configure the Symfony2 reverse proxy to support the
 
     // ...
     use Symfony\Bundle\FrameworkBundle\HttpCache\HttpCache;
+    use Symfony\Component\HttpFoundation\Request;
+    use Symfony\Component\HttpFoundation\Response;
 
     class AppCache extends HttpCache
     {

book/http_fundamentals.rst

@@ -363,6 +363,8 @@ need to check the incoming URI and execute different parts of your code dependin
 on that value. This can get ugly quickly::
 
     // index.php
+    use Symfony\Component\HttpFoundation\Request;
+    use Symfony\Component\HttpFoundation\Response;
     $request = Request::createFromGlobals();
     $path = $request->getPathInfo(); // the URI path being requested
 
@@ -457,6 +459,8 @@ the ``AcmeDemoBundle:Main:contact`` string is a short syntax that points to a
 specific PHP method ``contactAction`` inside a class called ``MainController``::
 
     // src/Acme/DemoBundle/Controller/MainController.php
+    use Symfony\Component\HttpFoundation\Response;
+
     class MainController
     {
         public function contactAction()

book/page_creation.rst

@@ -802,7 +802,8 @@ options of each feature.
     three formats (YAML, XML and PHP). Each has its own advantages and
     disadvantages. The choice of which to use is up to you:
 
-    * *YAML*: Simple, clean and readable;
+    * *YAML*: Simple, clean and readable (learn more about yaml in
+    * ":doc:`/components/yaml/yaml_format`");
 
     * *XML*: More powerful than YAML at times and supports IDE autocompletion;
 

book/templating.rst

@@ -1086,6 +1086,8 @@ you're actually using the templating engine service. For example::
 
 is equivalent to::
 
+    use Symfony\Component\HttpFoundation\Response;
+
     $engine = $this->container->get('templating');
     $content = $engine->render('AcmeArticleBundle:Article:index.html.twig');
 

book/translation.rst

@@ -97,6 +97,9 @@ of text (called a *message*), use the
 :method:`Symfony\\Component\\Translation\\Translator::trans` method. Suppose,
 for example, that you're translating a simple message from inside a controller::
 
+    // ...
+    use Symfony\Component\HttpFoundation\Response;
+
     public function indexAction()
     {
         $t = $this->get('translator')->trans('Symfony2 is great');
@@ -171,6 +174,9 @@ Message Placeholders
 
 Sometimes, a message containing a variable needs to be translated::
 
+    // ...
+    use Symfony\Component\HttpFoundation\Response;
+
     public function indexAction($name)
     {
         $t = $this->get('translator')->trans('Hello '.$name);
@@ -184,14 +190,17 @@ will try to look up the exact message, including the variable portions
 for every possible iteration of the ``$name`` variable, you can replace the
 variable with a "placeholder"::
 
+    // ...
+    use Symfony\Component\HttpFoundation\Response;
+
     public function indexAction($name)
     {
         $t = $this->get('translator')->trans(
             'Hello %name%',
             array('%name%' => $name)
         );
 
-        new Response($t);
+        return new Response($t);
     }
 
 Symfony2 will now look for a translation of the raw message (``Hello %name%``)
@@ -786,9 +795,9 @@ texts* and complex expressions:
 
     Using the translation tags or filters have the same effect, but with
     one subtle difference: automatic output escaping is only applied to
-    variables translated using a filter. In other words, if you need to
-    be sure that your translated variable is *not* output escaped, you must
-    apply the raw filter after the translation filter:
+    translations using a filter. In other words, if you need to be sure
+    that your translated is *not* output escaped, you must apply the 
+    ``raw`` filter after the translation filter:
 
     .. code-block:: jinja
 
@@ -799,11 +808,9 @@ texts* and complex expressions:
 
             {% set message = '<h3>foo</h3>' %}
 
-            {# a variable translated via a filter is escaped by default #}
+            {# strings and variables translated via a filter is escaped by default #}
             {{ message|trans|raw }}
-
-            {# but static strings are never escaped #}
-            {{ '<h3>foo</h3>'|trans }}
+            {{ '<h3>bar</h3>'|trans|raw }}
 
 .. versionadded:: 2.1
      You can now set the translation domain for an entire Twig template with a

components/console/helpers/dialoghelper.rst

@@ -96,6 +96,7 @@ method::
                     'The name of the bundle should be suffixed with \'Bundle\''
                 );
             }
+            return $answer;
         },
         false,
         'AcmeDemoBundle'
@@ -113,8 +114,8 @@ This methods has 2 new arguments, the full signature is::
 
 The ``$validator`` is a callback which handles the validation. It should
 throw an exception if there is something wrong. The exception message is displayed
-in the console, so it is a good practice to put some useful information 
-in it.
+in the console, so it is a good practice to put some useful information in it. The callback 
+function should also return the value of the user's input if the validation was successful.
 
 You can set the max number of times to ask in the ``$attempts`` argument.
 If you reach this max number it will use the default value, which is given

components/dependency_injection/compilation.rst

@@ -112,13 +112,20 @@ processed when the container is compiled at which point the Extensions are loade
     use Symfony\Component\DependencyInjection\Loader\YamlFileLoader;
 
     $container = new ContainerBuilder();
+    $container->registerExtension(new AcmeDemoExtension);
+
     $loader = new YamlFileLoader($container, new FileLocator(__DIR__));
     $loader->load('config.yml');
 
-    $container->registerExtension(new AcmeDemoExtension);
     // ...
     $container->compile();
 
+.. note::
+
+    When loading a config file that uses an extension alias as a key, the
+    extension must already have been registered with the container builder
+    or an exception will be thrown.
+
 The values from those sections of the config files are passed into the first
 argument of the ``load`` method of the extension::
 
@@ -239,6 +246,25 @@ but also load a secondary one only if a certain parameter is set::
         }
     }
 
+.. note::
+
+    Just registering an extension with the container is not enough to get
+    it included in the processed extensions when the container is compiled.
+    Loading config which uses the extension's alias as a key as in the above
+    examples will ensure it is loaded. The container builder can also be
+    told to load it with its
+    :method:`Symfony\\Component\\DependencyInjection\\ContainerBuilder::loadFromExtension`
+    method::
+
+        use Symfony\Component\DependencyInjection\ContainerBuilder;
+
+        $container = new ContainerBuilder();
+        $extension = new AcmeDemoExtension();
+        $container->registerExtension($extension);
+        $container->loadFromExtension($extension->getAlias());
+        $container->compile();
+
+
 .. note::
 
     If you need to manipulate the configuration loaded by an extension then

components/dependency_injection/definitions.rst

@@ -28,7 +28,7 @@ Getting and Setting Service Definitions
 There are also some helpful methods for
 working with the service definitions.
 
-To find out if there is a definition for a service id:: 
+To find out if there is a definition for a service id::
 
     $container->hasDefinition($serviceId);
 
@@ -84,7 +84,7 @@ To get an array of the constructor arguments for a definition you can use::
 
 or to get a single argument by its position::
 
-    $definition->getArgument($index); 
+    $definition->getArgument($index);
     //e.g. $definition->getArguments(0) for the first argument
 
 You can add a new argument to the end of the arguments array using::
@@ -95,7 +95,7 @@ The argument can be a string, an array, a service parameter by using ``%paramete
 or a service id by using ::
 
     use Symfony\Component\DependencyInjection\Reference;
-  
+
     // ...
 
     $definition->addArgument(new Reference('service_id'));
@@ -131,3 +131,9 @@ You can also replace any existing method calls with an array of new ones with::
 
     $definition->setMethodCalls($methodCalls);
 
+.. tip::
+
+    There are more examples of specific ways of working with definitions
+    in the PHP code blocks of the configuration examples on pages such as
+    :doc:`/components/dependency_injection/factories` and
+    :doc:`/components/dependency_injection/parentservices`.

components/dependency_injection/introduction.rst

@@ -147,7 +147,7 @@ If you do want to though then the container can call the setter method::
 
     $container
         ->register('newsletter_manager', 'NewsletterManager')
-        ->addMethodCall('setMailer', new Reference('mailer'));
+        ->addMethodCall('setMailer', array(new Reference('mailer')));
 
 You could then get your ``newsletter_manager`` service from the container
 like this::
@@ -259,6 +259,6 @@ The ``newsletter_manager`` and ``mailer`` services can be set up using config fi
 
         $container
             ->register('newsletter_manager', 'NewsletterManager')
-            ->addMethodCall('setMailer', new Reference('mailer'));
+            ->addMethodCall('setMailer', array(new Reference('mailer')));
 
 .. _Packagist: https://packagist.org/packages/symfony/dependency-injection

components/dom_crawler.rst

@@ -7,6 +7,11 @@ The DomCrawler Component
 
     The DomCrawler Component eases DOM navigation for HTML and XML documents.
 
+.. note::
+
+    While possible, the DomCrawler component is not designed for manipulation
+    of the DOM or re-dumping HTML/XML.
+
 Installation
 ------------
 
@@ -172,6 +177,22 @@ and :phpclass:`DOMNode` objects:
     $crawler->addNode($node);
     $crawler->add($document);
 
+.. sidebar:: Manipulating and Dumping a ``Crawler``
+
+    These methods on the ``Crawler`` are intended to initially populate your
+    ``Crawler`` and aren't intended to be used to further manipulate a DOM
+    (though this is possible). However, since the ``Crawler`` is a set of
+    :phpclass:`DOMElement` objects, you can use any method or property available
+    on :phpclass:`DOMElement`, :phpclass:`DOMNode` or :phpclass:`DOMDocument`.
+    For example, you could get the HTML of a ``Crawler`` with something like
+    this::
+    
+        $html = '';
+
+        foreach ($crawler as $domElement) {
+            $html.= $domElement->ownerDocument->saveHTML();
+        }
+
 Form and Link support
 ~~~~~~~~~~~~~~~~~~~~~
 

components/map.rst.inc

@@ -96,6 +96,7 @@
 
   * :doc:`/components/templating`
 
-* **YAML**
+* :doc:`/components/yaml/index`
 
-  * :doc:`/components/yaml`
+  * :doc:`/components/yaml/introduction`
+  * :doc:`/components/yaml/yaml_format`

components/yaml/index.rst

@@ -0,0 +1,8 @@
+Yaml
+====
+
+.. toctree::
+    :maxdepth: 2
+
+    introduction
+    yaml_format