diff --git a/best_practices/business-logic.rst b/best_practices/business-logic.rst index 417f57c004a..8feb8163bf7 100644 --- a/best_practices/business-logic.rst +++ b/best_practices/business-logic.rst @@ -57,8 +57,8 @@ post URL. Let's create a new ``Slugger`` class inside ``src/Utils/``:: } If you're using the :ref:`default services.yaml configuration `, -this class is auto-registered as a service whose ID is ``App\Utils\Slugger`` (or -simply ``Slugger::class`` if the class is already imported in your code). +this class is auto-registered as a service with the ID ``App\Utils\Slugger`` (to +prevent against typos, import the class and write ``Slugger::class`` in your code). .. best-practice:: diff --git a/bundles/configuration.rst b/bundles/configuration.rst index 7d44e07f315..37198e33689 100644 --- a/bundles/configuration.rst +++ b/bundles/configuration.rst @@ -48,8 +48,8 @@ Using the Bundle Extension -------------------------- Imagine you are creating a new bundle - AcmeSocialBundle - which provides -integration with Twitter, etc. To make your bundle easy to use, you want to -allow users to configure it with some configuration that looks like this: +integration with Twitter. To make your bundle configurable to the user, you +can add some configuration that looks like this: .. configuration-block:: diff --git a/components/dom_crawler.rst b/components/dom_crawler.rst index 46e75662eda..e0f573c5393 100644 --- a/components/dom_crawler.rst +++ b/components/dom_crawler.rst @@ -36,7 +36,7 @@ The :class:`Symfony\\Component\\DomCrawler\\Crawler` class provides methods to query and manipulate HTML and XML documents. An instance of the Crawler represents a set of :phpclass:`DOMElement` objects, -which are basically nodes that you can traverse easily:: +which are basically nodes that you can traverse:: use Symfony\Component\DomCrawler\Crawler; diff --git a/components/expression_language/extending.rst b/components/expression_language/extending.rst index 9f055d84156..7d1d758f855 100644 --- a/components/expression_language/extending.rst +++ b/components/expression_language/extending.rst @@ -127,7 +127,7 @@ or by using the second argument of the constructor:: { public function __construct(CacheItemPoolInterface $parser = null, array $providers = []) { - // prepends the default provider to let users override it easily + // prepends the default provider to let users override it array_unshift($providers, new StringExpressionLanguageProvider()); parent::__construct($parser, $providers); diff --git a/components/http_foundation/sessions.rst b/components/http_foundation/sessions.rst index e15d44411f6..fef88d6a10f 100644 --- a/components/http_foundation/sessions.rst +++ b/components/http_foundation/sessions.rst @@ -226,8 +226,7 @@ store it again:: ], ]; -So any processing of this might quickly get ugly, even simply adding a token to -the array:: +So any processing of this might quickly get ugly, even adding a token to the array:: $tokens = $session->get('tokens'); $tokens['c'] = $value; diff --git a/components/http_kernel.rst b/components/http_kernel.rst index ba21ae6f7b9..54eb6ab70af 100644 --- a/components/http_kernel.rst +++ b/components/http_kernel.rst @@ -47,12 +47,12 @@ This is a simplified overview of the request workflow in Symfony applications: #. The **browser** displays the **resource** to the **user**. Typically, some sort of framework or system is built to handle all the repetitive -tasks (e.g. routing, security, etc) so that a developer can easily build -each *page* of the application. Exactly *how* these systems are built varies -greatly. The HttpKernel component provides an interface that formalizes -the process of starting with a request and creating the appropriate response. -The component is meant to be the heart of any application or framework, no -matter how varied the architecture of that system:: +tasks (e.g. routing, security, etc) so that a developer can build each *page* of +the application. Exactly *how* these systems are built varies greatly. The HttpKernel +component provides an interface that formalizes the process of starting with a +request and creating the appropriate response. The component is meant to be the +heart of any application or framework, no matter how varied the architecture of +that system:: namespace Symfony\Component\HttpKernel; diff --git a/components/options_resolver.rst b/components/options_resolver.rst index c0059e05260..4b2526872d6 100644 --- a/components/options_resolver.rst +++ b/components/options_resolver.rst @@ -522,8 +522,8 @@ Options without Default Values In some cases, it is useful to define an option without setting a default value. This is useful if you need to know whether or not the user *actually* set an option or not. For example, if you set the default value for an option, -it's not possible to know whether the user passed this value or if it simply -comes from the default:: +it's not possible to know whether the user passed this value or if it comes +from the default:: // ... class Mailer diff --git a/components/yaml/yaml_format.rst b/components/yaml/yaml_format.rst index 78802213765..0ccb6f41a80 100644 --- a/components/yaml/yaml_format.rst +++ b/components/yaml/yaml_format.rst @@ -286,8 +286,8 @@ Comments can be added in YAML by prefixing them with a hash mark (``#``): .. note:: - Comments are simply ignored by the YAML parser and do not need to be - indented according to the current level of nesting in a collection. + Comments are ignored by the YAML parser and do not need to be indented + according to the current level of nesting in a collection. Explicit Typing --------------- diff --git a/configuration/environments.rst b/configuration/environments.rst index b579e1a04dd..9da57097f62 100644 --- a/configuration/environments.rst +++ b/configuration/environments.rst @@ -8,10 +8,10 @@ Every application is the combination of code and a set of configuration that dictates how that code should function. The configuration may define the database being used, if something should be cached or how verbose logging should be. -In Symfony, the idea of "environments" is the idea that the same codebase can be -run using multiple different configurations. For example, the ``dev`` environment -should use configuration that makes development easy and friendly, while the -``prod`` environment should use a set of configuration optimized for speed. +In Symfony, the idea of "environments" is that the same codebase can be run using +multiple different configurations. For example, the ``dev`` environment should use +configuration that makes development comfortable and friendly, while the ``prod`` +environment should use a set of configuration optimized for speed and security. .. index:: single: Environments; Configuration files diff --git a/contributing/code/bc.rst b/contributing/code/bc.rst index dbfe6b0e52c..bbe224497bf 100644 --- a/contributing/code/bc.rst +++ b/contributing/code/bc.rst @@ -22,7 +22,7 @@ method signature. Also, not every BC break has the same impact on application code. While some BC breaks require you to make significant changes to your classes or your -architecture, others are fixed as easily as changing the name of a method. +architecture, others are fixed by changing the name of a method. That's why we created this page for you. The section "Using Symfony Code" will tell you how you can ensure that your application won't break completely when diff --git a/contributing/code/conventions.rst b/contributing/code/conventions.rst index b90cbb565da..4fc64d07f34 100644 --- a/contributing/code/conventions.rst +++ b/contributing/code/conventions.rst @@ -85,8 +85,7 @@ Deprecations From time to time, some classes and/or methods are deprecated in the framework; that happens when a feature implementation cannot be changed because of backward compatibility issues, but we still want to propose a -"better" alternative. In that case, the old implementation can simply be -**deprecated**. +"better" alternative. In that case, the old implementation can be **deprecated**. A feature is marked as deprecated by adding a ``@deprecated`` phpdoc to relevant classes, methods, properties, ...:: diff --git a/contributing/code/experimental.rst b/contributing/code/experimental.rst index 9081cf5184c..998f112ba7b 100644 --- a/contributing/code/experimental.rst +++ b/contributing/code/experimental.rst @@ -5,8 +5,8 @@ All Symfony features benefit from our :doc:`Backward Compatibility Promise ` to give developers the confidence to upgrade to new versions safely and more often. -But sometimes, a new feature is controversial. Or finding a good API is not -easy. In such cases, we prefer to gather feedback from real-world usage, adapt +But sometimes, a new feature is controversial or you cannot find a convincing API. +In such cases, we prefer to gather feedback from real-world usage, adapt the API, or remove it altogether. Doing so is not possible with a no BC-break approach. diff --git a/controller.rst b/controller.rst index 8184f60e039..317d4108ed2 100644 --- a/controller.rst +++ b/controller.rst @@ -7,8 +7,8 @@ Controller A controller is a PHP function you create that reads information from the ``Request`` object and creates and returns a ``Response`` object. The response could be an HTML page, JSON, XML, a file download, a redirect, a 404 error or anything -else you can dream up. The controller executes whatever arbitrary logic -*your application* needs to render the content of a page. +else. The controller executes whatever arbitrary logic *your application* needs +to render the content of a page. .. tip:: diff --git a/doctrine/associations.rst b/doctrine/associations.rst index 24bad95a950..f872596cb8c 100644 --- a/doctrine/associations.rst +++ b/doctrine/associations.rst @@ -398,7 +398,7 @@ you. .. image:: /_images/doctrine/mapping_relations_proxy.png :align: center -What's important is the fact that you have easy access to the product's related +What's important is the fact that you have access to the product's related category, but the category data isn't actually retrieved until you ask for the category (i.e. it's "lazily loaded"). diff --git a/doctrine/dbal.rst b/doctrine/dbal.rst index 3d8ea18a627..aae00f9c2ee 100644 --- a/doctrine/dbal.rst +++ b/doctrine/dbal.rst @@ -13,8 +13,9 @@ How to Use Doctrine DBAL The `Doctrine`_ Database Abstraction Layer (DBAL) is an abstraction layer that sits on top of `PDO`_ and offers an intuitive and flexible API for communicating -with the most popular relational databases. In other words, the DBAL library -makes it easy to execute queries and perform other database actions. +with the most popular relational databases. The DBAL library allows you to write +queries independently of your ORM models, e.g. for building reports or direct +data manipulations. .. tip:: diff --git a/email.rst b/email.rst index f588eee0993..e1946dfa0fb 100644 --- a/email.rst +++ b/email.rst @@ -122,9 +122,9 @@ setting up a regular SMTP server. To do that, update the ``MAILER_URL`` of your # username is your full Gmail or Google Apps email address MAILER_URL=gmail://username:password@localhost -The ``gmail`` transport is simply a shortcut that uses the ``smtp`` transport, -``ssl`` encryption, ``login`` auth mode and ``smtp.gmail.com`` host. If your app -uses other encryption or auth mode, you must override those values +The ``gmail`` transport is a shortcut that uses the ``smtp`` transport, ``ssl`` +encryption, ``login`` auth mode and ``smtp.gmail.com`` host. If your app uses +other encryption or auth mode, you must override those values (:doc:`see mailer config reference `): .. code-block:: bash diff --git a/http_cache/esi.rst b/http_cache/esi.rst index 8f4a31f770f..c0b7ba36c39 100644 --- a/http_cache/esi.rst +++ b/http_cache/esi.rst @@ -250,6 +250,6 @@ The ``render_esi`` helper supports two other useful options: ``ignore_errors`` If set to true, an ``onerror`` attribute will be added to the ESI with a value of ``continue`` indicating that, in the event of a failure, the gateway cache - will simply remove the ESI tag silently. + will remove the ESI tag silently. .. _`ESI`: http://www.w3.org/TR/esi-lang diff --git a/messenger/handler_results.rst b/messenger/handler_results.rst index 1c541990635..7dede3b0f48 100644 --- a/messenger/handler_results.rst +++ b/messenger/handler_results.rst @@ -36,8 +36,8 @@ buses are central pieces of the application. Read Martin Fowler's As queries are usually synchronous and expected to be handled once, getting the result from the handler is a common need. -To make this easy, you can leverage the ``HandleTrait`` in any class that has -a ``$messageBus`` property:: +To avoid boilerplate code, you can leverage the ``HandleTrait`` in any class +that has a ``$messageBus`` property:: // src/Action/ListItems.php namespace App\Action; diff --git a/security.rst b/security.rst index c040acdcd2c..a6a7a9ab8bf 100644 --- a/security.rst +++ b/security.rst @@ -619,7 +619,7 @@ See :doc:`/security/securing_services`. Checking to see if a User is Logged In (IS_AUTHENTICATED_FULLY) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -If you *only* want to check if a user is simply logged in (you don't care about roles), +If you *only* want to check if a user is logged in (you don't care about roles), you have two options. First, if you've given *every* user ``ROLE_USER``, you can just check for that role. Otherwise, you can use a special "attribute" in place of a role:: diff --git a/security/guard_authentication.rst b/security/guard_authentication.rst index 4fd9a3840fc..ec9aaad4669 100644 --- a/security/guard_authentication.rst +++ b/security/guard_authentication.rst @@ -6,7 +6,7 @@ Custom Authentication System with Guard (API Token Example) Whether you need to build a traditional login form, an API token authentication system or you need to integrate with some proprietary single-sign-on system, the Guard -component can make it easy... and fun! +component will be the right choice! Guard authentication can be used to: @@ -14,7 +14,7 @@ Guard authentication can be used to: * Create an API token authentication system (done on this page!) * `Social Authentication`_ (or use `HWIOAuthBundle`_ for a robust, but non-Guard solution) -or anything else you dream up. In this example, we'll build an API token authentication +or anything else. In this example, we'll build an API token authentication system so we can learn more about Guard in detail. Step 1) Prepare your User Class diff --git a/service_container/service_subscribers_locators.rst b/service_container/service_subscribers_locators.rst index 5c00b0a82c3..7503ca5c011 100644 --- a/service_container/service_subscribers_locators.rst +++ b/service_container/service_subscribers_locators.rst @@ -380,8 +380,8 @@ provides an implementation for :class:`Symfony\\Component\\DependencyInjection\\ServiceSubscriberInterface` that looks through all methods in your class that have no arguments and a return type. It provides a ``ServiceLocator`` for the services of those return types. -The service id is ``__METHOD__``. This allows you to easily add dependencies -to your services based on type-hinted helper methods:: +The service id is ``__METHOD__``. This allows you to add dependencies to your +services based on type-hinted helper methods:: // src/Service/MyService.php namespace App\Service; diff --git a/templating.rst b/templating.rst index 71e5f5385d4..6ccb6447716 100644 --- a/templating.rst +++ b/templating.rst @@ -23,7 +23,7 @@ code. Templates --------- -A template is simply a text file that can generate any text-based format +A template is a text file that can generate any text-based format (HTML, XML, CSV, LaTeX ...). The most familiar type of template is a *PHP* template - a text file parsed by PHP that contains a mix of text and PHP code: @@ -386,10 +386,9 @@ the last part of the extension (e.g. ``.twig`` or ``.php``) specifies which of these two *engines* should be used. The first part of the extension, (e.g. ``.html``, ``.css``, etc) is the final format that the template will generate. Unlike the engine, which determines how Symfony parses the template, -this is simply an organizational tactic used in case the same resource needs -to be rendered as HTML (``index.html.twig``), XML (``index.xml.twig``), -or any other format. For more information, read the :doc:`/templating/formats` -section. +this is an organizational tactic used in case the same resource needs to be +rendered as HTML (``index.html.twig``), XML (``index.xml.twig``), or any other +format. For more information, read the :doc:`/templating/formats` section. .. index:: single: Templating; Tags and helpers diff --git a/templating/PHP.rst b/templating/PHP.rst index 6e89a46964b..a044564d862 100644 --- a/templating/PHP.rst +++ b/templating/PHP.rst @@ -66,9 +66,9 @@ Next, enable the php engine: ], ]); -You can now render a PHP template instead of a Twig one simply by using the -``.php`` extension in the template name instead of ``.twig``. The controller -below renders the ``index.html.php`` template:: +You can now render a PHP template instead of a Twig one by using the ``.php`` +extension in the template name instead of ``.twig``. The controller below +renders the ``index.html.php`` template:: // src/Controller/HelloController.php diff --git a/templating/formats.rst b/templating/formats.rst index 70ba2f72aa2..608f3e9e849 100644 --- a/templating/formats.rst +++ b/templating/formats.rst @@ -6,7 +6,7 @@ How to Work with Different Output Formats in Templates Templates are a generic way to render content in *any* format. While in most cases you'll use templates to render HTML content, a template can just -as easily generate JavaScript, CSS, XML or any other format you can dream of. +generate JavaScript, CSS, XML or any other format. For example, the same "resource" is often rendered in several formats. To render an article index page in XML, include the format in the diff --git a/templating/inheritance.rst b/templating/inheritance.rst index 10c48a00424..3394a4de234 100644 --- a/templating/inheritance.rst +++ b/templating/inheritance.rst @@ -47,9 +47,8 @@ Notice that this template extends the section template (``blog/layout.html.twig` which in turn extends the base application layout (``base.html.twig``). This is the common three-level inheritance model. -When building your application, you may choose to follow this method or simply +When building your application, you may choose to follow this method or make each page template extend the base application template directly (e.g. ``{% extends 'base.html.twig' %}``). The three-template model is a best-practice method used by vendor bundles so that the base template for a -bundle can be easily overridden to properly extend your application's base -layout. +bundle can be overridden to properly extend your application's base layout. diff --git a/templating/render_without_controller.rst b/templating/render_without_controller.rst index 16a1a4f4462..820611a82e4 100644 --- a/templating/render_without_controller.rst +++ b/templating/render_without_controller.rst @@ -54,8 +54,8 @@ can do this without creating a controller: return $routes; -The ``TemplateController`` will simply render whatever template you've passed as -the ``template`` default value. +The ``TemplateController`` will render whatever template you've passed as the +``template`` default value. You can also use this trick when rendering embedded controllers from within a template. But since the purpose of rendering a controller from diff --git a/testing/database.rst b/testing/database.rst index 0078d04fa7b..98f66389e4c 100644 --- a/testing/database.rst +++ b/testing/database.rst @@ -67,7 +67,7 @@ Suppose the class you want to test looks like this:: } Since the ``EntityManagerInterface`` gets injected into the class through the constructor, -it's easy to pass a mock object within a test:: +you can pass a mock object within a test:: // tests/Salary/SalaryCalculatorTest.php namespace App\Tests\Salary;