From 4317e2ac62e040499773b9e4fda8477290943462 Mon Sep 17 00:00:00 2001 From: Ryan Weaver Date: Tue, 15 Jan 2013 08:29:57 -0500 Subject: [PATCH 01/16] Documenting how we should use the versionadded tag - see https://groups.google.com/forum/#!msg/symfony-devs/-6HAQgAB2LY/uBSx8uYJQdQJ --- contributing/documentation/overview.rst | 30 +++++++++++++++++++++++++ 1 file changed, 30 insertions(+) diff --git a/contributing/documentation/overview.rst b/contributing/documentation/overview.rst index 87dd52c82f9..ccc327a9825 100644 --- a/contributing/documentation/overview.rst +++ b/contributing/documentation/overview.rst @@ -78,6 +78,36 @@ GitHub covers the topic of `pull requests`_ in detail. by going to the `Documentation Build Errors`_ page (it is updated each French night at 3AM when the server rebuilds the documentation). +Documenting new Features or Behavior Changes +-------------------------------------------- + +If you're documenting a brand new feature or a change that's been made in +Symfony2, you should precede your description of the change with a ``.. versionadded:: 2.X`` +tag and a short description: + +.. code-block:: text + + .. versionadded:: 2.2 + The ``askHiddenResponse`` method was added in Symfony 2.2. + + You can also ask a question and hide the response. This is particularly... + +If you're documenting a behavior change, it may be helpful to *briefly* describe +how the behavior has changed. + +.. code-block:: text + + .. versionadded:: 2.2 + The ``include()`` function is a new Twig feature that's available in + Symfony 2.2. Prior, the ``{% include %}`` tag was used. + +Whenever a new version of minor of Symfony2 is released (e.g. 2.3, 2.4, etc), +a new branch of the documentation is created from the ``master`` branch. +At this point, all the ``versionadded`` tags for Symfony2 versions that have +reached end-of-life will be removed. For example, if Symfony 2.5 were released +today, and 2.2 had recently reached its end-of-life, the 2.2 ``versionadded`` +tags would be removed from the new 2.5 branch. + Standards --------- From 163f6d5be04cb20625ec1717eb0cc0f496aabc8d Mon Sep 17 00:00:00 2001 From: Tyler King Date: Tue, 15 Jan 2013 10:50:19 -0330 Subject: [PATCH 02/16] askAndConfirm should return user's input to properly work. --- components/console/helpers/dialoghelper.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/components/console/helpers/dialoghelper.rst b/components/console/helpers/dialoghelper.rst index 7ce549899c6..e681fda9aac 100644 --- 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 validatation was successfull. 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 From 7bfff13b36471fd4272b9a45c99bd7a6c23a9234 Mon Sep 17 00:00:00 2001 From: Tyler King Date: Tue, 15 Jan 2013 14:13:55 -0330 Subject: [PATCH 03/16] Fixed typos --- components/console/helpers/dialoghelper.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/components/console/helpers/dialoghelper.rst b/components/console/helpers/dialoghelper.rst index e681fda9aac..70a0bcd60d1 100644 --- a/components/console/helpers/dialoghelper.rst +++ b/components/console/helpers/dialoghelper.rst @@ -91,7 +91,7 @@ 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. The callback -function should also return the value of the user's input if the validatation was successfull. +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 From c9b1cb4cfc8e0a4eb8670d95cf1e4223e843bca1 Mon Sep 17 00:00:00 2001 From: WouterJ Date: Sat, 19 Jan 2013 10:46:09 +0100 Subject: [PATCH 04/16] [#1382] Fixed jQuery bug --- cookbook/form/form_collections.rst | 13 ++++++++++--- 1 file changed, 10 insertions(+), 3 deletions(-) diff --git a/cookbook/form/form_collections.rst b/cookbook/form/form_collections.rst index 9c8654e58c9..803cb431e3a 100755 --- a/cookbook/form/form_collections.rst +++ b/cookbook/form/form_collections.rst @@ -369,6 +369,10 @@ will be show next): // add the "add a tag" anchor and li to the tags ul collectionHolder.append($newLinkLi); + // count the current form inputs we have (e.g. 2), use that as the new + // index when inserting a new item (e.g. 2) + collectionHolder.data('index', collectionHolder.find(':input').length); + $addTagLink.on('click', function(e) { // prevent the link from creating a "#" on the URL e.preventDefault(); @@ -393,12 +397,15 @@ one example: // Get the data-prototype explained earlier var prototype = collectionHolder.attr('data-prototype'); - // count the current form inputs we have (e.g. 2), use that as the new index (e.g. 2) - var newIndex = collectionHolder.find(':input').length; + // get the new index + var index = collectionHolder.data('index'); // Replace '$$name$$' in the prototype's HTML to // instead be a number based on how many items we have - var newForm = prototype.replace(/\$\$name\$\$/g, newIndex); + var newForm = prototype.replace(/\$\$name\$\$/g, index); + + // increase the index with one for the next item + collectionHolder.attr('index', index + 1); // Display the form in the page in an li, before the "Add a tag" link li var $newFormLi = $('
  • ').append(newForm); From 8697bbc09d3569e409f93ff79cd75be4bdda6694 Mon Sep 17 00:00:00 2001 From: WouterJ Date: Sat, 19 Jan 2013 10:47:08 +0100 Subject: [PATCH 05/16] Improved jQuery code --- cookbook/form/form_collections.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/cookbook/form/form_collections.rst b/cookbook/form/form_collections.rst index 803cb431e3a..ea71372beb4 100755 --- a/cookbook/form/form_collections.rst +++ b/cookbook/form/form_collections.rst @@ -395,7 +395,7 @@ one example: function addTagForm(collectionHolder, $newLinkLi) { // Get the data-prototype explained earlier - var prototype = collectionHolder.attr('data-prototype'); + var prototype = collectionHolder.data('prototype'); // get the new index var index = collectionHolder.data('index'); From f3f7068fd227b1ed97644dc71549de9f54daa8ae Mon Sep 17 00:00:00 2001 From: WouterJ Date: Sat, 19 Jan 2013 10:47:29 +0100 Subject: [PATCH 06/16] Fixed sphinx syntax --- cookbook/form/form_collections.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/cookbook/form/form_collections.rst b/cookbook/form/form_collections.rst index ea71372beb4..4d7e2b253b1 100755 --- a/cookbook/form/form_collections.rst +++ b/cookbook/form/form_collections.rst @@ -412,7 +412,7 @@ one example: $newLinkLi.before($newFormLi); } -.. note: +.. note:: It is better to separate your javascript in real JavaScript files than to write it inside the HTML as is done here. From ee6739d56602f1ec84bb63e35c3bce940dd6b259 Mon Sep 17 00:00:00 2001 From: WouterJ Date: Sun, 20 Jan 2013 17:50:20 +0100 Subject: [PATCH 07/16] Fixed code, thanks to @stof --- cookbook/form/form_collections.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/cookbook/form/form_collections.rst b/cookbook/form/form_collections.rst index 4d7e2b253b1..87b524e240a 100755 --- a/cookbook/form/form_collections.rst +++ b/cookbook/form/form_collections.rst @@ -405,7 +405,7 @@ one example: var newForm = prototype.replace(/\$\$name\$\$/g, index); // increase the index with one for the next item - collectionHolder.attr('index', index + 1); + collectionHolder.data('index', index + 1); // Display the form in the page in an li, before the "Add a tag" link li var $newFormLi = $('
  • ').append(newForm); From b723781f6429871adc450cc31fcc3be84ff0c6b0 Mon Sep 17 00:00:00 2001 From: Richard Miller Date: Sun, 20 Jan 2013 19:54:43 +0000 Subject: [PATCH 08/16] Moving registering extension above loading config in DI code sample --- components/dependency_injection/compilation.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/components/dependency_injection/compilation.rst b/components/dependency_injection/compilation.rst index c136a4149ba..934dfce0668 100644 --- a/components/dependency_injection/compilation.rst +++ b/components/dependency_injection/compilation.rst @@ -112,10 +112,11 @@ 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(); @@ -213,7 +214,7 @@ benefit of merging multiple files and validation of the configuration:: $processor = new Processor(); $config = $processor->processConfiguration($configuration, $configs); - $container->setParameter('acme_demo.FOO', $config['foo']); + $container->setParameter('acme_demo.FOO', $config['foo']) // ... } From 6e651711d178083769effa14ffd6abf8e4f920f7 Mon Sep 17 00:00:00 2001 From: Richard Miller Date: Sun, 20 Jan 2013 20:14:13 +0000 Subject: [PATCH 09/16] Adding a note about finding more examples of working with DI definitions --- components/dependency_injection/definitions.rst | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/components/dependency_injection/definitions.rst b/components/dependency_injection/definitions.rst index af551df6a34..c2c77a20701 100644 --- 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` From e4b9f1723c0074c401d1a9caa0f33927d0120dda Mon Sep 17 00:00:00 2001 From: Richard Miller Date: Sun, 20 Jan 2013 20:35:12 +0000 Subject: [PATCH 10/16] Re-adding deleted semicolon --- components/dependency_injection/compilation.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/components/dependency_injection/compilation.rst b/components/dependency_injection/compilation.rst index 934dfce0668..c6e8b8f6b43 100644 --- a/components/dependency_injection/compilation.rst +++ b/components/dependency_injection/compilation.rst @@ -214,7 +214,7 @@ benefit of merging multiple files and validation of the configuration:: $processor = new Processor(); $config = $processor->processConfiguration($configuration, $configs); - $container->setParameter('acme_demo.FOO', $config['foo']) + $container->setParameter('acme_demo.FOO', $config['foo']); // ... } From 3f27c9482632655641f3811dfe8e60c7c513eada Mon Sep 17 00:00:00 2001 From: Ryan Weaver Date: Sun, 20 Jan 2013 14:56:43 -0600 Subject: [PATCH 11/16] [#961] Clarifying what the DomDocument component is intended to do / not do - thanks to @jakzal --- components/dom_crawler.rst | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/components/dom_crawler.rst b/components/dom_crawler.rst index 843f5709db1..eed48ceed45 100644 --- a/components/dom_crawler.rst +++ b/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 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); +.. note:: + + 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 ~~~~~~~~~~~~~~~~~~~~~ From 2e8bb8b1f90912dcd564c83648fdd8e2443ab6e9 Mon Sep 17 00:00:00 2001 From: Ryan Weaver Date: Sun, 20 Jan 2013 15:15:47 -0600 Subject: [PATCH 12/16] [#2162] Fixing typo --- components/dependency_injection/definitions.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/components/dependency_injection/definitions.rst b/components/dependency_injection/definitions.rst index c2c77a20701..d8acaac9002 100644 --- a/components/dependency_injection/definitions.rst +++ b/components/dependency_injection/definitions.rst @@ -136,4 +136,4 @@ You can also replace any existing method calls with an array of new ones with:: 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` + :doc:`/components/dependency_injection/parentservices`. From 893199cc4887de49b3190f4bb5a87b667632c2e8 Mon Sep 17 00:00:00 2001 From: Ryan Weaver Date: Sun, 20 Jan 2013 15:31:52 -0600 Subject: [PATCH 13/16] Adding a link to the Doctrine chapter per a comment from @rpmsk --- book/from_flat_php_to_symfony2.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/from_flat_php_to_symfony2.rst b/book/from_flat_php_to_symfony2.rst index 7a5c21c40dd..508327a5acf 100644 --- a/book/from_flat_php_to_symfony2.rst +++ b/book/from_flat_php_to_symfony2.rst @@ -580,7 +580,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` 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: From fbb6196a96fdd05f898782a5c3a5100c74846483 Mon Sep 17 00:00:00 2001 From: Ryan Weaver Date: Sun, 20 Jan 2013 15:42:05 -0600 Subject: [PATCH 14/16] [#961] Tweaks per @WouterJ and @jakzal --- components/dom_crawler.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/components/dom_crawler.rst b/components/dom_crawler.rst index eed48ceed45..517a3dbb98b 100644 --- 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 From a3043dbd55fa70d4610419961d782db84d4d7b85 Mon Sep 17 00:00:00 2001 From: Ryan Weaver Date: Sun, 20 Jan 2013 15:53:11 -0600 Subject: [PATCH 15/16] [#2138] Typo fix per @Stof --- contributing/documentation/overview.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/contributing/documentation/overview.rst b/contributing/documentation/overview.rst index 309f6ae8de2..9427f751b9f 100644 --- a/contributing/documentation/overview.rst +++ b/contributing/documentation/overview.rst @@ -133,7 +133,7 @@ how the behavior has changed. The ``include()`` function is a new Twig feature that's available in Symfony 2.2. Prior, the ``{% include %}`` tag was used. -Whenever a new version of minor of Symfony2 is released (e.g. 2.3, 2.4, etc), +Whenever a new minor version of Symfony2 is released (e.g. 2.3, 2.4, etc), a new branch of the documentation is created from the ``master`` branch. At this point, all the ``versionadded`` tags for Symfony2 versions that have reached end-of-life will be removed. For example, if Symfony 2.5 were released From 8c53a12e1cabcd7fa34dd03c22e712476b504cd6 Mon Sep 17 00:00:00 2001 From: Vladimir Schmidt Date: Mon, 21 Jan 2013 23:19:39 +0100 Subject: [PATCH 16/16] Update book/security.rst [fix] about security/firewalls/{id}/context in pitfalls --- book/security.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/book/security.rst b/book/security.rst index 8d4c7d57c55..00a77de238d 100644 --- a/book/security.rst +++ b/book/security.rst @@ -655,7 +655,8 @@ see :doc:`/cookbook/security/form_login`. If you're using multiple firewalls and you authenticate against one firewall, you will *not* be authenticated against any other firewalls automatically. - Different firewalls are like different security systems. That's why, + Different firewalls are like different security systems. To do this you have + to explicitly specify the same context for different firewalls. But usually for most applications, having one main firewall is enough. Authorization