diff --git a/.alexrc b/.alexrc new file mode 100644 index 00000000000..168d412c177 --- /dev/null +++ b/.alexrc @@ -0,0 +1,16 @@ +{ + "allow": [ + "attack", + "attacks", + "bigger", + "color", + "colors", + "failure", + "hook", + "hooks", + "host-hostess", + "invalid", + "remain", + "special" + ] +} diff --git a/bundles.rst b/bundles.rst index 130171e0120..dc087137fee 100644 --- a/bundles.rst +++ b/bundles.rst @@ -45,9 +45,9 @@ Creating a Bundle ----------------- This section creates and enables a new bundle to show there are only a few steps required. -The new bundle is called AcmeTestBundle, where the ``Acme`` portion is just a -dummy name that should be replaced by some "vendor" name that represents you or -your organization (e.g. ABCTestBundle for some company named ``ABC``). +The new bundle is called AcmeTestBundle, where the ``Acme`` portion is a dummy +name that should be replaced by some "vendor" name that represents you or your +organization (e.g. ABCTestBundle for some company named ``ABC``). Start by creating a ``src/Acme/TestBundle/`` directory and adding a new file called ``AcmeTestBundle.php``:: diff --git a/configuration.rst b/configuration.rst index 76ac0df6c3e..180e513e7ad 100644 --- a/configuration.rst +++ b/configuration.rst @@ -351,7 +351,7 @@ a new ``locale`` parameter is added to the ``config/services.yaml`` file). Configuration Environments -------------------------- -You have just one application, but whether you realize it or not, you need it +You have only one application, but whether you realize it or not, you need it to behave differently at different times: * While **developing**, you want to log everything and expose nice debugging tools; diff --git a/configuration/dot-env-changes.rst b/configuration/dot-env-changes.rst index 9c9c9df2e81..89844d991b1 100644 --- a/configuration/dot-env-changes.rst +++ b/configuration/dot-env-changes.rst @@ -20,8 +20,8 @@ important changes: * B) The ``.env`` file **is** now committed to your repository. It was previously ignored via the ``.gitignore`` file (the updated recipe does not ignore this file). Because - this file is committed, it should contain non-sensitive, default values. Basically, - the ``.env.dist`` file was moved to ``.env``. + this file is committed, it should contain non-sensitive, default values. The + ``.env`` can be seen as the previous ``.env.dist`` file. * C) A ``.env.local`` file can now be created to *override* values in ``.env`` for your machine. This file is ignored in the new ``.gitignore``. diff --git a/configuration/front_controllers_and_kernel.rst b/configuration/front_controllers_and_kernel.rst index ba702cbdc49..090abb86e55 100644 --- a/configuration/front_controllers_and_kernel.rst +++ b/configuration/front_controllers_and_kernel.rst @@ -30,7 +30,7 @@ The `front controller`_ is a design pattern; it is a section of code that *all* requests served by an application run through. In the Symfony Skeleton, this role is taken by the ``index.php`` file in the -``public/`` directory. This is the very first PHP script executed when a +``public/`` directory. This is the very first PHP script that is run when a request is processed. The main purpose of the front controller is to create an instance of the diff --git a/configuration/micro_kernel_trait.rst b/configuration/micro_kernel_trait.rst index 84d8da1f028..890f60d1ca8 100644 --- a/configuration/micro_kernel_trait.rst +++ b/configuration/micro_kernel_trait.rst @@ -20,7 +20,7 @@ via Composer: symfony/http-foundation symfony/routing \ symfony/dependency-injection symfony/framework-bundle -Next, create an ``index.php`` file that defines the kernel class and executes it:: +Next, create an ``index.php`` file that defines the kernel class and runs it:: // index.php use Symfony\Bundle\FrameworkBundle\Kernel\MicroKernelTrait; diff --git a/configuration/multiple_kernels.rst b/configuration/multiple_kernels.rst index a43aa491920..e6110bb69c2 100644 --- a/configuration/multiple_kernels.rst +++ b/configuration/multiple_kernels.rst @@ -16,8 +16,8 @@ request to generate the response. This single kernel approach is a convenient default, but Symfony applications can define any number of kernels. Whereas -:ref:`environments ` execute the same application -with different configurations, kernels can execute different parts of the same +:ref:`environments ` run the same application with +different configurations, kernels can run different parts of the same application. These are some of the common use cases for creating multiple kernels: @@ -123,7 +123,7 @@ Finally, define the configuration files that the new ``ApiKernel`` will load. According to the above code, this config will live in one or multiple files stored in ``config/api/`` and ``config/api/ENVIRONMENT_NAME/`` directories. -The new configuration files can be created from scratch when you load just a few +The new configuration files can be created from scratch when you load only a few bundles, because it will be small. Otherwise, duplicate the existing config files in ``config/packages/`` or better, import them and override the needed options. @@ -133,13 +133,12 @@ Executing Commands with a Different Kernel The ``bin/console`` script used to run Symfony commands always uses the default ``Kernel`` class to build the application and load the commands. If you need -to execute console commands using the new kernel, duplicate the ``bin/console`` +to run console commands using the new kernel, duplicate the ``bin/console`` script and rename it (e.g. ``bin/api``). Then, replace the ``Kernel`` instance by your own kernel instance -(e.g. ``ApiKernel``) and now you can execute commands using the new kernel -(e.g. ``php bin/api cache:clear``) Now you can use execute commands using the -new kernel. +(e.g. ``ApiKernel``). Now you can run commands using the new kernel +(e.g. ``php bin/api cache:clear``). .. note:: diff --git a/configuration/using_parameters_in_dic.rst b/configuration/using_parameters_in_dic.rst index 8a19b4ebc39..730043af714 100644 --- a/configuration/using_parameters_in_dic.rst +++ b/configuration/using_parameters_in_dic.rst @@ -10,8 +10,8 @@ There are special cases such as when you want, for instance, to use the ``%kernel.debug%`` parameter to make the services in your bundle enter debug mode. For this case there is more work to do in order to make the system understand the parameter value. By default, -your parameter ``%kernel.debug%`` will be treated as a -simple string. Consider the following example:: +your parameter ``%kernel.debug%`` will be treated as a string. Consider the +following example:: // inside Configuration class $rootNode diff --git a/console.rst b/console.rst index 8b015737c85..b577cfdee02 100644 --- a/console.rst +++ b/console.rst @@ -127,7 +127,7 @@ this is already done for you, thanks to :ref:`autoconfiguration ` covers how to create a console command. This article covers how to use a console command directly from your controller. -You may have the need to execute some function that is only available in a -console command. Usually, you should refactor the command and move some logic -into a service that can be reused in the controller. However, when the command -is part of a third-party library, you wouldn't want to modify or duplicate -their code. Instead, you can execute the command directly. +You may have the need to call some function that is only available in a console +command. Usually, you should refactor the command and move some logic into a +service that can be reused in the controller. However, when the command is part +of a third-party library, you don't want to modify or duplicate their code. +Instead, you can run the command directly from the controller. .. caution:: diff --git a/console/commands_as_services.rst b/console/commands_as_services.rst index 9b1e19ac8eb..af4f275e221 100644 --- a/console/commands_as_services.rst +++ b/console/commands_as_services.rst @@ -52,8 +52,9 @@ For example, suppose you want to log something from within your command:: If you're using the :ref:`default services.yaml configuration `, the command class will automatically be registered as a service and passed the ``$logger`` -argument (thanks to autowiring). In other words, *just* by creating this class, everything -works! You can call the ``app:sunshine`` command and start logging. +argument (thanks to autowiring). In other words, you only need to create this +class and everything works automatically! You can call the ``app:sunshine`` +command and start logging. .. caution:: diff --git a/console/hide_commands.rst b/console/hide_commands.rst index 814888fe660..db39ca824f8 100644 --- a/console/hide_commands.rst +++ b/console/hide_commands.rst @@ -4,9 +4,9 @@ How to Hide Console Commands By default, all console commands are listed when executing the console application script without arguments or when using the ``list`` command. -However, sometimes commands are not intended to be executed by end-users; for +However, sometimes commands are not intended to be run by end-users; for example, commands for the legacy parts of the application, commands exclusively -executed through scheduled tasks, etc. +run through scheduled tasks, etc. In those cases, you can define the command as **hidden** by setting the ``setHidden()`` method to ``true`` in the command configuration:: diff --git a/console/input.rst b/console/input.rst index d71d4aaf9f8..182a7c579e2 100644 --- a/console/input.rst +++ b/console/input.rst @@ -186,13 +186,13 @@ flag: ; Note that to comply with the `docopt standard`_, long options can specify their -values after a white space or an ``=`` sign (e.g. ``--iterations 5`` or -``--iterations=5``), but short options can only use white spaces or no +values after a whitespace or an ``=`` sign (e.g. ``--iterations 5`` or +``--iterations=5``), but short options can only use whitespaces or no separation at all (e.g. ``-i 5`` or ``-i5``). .. caution:: - While it is possible to separate an option from its value with a white space, + While it is possible to separate an option from its value with a whitespace, using this form leads to an ambiguity should the option appear before the command name. For example, ``php bin/console --iterations 5 app:greet Fabien`` is ambiguous; Symfony would interpret ``5`` as the command name. To avoid diff --git a/console/lockable_trait.rst b/console/lockable_trait.rst index 1b810c85f15..1be62776742 100644 --- a/console/lockable_trait.rst +++ b/console/lockable_trait.rst @@ -1,9 +1,9 @@ -Prevent Multiple Executions of a Console Command -================================================ +Prevent Running the Same Console Command Multiple Times +======================================================= -A simple but effective way to prevent multiple executions of the same command in -a single server is to use `locks`_. The :doc:`Lock component ` -provides multiple classes to create locks based on the filesystem (:ref:`FlockStore `), +You can use `locks`_ to prevent the same command from running multiple times on +the same server. The :doc:`Lock component ` provides multiple +classes to create locks based on the filesystem (:ref:`FlockStore `), shared memory (:ref:`SemaphoreStore `) and even databases and Redis servers. diff --git a/controller.rst b/controller.rst index e3b2cceb8a2..d29608e6128 100644 --- a/controller.rst +++ b/controller.rst @@ -7,7 +7,7 @@ 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. The controller executes whatever arbitrary logic *your application* needs +else. The controller runs whatever arbitrary logic *your application* needs to render the content of a page. .. tip:: @@ -16,9 +16,9 @@ to render the content of a page. :doc:`/page_creation` and then come back! .. index:: - single: Controller; Simple example + single: Controller; Basic example -A Simple Controller +A Basic Controller ------------------- While a controller can be any PHP callable (function, method on an object, diff --git a/controller/argument_value_resolver.rst b/controller/argument_value_resolver.rst index 6bee70a90b5..cfd90123e51 100644 --- a/controller/argument_value_resolver.rst +++ b/controller/argument_value_resolver.rst @@ -126,7 +126,7 @@ and defining a service for it. The interface defines two methods: ``supports()`` This method is used to check whether the value resolver supports the - given argument. ``resolve()`` will only be executed when this returns ``true``. + given argument. ``resolve()`` will only be called when this returns ``true``. ``resolve()`` This method will resolve the actual value for the argument. Once the value is resolved, you must `yield`_ the value to the ``ArgumentResolver``. diff --git a/controller/error_pages.rst b/controller/error_pages.rst index 0636d389251..25bdfb5d467 100644 --- a/controller/error_pages.rst +++ b/controller/error_pages.rst @@ -6,8 +6,8 @@ How to Customize Error Pages ============================ In Symfony applications, all errors are treated as exceptions, no matter if they -are just a 404 Not Found error or a fatal error triggered by throwing some -exception in your code. +are a 404 Not Found error or a fatal error triggered by throwing some exception +in your code. In the :ref:`development environment `, Symfony catches all the exceptions and displays a special **exception page** @@ -19,7 +19,7 @@ with lots of debug information to help you discover the root problem: :class: with-browser Since these pages contain a lot of sensitive internal information, Symfony won't -display them in the production environment. Instead, it'll show a simple and +display them in the production environment. Instead, it'll show a minimal and generic **error page**: .. image:: /_images/controller/error_pages/errors-in-prod-environment.png @@ -30,7 +30,7 @@ generic **error page**: Error pages for the production environment can be customized in different ways depending on your needs: -#. If you just want to change the contents and styles of the error pages to match +#. If you only want to change the contents and styles of the error pages to match the rest of your application, :ref:`override the default error templates `; #. If you want to change the contents of non-HTML error output, @@ -39,7 +39,7 @@ depending on your needs: #. If you also want to tweak the logic used by Symfony to generate error pages, :ref:`override the default error controller `; -#. If you need total control of exception handling to execute your own logic +#. If you need total control of exception handling to run your own logic :ref:`use the kernel.exception event `. .. _use-default-error-controller: diff --git a/controller/forwarding.rst b/controller/forwarding.rst index 74a6ffedeed..0f231e07b42 100644 --- a/controller/forwarding.rst +++ b/controller/forwarding.rst @@ -34,5 +34,5 @@ The target controller method might look something like this:: // ... create and return a Response object } -Just like when creating a controller for a route, the order of the arguments -of the ``fancy()`` method doesn't matter: the matching is done by name. +Like when creating a controller for a route, the order of the arguments of the +``fancy()`` method doesn't matter: the matching is done by name. diff --git a/deployment.rst b/deployment.rst index b594338b8bd..85b772b3a55 100644 --- a/deployment.rst +++ b/deployment.rst @@ -128,7 +128,7 @@ While developing locally, you'll usually store these in ``.env`` and ``.env.loca on your setup: they can be set at the command line, in your Nginx configuration, or via other methods provided by your hosting service. -2. Or, create a ``.env.local`` file just like your local development (see note below) +2. Or, create a ``.env.local`` file like your local development (see note below) There is no significant advantage to either of the two options: use whatever is most natural in your hosting environment. diff --git a/doctrine/associations.rst b/doctrine/associations.rst index cf769166122..017f5903391 100644 --- a/doctrine/associations.rst +++ b/doctrine/associations.rst @@ -15,7 +15,7 @@ There are **two** main relationship/association types: ``ManyToOne`` / ``OneToMany`` The most common relationship, mapped in the database with a foreign key column (e.g. a ``category_id`` column on the ``product`` table). This is - actually just *one* association type, but seen from the two different *sides* + actually only *one* association type, but seen from the two different *sides* of the relation. ``ManyToMany`` @@ -299,7 +299,7 @@ config. *exactly* like an array, but has some added flexibility. Just imagine that it is an ``array`` and you'll be in good shape. -Your database is setup! Now, execute the migrations like normal: +Your database is setup! Now, run the migrations like normal: .. code-block:: terminal @@ -374,8 +374,8 @@ Doctrine takes care of the rest when saving. Fetching Related Objects ------------------------ -When you need to fetch associated objects, your workflow looks just like it -did before. First, fetch a ``$product`` object and then access its related +When you need to fetch associated objects, your workflow looks like it did +before. First, fetch a ``$product`` object and then access its related ``Category`` object:: use App\Entity\Product; @@ -395,7 +395,7 @@ did before. First, fetch a ``$product`` object and then access its related } In this example, you first query for a ``Product`` object based on the product's -``id``. This issues a query for *just* the product data and hydrates the +``id``. This issues a query to fetch *only* the product data and hydrates the ``$product``. Later, when you call ``$product->getCategory()->getName()``, Doctrine silently makes a second query to find the ``Category`` that's related to this ``Product``. It prepares the ``$category`` object and returns it to @@ -493,7 +493,7 @@ This will *still* return an array of ``Product`` objects. But now, when you call ``$product->getCategory()`` and use that data, no second query is made. Now, you can use this method in your controller to query for a ``Product`` -object and its related ``Category`` with just one query:: +object and its related ``Category`` in one query:: public function show($id) { diff --git a/doctrine/events.rst b/doctrine/events.rst index 8d059ab3494..b1a1fc8e825 100644 --- a/doctrine/events.rst +++ b/doctrine/events.rst @@ -7,7 +7,7 @@ Doctrine Events `Doctrine`_, the set of PHP libraries used by Symfony to work with databases, provides a lightweight event system to update entities during the application execution. These events, called `lifecycle events`_, allow to perform tasks such -as *"update the createdAt property automatically just before persisting entities +as *"update the createdAt property automatically right before persisting entities of this type"*. Doctrine triggers events before/after performing the most common entity diff --git a/doctrine/multiple_entity_managers.rst b/doctrine/multiple_entity_managers.rst index 38711b468c1..a6c15974ce5 100644 --- a/doctrine/multiple_entity_managers.rst +++ b/doctrine/multiple_entity_managers.rst @@ -256,7 +256,7 @@ the default entity manager (i.e. ``default``) is returned:: } } -You can now use Doctrine just as you did before - using the ``default`` entity +You can now use Doctrine like you did before - using the ``default`` entity manager to persist and fetch entities that it manages and the ``customer`` entity manager to persist and fetch its entities. diff --git a/event_dispatcher.rst b/event_dispatcher.rst index 8bef74f26d9..70cfaeb2ac6 100644 --- a/event_dispatcher.rst +++ b/event_dispatcher.rst @@ -106,15 +106,15 @@ using a special "tag": ->addTag('kernel.event_listener', ['event' => 'kernel.exception']) ; -Symfony follows this logic to decide which method to execute inside the event +Symfony follows this logic to decide which method to call inside the event listener class: #. If the ``kernel.event_listener`` tag defines the ``method`` attribute, that's - the name of the method to be executed; -#. If no ``method`` attribute is defined, try to execute the method whose name + the name of the method to be called; +#. If no ``method`` attribute is defined, try to call the method whose name is ``on`` + "camel-cased event name" (e.g. ``onKernelException()`` method for the ``kernel.exception`` event); -#. If that method is not defined either, try to execute the ``__invoke()`` magic +#. If that method is not defined either, try to call the ``__invoke()`` magic method (which makes event listeners invokable); #. If the ``_invoke()`` method is not defined either, throw an exception. @@ -142,7 +142,7 @@ If different event subscriber methods listen to the same event, their order is defined by the ``priority`` parameter. This value is a positive or negative integer which defaults to ``0``. The higher the number, the earlier the method is called. **Priority is aggregated for all listeners and subscribers**, so your -methods could be executed before or after the methods defined in other listeners +methods could be called before or after the methods defined in other listeners and subscribers. To learn more about event subscribers, read :doc:`/components/event_dispatcher`. The following example shows an event subscriber that defines several methods which diff --git a/event_dispatcher/before_after_filters.rst b/event_dispatcher/before_after_filters.rst index 771163f4cb8..6c48d62ee24 100644 --- a/event_dispatcher/before_after_filters.rst +++ b/event_dispatcher/before_after_filters.rst @@ -5,8 +5,8 @@ How to Set Up Before and After Filters ====================================== It is quite common in web application development to need some logic to be -executed just before or just after your controller actions acting as filters -or hooks. +performed right before or directly after your controller actions acting as +filters or hooks. Some web frameworks define methods like ``preExecute()`` and ``postExecute()``, but there is no such thing in Symfony. The good news is that there is a much diff --git a/event_dispatcher/method_behavior.rst b/event_dispatcher/method_behavior.rst index 7d93d074353..cea11e72d8d 100644 --- a/event_dispatcher/method_behavior.rst +++ b/event_dispatcher/method_behavior.rst @@ -7,9 +7,9 @@ How to Customize a Method Behavior without Using Inheritance Doing something before or after a Method Call --------------------------------------------- -If you want to do something just before, or just after a method is called, you -can dispatch an event respectively at the beginning or at the end of the -method:: +If you want to do something right before, or directly after a method is +called, you can dispatch an event respectively at the beginning or at the +end of the method:: class CustomMailer { @@ -36,10 +36,14 @@ method:: } } -In this example, two events are thrown: ``mailer.pre_send``, before the method is -executed, and ``mailer.post_send`` after the method is executed. Each uses a -custom Event class to communicate information to the listeners of the two -events. For example, ``BeforeSendMailEvent`` might look like this:: +In this example, two events are dispatched: + +#. ``mailer.pre_send``, before the method is called, +#. and ``mailer.post_send`` after the method is called. + +Each uses a custom Event class to communicate information to the listeners +of the two events. For example, ``BeforeSendMailEvent`` might look like +this:: // src/Event/BeforeSendMailEvent.php namespace App\Event; diff --git a/form/data_based_validation.rst b/form/data_based_validation.rst index 0c89ea2fef1..383883ba91f 100644 --- a/form/data_based_validation.rst +++ b/form/data_based_validation.rst @@ -23,9 +23,9 @@ to an array callback:: } This will call the static method ``determineValidationGroups()`` on the -``Client`` class after the form is submitted, but before validation is executed. -The Form object is passed as an argument to that method (see next example). -You can also define whole logic inline by using a ``Closure``:: +``Client`` class after the form is submitted, but before validation is +invoked. The Form object is passed as an argument to that method (see next +example). You can also define whole logic inline by using a ``Closure``:: use App\Entity\Client; use Symfony\Component\Form\FormInterface; diff --git a/form/data_transformers.rst b/form/data_transformers.rst index d976deb5197..91ed89a3fce 100644 --- a/form/data_transformers.rst +++ b/form/data_transformers.rst @@ -24,8 +24,8 @@ to render the form, and then back into a ``DateTime`` object on submit. .. _simple-example-sanitizing-html-on-user-input: -Simple Example: Transforming String Tags from User Input to an Array --------------------------------------------------------------------- +Example #1: Transforming Strings Form Data Tags from User Input to an Array +--------------------------------------------------------------------------- Suppose you have a Task form with a tags ``text`` type:: @@ -56,7 +56,7 @@ Suppose you have a Task form with a tags ``text`` type:: } Internally the ``tags`` are stored as an array, but displayed to the user as a -simple comma separated string to make them easier to edit. +plain comma separated string to make them easier to edit. This is a *perfect* time to attach a custom data transformer to the ``tags`` field. The easiest way to do this is with the :class:`Symfony\\Component\\Form\\CallbackTransformer` @@ -115,8 +115,8 @@ slightly:: ->addModelTransformer(...) ); -Harder Example: Transforming an Issue Number into an Issue Entity ------------------------------------------------------------------ +Example #2: Transforming an Issue Number into an Issue Entity +------------------------------------------------------------- Say you have a many-to-one relation from the Task entity to an Issue entity (i.e. each Task has an optional foreign key to its related Issue). Adding a list box with all @@ -233,7 +233,7 @@ to and from the issue number and the ``Issue`` object:: } } -Just like in the first example, a transformer has two directions. The ``transform()`` +Like the first example, the transformer has two directions. The ``transform()`` method is responsible for converting the data used in your code to a format that can be rendered in your form (e.g. an ``Issue`` object to its ``id``, a string). The ``reverseTransform()`` method does the reverse: it converts the submitted value diff --git a/form/embedded.rst b/form/embedded.rst index 6568b09611f..9da8104b143 100644 --- a/form/embedded.rst +++ b/form/embedded.rst @@ -14,7 +14,7 @@ be achieved by the Form component. Embedding a Single Object ------------------------- -Suppose that each ``Task`` belongs to a simple ``Category`` object. Start by +Suppose that each ``Task`` belongs to a ``Category`` object. Start by creating the ``Category`` object:: // src/Entity/Category.php diff --git a/form/form_collections.rst b/form/form_collections.rst index 356715a2e5b..1d0b56c244a 100644 --- a/form/form_collections.rst +++ b/form/form_collections.rst @@ -397,7 +397,7 @@ Next, add a ``by_reference`` option to the ``tags`` field and set it to ``false` With these two changes, when the form is submitted, each new ``Tag`` object is added to the ``Task`` class by calling the ``addTag()`` method. Before this change, they were added internally by the form by calling ``$task->getTags()->add($tag)``. -That was just fine, but forcing the use of the "adder" method makes handling +That was fine, but forcing the use of the "adder" method makes handling these new ``Tag`` objects easier (especially if you're using Doctrine, which you will learn about next!). diff --git a/form/unit_testing.rst b/form/unit_testing.rst index a1ea0a58099..ee096c167dd 100644 --- a/form/unit_testing.rst +++ b/form/unit_testing.rst @@ -20,7 +20,7 @@ The only class that is usually manipulated by programmers is the form type class which serves as a form blueprint. It is used to generate the ``Form`` and the ``FormView``. You could test it directly by mocking its interactions with the factory but it would be complex. It is better to pass it to FormFactory like it -is done in a real application. It is simple to bootstrap and you can trust +is done in a real application. It is easier to bootstrap and you can trust the Symfony components enough to use them as a testing base. There is already a class that you can benefit from for testing: @@ -94,7 +94,7 @@ be the first test you write:: $form = $this->factory->create(TestedType::class, $formData); This test checks that none of your data transformers used by the form -failed. The :method:`Symfony\\Component\\Form\\FormInterface::isSynchronized` +produces an error. The :method:`Symfony\\Component\\Form\\FormInterface::isSynchronized` method is only set to ``false`` if a data transformer throws an exception:: $form->submit($formData); @@ -139,8 +139,8 @@ Testings Types Registered as Services Your form may be used as a service, as it depends on other services (e.g. the Doctrine entity manager). In these cases, using the above code won't work, as -the Form component just instantiates the form type without passing any -arguments to the constructor. +the Form component instantiates the form type without passing any arguments +to the constructor. To solve this, you have to mock the injected dependencies, instantiate your own form type and use the :class:`Symfony\\Component\\Form\\PreloadedExtension` to diff --git a/form/validation_group_service_resolver.rst b/form/validation_group_service_resolver.rst index 9953e5d176e..e497a7556df 100644 --- a/form/validation_group_service_resolver.rst +++ b/form/validation_group_service_resolver.rst @@ -2,8 +2,8 @@ How to Dynamically Configure Form Validation Groups =================================================== Sometimes you need advanced logic to determine the validation groups. If they -can't be determined by a simple callback, you can use a service. Create a -service that implements ``__invoke()`` which accepts a ``FormInterface`` as a +can't be determined by a callback, you can use a service. Create a service +that implements ``__invoke()`` which accepts a ``FormInterface`` as a parameter:: // src/Validation/ValidationGroupResolver.php diff --git a/form/without_class.rst b/form/without_class.rst index 0d9cbff0b82..50efc1dbcc7 100644 --- a/form/without_class.rst +++ b/form/without_class.rst @@ -8,8 +8,9 @@ In most cases, a form is tied to an object, and the fields of the form get and store their data on the properties of that object. This is exactly what you've seen so far in this article with the ``Task`` class. -But sometimes, you may just want to use a form without a class, and get back -an array of the submitted data. The ``getData()`` method allows you to do exactly that:: +But sometimes, you may want to use a form without a class, and get back an +array of the submitted data. The ``getData()`` method allows you to do +exactly that:: // make sure you've imported the Request namespace above the class use Symfony\Component\HttpFoundation\Request; @@ -72,7 +73,7 @@ you want to use. See :doc:`/validation` for more details. .. _form-option-constraints: But if the form is not mapped to an object and you instead want to retrieve a -simple array of your submitted data, how can you add constraints to the data of +array of your submitted data, how can you add constraints to the data of your form? The answer is to set up the constraints yourself, and attach them to the individual diff --git a/forms.rst b/forms.rst index 7f877f6cdb3..ab433b533db 100644 --- a/forms.rst +++ b/forms.rst @@ -35,7 +35,7 @@ The recommended workflow when working with Symfony forms is the following: data and do something with it (e.g. persist it in a database). Each of these steps is explained in detail in the next sections. To make -examples easier to follow, all of them assume that you're building a simple Todo +examples easier to follow, all of them assume that you're building a small Todo list application that displays "tasks". Users create and edit tasks using Symfony forms. Each task is an instance of the diff --git a/frontend.rst b/frontend.rst index e05f26ed314..47d3111dd33 100644 --- a/frontend.rst +++ b/frontend.rst @@ -7,9 +7,9 @@ Managing CSS and JavaScript Do you prefer video tutorials? Check out the `Webpack Encore screencast series`_. Symfony ships with a pure-JavaScript library - called Webpack Encore - that makes -working with CSS and JavaScript a joy. You can use it, use something else, or just -create static CSS and JS files in your ``public/`` directory and include them in your -templates. +working with CSS and JavaScript a joy. You can use it, use something else, or +create static CSS and JS files in your ``public/`` directory directly and +include them in your templates. .. _frontend-webpack-encore: diff --git a/http_cache/expiration.rst b/http_cache/expiration.rst index f7588a5e4e6..d30893b58fe 100644 --- a/http_cache/expiration.rst +++ b/http_cache/expiration.rst @@ -53,8 +53,7 @@ Expiration with the ``Expires`` Header -------------------------------------- An alternative to the ``Cache-Control`` header is ``Expires``. There's no advantage -or disadvantage to either: they're just different ways to set expiration caching -on your response. +or disadvantage to either. According to the HTTP specification, "the ``Expires`` header field gives the date/time after which the response is considered stale." The ``Expires`` diff --git a/http_cache/validation.rst b/http_cache/validation.rst index 24d3711cfe5..3a1dabf902e 100644 --- a/http_cache/validation.rst +++ b/http_cache/validation.rst @@ -48,7 +48,7 @@ An ``ETag`` is like a fingerprint and is used to quickly compare if two different versions of a resource are equivalent. Like fingerprints, each ``ETag`` must be unique across all representations of the same resource. -To see a simple implementation, generate the ``ETag`` as the ``md5`` of the +To see a short implementation, generate the ``ETag`` as the ``md5`` of the content:: // src/Controller/DefaultController.php @@ -96,8 +96,8 @@ to 304. app. This is how the cache and server communicate with each other and decide whether or not the resource has been updated since it was cached. -This algorithm is simple enough and very generic, but you need to create the -whole ``Response`` before being able to compute the ``ETag``, which is sub-optimal. +This algorithm works and is very generic, but you need to create the whole +``Response`` before being able to compute the ``ETag``, which is sub-optimal. In other words, it saves on bandwidth, but not CPU cycles. In the :ref:`optimizing-cache-validation` section, you'll see how validation @@ -185,8 +185,7 @@ Optimizing your Code with Validation The main goal of any caching strategy is to lighten the load on the application. Put another way, the less you do in your application to return a 304 response, -the better. The ``Response::isNotModified()`` method does exactly that by -exposing a simple and efficient pattern:: +the better. The ``Response::isNotModified()`` method does exactly that:: // src/Controller/ArticleController.php namespace App\Controller; diff --git a/http_cache/varnish.rst b/http_cache/varnish.rst index f28a53e09b0..dd38b717ea8 100644 --- a/http_cache/varnish.rst +++ b/http_cache/varnish.rst @@ -53,7 +53,7 @@ header. In this case, you need to add the following configuration snippet: Cookies and Caching ------------------- -By default, a sane caching proxy does not cache anything when a request is sent +By default, most caching proxies do not cache anything when a request is sent with :ref:`cookies or a basic authentication header `. This is because the content of the page is supposed to depend on the cookie value or authentication header. diff --git a/introduction/from_flat_php_to_symfony.rst b/introduction/from_flat_php_to_symfony.rst index 85b5f3612d4..40a421f85dd 100644 --- a/introduction/from_flat_php_to_symfony.rst +++ b/introduction/from_flat_php_to_symfony.rst @@ -14,7 +14,7 @@ is around Symfony, this article is for you. Instead of *telling* you that Symfony allows you to develop faster and better software than with flat PHP, you'll see for yourself. -In this article, you'll write a simple application in flat PHP, and then +In this article, you'll write a basic application in flat PHP, and then refactor it to be more organized. You'll travel through time, seeing the decisions behind why web development has evolved over the past several years to where it is now. @@ -22,8 +22,8 @@ to where it is now. By the end, you'll see how Symfony can rescue you from mundane tasks and let you take back control of your code. -A Simple Blog in Flat PHP -------------------------- +A Basic Blog in Flat PHP +------------------------ In this article, you'll build the token blog application using only flat PHP. To begin, create a single page that displays blog entries that have been @@ -61,7 +61,7 @@ persisted to the database. Writing in flat PHP is quick and dirty: $connection = null; ?> -That's quick to write, fast to execute, and, as your app grows, impossible +That's quick to write, fast to deploy and run, and, as your app grows, impossible to maintain. There are several problems that need to be addressed: * **No error-checking**: What if the connection to the database fails? @@ -181,7 +181,7 @@ of the application are isolated in a new file called ``model.php``:: in this example, only a portion (or none) of the model is actually concerned with accessing a database. -The controller (``index.php``) is now just a few lines of code:: +The controller (``index.php``) is now only a few lines of code:: // index.php require_once 'model.php'; @@ -390,7 +390,7 @@ functions) is called. In reality, the front controller is beginning to look and act a lot like how Symfony handles and routes requests. But be careful not to confuse the terms *front controller* and *controller*. Your -app will usually have just *one* front controller, which boots your code. You will +app will usually have only *one* front controller, which boots your code. You will have *many* controller functions: one for each page. .. tip:: @@ -527,12 +527,11 @@ The Sample Application in Symfony ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The blog has come a *long* way, but it still contains a lot of code for such -a simple application. Along the way, you've made a simple routing -system and a method using ``ob_start()`` and ``ob_get_clean()`` to render -templates. If, for some reason, you needed to continue building this "framework" -from scratch, you could at least use Symfony's standalone -:doc:`Routing ` component and :doc:`Twig `, which -already solve these problems. +a basic application. Along the way, you've made a basic routing system and +a method using ``ob_start()`` and ``ob_get_clean()`` to render templates. +If, for some reason, you needed to continue building this "framework" from +scratch, you could at least use Symfony's standalone :doc:`Routing ` +component and :doc:`Twig `, which already solve these problems. Instead of re-solving common problems, you can let Symfony take care of them for you. Here's the same sample application, now built in Symfony:: @@ -623,7 +622,7 @@ The ``layout.php`` file is nearly identical: really similar to updating the ``list.html.twig`` template. When Symfony's engine (called the Kernel) boots up, it needs a map so -that it knows which controllers to execute based on the request information. +that it knows which controllers to call based on the request information. A routing configuration map - ``config/routes.yaml`` - provides this information in a readable format: @@ -655,8 +654,8 @@ The front controller's only job is to initialize Symfony's engine (called the Kernel) and pass it a ``Request`` object to handle. The Symfony core asks the router to inspect the request. The router matches the incoming URL to a specific route and returns information about the route, including the -controller that should be executed. The correct controller from the matched -route is executed and your code inside the controller creates and returns the +controller that should be called. The correct controller from the matched +route is called and your code inside the controller creates and returns the appropriate ``Response`` object. The HTTP headers and content of the ``Response`` object are sent back to the client. diff --git a/logging/monolog_console.rst b/logging/monolog_console.rst index f3c67160283..9eb8b28b062 100644 --- a/logging/monolog_console.rst +++ b/logging/monolog_console.rst @@ -7,7 +7,7 @@ How to Configure Monolog to Display Console Messages It is possible to use the console to print messages for certain :doc:`verbosity levels ` using the :class:`Symfony\\Component\\Console\\Output\\OutputInterface` instance that -is passed when a command gets executed. +is passed when a command is run. When a lot of logging has to happen, it's cumbersome to print information depending on the verbosity settings (``-v``, ``-vv``, ``-vvv``) because the diff --git a/mailer.rst b/mailer.rst index 6d336bfe5b7..7c75e72032b 100644 --- a/mailer.rst +++ b/mailer.rst @@ -706,7 +706,7 @@ Inky Email Templating Language Creating beautifully designed emails that work on every email client is so complex that there are HTML/CSS frameworks dedicated to that. One of the most -popular frameworks is called `Inky`_. It defines a syntax based on some simple +popular frameworks is called `Inky`_. It defines a syntax based on some HTML-like tags which are later transformed into the real HTML code sent to users: .. code-block:: html diff --git a/messenger.rst b/messenger.rst index 8b3b93ad415..6fe7fe7d3f3 100644 --- a/messenger.rst +++ b/messenger.rst @@ -987,22 +987,22 @@ The transport has a number of options: Options defined under ``options`` take precedence over ones defined in the DSN. -================== =================================== ====================== - Option Description Default -================== =================================== ====================== -table_name Name of the table messenger_messages -queue_name Name of the queue (a column in the default +================== ===================================== ====================== + Option Description Default +================== ===================================== ====================== +table_name Name of the table messenger_messages +queue_name Name of the queue (a column in the default table, to use one table for multiple transports) -redeliver_timeout Timeout before retrying a message 3600 +redeliver_timeout Timeout before retrying a message 3600 that's in the queue but in the - "handling" state (if a worker died + "handling" state (if a worker stopped for some reason, this will occur, eventually you should retry the message) - in seconds. auto_setup Whether the table should be created - automatically during send / get. true -================== =================================== ====================== + automatically during send / get. true +================== ===================================== ====================== Beanstalkd Transport ~~~~~~~~~~~~~~~~~~~~ diff --git a/messenger/dispatch_after_current_bus.rst b/messenger/dispatch_after_current_bus.rst index e5dac59203e..c2b85c2aaad 100644 --- a/messenger/dispatch_after_current_bus.rst +++ b/messenger/dispatch_after_current_bus.rst @@ -4,7 +4,7 @@ Transactional Messages: Handle New Messages After Handling is Done ================================================================== -A message handler can ``dispatch`` new messages during execution, to either the +A message handler can ``dispatch`` new messages while handling others, to either the same or a different bus (if the application has :doc:`multiple buses `). Any errors or exceptions that occur during this process can have unintended consequences, such as: diff --git a/page_creation.rst b/page_creation.rst index 43d06a5808c..45187a9ac41 100644 --- a/page_creation.rst +++ b/page_creation.rst @@ -63,7 +63,7 @@ random) number and prints it. To do that, create a "Controller" class and a } Now you need to associate this controller function with a public URL (e.g. ``/lucky/number``) -so that the ``number()`` method is executed when a user browses to it. This association +so that the ``number()`` method is called when a user browses to it. This association is defined by creating a **route** in the ``config/routes.yaml`` file: .. code-block:: yaml @@ -136,7 +136,7 @@ special things happened, both thanks to a powerful Composer plugin called First, ``annotations`` isn't a real package name: it's an *alias* (i.e. shortcut) that Flex resolves to ``sensio/framework-extra-bundle``. -Second, after this package was downloaded, Flex executed a *recipe*, which is a +Second, after this package was downloaded, Flex runs a *recipe*, which is a set of automated instructions that tell Symfony how to integrate an external package. `Flex recipes`_ exist for many packages and have the ability to do a lot, like adding configuration files, creating directories, updating ``.gitignore`` @@ -179,21 +179,22 @@ You'll learn about many more commands as you continue! The Web Debug Toolbar: Debugging Dream -------------------------------------- -One of Symfony's *killer* features is the Web Debug Toolbar: a bar that displays +One of Symfony's *amazing* features is the Web Debug Toolbar: a bar that displays a *huge* amount of debugging information along the bottom of your page while developing. This is all included out of the box using a :ref:`Symfony pack ` called ``symfony/profiler-pack``. -You will see a black bar along the bottom of the page. You'll learn more about all the information it holds -along the way, but feel free to experiment: hover over and click -the different icons to get information about routing, performance, logging and more. +You will see a dark bar along the bottom of the page. You'll learn more about +all the information it holds along the way, but feel free to experiment: hover +over and click the different icons to get information about routing, +performance, logging and more. Rendering a Template -------------------- If you're returning HTML from your controller, you'll probably want to render a template. Fortunately, Symfony comes with `Twig`_: a templating language that's -easy, powerful and actually quite fun. +minimal, powerful and actually quite fun. Install the twig package with: diff --git a/profiler/data_collector.rst b/profiler/data_collector.rst index 41378ab6464..292047b5dc7 100644 --- a/profiler/data_collector.rst +++ b/profiler/data_collector.rst @@ -82,7 +82,7 @@ request:: The ``collect()`` method is called during the :ref:`kernel.response ` event. If you need to collect data that is only available later, implement :class:`Symfony\\Component\\HttpKernel\\DataCollector\\LateDataCollectorInterface` -and define the ``lateCollect()`` method, which is invoked just before the profiler +and define the ``lateCollect()`` method, which is invoked right before the profiler data serialization (during :ref:`kernel.terminate ` event). .. _data_collector_tag: @@ -127,7 +127,7 @@ template access to the collected information:: } } -In the simplest case, you just want to display the information in the toolbar +In the simplest case, you want to display the information in the toolbar without providing a profiler panel. This requires to define the ``toolbar`` block and set the value of two variables called ``icon`` and ``text``: diff --git a/routing.rst b/routing.rst index ca1e3e33d76..b709134d817 100644 --- a/routing.rst +++ b/routing.rst @@ -4,7 +4,7 @@ Routing ======= -When your application receives a request, it executes a +When your application receives a request, it calls a :doc:`controller action ` to generate the response. The routing configuration defines which action to run for each incoming URL. It also provides other useful features, like generating SEO-friendly URLs (e.g. diff --git a/routing/custom_route_loader.rst b/routing/custom_route_loader.rst index 6b8d2370cfe..1aa1c882f94 100644 --- a/routing/custom_route_loader.rst +++ b/routing/custom_route_loader.rst @@ -4,7 +4,7 @@ How to Create a custom Route Loader =================================== -Simple applications can define all their routes in a single configuration file - +Basic applications can define all their routes in a single configuration file - usually ``config/routes.yaml`` (see :ref:`routing-creating-routes`). However, in most applications it's common to import routes definitions from different resources: PHP annotations in controller files, YAML, XML or PHP diff --git a/routing/routing_from_database.rst b/routing/routing_from_database.rst index 01281de39a8..03016259127 100644 --- a/routing/routing_from_database.rst +++ b/routing/routing_from_database.rst @@ -22,7 +22,7 @@ For these cases, the ``DynamicRouter`` offers an alternative approach: When all routes are known during deploy time and the number is not too high, using a :doc:`custom route loader ` is the -preferred way to add more routes. When working with just one type of +preferred way to add more routes. When working with only one type of objects, a slug parameter on the object and the ``@ParamConverter`` annotation work fine (see `FrameworkExtraBundle`_) . diff --git a/security.rst b/security.rst index 358ce477b8c..17940135f73 100644 --- a/security.rst +++ b/security.rst @@ -341,7 +341,7 @@ A "firewall" is your authentication system: the configuration below it defines Only one firewall is active on each request: Symfony uses the ``pattern`` key to find the first match (you can also :doc:`match by host or other things `). -The ``dev`` firewall is really a fake firewall: it just makes sure that you don't +The ``dev`` firewall is really a fake firewall: it makes sure that you don't accidentally block Symfony's dev tools - which live under URLs like ``/_profiler`` and ``/_wdt``. @@ -659,7 +659,7 @@ You can deny access from inside a controller:: That's it! If access is not granted, a special :class:`Symfony\\Component\\Security\\Core\\Exception\\AccessDeniedException` -is thrown and no more code in your controller is executed. Then, one of two things +is thrown and no more code in your controller is called. Then, one of two things will happen: 1) If the user isn't logged in yet, they will be asked to log in (e.g. redirected @@ -735,8 +735,8 @@ Checking to see if a User is Logged In (IS_AUTHENTICATED_FULLY) 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:: +check for that role. Otherwise, you can use a special "attribute" in place of a +role:: // ... diff --git a/security/access_control.rst b/security/access_control.rst index d7a96345b8e..9b345b87a24 100644 --- a/security/access_control.rst +++ b/security/access_control.rst @@ -260,7 +260,7 @@ the external IP address ``10.0.0.1``: * The second access control rule is enabled (the only restriction being the ``path``) and so it matches. If you make sure that no users ever have ``ROLE_NO_ACCESS``, then access is denied (``ROLE_NO_ACCESS`` can be anything - that does not match an existing role, it just serves as a trick to always + that does not match an existing role, it only serves as a trick to always deny access). But if the same request comes from ``127.0.0.1`` or ``::1`` (the IPv6 loopback diff --git a/security/access_denied_handler.rst b/security/access_denied_handler.rst index a6800e2f0f0..e9e780e75ef 100644 --- a/security/access_denied_handler.rst +++ b/security/access_denied_handler.rst @@ -10,7 +10,7 @@ with a service to return a custom response. First, create a class that implements :class:`Symfony\\Component\\Security\\Http\\Authorization\\AccessDeniedHandlerInterface`. This interface defines one method called ``handle()`` where you can implement whatever -logic that should execute when access is denied for the current user (e.g. send a +logic that should run when access is denied for the current user (e.g. send a mail, log a message, or generally return a custom response):: namespace App\Security; diff --git a/security/csrf.rst b/security/csrf.rst index a346340bc24..9e87c4da495 100644 --- a/security/csrf.rst +++ b/security/csrf.rst @@ -68,7 +68,7 @@ protected forms. As an alternative, you can: cache the rest of the page contents; * Cache the entire page and load the form via an uncached AJAX request; * Cache the entire page and use :doc:`hinclude.js ` to - load just the CSRF token with an uncached AJAX request and replace the form + load the CSRF token with an uncached AJAX request and replace the form field value with it. CSRF Protection in Symfony Forms @@ -129,7 +129,7 @@ Although Symfony Forms provide automatic CSRF protection by default, you may need to generate and check CSRF tokens manually for example when using regular HTML forms not managed by the Symfony Form component. -Consider a simple HTML form created to allow deleting items. First, use the +Consider a HTML form created to allow deleting items. First, use the :ref:`csrf_token() Twig function ` to generate a CSRF token in the template and store it as a hidden form field: diff --git a/security/form_login_setup.rst b/security/form_login_setup.rst index 85c187da36c..3f2dd210848 100644 --- a/security/form_login_setup.rst +++ b/security/form_login_setup.rst @@ -145,7 +145,7 @@ Edit the ``security.yaml`` file in order to declare the ``/logout`` path: ], ]); -**Step 2.** The template has very little to do with security: it just generates +**Step 2.** The template has very little to do with security: it generates a traditional HTML form that submits to ``/login``: .. code-block:: html+twig @@ -409,8 +409,6 @@ Controlling Error Messages You can cause authentication to fail with a custom message at any step by throwing a custom :class:`Symfony\\Component\\Security\\Core\\Exception\\CustomUserMessageAuthenticationException`. -This is an easy way to control the error message. - But in some cases, like if you return ``false`` from ``checkCredentials()``, you may see an error that comes from the core of Symfony - like ``Invalid credentials.``. diff --git a/security/guard_authentication.rst b/security/guard_authentication.rst index 9245faace34..5440a3cf24e 100644 --- a/security/guard_authentication.rst +++ b/security/guard_authentication.rst @@ -27,8 +27,8 @@ on each request with their API token. Your job is to read this and find the asso user (if any). First, make sure you've followed the main :doc:`Security Guide ` to -create your ``User`` class. Then, to keep things simple, add an ``apiToken`` property -directly to your ``User`` class (the ``make:entity`` command is a good way to do this): +create your ``User`` class. Then add an ``apiToken`` property directly to +your ``User`` class (the ``make:entity`` command is a good way to do this): .. code-block:: diff @@ -47,7 +47,7 @@ directly to your ``User`` class (the ``make:entity`` command is a good way to do // the getter and setter methods } -Don't forget to generate and execute the migration: +Don't forget to generate and run the migration: .. code-block:: terminal @@ -498,7 +498,7 @@ Frequently Asked Questions -------------------------- **Can I have Multiple Authenticators?** - Yes! But when you do, you'll need to choose just *one* authenticator to be your + Yes! But when you do, you'll need to choose only *one* authenticator to be your "entry_point". This means you'll need to choose *which* authenticator's ``start()`` method should be called when an anonymous user tries to access a protected resource. For more details, see :doc:`/security/multiple_guard_authenticators`. @@ -509,12 +509,12 @@ Frequently Asked Questions collide with other ways to authenticate. **Can I use this with FOSUserBundle?** - Yes! Actually, FOSUserBundle doesn't handle security: it simply gives you a + Yes! Actually, FOSUserBundle doesn't handle security: it only gives you a ``User`` object and some routes and controllers to help with login, registration, forgot password, etc. When you use FOSUserBundle, you typically use ``form_login`` to actually authenticate the user. You can continue doing that (see previous question) or use the ``User`` object from FOSUserBundle and create your own - authenticator(s) (just like in this article). + authenticator(s) (like in this article). .. _`Social Authentication`: https://github.com/knpuniversity/oauth2-client-bundle#authenticating-with-guard .. _`HWIOAuthBundle`: https://github.com/hwi/HWIOAuthBundle diff --git a/security/json_login_setup.rst b/security/json_login_setup.rst index b304286bc30..a4cbc5880b2 100644 --- a/security/json_login_setup.rst +++ b/security/json_login_setup.rst @@ -136,7 +136,7 @@ system intercepts the request and initiates the authentication process: Symfony takes care of authenticating the user with the submitted username and password or triggers an error in case the authentication process fails. If the -authentication is successful, the controller defined earlier will be executed. +authentication is successful, the controller defined earlier will be called. If the JSON document has a different structure, you can specify the path to access the ``username`` and ``password`` properties using the ``username_path`` diff --git a/security/remember_me.rst b/security/remember_me.rst index 4bf8e61ff52..de9f51afddf 100644 --- a/security/remember_me.rst +++ b/security/remember_me.rst @@ -298,7 +298,7 @@ so ``DoctrineTokenProvider`` can store the tokens: ]); Finally, set the ``token_provider`` option of the ``remember_me`` config to the -service you just created: +service you created before: .. configuration-block:: diff --git a/security/voters.rst b/security/voters.rst index af65fb9ca54..8970289aaff 100644 --- a/security/voters.rst +++ b/security/voters.rst @@ -202,7 +202,7 @@ To recap, here's what's expected from the two abstract methods: ``voteOnAttribute(string $attribute, $subject, TokenInterface $token)`` If you return ``true`` from ``supports()``, then this method is called. Your - job is simple: return ``true`` to allow access and ``false`` to deny access. + job is to return ``true`` to allow access and ``false`` to deny access. The ``$token`` can be used to find the current user object (if any). In this example, all of the complex business logic is included to determine access. @@ -216,7 +216,7 @@ and tag it with ``security.voter``. But if you're using the :ref:`default services.yaml configuration `, that's done automatically for you! When you :ref:`call isGranted() with view/edit and pass a Post object `, -your voter will be executed and you can control access. +your voter will be called and you can control access. Checking for Roles inside a Voter --------------------------------- diff --git a/service_container.rst b/service_container.rst index 80b6dde6b07..c32ac9e7f01 100644 --- a/service_container.rst +++ b/service_container.rst @@ -115,7 +115,7 @@ it can't be re-used. Instead, you decide to create a new class:: } } -Congratulations! You've just created your first service class! You can use it immediately +Congratulations! You've created your first service class! You can use it immediately inside your controller:: use App\Service\MessageGenerator; @@ -257,7 +257,7 @@ find the matching service. If it can't, you'll see a clear exception with a help suggestion. By the way, this method of adding dependencies to your ``__construct()`` method is -called *dependency injection*. It's a scary term for a simple concept. +called *dependency injection*. .. _services-debug-container-types: diff --git a/service_container/3.3-di-changes.rst b/service_container/3.3-di-changes.rst index e9a4fca1c86..eccdc590db4 100644 --- a/service_container/3.3-di-changes.rst +++ b/service_container/3.3-di-changes.rst @@ -386,7 +386,7 @@ as before. But now that your controllers are services, you can use dependency in and autowiring like any other service. To make life even easier, it's now possible to autowire arguments to your controller -action methods, just like you can with the constructor of services. For example:: +action methods, like you can with the constructor of services. For example:: use Psr\Log\LoggerInterface; diff --git a/service_container/alias_private.rst b/service_container/alias_private.rst index 97255503c12..6e032b10a6f 100644 --- a/service_container/alias_private.rst +++ b/service_container/alias_private.rst @@ -80,11 +80,9 @@ from the container:: $container->get(Foo::class); -Simply said: A service can be marked as private if you do not want to access -it directly from your code. - -However, if a service has been marked as private, you can still alias it -(see below) to access this service (via the alias). +Thus, a service can be marked as private if you do not want to access it +directly from your code. However, if a service has been marked as private, +you can still alias it (see below) to access this service (via the alias). .. _services-alias: diff --git a/service_container/configurators.rst b/service_container/configurators.rst index bf196b59575..6e76784a284 100644 --- a/service_container/configurators.rst +++ b/service_container/configurators.rst @@ -190,8 +190,7 @@ all the classes are already loaded as services. All you need to do is specify th .. _configurators-invokable: Services can be configured via invokable configurators (replacing the -``configure()`` method with ``__invoke()``) by omitting the method name, just as -routes can reference :ref:`invokable controllers `. +``configure()`` method with ``__invoke()``) by omitting the method name: .. configuration-block:: diff --git a/service_container/expression_language.rst b/service_container/expression_language.rst index 62f469ed59d..9ba64eee074 100644 --- a/service_container/expression_language.rst +++ b/service_container/expression_language.rst @@ -77,7 +77,7 @@ In this context, you have access to 2 functions: ``service`` Returns a given service (see the example above). ``parameter`` - Returns a specific parameter value (syntax is just like ``service``). + Returns a specific parameter value (syntax is like ``service``). You also have access to the :class:`Symfony\\Component\\DependencyInjection\\Container` via a ``container`` variable. Here's another example: diff --git a/service_container/factories.rst b/service_container/factories.rst index e42026db5c7..f7a2bdf2af3 100644 --- a/service_container/factories.rst +++ b/service_container/factories.rst @@ -183,8 +183,7 @@ factory service can be used as a callback:: } Services can be created and configured via invokable factories by omitting the -method name, just as routes can reference -:ref:`invokable controllers `. +method name: .. configuration-block:: diff --git a/service_container/injection_types.rst b/service_container/injection_types.rst index fe4c4bfde77..e69bd33c26c 100644 --- a/service_container/injection_types.rst +++ b/service_container/injection_types.rst @@ -201,8 +201,9 @@ so, here's the advantages of immutable-setters: The disadvantages are: -* As the setter call is optional, a dependency can be null during execution, - you must check that the dependency is available before calling it. +* As the setter call is optional, a dependency can be null when calling + methods of the service. You must check that the dependency is available + before using it. * Unless the service is declared lazy, it is incompatible with services that reference each other in what are called circular loops. @@ -290,10 +291,10 @@ This time the advantages are: The disadvantages of setter injection are: -* The setter can be called more than just at the time of construction so - you cannot be sure the dependency is not replaced during the lifetime - of the object (except by explicitly writing the setter method to check - if it has already been called). +* The setter can be called more than once, also long after initialization, + so you cannot be sure the dependency is not replaced during the lifetime + of the object (except by explicitly writing the setter method to check if + it has already been called). * You cannot be sure the setter will be called and so you need to add checks that any required dependencies are injected. diff --git a/service_container/lazy_services.rst b/service_container/lazy_services.rst index 0370e52b0ff..936316bb029 100644 --- a/service_container/lazy_services.rst +++ b/service_container/lazy_services.rst @@ -20,7 +20,7 @@ in order to construct your ``NewsletterManager``. Configuring lazy services is one answer to this. With a lazy service, a "proxy" of the ``mailer`` service is actually injected. It looks and acts -just like the ``mailer``, except that the ``mailer`` isn't actually instantiated +like the ``mailer``, except that the ``mailer`` isn't actually instantiated until you interact with the proxy in some way. .. caution:: diff --git a/service_container/parent_services.rst b/service_container/parent_services.rst index d39e7ddaf20..619ac11452c 100644 --- a/service_container/parent_services.rst +++ b/service_container/parent_services.rst @@ -58,9 +58,8 @@ Your child service classes may look like this:: // ... } -Just as you use PHP inheritance to avoid duplication in your PHP code, the -service container allows you to extend parent services in order to avoid -duplicated service definitions: +The service container allows you to extend parent services in order to +avoid duplicated service definitions: .. configuration-block:: diff --git a/service_container/service_subscribers_locators.rst b/service_container/service_subscribers_locators.rst index 796184198dd..1fcd744aa4b 100644 --- a/service_container/service_subscribers_locators.rst +++ b/service_container/service_subscribers_locators.rst @@ -13,7 +13,7 @@ the explicit dependency injection since services are not all meant to be ``lazy`` (see :doc:`/service_container/lazy_services`). This can typically be the case in your controllers, where you may inject several -services in the constructor, but the action executed only uses some of them. +services in the constructor, but the action called only uses some of them. Another example are applications that implement the `Command pattern`_ using a CommandBus to map command handlers by Command class names and use them to handle their respective command when it is asked for:: diff --git a/service_container/tags.rst b/service_container/tags.rst index 2819c1bd267..3e1f7a6c338 100644 --- a/service_container/tags.rst +++ b/service_container/tags.rst @@ -55,7 +55,7 @@ initialization of TwigBundle and added to Twig as extensions. Other tags are used to integrate your services into other systems. For a list of all the tags available in the core Symfony Framework, check out :doc:`/reference/dic_tags`. Each of these has a different effect on your service -and many tags require additional arguments (beyond just the ``name`` parameter). +and many tags require additional arguments (beyond the ``name`` parameter). **For most users, this is all you need to know**. If you want to go further and learn how to create your own custom tags, keep reading. diff --git a/setup.rst b/setup.rst index 5639435267f..8e8f7c5610e 100644 --- a/setup.rst +++ b/setup.rst @@ -170,10 +170,10 @@ following example: $ cd my-project/ $ composer require logger -If you execute that command in a Symfony application which doesn't use Flex, -you'll see a Composer error explaining that ``logger`` is not a valid package -name. However, if the application has Symfony Flex installed, that command -installs and enables all the packages needed to use the official Symfony logger. +If you run that command in a Symfony application which doesn't use Flex, you'll +see a Composer error explaining that ``logger`` is not a valid package name. +However, if the application has Symfony Flex installed, that command installs +and enables all the packages needed to use the official Symfony logger. .. _recipes-description: diff --git a/setup/homestead.rst b/setup/homestead.rst index 9802122a20d..d9526949b55 100644 --- a/setup/homestead.rst +++ b/setup/homestead.rst @@ -28,7 +28,7 @@ Setting Up a Symfony Application Imagine you've installed your Symfony application in ``~/projects/symfony_demo`` on your local system. You first need Homestead to -sync your files in this project. Execute ``homestead edit`` to edit the +sync your files in this project. Run ``homestead edit`` to edit the Homestead configuration and configure the ``~/projects`` directory: .. code-block:: yaml diff --git a/setup/symfony_server.rst b/setup/symfony_server.rst index 0068cabf193..f942fde3f12 100644 --- a/setup/symfony_server.rst +++ b/setup/symfony_server.rst @@ -9,7 +9,7 @@ Although this server is not intended for production use, it supports HTTP/2, TLS/SSL, automatic generation of security certificates, local domains, and many other features that sooner or later you'll need when developing web projects. Moreover, the server is not tied to Symfony and you can also use it with any -PHP application and even with HTML/SPA (single page applications). +PHP application and even with HTML or single page applications. Installation ------------ diff --git a/setup/unstable_versions.rst b/setup/unstable_versions.rst index be199a783d5..27036493fd4 100644 --- a/setup/unstable_versions.rst +++ b/setup/unstable_versions.rst @@ -11,14 +11,14 @@ Creating a New Project Based on an Unstable Symfony Version Suppose that the Symfony 4.0 version hasn't been released yet and you want to create a new project to test its features. First, `install the Composer package manager`_. Then, open a command console, enter your project's directory and -execute the following command: +run the following command: .. code-block:: terminal # Download the absolute latest commit $ composer create-project symfony/skeleton my_project -s dev -Once the command finishes its execution, you'll have a new Symfony project created +Once the command finishes, you'll have a new Symfony project created in the ``my_project/`` directory. Upgrading your Project to an Unstable Symfony Version diff --git a/setup/upgrade_major.rst b/setup/upgrade_major.rst index f22c92aa4bd..89f80ae109f 100644 --- a/setup/upgrade_major.rst +++ b/setup/upgrade_major.rst @@ -47,7 +47,7 @@ in your browser, these notices are shown in the web dev toolbar: :class: with-browser Ultimately, you should aim to stop using the deprecated functionality. -Sometimes, this is easy: the warning might tell you exactly what to change. +Sometimes the warning might tell you exactly what to change. But other times, the warning might be unclear: a setting somewhere might cause a class deeper to trigger the warning. In this case, Symfony does its diff --git a/setup/upgrade_minor.rst b/setup/upgrade_minor.rst index 89c83f5c160..09a88124fa8 100644 --- a/setup/upgrade_minor.rst +++ b/setup/upgrade_minor.rst @@ -79,7 +79,7 @@ Next, use Composer to download new versions of the libraries: In theory, you should be done! However, you *may* need to make a few changes to your code to get everything working. Additionally, some features you're -using might still work, but might now be deprecated. While that's just fine, +using might still work, but might now be deprecated. While that's fine, if you know about these deprecations, you can start to fix them over time. Every version of Symfony comes with an UPGRADE file (e.g. `UPGRADE-4.4.md`_) diff --git a/testing.rst b/testing.rst index 820ad1cc533..2b2abbcf3aa 100644 --- a/testing.rst +++ b/testing.rst @@ -63,8 +63,8 @@ If you want to test an entire feature of your application (e.g. registering as a user or generating an invoice), see the section about :ref:`Functional Tests `. Writing Symfony unit tests is no different from writing standard PHPUnit -unit tests. Suppose, for example, that you have an *incredibly* simple class -called ``Calculator`` in the ``src/Util/`` directory of the app:: +unit tests. Suppose, for example, that you have an class called ``Calculator`` +in the ``src/Util/`` directory of the app:: // src/Util/Calculator.php namespace App\Util; @@ -105,8 +105,8 @@ of your application:: ``src/Util/`` directory, put the test in the ``tests/Util/`` directory. -Just like in your real application - autoloading is automatically enabled -via the ``vendor/autoload.php`` file (as configured by default in the +Like in your real application - autoloading is automatically enabled via the +``vendor/autoload.php`` file (as configured by default in the ``phpunit.xml.dist`` file). You can also limit a test run to a directory or a specific test file: @@ -671,7 +671,7 @@ Accessing the Profiler Data On each request, you can enable the Symfony profiler to collect data about the internal handling of that request. For example, the profiler could be used to -verify that a given page executes less than a certain number of database +verify that a given page runs less than a certain number of database queries when loading. To get the Profiler for the last request, do the following:: diff --git a/testing/insulating_clients.rst b/testing/insulating_clients.rst index ad7820688b5..e2a5b8d9ff4 100644 --- a/testing/insulating_clients.rst +++ b/testing/insulating_clients.rst @@ -38,7 +38,7 @@ can insulate your clients:: $this->assertEquals(Response::HTTP_CREATED, $harry->getResponse()->getStatusCode()); $this->assertRegExp('/Hello/', $sally->getResponse()->getContent()); -Insulated clients transparently execute their requests in a dedicated and +Insulated clients transparently run their requests in a dedicated and clean PHP process, thus avoiding any side effects. .. tip:: diff --git a/testing/profiling.rst b/testing/profiling.rst index bfe336442ec..882d2bdbf15 100644 --- a/testing/profiling.rst +++ b/testing/profiling.rst @@ -58,7 +58,7 @@ tests significantly. That's why Symfony disables it by default: ]); Setting ``collect`` to ``true`` enables the profiler for all tests. However, if -you need the profiler just in a few tests, you can keep it disabled globally and +you need the profiler only in a few tests, you can keep it disabled globally and enable the profiler individually on each test by calling ``$client->enableProfiler()``. diff --git a/translation.rst b/translation.rst index 1c0caf7aff3..19525ea38ce 100644 --- a/translation.rst +++ b/translation.rst @@ -110,7 +110,7 @@ Translation of text is done through the ``translator`` service (:class:`Symfony\\Component\\Translation\\Translator`). To translate a block of text (called a *message*), use the :method:`Symfony\\Component\\Translation\\Translator::trans` method. Suppose, -for example, that you're translating a simple message from inside a controller:: +for example, that you're translating a static message from inside a controller:: // ... use Symfony\Contracts\Translation\TranslatorInterface; @@ -124,7 +124,7 @@ for example, that you're translating a simple message from inside a controller:: .. _translation-resources: -When this code is executed, Symfony will attempt to translate the message +When this code is run, Symfony will attempt to translate the message "Symfony is great" based on the ``locale`` of the user. For this to work, you need to tell Symfony how to translate the message via a "translation resource", which is usually a file that contains a collection of translations diff --git a/validation.rst b/validation.rst index 2df2d65ba63..837514f55c5 100644 --- a/validation.rst +++ b/validation.rst @@ -8,8 +8,8 @@ Validation is a very common task in web applications. Data entered in forms needs to be validated. Data also needs to be validated before it is written into a database or passed to a web service. -Symfony provides a `Validator`_ component that makes this task easy and -transparent. This component is based on the `JSR303 Bean Validation specification`_. +Symfony provides a `Validator`_ component to handle this for you. This +component is based on the `JSR303 Bean Validation specification`_. Installation ------------ @@ -39,13 +39,13 @@ your application:: private $name; } -So far, this is just an ordinary class that serves some purpose inside your -application. The goal of validation is to tell you if the data -of an object is valid. For this to work, you'll configure a list of rules -(called :ref:`constraints `) that the object must -follow in order to be valid. These rules are usually defined using PHP code or -annotations but they can also be defined as ``.yaml`` or -``.xml`` files inside the ``config/validator/`` directory: +So far, this is an ordinary class that serves some purpose inside your +application. The goal of validation is to tell you if the data of an object is +valid. For this to work, you'll configure a list of rules (called +:ref:`constraints `) that the object must follow in +order to be valid. These rules are usually defined using PHP code or +annotations but they can also be defined as ``.yaml`` or ``.xml`` files inside +the ``config/validator/`` directory: For example, to guarantee that the ``$name`` property is not empty, add the following: diff --git a/validation/custom_constraint.rst b/validation/custom_constraint.rst index 68210299dc9..5d5ae9fa22c 100644 --- a/validation/custom_constraint.rst +++ b/validation/custom_constraint.rst @@ -5,9 +5,9 @@ How to Create a custom Validation Constraint ============================================ You can create a custom constraint by extending the base constraint class, -:class:`Symfony\\Component\\Validator\\Constraint`. -As an example you're going to create a simple validator that checks if a string -contains only alphanumeric characters. +:class:`Symfony\\Component\\Validator\\Constraint`. As an example you're +going to create a basic validator that checks if a string contains only +alphanumeric characters. Creating the Constraint Class ----------------------------- @@ -40,7 +40,7 @@ Creating the Validator itself As you can see, a constraint class is fairly minimal. The actual validation is performed by another "constraint validator" class. The constraint validator class is specified by the constraint's ``validatedBy()`` method, which -includes some simple default logic:: +has this default logic:: // in the base Symfony\Component\Validator\Constraint class public function validatedBy() @@ -52,7 +52,7 @@ In other words, if you create a custom ``Constraint`` (e.g. ``MyConstraint``), Symfony will automatically look for another class, ``MyConstraintValidator`` when actually performing the validation. -The validator class is also simple, and only has one required method ``validate()``:: +The validator class only has one required method ``validate()``:: // src/Validator/Constraints/ContainsAlphanumericValidator.php namespace App\Validator\Constraints; @@ -103,7 +103,7 @@ The ``addViolation()`` method call finally adds the violation to the context. Using the new Validator ----------------------- -You can use custom validators just as the ones provided by Symfony itself: +You can use custom validators like the ones provided by Symfony itself: .. configuration-block:: diff --git a/validation/groups.rst b/validation/groups.rst index 68daaeb6561..b25c82236fc 100644 --- a/validation/groups.rst +++ b/validation/groups.rst @@ -8,7 +8,7 @@ By default, when validating an object all constraints of this class will be checked whether or not they actually pass. In some cases, however, you will need to validate an object against only *some* constraints on that class. To do this, you can organize each constraint into one or more "validation -groups" and then apply validation against just one group of constraints. +groups" and then apply validation against one group of constraints. For example, suppose you have a ``User`` class, which is used both when a user registers and when a user updates their contact information later: diff --git a/validation/raw_values.rst b/validation/raw_values.rst index 34f8b7ac09e..cd25bec0653 100644 --- a/validation/raw_values.rst +++ b/validation/raw_values.rst @@ -4,7 +4,7 @@ How to Validate Raw Values (Scalar Values and Arrays) ===================================================== -Usually you will be validating entire objects. But sometimes, you just want +Usually you will be validating entire objects. But sometimes, you want to validate a simple value - like to verify that a string is a valid email address. From inside a controller, it looks like this:: @@ -102,6 +102,6 @@ Validation of arrays is possible using the ``Collection`` constraint:: $violations = $validator->validate($input, $constraint, $groups); The ``validate()`` method returns a :class:`Symfony\\Component\\Validator\\ConstraintViolationList` -object, which acts just like an array of errors. Each error in the collection +object, which acts like an array of errors. Each error in the collection is a :class:`Symfony\\Component\\Validator\\ConstraintViolation` object, which holds the error message on its ``getMessage()`` method. diff --git a/workflow.rst b/workflow.rst index 3c4ded35890..0eee96f8a66 100644 --- a/workflow.rst +++ b/workflow.rst @@ -313,7 +313,7 @@ order: * ``workflow.[workflow name].transition.[transition name]`` ``workflow.enter`` - The subject is about to enter a new place. This event is triggered just + The subject is about to enter a new place. This event is triggered right before the subject places are updated, which means that the marking of the subject is not yet updated with the new places. @@ -595,7 +595,7 @@ This class has these additional methods: Blocking Transitions -------------------- -The execution of the workflow can be controlled by executing custom logic to +The execution of the workflow can be controlled by calling custom logic to decide if the current transition is blocked or allowed before applying it. This feature is provided by "guards", which can be used in two ways. @@ -812,8 +812,7 @@ Storing Metadata In case you need it, you can store arbitrary metadata in workflows, their places, and their transitions using the ``metadata`` option. This metadata can -be as simple as the title of the workflow or as complex as your own application -requires: +be only the title of the workflow or very complex objects: .. configuration-block::