From 0f80bb64790db342a4b384f07b0380e5d0be3c8c Mon Sep 17 00:00:00 2001 From: Talita Kocjan Zager Date: Mon, 15 Feb 2016 11:50:18 +0100 Subject: [PATCH 1/2] [best practices] mostly typos --- best_practices/business-logic.rst | 2 +- best_practices/configuration.rst | 4 +--- best_practices/controllers.rst | 4 ++-- best_practices/creating-the-project.rst | 8 +++----- best_practices/forms.rst | 14 +++++++------- best_practices/i18n.rst | 10 +++++----- best_practices/tests.rst | 10 ++++------ 7 files changed, 23 insertions(+), 29 deletions(-) diff --git a/best_practices/business-logic.rst b/best_practices/business-logic.rst index 913d7a69ab1..3f1022a10d1 100644 --- a/best_practices/business-logic.rst +++ b/best_practices/business-logic.rst @@ -193,7 +193,7 @@ The three entities defined by our sample blog application are a good example: Doctrine Mapping Information ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Doctrine Entities are plain PHP objects that you store in some "database". +Doctrine entities are plain PHP objects that you store in some "database". Doctrine only knows about your entities through the mapping metadata configured for your model classes. Doctrine supports four metadata formats: YAML, XML, PHP and annotations. diff --git a/best_practices/configuration.rst b/best_practices/configuration.rst index 7f4d99c204d..76aac62de31 100644 --- a/best_practices/configuration.rst +++ b/best_practices/configuration.rst @@ -107,9 +107,7 @@ 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: - -.. code-block:: php +You could, for example, define a ``NUM_ITEMS`` constant in the ``Post`` entity:: // src/AppBundle/Entity/Post.php namespace AppBundle\Entity; diff --git a/best_practices/controllers.rst b/best_practices/controllers.rst index dc21bc9f767..171e6f38a53 100644 --- a/best_practices/controllers.rst +++ b/best_practices/controllers.rst @@ -80,7 +80,7 @@ The ``@Template`` annotation is useful, but also involves some magic. We don't think its benefit is worth the magic, and so recommend against using it. -Most of the time, ``@Template`` is used without any parameters, which makes +Most of the time, ``@Template()`` is used without any parameters, which makes it more difficult to know which template is being rendered. It also makes it less obvious to beginners that a controller should always return a Response object (unless you're using a view layer). @@ -148,7 +148,7 @@ For example: )); } -Normally, you'd expect a ``$id`` argument to ``showAction``. Instead, by +Normally, you'd expect a ``$id`` argument to ``showAction()``. Instead, by creating a new argument (``$post``) and type-hinting it with the ``Post`` class (which is a Doctrine entity), the ParamConverter automatically queries for an object whose ``$id`` property matches the ``{id}`` value. It will diff --git a/best_practices/creating-the-project.rst b/best_practices/creating-the-project.rst index 7e658fdae59..45dcc987220 100644 --- a/best_practices/creating-the-project.rst +++ b/best_practices/creating-the-project.rst @@ -104,7 +104,7 @@ ProductBundle, then there's no advantage to having two separate bundles. .. best-practice:: - Create only one bundle called AppBundle for your application logic + Create only one bundle called AppBundle for your application logic. Implementing a single AppBundle bundle in your projects will make your code more concise and easier to understand. Starting in Symfony 2.6, the official @@ -179,8 +179,6 @@ The changes are pretty superficial, but for now, we recommend that you use the Symfony directory structure. .. _`Composer`: https://getcomposer.org/ -.. _`Get Started`: https://getcomposer.org/doc/00-intro.md -.. _`Composer download page`: https://getcomposer.org/download/ -.. _`public checksums repository`: https://github.com/sensiolabs/checksums -.. _`these steps`: http://fabien.potencier.org/signing-project-releases.html .. _`Phar extension`: http://php.net/manual/en/intro.phar.php +.. _`public checksums repository`: https://github.com/sensiolabs/checksums +.. _`these steps`: http://fabien.potencier.org/signing-project-releases.html \ No newline at end of file diff --git a/best_practices/forms.rst b/best_practices/forms.rst index 43e8c49fa00..a790437854b 100644 --- a/best_practices/forms.rst +++ b/best_practices/forms.rst @@ -54,7 +54,7 @@ form in its own PHP class:: Put the form type classes in the ``AppBundle\Form`` namespace, unless you use other custom form classes like data transformers. -To use the class, use ``createForm`` and instantiate the new class:: +To use the class, use ``createForm()`` and instantiate the new class:: // ... use AppBundle\Form\PostType; @@ -160,8 +160,8 @@ thing in one line to rendering each part of each field independently. The best way depends on how much customization you need. One of the simplest ways - which is especially useful during development - -is to render the form tags and use ``form_widget()`` to render all of the -fields: +is to render the form tags and use Twig ``form_widget()`` function to render +all of the fields: .. code-block:: html+twig @@ -171,7 +171,7 @@ fields: If you need more control over how your fields are rendered, then you should remove the ``form_widget(form)`` function and render your fields individually. -See the :doc:`/cookbook/form/form_customization` article for more information +See the :doc:`/cookbook/form/form_customization` cookbook article for more information on this and how you can control *how* the form renders at a global level using form theming. @@ -204,9 +204,9 @@ Handling a form submit usually follows a similar template: There are really only two notable things here. First, we recommend that you use a single action for both rendering the form and handling the form submit. -For example, you *could* have a ``newAction`` that *only* renders the form -and a ``createAction`` that *only* processes the form submit. Both those -actions will be almost identical. So it's much simpler to let ``newAction`` +For example, you *could* have a ``newAction()`` that *only* renders the form +and a ``createAction()`` that *only* processes the form submit. Both those +actions will be almost identical. So it's much simpler to let ``newAction()`` handle everything. Second, we recommend using ``$form->isSubmitted()`` in the ``if`` statement diff --git a/best_practices/i18n.rst b/best_practices/i18n.rst index 6d87c608344..27275b2630d 100644 --- a/best_practices/i18n.rst +++ b/best_practices/i18n.rst @@ -47,13 +47,13 @@ Translation Source File Location .. best-practice:: - Store the translation files in the ``app/Resources/translations/`` directory. + Store the translation files in the ``app/Resources/translations/`` + directory. Traditionally, Symfony developers have created these files in the -``Resources/translations/`` directory of each bundle. - -But since the ``app/Resources/`` directory is considered the global location -for the application's resources, storing translations in ``app/Resources/translations/`` +``Resources/translations/`` directory of each bundle. But since the +``app/Resources/`` directory is considered the global location for the +application's resources, storing translations in ``app/Resources/translations/`` centralizes them *and* gives them priority over any other translation file. This lets you override translations defined in third-party bundles. diff --git a/best_practices/tests.rst b/best_practices/tests.rst index 0fc3602bf41..1f41afb9de7 100644 --- a/best_practices/tests.rst +++ b/best_practices/tests.rst @@ -26,9 +26,7 @@ functional tests, you can quickly spot any big errors before you deploy them: Define a functional test that at least checks if your application pages are successfully loading. -A functional test can be as easy as this: - -.. code-block:: php +A functional test can be as easy as this:: // src/AppBundle/Tests/ApplicationAvailabilityFunctionalTest.php namespace AppBundle\Tests; @@ -116,10 +114,10 @@ Learn More about Functional Tests Consider using the `HautelookAliceBundle`_ to generate real-looking data for your test fixtures using `Faker`_ and `Alice`_. -.. _`Faker`: https://github.com/fzaninotto/Faker -.. _`Alice`: https://github.com/nelmio/alice .. _`PhpUnit`: https://phpunit.de/ .. _`PhpSpec`: http://www.phpspec.net/ -.. _`Mink`: http://mink.behat.org .. _`smoke testing`: https://en.wikipedia.org/wiki/Smoke_testing_(software) +.. _`Mink`: http://mink.behat.org .. _`HautelookAliceBundle`: https://github.com/hautelook/AliceBundle +.. _`Faker`: https://github.com/fzaninotto/Faker +.. _`Alice`: https://github.com/nelmio/alice From fe2e1eddb808532e447c3d73cb3198f115147c61 Mon Sep 17 00:00:00 2001 From: Talita Kocjan Zager Date: Fri, 11 Mar 2016 20:29:35 +0100 Subject: [PATCH 2/2] changes according to comments after pull request --- best_practices/controllers.rst | 4 ++-- best_practices/forms.rst | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/best_practices/controllers.rst b/best_practices/controllers.rst index 171e6f38a53..5c024786621 100644 --- a/best_practices/controllers.rst +++ b/best_practices/controllers.rst @@ -73,14 +73,14 @@ Template Configuration .. best-practice:: - Don't use the ``@Template()`` annotation to configure the template used by + Don't use the ``@Template`` annotation to configure the template used by the controller. The ``@Template`` annotation is useful, but also involves some magic. We don't think its benefit is worth the magic, and so recommend against using it. -Most of the time, ``@Template()`` is used without any parameters, which makes +Most of the time, ``@Template`` is used without any parameters, which makes it more difficult to know which template is being rendered. It also makes it less obvious to beginners that a controller should always return a Response object (unless you're using a view layer). diff --git a/best_practices/forms.rst b/best_practices/forms.rst index a790437854b..17e5f954fb2 100644 --- a/best_practices/forms.rst +++ b/best_practices/forms.rst @@ -160,7 +160,7 @@ thing in one line to rendering each part of each field independently. The best way depends on how much customization you need. One of the simplest ways - which is especially useful during development - -is to render the form tags and use Twig ``form_widget()`` function to render +is to render the form tags and use ``form_widget()`` function to render all of the fields: .. code-block:: html+twig