Merge branch '2.8'

* 2.8: (122 commits)
  moving options below basic usage
  changing a few orders of sections - mostly to move overridden after the main options
  Rewrite note a bit
  fix capitalization
  tweak headline to be consistent with 2.6
  [Contributing] [Standards] Added entry for identical comparison
  Wrap the table creation inside the class extending Command, so users know where the  comes. They can use it as standalone when needed
  [Serializer] Array Denormalization
  [Cookbook][Assetic] complete a sentence
  Fixing "Undefined method" error on Symfony 2.7
  [symfony#5293] Tweak to link to the article about parent bundles
  Minor tweak to remove FOSUserBundle example and replace with a link to the doc about this
  overriding 3rd party bundles
  Adjust line wrapping
  Add formatting for file and method names
  Update load_balancer_reverse_proxy.rst
  removing upgrading.rst - this has already been moved into several documents in its own section
  [symfony#5166] Minor tweaks
  Revert "Changed dump() to var_dump()"
  Changed dump() to var_dump()
  ...

Author: weaverryan

best_practices/creating-the-project.rst

@@ -110,6 +110,11 @@ Symfony documentation uses the AppBundle name.
     There is no need to prefix the AppBundle with your own vendor (e.g.
     AcmeAppBundle), because this application bundle is never going to be
     shared.
+    
+.. note::
+    
+    Another reason to create a new bundle is when you're overriding something 
+    in a vendor's bundle (e.g. a controller). See :doc:`/cookbook/bundles/inheritance`.
 
 All in all, this is the typical directory structure of a Symfony application
 that follows these best practices:

book/doctrine.rst

@@ -1204,7 +1204,8 @@ to the given ``Category`` object via their ``category_id`` value.
         $category = $product->getCategory();
 
         // prints "Proxies\AppBundleEntityCategoryProxy"
-        echo get_class($category);
+        dump(get_class($category));
+        die();
 
     This proxy object extends the true ``Category`` object, and looks and
     acts exactly like it. The difference is that, by using a proxy object,

book/service_container.rst

@@ -276,10 +276,11 @@ The service container is built using a single configuration resource
 be imported from inside this file in one way or another. This gives you absolute
 flexibility over the services in your application.
 
-External service configuration can be imported in two different ways. The
-first - and most common method - is via the ``imports`` directive. Later, you'll
-learn about the second method, which is the flexible and preferred method
-for importing service configuration from third-party bundles.
+External service configuration can be imported in two different ways. The first 
+method, commonly used to import container configuration from the bundles you've 
+created - is via the ``imports`` directive. The second method, although slightly more 
+complex offers more flexibility and is commonly used to import third-party bundle 
+configuration. Read on to learn more about both methods.
 
 .. index::
    single: Service Container; Imports

book/translation.rst

@@ -12,11 +12,13 @@ wrapping each with a function capable of translating the text (or "message")
 into the language of the user::
 
     // text will *always* print out in English
-    echo 'Hello World';
+    dump('Hello World');
+    die();
 
     // text can be translated into the end-user's language or
     // default to English
-    echo $translator->trans('Hello World');
+    dump($translator->trans('Hello World'));
+    die();
 
 .. note::
 

components/class_loader/class_map_generator.rst

@@ -50,7 +50,7 @@ method::
 
     use Symfony\Component\ClassLoader\ClassMapGenerator;
 
-    print_r(ClassMapGenerator::createMap(__DIR__.'/library'));
+    var_dump(ClassMapGenerator::createMap(__DIR__.'/library'));
 
 Given the files and class from the table above, you should see an output like
 this:

components/console/console_arguments.rst

@@ -14,6 +14,7 @@ Have a look at the following command that has three options::
 
     use Symfony\Component\Console\Command\Command;
     use Symfony\Component\Console\Input\InputArgument;
+    use Symfony\Component\Console\Input\InputDefinition;
     use Symfony\Component\Console\Input\InputInterface;
     use Symfony\Component\Console\Input\InputOption;
     use Symfony\Component\Console\Output\OutputInterface;

components/console/helpers/table.rst

@@ -21,18 +21,25 @@ To display a table, use :class:`Symfony\\Component\\Console\\Helper\\Table`,
 set the headers, set the rows and then render the table::
 
     use Symfony\Component\Console\Helper\Table;
-
-    $table = new Table($output);
-    $table
-        ->setHeaders(array('ISBN', 'Title', 'Author'))
-        ->setRows(array(
-            array('99921-58-10-7', 'Divine Comedy', 'Dante Alighieri'),
-            array('9971-5-0210-0', 'A Tale of Two Cities', 'Charles Dickens'),
-            array('960-425-059-0', 'The Lord of the Rings', 'J. R. R. Tolkien'),
-            array('80-902734-1-6', 'And Then There Were None', 'Agatha Christie'),
-        ))
-    ;
-    $table->render();
+    // ...
+
+    class SomeCommand extends Command
+    {
+        public function execute(InputInterface $input, OutputInterface $output)
+        {
+            $table = new Table($output);
+            $table
+                ->setHeaders(array('ISBN', 'Title', 'Author'))
+                ->setRows(array(
+                    array('99921-58-10-7', 'Divine Comedy', 'Dante Alighieri'),
+                    array('9971-5-0210-0', 'A Tale of Two Cities', 'Charles Dickens'),
+                    array('960-425-059-0', 'The Lord of the Rings', 'J. R. R. Tolkien'),
+                    array('80-902734-1-6', 'And Then There Were None', 'Agatha Christie'),
+                ))
+            ;
+            $table->render();
+        }
+    }
 
 You can add a table separator anywhere in the output by passing an instance of
 :class:`Symfony\\Component\\Console\\Helper\\TableSeparator` as a row::

components/console/introduction.rst

@@ -200,7 +200,7 @@ level of verbosity.
 It is possible to print a message in a command for only a specific verbosity
 level. For example::
 
-    if (OutputInterface::VERBOSITY_VERBOSE <= $output->getVerbosity()) {
+    if ($output->getVerbosity() >= OutputInterface::VERBOSITY_VERBOSE) {
         $output->writeln(...);
     }
 

components/console/logger.rst

@@ -80,7 +80,9 @@ The association between the log level and the verbosity can be configured
 through the second parameter of the :class:`Symfony\\Component\\Console\\ConsoleLogger`
 constructor::
 
+    use Psr\Log\LogLevel;
     // ...
+
     $verbosityLevelMap = array(
         LogLevel::NOTICE => OutputInterface::VERBOSITY_NORMAL,
         LogLevel::INFO   => OutputInterface::VERBOSITY_NORMAL,

components/css_selector.rst

@@ -51,7 +51,7 @@ equivalents::
 
     use Symfony\Component\CssSelector\CssSelector;
 
-    print CssSelector::toXPath('div.item > h4 > a');
+    var_dump(CssSelector::toXPath('div.item > h4 > a'));
 
 This gives the following output:
 

components/dependency_injection/advanced.rst

@@ -4,6 +4,8 @@
 Advanced Container Configuration
 ================================
 
+.. _container-private-services:
+
 Marking Services as public / private
 ------------------------------------
 

components/dom_crawler.rst

@@ -47,7 +47,7 @@ traverse easily::
     $crawler = new Crawler($html);
 
     foreach ($crawler as $domElement) {
-        print $domElement->nodeName;
+        var_dump($domElement->nodeName);
     }
 
 Specialized :class:`Symfony\\Component\\DomCrawler\\Link` and
@@ -301,6 +301,12 @@ and :phpclass:`DOMNode` objects:
 
     The ``html`` method is new in Symfony 2.3.
 
+    .. caution::
+
+        Due to an issue in PHP, the ``html()`` method returns wrongly decoded HTML
+        entities in PHP versions lower than 5.3.6 (for example, it returns ``•``
+        instead of ``•``).
+
 Links
 ~~~~~
 

components/event_dispatcher/generic_event.rst

@@ -75,7 +75,7 @@ the event arguments::
     );
     $dispatcher->dispatch('foo', $event);
 
-    echo $event['counter'];
+    var_dump($event['counter']);
 
     class FooListener
     {
@@ -96,7 +96,7 @@ Filtering data::
     $event = new GenericEvent($subject, array('data' => 'Foo'));
     $dispatcher->dispatch('foo', $event);
 
-    echo $event['data'];
+    var_dump($event['data']);
 
     class FooListener
     {
@@ -105,3 +105,4 @@ Filtering data::
             $event['data'] = strtolower($event['data']);
         }
     }
+

components/event_dispatcher/introduction.rst

@@ -638,7 +638,7 @@ dispatched, are passed as arguments to the listener::
     {
         public function myEventListener(Event $event, $eventName, EventDispatcherInterface $dispatcher)
         {
-            echo $eventName;
+            // ... do something with the event name
         }
     }
 

components/expression_language/caching.rst

@@ -56,7 +56,7 @@ Both ``evaluate()`` and ``compile()`` can handle ``ParsedExpression`` and
     // the parse() method returns a ParsedExpression
     $expression = $language->parse('1 + 4', array());
 
-    echo $language->evaluate($expression); // prints 5
+    var_dump($language->evaluate($expression)); // prints 5
 
 .. code-block:: php
 
@@ -68,7 +68,7 @@ Both ``evaluate()`` and ``compile()`` can handle ``ParsedExpression`` and
         serialize($language->parse('1 + 4', array()))
     );
 
-    echo $language->evaluate($expression); // prints 5
+    var_dump($language->evaluate($expression)); // prints 5
 
 .. _DoctrineBridge: https://github.com/symfony/DoctrineBridge
 .. _`doctrine cache library`: http://docs.doctrine-project.org/projects/doctrine-common/en/latest/reference/caching.html

components/expression_language/extending.rst

@@ -44,7 +44,7 @@ This method has 3 arguments:
         return strtolower($str);
     });
 
-    echo $language->evaluate('lowercase("HELLO")');
+    var_dump($language->evaluate('lowercase("HELLO")'));
 
 This will print ``hello``. Both the **compiler** and **evaluator** are passed
 an ``arguments`` variable as their first argument, which is equal to the
@@ -126,3 +126,4 @@ or by using the second argument of the constructor::
                 parent::__construct($parser, $providers);
             }
         }
+

components/expression_language/introduction.rst

@@ -68,9 +68,9 @@ The main class of the component is
 
     $language = new ExpressionLanguage();
 
-    echo $language->evaluate('1 + 2'); // displays 3
+    var_dump($language->evaluate('1 + 2')); // displays 3
 
-    echo $language->compile('1 + 2'); // displays (1 + 2)
+    var_dump($language->compile('1 + 2')); // displays (1 + 2)
 
 Expression Syntax
 -----------------
@@ -96,12 +96,12 @@ PHP type (including objects)::
     $apple = new Apple();
     $apple->variety = 'Honeycrisp';
 
-    echo $language->evaluate(
+    var_dump($language->evaluate(
         'fruit.variety',
         array(
             'fruit' => $apple,
         )
-    );
+    ));
 
 This will print "Honeycrisp". For more information, see the :doc:`/components/expression_language/syntax`
 entry, especially :ref:`component-expression-objects` and :ref:`component-expression-arrays`.

components/expression_language/syntax.rst

@@ -42,12 +42,12 @@ to JavaScript::
     $apple = new Apple();
     $apple->variety = 'Honeycrisp';
 
-    echo $language->evaluate(
+    var_dump($language->evaluate(
         'fruit.variety',
         array(
             'fruit' => $apple,
         )
-    );
+    ));
 
 This will print out ``Honeycrisp``.
 
@@ -72,12 +72,12 @@ JavaScript::
 
     $robot = new Robot();
 
-    echo $language->evaluate(
+    var_dump($language->evaluate(
         'robot.sayHi(3)',
         array(
             'robot' => $robot,
         )
-    );
+    ));
 
 This will print out ``Hi Hi Hi!``.
 
@@ -93,9 +93,9 @@ constant::
 
     define('DB_USER', 'root');
 
-    echo $language->evaluate(
+    var_dump($language->evaluate(
         'constant("DB_USER")'
-    );
+    ));
 
 This will print out ``root``.
 
@@ -114,12 +114,12 @@ array keys, similar to JavaScript::
 
     $data = array('life' => 10, 'universe' => 10, 'everything' => 22);
 
-    echo $language->evaluate(
+    var_dump($language->evaluate(
         'data["life"] + data["universe"] + data["everything"]',
         array(
             'data' => $data,
         )
-    );
+    ));
 
 This will print out ``42``.
 
@@ -140,14 +140,14 @@ Arithmetic Operators
 
 For example::
 
-    echo $language->evaluate(
+    var_dump($language->evaluate(
         'life + universe + everything',
         array(
             'life' => 10,
             'universe' => 10,
             'everything' => 22,
         )
-    );
+    ));
 
 This will print out ``42``.
 
@@ -230,13 +230,13 @@ String Operators
 
 For example::
 
-    echo $language->evaluate(
+    var_dump($language->evaluate(
         'firstName~" "~lastName',
         array(
             'firstName' => 'Arthur',
             'lastName' => 'Dent',
         )
-    );
+    ));
 
 This would print out ``Arthur Dent``.
 

components/finder.rst

@@ -30,14 +30,14 @@ directories::
     $finder->files()->in(__DIR__);
 
     foreach ($finder as $file) {
-        // Print the absolute path
-        print $file->getRealpath()."\n";
+        // Dump the absolute path
+        var_dump($file->getRealpath());
 
-        // Print the relative path to the file, omitting the filename
-        print $file->getRelativePath()."\n";
+        // Dump the relative path to the file, omitting the filename
+        var_dump($file->getRelativePath());
 
-        // Print the relative path to the file
-        print $file->getRelativePathname()."\n";
+        // Dump the relative path to the file
+        var_dump($file->getRelativePathname());
     }
 
 The ``$file`` is an instance of :class:`Symfony\\Component\\Finder\\SplFileInfo`
@@ -118,9 +118,7 @@ And it also works with user-defined streams::
     $finder = new Finder();
     $finder->name('photos*')->size('< 100K')->date('since 1 hour ago');
     foreach ($finder->in('s3://bucket-name') as $file) {
-        // ... do something
-
-        print $file->getFilename()."\n";
+        // ... do something with the file
     }
 
 .. note::

components/form/introduction.rst

@@ -396,9 +396,9 @@ is created from the form factory.
             ->add('dueDate', 'date')
             ->getForm();
 
-        echo $twig->render('new.html.twig', array(
+        var_dump($twig->render('new.html.twig', array(
             'form' => $form->createView(),
-        ));
+        )));
 
     .. code-block:: php-symfony