Improve naming in documentation

best_practices/configuration.rst

@@ -101,20 +101,20 @@ to control the number of posts to display on the blog homepage:
 
     # app/config/config.yml
     parameters:
-        homepage.num_items: 10
+        homepage.number_of_items: 10
 
 If you've done something like this in the past, it's likely that you've in fact
 *never* actually needed to change that value. Creating a configuration
 option for a value that you are never going to configure just isn't necessary.
 Our recommendation is to define these values as constants in your application.
-You could, for example, define a ``NUM_ITEMS`` constant in the ``Post`` entity::
+You could, for example, define a ``NUMBER_OF_ITEMS`` constant in the ``Post`` entity::
 
     // src/AppBundle/Entity/Post.php
     namespace AppBundle\Entity;
 
     class Post
     {
-        const NUM_ITEMS = 10;
+        const NUMBER_OF_ITEMS = 10;
 
         // ...
     }
@@ -129,7 +129,7 @@ Constants can be used for example in your Twig templates thanks to the
 .. code-block:: html+twig
 
     <p>
-        Displaying the {{ constant('NUM_ITEMS', post) }} most recent results.
+        Displaying the {{ constant('NUMBER_OF_ITEMS', post) }} most recent results.
     </p>
 
 And Doctrine entities and repositories can now easily access these values,
@@ -144,7 +144,7 @@ whereas they cannot access the container parameters:
 
     class PostRepository extends EntityRepository
     {
-        public function findLatest($limit = Post::NUM_ITEMS)
+        public function findLatest($limit = Post::NUMBER_OF_ITEMS)
         {
             // ...
         }

best_practices/forms.rst

@@ -189,9 +189,9 @@ Handling a form submit usually follows a similar template:
         $form->handleRequest($request);
 
         if ($form->isSubmitted() && $form->isValid()) {
-            $em = $this->getDoctrine()->getManager();
-            $em->persist($post);
-            $em->flush();
+            $entityManager = $this->getDoctrine()->getManager();
+            $entityManager->persist($post);
+            $entityManager->flush();
 
             return $this->redirect($this->generateUrl(
                 'admin_post_show',

bundles/configuration.rst

@@ -269,9 +269,9 @@ In your extension, you can load this and dynamically set its arguments::
         $configuration = new Configuration();
         $config = $this->processConfiguration($configuration, $configs);
 
-        $def = $container->getDefinition('acme.social.twitter_client');
-        $def->replaceArgument(0, $config['twitter']['client_id']);
-        $def->replaceArgument(1, $config['twitter']['client_secret']);
+        $definition = $container->getDefinition('acme.social.twitter_client');
+        $definition->replaceArgument(0, $config['twitter']['client_id']);
+        $definition->replaceArgument(1, $config['twitter']['client_secret']);
     }
 
 .. tip::

components/asset.rst

@@ -169,9 +169,9 @@ that path over and over again::
     use Symfony\Component\Asset\PathPackage;
     // ...
 
-    $package = new PathPackage('/static/images', new StaticVersionStrategy('v1'));
+    $pathPackage = new PathPackage('/static/images', new StaticVersionStrategy('v1'));
 
-    echo $package->getUrl('/logo.png');
+    echo $pathPackage->getUrl('/logo.png');
     // result: /static/images/logo.png?v1
 
 Request Context Aware Assets
@@ -185,13 +185,13 @@ class can take into account the context of the current request::
     use Symfony\Component\Asset\Context\RequestStackContext;
     // ...
 
-    $package = new PathPackage(
+    $pathPackage = new PathPackage(
         '/static/images',
         new StaticVersionStrategy('v1'),
         new RequestStackContext($requestStack)
     );
 
-    echo $package->getUrl('/logo.png');
+    echo $pathPackage->getUrl('/logo.png');
     // result: /somewhere/static/images/logo.png?v1
 
 Now that the request context is set, the ``PathPackage`` will prepend the
@@ -212,25 +212,25 @@ class to generate absolute URLs for their assets::
     use Symfony\Component\Asset\UrlPackage;
     // ...
 
-    $package = new UrlPackage(
+    $urlPackage = new UrlPackage(
         'http://static.example.com/images/',
         new StaticVersionStrategy('v1')
     );
 
-    echo $package->getUrl('/logo.png');
+    echo $urlPackage->getUrl('/logo.png');
     // result: http://static.example.com/images/logo.png?v1
 
 You can also pass a schema-agnostic URL::
 
     use Symfony\Component\Asset\UrlPackage;
     // ...
 
-    $package = new UrlPackage(
+    $urlPackage = new UrlPackage(
         '//static.example.com/images/',
         new StaticVersionStrategy('v1')
     );
 
-    echo $package->getUrl('/logo.png');
+    echo $urlPackage->getUrl('/logo.png');
     // result: //static.example.com/images/logo.png?v1
 
 This is useful because assets will automatically be requested via HTTPS if
@@ -248,11 +248,11 @@ constructor::
         '//static1.example.com/images/',
         '//static2.example.com/images/',
     );
-    $package = new UrlPackage($urls, new StaticVersionStrategy('v1'));
+    $urlPackage = new UrlPackage($urls, new StaticVersionStrategy('v1'));
 
-    echo $package->getUrl('/logo.png');
+    echo $urlPackage->getUrl('/logo.png');
     // result: http://static1.example.com/images/logo.png?v1
-    echo $package->getUrl('/icon.png');
+    echo $urlPackage->getUrl('/icon.png');
     // result: http://static2.example.com/images/icon.png?v1
 
 For each asset, one of the URLs will be randomly used. But, the selection
@@ -271,13 +271,13 @@ protocol-relative URLs for HTTPs requests, any base URL for HTTP requests)::
     use Symfony\Component\Asset\Context\RequestStackContext;
     // ...
 
-    $package = new UrlPackage(
+    $urlPackage = new UrlPackage(
         array('http://example.com/', 'https://example.com/'),
         new StaticVersionStrategy('v1'),
         new RequestStackContext($requestStack)
     );
 
-    echo $package->getUrl('/logo.png');
+    echo $urlPackage->getUrl('/logo.png');
     // assuming the RequestStackContext says that we are on a secure host
     // result: https://example.com/logo.png?v1
 

components/browser_kit.rst

@@ -140,8 +140,8 @@ retrieve any cookie while making requests with the client::
     // Get cookie data
     $name       = $cookie->getName();
     $value      = $cookie->getValue();
-    $raw        = $cookie->getRawValue();
-    $secure     = $cookie->isSecure();
+    $rawValue   = $cookie->getRawValue();
+    $isSecure   = $cookie->isSecure();
     $isHttpOnly = $cookie->isHttpOnly();
     $isExpired  = $cookie->isExpired();
     $expires    = $cookie->getExpiresTime();

components/config/definition.rst

@@ -534,8 +534,8 @@ tree with ``append()``::
 
     public function addParametersNode()
     {
-        $builder = new TreeBuilder();
-        $node = $builder->root('parameters');
+        $treeBuilder = new TreeBuilder();
+        $node = $treeBuilder->root('parameters');
 
         $node
             ->isRequired()
@@ -772,18 +772,18 @@ Otherwise the result is a clean array of configuration values::
     use Symfony\Component\Config\Definition\Processor;
     use Acme\DatabaseConfiguration;
 
-    $config1 = Yaml::parse(
+    $config = Yaml::parse(
         file_get_contents(__DIR__.'/src/Matthias/config/config.yml')
     );
-    $config2 = Yaml::parse(
+    $extraConfig = Yaml::parse(
         file_get_contents(__DIR__.'/src/Matthias/config/config_extra.yml')
     );
 
-    $configs = array($config1, $config2);
+    $configs = array($config, $extraConfig);
 
     $processor = new Processor();
-    $configuration = new DatabaseConfiguration();
+    $databaseConfiguration = new DatabaseConfiguration();
     $processedConfiguration = $processor->processConfiguration(
-        $configuration,
+        $databaseConfiguration,
         $configs
     );

components/config/resources.rst

@@ -21,8 +21,8 @@ files. This can be done with the :class:`Symfony\\Component\\Config\\FileLocator
 
     $configDirectories = array(__DIR__.'/app/config');
 
-    $locator = new FileLocator($configDirectories);
-    $yamlUserFiles = $locator->locate('users.yml', null, false);
+    $fileLocator = new FileLocator($configDirectories);
+    $yamlUserFiles = $fileLocator->locate('users.yml', null, false);
 
 The locator receives a collection of locations where it should look for
 files. The first argument of ``locate()`` is the name of the file to look
@@ -84,7 +84,7 @@ the resource::
     use Symfony\Component\Config\Loader\LoaderResolver;
     use Symfony\Component\Config\Loader\DelegatingLoader;
 
-    $loaderResolver = new LoaderResolver(array(new YamlUserLoader($locator)));
+    $loaderResolver = new LoaderResolver(array(new YamlUserLoader($fileLocator)));
     $delegatingLoader = new DelegatingLoader($loaderResolver);
 
     $delegatingLoader->load(__DIR__.'/users.yml');

components/console/helpers/dialoghelper.rst

@@ -52,7 +52,7 @@ You can also ask question with more than a simple yes/no answer. For instance,
 if you want to know a bundle name, you can add this to your command::
 
     // ...
-    $bundle = $dialog->ask(
+    $bundleName = $dialog->ask(
         $output,
         'Please enter the name of the bundle',
         'AcmeDemoBundle'
@@ -71,7 +71,7 @@ will be autocompleted as the user types::
 
     $dialog = $this->getHelper('dialog');
     $bundleNames = array('AcmeDemoBundle', 'AcmeBlogBundle', 'AcmeStoreBundle');
-    $name = $dialog->ask(
+    $bundleName = $dialog->ask(
         $output,
         'Please enter the name of a bundle',
         'FooBundle',
@@ -109,7 +109,7 @@ be suffixed with ``Bundle``. You can validate that by using the
 method::
 
     // ...
-    $bundle = $dialog->askAndValidate(
+    $bundleName = $dialog->askAndValidate(
         $output,
         'Please enter the name of the bundle',
         function ($answer) {

components/console/helpers/progressbar.rst

@@ -16,24 +16,24 @@ number of units, and advance the progress as the command executes::
     use Symfony\Component\Console\Helper\ProgressBar;
 
     // creates a new progress bar (50 units)
-    $progress = new ProgressBar($output, 50);
+    $progressBar = new ProgressBar($output, 50);
 
     // starts and displays the progress bar
-    $progress->start();
+    $progressBar->start();
 
     $i = 0;
     while ($i++ < 50) {
         // ... do some work
 
         // advances the progress bar 1 unit
-        $progress->advance();
+        $progressBar->advance();
 
         // you can also advance the progress bar by more than 1 unit
-        // $progress->advance(3);
+        // $progressBar->advance(3);
     }
 
     // ensures that the progress bar is at 100%
-    $progress->finish();
+    $progressBar->finish();
 
 Instead of advancing the bar by a number of steps (with the
 :method:`Symfony\\Component\\Console\\Helper\\ProgressBar::advance` method),
@@ -64,7 +64,7 @@ If you don't know the number of steps in advance, just omit the steps argument
 when creating the :class:`Symfony\\Component\\Console\\Helper\\ProgressBar`
 instance::
 
-    $progress = new ProgressBar($output);
+    $progressBar = new ProgressBar($output);
 
 The progress will then be displayed as a throbber:
 
@@ -131,7 +131,7 @@ level of verbosity of the ``OutputInterface`` instance:
 Instead of relying on the verbosity mode of the current command, you can also
 force a format via ``setFormat()``::
 
-    $bar->setFormat('verbose');
+    $progressBar->setFormat('verbose');
 
 The built-in formats are the following:
 
@@ -153,7 +153,7 @@ Custom Formats
 
 Instead of using the built-in formats, you can also set your own::
 
-    $bar->setFormat('%bar%');
+    $progressBar->setFormat('%bar%');
 
 This sets the format to only display the progress bar itself:
 
@@ -180,7 +180,7 @@ current progress of the bar. Here is a list of the built-in placeholders:
 For instance, here is how you could set the format to be the same as the
 ``debug`` one::
 
-    $bar->setFormat(' %current%/%max% [%bar%] %percent:3s%% %elapsed:6s%/%estimated:-6s% %memory:6s%');
+    $progressBar->setFormat(' %current%/%max% [%bar%] %percent:3s%% %elapsed:6s%/%estimated:-6s% %memory:6s%');
 
 Notice the ``:6s`` part added to some placeholders? That's how you can tweak
 the appearance of the bar (formatting and alignment). The part after the colon
@@ -191,8 +191,8 @@ also define global formats::
 
     ProgressBar::setFormatDefinition('minimal', 'Progress: %percent%%');
 
-    $bar = new ProgressBar($output, 3);
-    $bar->setFormat('minimal');
+    $progressBar = new ProgressBar($output, 3);
+    $progressBar->setFormat('minimal');
 
 This code defines a new ``minimal`` format that you can then use for your
 progress bars:
@@ -216,8 +216,8 @@ variant::
     ProgressBar::setFormatDefinition('minimal', '%percent%% %remaining%');
     ProgressBar::setFormatDefinition('minimal_nomax', '%percent%%');
 
-    $bar = new ProgressBar($output);
-    $bar->setFormat('minimal');
+    $progressBar = new ProgressBar($output);
+    $progressBar->setFormat('minimal');
 
 When displaying the progress bar, the format will automatically be set to
 ``minimal_nomax`` if the bar does not have a maximum number of steps like in
@@ -246,16 +246,16 @@ Amongst the placeholders, ``bar`` is a bit special as all the characters used
 to display it can be customized::
 
     // the finished part of the bar
-    $progress->setBarCharacter('<comment>=</comment>');
+    $progressBar->setBarCharacter('<comment>=</comment>');
 
     // the unfinished part of the bar
-    $progress->setEmptyBarCharacter(' ');
+    $progressBar->setEmptyBarCharacter(' ');
 
     // the progress character
-    $progress->setProgressCharacter('|');
+    $progressBar->setProgressCharacter('|');
 
     // the bar width
-    $progress->setBarWidth(50);
+    $progressBar->setBarWidth(50);
 
 .. caution::
 
@@ -265,17 +265,17 @@ to display it can be customized::
     :method:`Symfony\\Component\\Console\\Helper\\ProgressBar::setRedrawFrequency`,
     so it updates on only some iterations::
 
-        $progress = new ProgressBar($output, 50000);
-        $progress->start();
+        $progressBar = new ProgressBar($output, 50000);
+        $progressBar->start();
 
         // update every 100 iterations
-        $progress->setRedrawFrequency(100);
+        $progressBar->setRedrawFrequency(100);
 
         $i = 0;
         while ($i++ < 50000) {
             // ... do some work
 
-            $progress->advance();
+            $progressBar->advance();
         }
 
 Custom Placeholders
@@ -288,8 +288,8 @@ that displays the number of remaining steps::
 
     ProgressBar::setPlaceholderFormatterDefinition(
         'remaining_steps',
-        function (ProgressBar $bar, OutputInterface $output) {
-            return $bar->getMaxSteps() - $bar->getProgress();
+        function (ProgressBar $progressBar, OutputInterface $output) {
+            return $progressBar->getMaxSteps() - $progressBar->getProgress();
         }
     );