Merge branch '2.0' into 2.1

weaverryan · weaverryan · commit cae9f9fe22a3 · 2013-01-24T21:51:08.000-08:00
diff --git a/book/controller.rst b/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);
 
diff --git a/book/doctrine.rst b/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:
diff --git a/book/forms.rst b/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)
     {
diff --git a/book/from_flat_php_to_symfony2.rst b/book/from_flat_php_to_symfony2.rst
@@ -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:
diff --git a/book/http_cache.rst b/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
@@ -1010,6 +1014,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
     {
diff --git a/book/http_fundamentals.rst b/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()
diff --git a/book/page_creation.rst b/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;
 
diff --git a/book/templating.rst b/book/templating.rst
@@ -1045,6 +1045,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');
 
diff --git a/book/translation.rst b/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
diff --git a/components/console/helpers/dialoghelper.rst b/components/console/helpers/dialoghelper.rst
@@ -72,6 +72,7 @@ method::
                     'The name of the bundle should be suffixed with \'Bundle\''
                 );
             }
+            return $answer;
         },
         false,
         'AcmeDemoBundle'
@@ -89,8 +90,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
diff --git a/components/dependency_injection/compilation.rst b/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
diff --git a/components/dependency_injection/definitions.rst b/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`.
diff --git a/components/dependency_injection/introduction.rst b/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
diff --git a/components/dom_crawler.rst b/components/dom_crawler.rst
@@ -9,8 +9,8 @@ The DomCrawler Component
 
 .. note::
 
-    While possible, the DomCrawler is not designed for manipulation of the
-    DOM or re-dumping HTML/XML.
+    While possible, the DomCrawler component is not designed for manipulation
+    of the DOM or re-dumping HTML/XML.
 
 Installation
 ------------
@@ -177,7 +177,7 @@ and :phpclass:`DOMNode` objects:
     $crawler->addNode($node);
     $crawler->add($document);
 
-.. note::
+.. 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
diff --git a/components/map.rst.inc b/components/map.rst.inc
@@ -91,6 +91,7 @@
 
   * :doc:`/components/templating`
 
-* **YAML**
+* :doc:`/components/yaml/index`
 
-  * :doc:`/components/yaml`
+  * :doc:`/components/yaml/introduction`
+  * :doc:`/components/yaml/yaml_format`
diff --git a/components/yaml/index.rst b/components/yaml/index.rst
@@ -0,0 +1,8 @@
+Yaml
+====
+
+.. toctree::
+    :maxdepth: 2
+
+    introduction
+    yaml_format
diff --git a/components/yaml/introduction.rst b/components/yaml/introduction.rst
diff --git a/components/yaml/yaml_format.rst b/components/yaml/yaml_format.rst
diff --git a/contributing/code/standards.rst b/contributing/code/standards.rst
diff --git a/contributing/documentation/overview.rst b/contributing/documentation/overview.rst
diff --git a/redirection_map b/redirection_map
diff --git a/reference/configuration/security.rst b/reference/configuration/security.rst
diff --git a/reference/constraints/File.rst b/reference/constraints/File.rst

Original file line number	Diff line number	Diff line change
`@@ -205,6 +205,7 @@ user must be bound to the form. Add the following functionality to your`
`205`	`205`	`controller::`
`206`	`206`
`207`	`207`	`// ...`
	`208`	`+ use Symfony\Component\HttpFoundation\Request;`
`208`	`209`
`209`	`210`	`public function newAction(Request $request)`
`210`	`211`	`{`
Original file line number	Diff line number	Diff line change
`@@ -582,7 +582,7 @@ them for you. Here's the same sample application, now built in Symfony2::`
`582`	`582`	`}`
`583`	`583`	`}`
`584`	`584`
`585`		`-The two controllers are still lightweight. Each uses the Doctrine ORM library`
	`585`	+The two controllers are still lightweight. Each uses the :doc:`Doctrine ORM library</book/doctrine>`
`586`	`586`	to retrieve objects from the database and the ``Templating`` component to
`587`	`587`	render a template and return a ``Response`` object. The list template is
`588`	`588`	`now quite a bit simpler:`