diff --git a/.doctor-rst.yaml b/.doctor-rst.yaml index f8a111cf2c6..4b2c3ad80cc 100644 --- a/.doctor-rst.yaml +++ b/.doctor-rst.yaml @@ -29,6 +29,7 @@ rules: no_blank_line_after_filepath_in_yaml_code_block: ~ no_brackets_in_method_directive: ~ no_composer_req: ~ + no_contraction: ~ no_directive_after_shorthand: ~ no_explicit_use_of_code_block_php: ~ no_inheritdoc: ~ diff --git a/_build/maintainer_guide.rst b/_build/maintainer_guide.rst index fcee70f8f90..043524e24eb 100644 --- a/_build/maintainer_guide.rst +++ b/_build/maintainer_guide.rst @@ -3,7 +3,7 @@ Symfony Docs Maintainer Guide The `symfony/symfony-docs`_ repository stores the Symfony project documentation and is managed by the `Symfony Docs team`_. This article explains in detail some -of those management tasks, so it's only useful for maintainers and not regular +of those management tasks, so it is only useful for maintainers and not regular readers or Symfony developers. Reviewing Pull Requests @@ -17,7 +17,7 @@ but there are extra things to keep in mind for maintainers: * Don't assume that contributors know what you think is obvious (e.g. lots of them don't know what to "squash commits" means). * Don't use acronyms like IMO, IIRC, etc. or complex English words (most - contributors are not native in English and it's intimidating for them). + contributors are not native in English and it is intimidating for them). * Never engage in a heated discussion. Lock it right away using GitHub. * Never discuss non-tech issues. Some PRs are related to our Diversity initiative and some people always try to drag you into politics. Never engage in that and @@ -26,14 +26,14 @@ but there are extra things to keep in mind for maintainers: Fixing Minor Issues Yourself ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -It's common for new contributors to make lots of minor mistakes in the syntax -of the RST format used in the docs. It's also common for non English speakers to +It is common for new contributors to make lots of minor mistakes in the syntax +of the RST format used in the docs. It is also common for non English speakers to make minor typos. Even if your intention is good, if you add lots of comments when reviewing a -first contribution, that person will probably not contribute again. It's better +first contribution, that person will probably not contribute again. It is better to fix the minor errors and typos yourself while merging. If that person -contributes again, it's OK to mention some of the minor issues to educate them. +contributes again, it is OK to mention some of the minor issues to educate them. .. code-block:: terminal @@ -53,7 +53,7 @@ contributes again, it's OK to mention some of the minor issues to educate them. $ git commit -a # Use "Minor reword", "Minor tweak", etc. as the commit message - # now run the 'push' command shown above by 'gh' (it's different each time) + # now run the 'push' command shown above by 'gh' (it is different each time) $ git push gh "5.4" refs/notes/github-comments Merging Pull Requests @@ -93,8 +93,8 @@ interface. Then: Merging Process ~~~~~~~~~~~~~~~ -At first, it's common to make mistakes and merge things badly. Don't worry. This -has happened to all of us and we've always been able to recover from any mistake. +At first, it is common to make mistakes and merge things badly. Don't worry. This +has happened to all of us and we have always been able to recover from any mistake. Step 1: Select the right branch to merge ........................................ @@ -107,7 +107,7 @@ PRs must be merged in the oldest maintained branch where they are applicable: usually means ``master``. And don't forget to check that new feature includes the ``versionadded`` directive. -It's very common for contributors (specially newcomers) to select the wrong +It is very common for contributors (specially newcomers) to select the wrong branch for their PRs, so we must always check if the change should go to the proposed branch or not. @@ -121,12 +121,12 @@ Never use GitHub's web interface (or desktop clients) to merge PRs or to solve merge conflicts. Always use the ``gh`` tool for anything related to merges. We require two approval votes from team members before merging a PR, except if -it's a typo, a small change or clearly an error. +it is a typo, a small change or clearly an error. If a PR contains lots of commits, there's no need to ask the contributor to squash them. The ``gh`` tool does that automatically. The only exceptions are when commits are made by more than one person and when there's a merge commit. -``gh`` can't squash commits in those cases, so it's better to ask to the +``gh`` cannot squash commits in those cases, so it is better to ask to the original contributor. .. code-block:: terminal @@ -147,13 +147,13 @@ original contributor. $ git push origin $ git push upstream -It's common to have to change the branch where a PR is merged. Instead of asking +It is common to have to change the branch where a PR is merged. Instead of asking the contributors to rebase their PRs, the "gh" tool can change the branch with the ``-s`` option: .. code-block:: terminal - # e.g. this PR was sent against 'master', but it's merged in '4.4' + # e.g. this PR was sent against 'master', but it is merged in '4.4' $ gh merge 11160 -s 4.4 Sometimes, when changing the branch, you may face rebase issues, but they are @@ -228,7 +228,7 @@ maintained branches until ``master``. Imagine that you are merging a PR against .. tip:: - When the support of a Symfony branch ends, it's recommended to delete your + When the support of a Symfony branch ends, it is recommended to delete your local branch to avoid merging in it unawarely: .. code-block:: terminal @@ -250,12 +250,12 @@ When updating your local branches before merging: $ git checkout 4.4 $ git merge upstream/4.4 -It's possible that you merge a wrong upstream branch unawarely. It's usually -easy to spot because you'll see lots of conflicts: +It is possible that you merge a wrong upstream branch unawarely. It is usually +easy to spot because you will see lots of conflicts: .. code-block:: terminal - # DON'T DO THIS! It's a wrong branch merge + # DON'T DO THIS! It is a wrong branch merge $ git checkout 4.4 $ git merge upstream/5.0 @@ -269,12 +269,12 @@ local branch and check it out again: $ git checkout 4.4 upstream/4.4 If you did push the wrong branch merge, ask for help in the documentation -mergers chat and we'll help solve the problem. +mergers chat and we will help solve the problem. Solving merge conflicts ....................... -When merging things to upper branches, most of the times you'll see conflicts: +When merging things to upper branches, most of the times you will see conflicts: .. code-block:: terminal @@ -303,7 +303,7 @@ the marker used by Git for conflicts) and then do this: .. tip:: When there are lots of conflicts, look for ``<<<<<`` with your editor in all - docs before committing the changes. It's common to forget about some of them. + docs before committing the changes. It is common to forget about some of them. If you prefer, you can run this too: ``git grep --cached "<<<<<"``. Merging deleted files diff --git a/_includes/_annotation_loader_tip.rst.inc b/_includes/_annotation_loader_tip.rst.inc index 0f4267b07f5..39ebffa373c 100644 --- a/_includes/_annotation_loader_tip.rst.inc +++ b/_includes/_annotation_loader_tip.rst.inc @@ -5,7 +5,7 @@ .. tip:: - Annotation classes aren't loaded automatically, so you must load them + Annotation classes are not loaded automatically, so you must load them using a class loader like this:: use Composer\Autoload\ClassLoader; diff --git a/_includes/_rewrite_rule_tip.rst.inc b/_includes/_rewrite_rule_tip.rst.inc index fe69882c4f7..b4f581e4d1a 100644 --- a/_includes/_rewrite_rule_tip.rst.inc +++ b/_includes/_rewrite_rule_tip.rst.inc @@ -2,5 +2,5 @@ By using rewrite rules in your :doc:`web server configuration `, - the ``index.php`` won't be needed and you will have beautiful, clean URLs + the ``index.php`` will not be needed and you will have beautiful, clean URLs (e.g. ``/show``). diff --git a/best_practices.rst b/best_practices.rst index 32af3400c0a..f411e128726 100644 --- a/best_practices.rst +++ b/best_practices.rst @@ -40,7 +40,7 @@ Use the Default Directory Structure ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Unless your project follows a development practice that imposes a certain -directory structure, follow the default Symfony directory structure. It's flat, +directory structure, follow the default Symfony directory structure. It is flat, self-explanatory and not coupled to Symfony: .. code-block:: text @@ -123,7 +123,7 @@ Then, use just one or two words to describe the purpose of the parameter: app.dir: '...' # do this: short but easy to understand names app.contents_dir: '...' - # it's OK to use dots, underscores, dashes or nothing, but always + # it is OK to use dots, underscores, dashes or nothing, but always # be consistent and use the same format for all the parameters app.dir.contents: '...' app.contents-dir: '...' @@ -150,7 +150,7 @@ Twig templates and Doctrine entities, whereas parameters are only available from places with access to the :doc:`service container `. The only notable disadvantage of using constants for this kind of configuration -values is that it's complicated to redefine their values in your tests. +values is that it is complicated to redefine their values in your tests. Business Logic -------------- @@ -191,9 +191,9 @@ Use the YAML Format to Configure your own Services If you use the :ref:`default services.yaml configuration `, most services will be configured automatically. However, in some edge cases -you'll need to configure services (or parts of them) manually. +you will need to configure services (or parts of them) manually. -YAML is the format recommended configuring services because it's friendly to +YAML is the format recommended configuring services because it is friendly to newcomers and concise, but Symfony also supports XML and PHP configuration. Use Attributes to Define the Doctrine Entity Mapping @@ -203,7 +203,7 @@ Doctrine entities are plain PHP objects that you store in some "database". Doctrine only knows about your entities through the mapping metadata configured for your model classes. -Doctrine supports several metadata formats, but it's recommended to use PHP +Doctrine supports several metadata formats, but it is recommended to use PHP attributes because they are by far the most convenient and agile way of setting up and looking for mapping information. @@ -222,7 +222,7 @@ or checking security permissions. Extending your controllers from this base controller couples your application to Symfony. Coupling is generally wrong, but it may be OK in this case because -controllers shouldn't contain any business logic. Controllers should contain +controllers should not contain any business logic. Controllers should contain nothing more than a few lines of *glue-code*, so you are not coupling the important parts of your application. @@ -257,12 +257,12 @@ constructor arguments. Use ParamConverters If They Are Convenient ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -If you're using :doc:`Doctrine `, then you can *optionally* use the +If you are using :doc:`Doctrine `, then you can *optionally* use the `ParamConverter`_ to automatically query for an entity and pass it as an argument to your controller. It will also show a 404 page if no entity can be found. If the logic to get an entity from a route variable is more complex, instead of -configuring the ParamConverter, it's better to make the Doctrine query inside +configuring the ParamConverter, it is better to make the Doctrine query inside the controller (e.g. by calling to a :doc:`Doctrine repository method `). Templates @@ -298,16 +298,16 @@ Add Form Buttons in Templates Form classes should be agnostic to where they will be used. For example, the button of a form used to both create and edit items should change from "Add new" -to "Save changes" depending on where it's used. +to "Save changes" depending on where it is used. -Instead of adding buttons in form classes or the controllers, it's recommended +Instead of adding buttons in form classes or the controllers, it is recommended to add buttons in the templates. This also improves the separation of concerns because the button styling (CSS class and other attributes) is defined in the template instead of in a PHP class. However, if you create a :doc:`form with multiple submit buttons ` you should define them in the controller instead of the template. Otherwise, you -won't be able to check which button was clicked when handling the form in the controller. +will not be able to check which button was clicked when handling the form in the controller. Define Validation Constraints on the Underlying Object ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -323,7 +323,7 @@ Use a Single Action to Render and Process the Form :ref:`Rendering forms ` and :ref:`processing forms ` are two of the main tasks when handling forms. Both are too similar (most of the -time, almost identical), so it's much simpler to let a single controller action +time, almost identical), so it is much simpler to let a single controller action handle both. .. _best-practice-internationalization: @@ -336,7 +336,7 @@ Use the XLIFF Format for Your Translation Files Of all the translation formats supported by Symfony (PHP, Qt, ``.po``, ``.mo``, JSON, CSV, INI, etc.), ``XLIFF`` and ``gettext`` have the best support in the tools used -by professional translators. And since it's based on XML, you can validate ``XLIFF`` +by professional translators. And since it is based on XML, you can validate ``XLIFF`` file contents as you write them. Symfony also supports notes in XLIFF files, making them more user-friendly for @@ -361,7 +361,7 @@ Define a Single Firewall ~~~~~~~~~~~~~~~~~~~~~~~~ Unless you have two legitimately different authentication systems and users -(e.g. form login for the main site and a token system for your API only), it's +(e.g. form login for the main site and a token system for your API only), it is recommended to have only one firewall to keep things simple. Additionally, you should use the ``anonymous`` key under your firewall. If you @@ -439,7 +439,7 @@ checks that all application URLs load successfully:: } Add this test while creating your application because it requires little effort -and checks that none of your pages returns an error. Later, you'll add more +and checks that none of your pages returns an error. Later, you will add more specific tests for each page. .. _hardcode-urls-in-a-functional-test: @@ -447,13 +447,13 @@ specific tests for each page. Hard-code URLs in a Functional Test ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -In Symfony applications, it's recommended to :ref:`generate URLs ` +In Symfony applications, it is recommended to :ref:`generate URLs ` using routes to automatically update all links when a URL changes. However, if a -public URL changes, users won't be able to browse it unless you set up a +public URL changes, users will not be able to browse it unless you set up a redirection to the new URL. -That's why it's recommended to use raw URLs in tests instead of generating them -from routes. Whenever a route changes, tests will fail, and you'll know that +That's why it is recommended to use raw URLs in tests instead of generating them +from routes. Whenever a route changes, tests will fail, and you will know that you must set up a redirection. .. _`Symfony Demo`: https://github.com/symfony/demo diff --git a/bundles.rst b/bundles.rst index ed194614c34..0e98d0dedbe 100644 --- a/bundles.rst +++ b/bundles.rst @@ -30,7 +30,7 @@ file:: Symfony\Bundle\MonologBundle\MonologBundle::class => ['all' => true], Doctrine\Bundle\DoctrineBundle\DoctrineBundle::class => ['all' => true], Sensio\Bundle\FrameworkExtraBundle\SensioFrameworkExtraBundle::class => ['all' => true], - // this bundle is enabled only in 'dev' and 'test', so you can't use it in 'prod' + // this bundle is enabled only in 'dev' and 'test', so you cannot use it in 'prod' Symfony\Bundle\WebProfilerBundle\WebProfilerBundle::class => ['dev' => true, 'test' => true], ]; @@ -69,7 +69,7 @@ called ``AcmeTestBundle.php``:: This empty class is the only piece you need to create the new bundle. Though commonly empty, this class is powerful and can be used to customize the behavior -of the bundle. Now that you've created the bundle, enable it:: +of the bundle. Now that you have created the bundle, enable it:: // config/bundles.php return [ @@ -111,7 +111,7 @@ to be adjusted if needed: A bundle can be as small or large as the feature it implements. It contains only the files you need and nothing else. -As you move through the guides, you'll learn how to persist objects to a +As you move through the guides, you will learn how to persist objects to a database, create and validate forms, create translations for your application, write tests and much more. Each of these has their own place and role within the bundle. diff --git a/bundles/best_practices.rst b/bundles/best_practices.rst index f1c8e4ad555..0b6940c648d 100644 --- a/bundles/best_practices.rst +++ b/bundles/best_practices.rst @@ -165,7 +165,7 @@ CSS or any other language. Doctrine Entities/Documents --------------------------- -If the bundle includes Doctrine ORM entities and/or ODM documents, it's +If the bundle includes Doctrine ORM entities and/or ODM documents, it is recommended to define their mapping using XML files stored in ``Resources/config/doctrine/``. This allows to override that mapping using the :doc:`standard Symfony mechanism to override bundle parts `. @@ -255,7 +255,7 @@ Installation Bundles should set ``"type": "symfony-bundle"`` in their ``composer.json`` file. With this, :ref:`Symfony Flex ` will be able to automatically -enable your bundle when it's installed. +enable your bundle when it is installed. If your bundle requires any setup (e.g. configuration, new files, changes to ``.gitignore``, etc), then you should create a `Symfony Flex recipe`_. @@ -467,7 +467,7 @@ Services If the bundle defines services, they must be prefixed with the bundle alias instead of using fully qualified class names like you do in your project services. For example, AcmeBlogBundle services must be prefixed with ``acme_blog``. -The reason is that bundles shouldn't rely on features such as service autowiring +The reason is that bundles should not rely on features such as service autowiring or autoconfiguration to not impose an overhead when compiling application services. In addition, services not meant to be used by the application directly, should @@ -508,7 +508,7 @@ The ``composer.json`` file should include at least the following metadata: a string (or array of strings) with a `valid license identifier`_, such as ``MIT``. ``autoload`` - This information is used by Symfony to load the classes of the bundle. It's + This information is used by Symfony to load the classes of the bundle. It is recommended to use the `PSR-4`_ autoload standard: use the namespace as key, and the location of the bundle's main class (relative to ``composer.json``) as value. As the main class is located in the ``src/`` directory of the bundle: diff --git a/bundles/configuration.rst b/bundles/configuration.rst index c49e53e9987..12e461da313 100644 --- a/bundles/configuration.rst +++ b/bundles/configuration.rst @@ -6,7 +6,7 @@ How to Create Friendly Configuration for a Bundle ================================================= If you open your main application configuration directory (usually -``config/packages/``), you'll see a number of different files, such as +``config/packages/``), you will see a number of different files, such as ``framework.yaml``, ``twig.yaml`` and ``doctrine.yaml``. Each of these configures a specific bundle, allowing you to define options at a high level and then let the bundle make all the low-level, complex changes based on your @@ -103,7 +103,7 @@ load correct services and parameters inside an "Extension" class. .. note:: The root key of your bundle configuration (``acme_social`` in the previous - example) is automatically determined from your bundle name (it's the + example) is automatically determined from your bundle name (it is the `snake case`_ of the bundle name without the ``Bundle`` suffix ). .. seealso:: @@ -231,7 +231,7 @@ thrown):: // $config['twitter']['client_id'] and $config['twitter']['client_secret'] } -The ``processConfiguration()`` method uses the configuration tree you've defined +The ``processConfiguration()`` method uses the configuration tree you have defined in the ``Configuration`` class to validate, normalize and merge all the configuration arrays together. @@ -306,7 +306,7 @@ In your extension, you can load this and dynamically set its arguments:: Using the Config component is fully optional. The ``load()`` method gets an array of configuration values. You can instead parse these arrays yourself (e.g. by overriding configurations and using :phpfunction:`isset` to check - for the existence of a value). Be aware that it'll be very hard to support XML:: + for the existence of a value). Be aware that it will be very hard to support XML:: public function load(array $configs, ContainerBuilder $containerBuilder) { diff --git a/bundles/extension.rst b/bundles/extension.rst index eadd0ab864a..4105c1ff77c 100644 --- a/bundles/extension.rst +++ b/bundles/extension.rst @@ -15,7 +15,7 @@ Creating an Extension Class In order to load service configuration, you have to create a Dependency Injection (DI) Extension for your bundle. By default, the Extension class must -follow these conventions (but later you'll learn how to skip them if needed): +follow these conventions (but later you will learn how to skip them if needed): * It has to live in the ``DependencyInjection`` namespace of the bundle; @@ -40,7 +40,7 @@ This is how the extension of an AcmeHelloBundle should look like:: { public function load(array $configs, ContainerBuilder $containerBuilder) { - // ... you'll load the files here later + // ... you will load the files here later } } @@ -144,6 +144,6 @@ the full classmap executing the ``dump-autoload`` command of Composer. .. caution:: - This technique can't be used when the classes to compile use the ``__DIR__`` + This technique cannot be used when the classes to compile use the ``__DIR__`` or ``__FILE__`` constants, because their values will change when loading these classes from the ``classes.php`` file. diff --git a/bundles/override.rst b/bundles/override.rst index 6cf3d37c386..a2bb763f95d 100644 --- a/bundles/override.rst +++ b/bundles/override.rst @@ -93,7 +93,7 @@ Entities & Entity Mapping ------------------------- Overriding entity mapping is only possible if a bundle provides a mapped -superclass (such as the ``User`` entity in the FOSUserBundle). It's possible to +superclass (such as the ``User`` entity in the FOSUserBundle). It is possible to override attributes and associations in this way. Learn more about this feature and its limitations in `the Doctrine documentation`_. diff --git a/bundles/prepend_extension.rst b/bundles/prepend_extension.rst index 53f0fed9da9..e4462404bad 100644 --- a/bundles/prepend_extension.rst +++ b/bundles/prepend_extension.rst @@ -7,7 +7,7 @@ How to Simplify Configuration of Multiple Bundles When building reusable and extensible applications, developers are often faced with a choice: either create a single large bundle or multiple smaller -bundles. Creating a single bundle has the drawback that it's impossible for +bundles. Creating a single bundle has the drawback that it is impossible for users to remove unused functionality. Creating multiple bundles has the drawback that configuration becomes more tedious and settings often need to be repeated for various bundles. @@ -80,7 +80,7 @@ in case a specific other bundle is not registered:: } } - // get the configuration of AcmeHelloExtension (it's a list of configuration) + // get the configuration of AcmeHelloExtension (it is a list of configuration) $configs = $containerBuilder->getExtensionConfig($this->getAlias()); // iterate in reverse to preserve the original order after prepending the config @@ -162,4 +162,4 @@ More than one Bundle using PrependExtensionInterface If there is more than one bundle that prepends the same extension and defines the same key, the bundle that is registered **first** will take priority: -next bundles won't override this specific config setting. +next bundles will not override this specific config setting. diff --git a/cache.rst b/cache.rst index e9ff5d41de2..0133ed2825b 100644 --- a/cache.rst +++ b/cache.rst @@ -102,7 +102,7 @@ adapter (template) they use by using the ``app`` and ``system`` key like: .. tip:: - While it is possible to reconfigure the ``system`` cache, it's recommended + While it is possible to reconfigure the ``system`` cache, it is recommended to keep the default configuration applied to it by Symfony. The Cache component comes with a series of adapters pre-configured: @@ -495,9 +495,9 @@ chain of adapters. A cache chain combines several cache pools into a single one. When storing an item in a cache chain, Symfony stores it in all pools sequentially. When -retrieving an item, Symfony tries to get it from the first pool. If it's not +retrieving an item, Symfony tries to get it from the first pool. If it is not found, it tries the next pools until the item is found or an exception is thrown. -Because of this behavior, it's recommended to define the adapters in the chain +Because of this behavior, it is recommended to define the adapters in the chain in order from fastest to slowest. If an error happens when storing an item in a pool, Symfony stores it in the diff --git a/components/asset.rst b/components/asset.rst index 9903702823e..8165bf201ed 100644 --- a/components/asset.rst +++ b/components/asset.rst @@ -34,7 +34,7 @@ simple. Hardcoding URLs can be a disadvantage because: carefully update the URLs of all assets included in all templates. The Asset component allows to move assets effortlessly just by changing the base path value associated with the package of assets; -* **It's nearly impossible to use multiple CDNs**: this technique requires +* **It is nearly impossible to use multiple CDNs**: this technique requires you to change the URL of the asset randomly for each request. The Asset component provides out-of-the-box support for any number of multiple CDNs, both regular (``http://``) and secure (``https://``). diff --git a/components/browser_kit.rst b/components/browser_kit.rst index 0d1f774e845..a868241245a 100644 --- a/components/browser_kit.rst +++ b/components/browser_kit.rst @@ -187,7 +187,7 @@ request format (uppercase, underscores instead of dashes and prefixed with ``HTT Before saving those headers to the request, they are lower-cased, with ``HTTP_`` stripped, and underscores converted into dashes. -If you're making a request to an application that has special rules about header +If you are making a request to an application that has special rules about header capitalization or punctuation, override the ``getHeaders()`` method, which must return an associative array of headers:: diff --git a/components/cache.rst b/components/cache.rst index 29c1f0fd42b..b3209b46b82 100644 --- a/components/cache.rst +++ b/components/cache.rst @@ -150,7 +150,7 @@ The following cache adapters are available: Generic Caching (PSR-6) ----------------------- -To use the generic PSR-6 Caching abilities, you'll need to learn its key +To use the generic PSR-6 Caching abilities, you will need to learn its key concepts: **Item** diff --git a/components/cache/adapters/filesystem_adapter.rst b/components/cache/adapters/filesystem_adapter.rst index 2a168d2522e..9300e876403 100644 --- a/components/cache/adapters/filesystem_adapter.rst +++ b/components/cache/adapters/filesystem_adapter.rst @@ -59,7 +59,7 @@ Working with Tags ----------------- In order to use tag-based invalidation, you can wrap your adapter in -:class:`Symfony\\Component\\Cache\\Adapter\\TagAwareAdapter`, but it's often +:class:`Symfony\\Component\\Cache\\Adapter\\TagAwareAdapter`, but it is often more interesting to use the dedicated :class:`Symfony\\Component\\Cache\\Adapter\\FilesystemTagAwareAdapter`. Since tag invalidation logic is implemented using links on filesystem, this adapter offers better read performance when using tag-based invalidation:: diff --git a/components/cache/adapters/memcached_adapter.rst b/components/cache/adapters/memcached_adapter.rst index 009ead59cbd..9805d8bc5e3 100644 --- a/components/cache/adapters/memcached_adapter.rst +++ b/components/cache/adapters/memcached_adapter.rst @@ -199,7 +199,7 @@ Available Options ``recv_timeout`` (type: ``int``, default: ``0``) Specifies the amount of time (in microseconds) before timing out during an outgoing socket (read) operation. - When the ``no_block`` option isn't enabled, this will allow you to still have timeouts on the reading of data. + When the ``no_block`` option is not enabled, this will allow you to still have timeouts on the reading of data. Valid option values include ``0`` or *any positive integer*. @@ -211,7 +211,7 @@ Available Options ``send_timeout`` (type: ``int``, default: ``0``) Specifies the amount of time (in microseconds) before timing out during an - incoming socket (send) operation. When the ``no_block`` option isn't enabled, + incoming socket (send) operation. When the ``no_block`` option is not enabled, this will allow you to still have timeouts on the sending of data. Valid option values include ``0`` or *any positive integer*. diff --git a/components/cache/adapters/php_array_cache_adapter.rst b/components/cache/adapters/php_array_cache_adapter.rst index 52259b87f86..b6741041af3 100644 --- a/components/cache/adapters/php_array_cache_adapter.rst +++ b/components/cache/adapters/php_array_cache_adapter.rst @@ -12,7 +12,7 @@ is mostly read-only after warm-up:: use Symfony\Component\Cache\Adapter\FilesystemAdapter; use Symfony\Component\Cache\Adapter\PhpArrayAdapter; - // somehow, decide it's time to warm up the cache! + // somehow, decide it is time to warm up the cache! if ($needsWarmup) { // some static values $values = [ diff --git a/components/cache/adapters/redis_adapter.rst b/components/cache/adapters/redis_adapter.rst index 9596386b80e..516619550d9 100644 --- a/components/cache/adapters/redis_adapter.rst +++ b/components/cache/adapters/redis_adapter.rst @@ -195,7 +195,7 @@ Available Options requires phpredis v4 or higher and a TCP-keepalive enabled server. ``lazy`` (type: ``bool``, default: ``null``) - Enables or disables lazy connections to the backend. It's ``false`` by + Enables or disables lazy connections to the backend. It is ``false`` by default when using this as a stand-alone component and ``true`` by default when using it inside a Symfony application. @@ -227,7 +227,7 @@ Available Options Working with Tags ----------------- -In order to use tag-based invalidation, you can wrap your adapter in :class:`Symfony\\Component\\Cache\\Adapter\\TagAwareAdapter`, but when Redis is used as backend, it's often more interesting to use the dedicated :class:`Symfony\\Component\\Cache\\Adapter\\RedisTagAwareAdapter`. Since tag invalidation logic is implemented in Redis itself, this adapter offers better performance when using tag-based invalidation:: +In order to use tag-based invalidation, you can wrap your adapter in :class:`Symfony\\Component\\Cache\\Adapter\\TagAwareAdapter`, but when Redis is used as backend, it is often more interesting to use the dedicated :class:`Symfony\\Component\\Cache\\Adapter\\RedisTagAwareAdapter`. Since tag invalidation logic is implemented in Redis itself, this adapter offers better performance when using tag-based invalidation:: use Symfony\Component\Cache\Adapter\RedisAdapter; use Symfony\Component\Cache\Adapter\RedisTagAwareAdapter; diff --git a/components/cache/cache_items.rst b/components/cache/cache_items.rst index 027bb59f4a9..c843fb6318d 100644 --- a/components/cache/cache_items.rst +++ b/components/cache/cache_items.rst @@ -71,7 +71,7 @@ By default, cache items are stored permanently. In practice, this "permanent storage" can vary greatly depending on the type of cache being used, as explained in the :doc:`/components/cache/cache_pools` article. -However, in some applications it's common to use cache items with a shorter +However, in some applications it is common to use cache items with a shorter lifespan. Consider for example an application which caches the latest news just for one minute. In those cases, use the ``expiresAfter()`` method to set the number of seconds to cache the item:: @@ -102,7 +102,7 @@ In order to decide if the returned object represents a value coming from the sto or not, caches use the concept of hits and misses: * **Cache Hits** occur when the requested item is found in the cache, its value - is not corrupted or invalid and it hasn't expired; + is not corrupted or invalid and it has not expired; * **Cache Misses** are the opposite of hits, so they occur when the item is not found in the cache, its value is corrupted or invalid for any reason or the item has expired. diff --git a/components/cache/cache_pools.rst b/components/cache/cache_pools.rst index 375b514fe80..5415c066118 100644 --- a/components/cache/cache_pools.rst +++ b/components/cache/cache_pools.rst @@ -102,7 +102,7 @@ If you need to fetch several cache items simultaneously, use instead the // ... $stocks = $cache->getItems(['AAPL', 'FB', 'GOOGL', 'MSFT']); -Again, if any of the keys doesn't represent a valid cache item, you won't get +Again, if any of the keys doesn't represent a valid cache item, you will not get a ``null`` value but an empty ``CacheItem`` object. The last method related to fetching cache items is ``hasItem($key)``, which diff --git a/components/cache/psr6_psr16_adapters.rst b/components/cache/psr6_psr16_adapters.rst index 6b98d26744b..05f44003fc5 100644 --- a/components/cache/psr6_psr16_adapters.rst +++ b/components/cache/psr6_psr16_adapters.rst @@ -31,7 +31,7 @@ example:: } } -But, you already have a PSR-16 cache object, and you'd like to pass this to the class +But, you already have a PSR-16 cache object, and you would like to pass this to the class instead. No problem! The Cache component provides the :class:`Symfony\\Component\\Cache\\Adapter\\Psr16Adapter` class for exactly this use-case:: @@ -66,7 +66,7 @@ example:: } } -But, you already have a PSR-6 cache pool object, and you'd like to pass this to +But, you already have a PSR-6 cache pool object, and you would like to pass this to the class instead. No problem! The Cache component provides the :class:`Symfony\\Component\\Cache\\Psr16Cache` class for exactly this use-case:: diff --git a/components/config/definition.rst b/components/config/definition.rst index 8d336ea17b3..82845fc96e7 100644 --- a/components/config/definition.rst +++ b/components/config/definition.rst @@ -215,7 +215,7 @@ Before defining the children of an array node, you can provide options like: ``isRequired()`` is also called). ``addDefaultsIfNotSet()`` If any child nodes have default values, use them if explicit values - haven't been provided. + have not been provided. ``normalizeKeys(false)`` If called (with ``false``), keys with dashes are *not* normalized to underscores. It is recommended to use this with prototype nodes where the user will define @@ -657,7 +657,7 @@ normalization would make both of these ``auto_connect``. .. caution:: - The target key will not be altered if it's mixed like + The target key will not be altered if it is mixed like ``foo-bar_moo`` or if it already exists. Another difference between YAML and XML is in the way arrays of values may diff --git a/components/console/helpers/formatterhelper.rst b/components/console/helpers/formatterhelper.rst index 78dd3dfa581..30d01a13072 100644 --- a/components/console/helpers/formatterhelper.rst +++ b/components/console/helpers/formatterhelper.rst @@ -14,7 +14,7 @@ in the default helper set and you can get it by calling $formatter = $this->getHelper('formatter'); -The methods return a string, which you'll usually render to the console by +The methods return a string, which you will usually render to the console by passing it to the :method:`OutputInterface::writeln ` method. @@ -60,7 +60,7 @@ method creates the desired output. If you pass ``true`` as third parameter, the block will be formatted with more padding (one blank line above and below the messages and 2 spaces on the left and right). -The exact "style" you use in the block is up to you. In this case, you're using +The exact "style" you use in the block is up to you. In this case, you are using the pre-defined ``error`` style, but there are other styles, or you can create your own. See :doc:`/console/coloring`. diff --git a/components/console/helpers/processhelper.rst b/components/console/helpers/processhelper.rst index 45572d90a66..9ce7d6d7252 100644 --- a/components/console/helpers/processhelper.rst +++ b/components/console/helpers/processhelper.rst @@ -4,7 +4,7 @@ Process Helper ============== -The Process Helper shows processes as they're running and reports +The Process Helper shows processes as they are running and reports useful information about process status. To display process details, use the :class:`Symfony\\Component\\Console\\Helper\\ProcessHelper` diff --git a/components/console/helpers/progressbar.rst b/components/console/helpers/progressbar.rst index 2a2c9473cff..883ebc4c87d 100644 --- a/components/console/helpers/progressbar.rst +++ b/components/console/helpers/progressbar.rst @@ -92,7 +92,7 @@ that the progress bar display is refreshed with a 100% completion. If you want to output something while the progress bar is running, call :method:`Symfony\\Component\\Console\\Helper\\ProgressBar::clear` first. - After you're done, call + After you are done, call :method:`Symfony\\Component\\Console\\Helper\\ProgressBar::display` to show the progress bar again. @@ -158,7 +158,7 @@ level of verbosity of the ``OutputInterface`` instance: .. note:: - If you call a command with the quiet flag (``-q``), the progress bar won't + If you call a command with the quiet flag (``-q``), the progress bar will not be displayed. Instead of relying on the verbosity mode of the current command, you can also @@ -377,7 +377,7 @@ of the custom placeholders:: Displaying Multiple Progress Bars --------------------------------- -When using :ref:`Console output sections ` it's +When using :ref:`Console output sections ` it is possible to display multiple progress bars at the same time and change their progress independently:: diff --git a/components/console/helpers/questionhelper.rst b/components/console/helpers/questionhelper.rst index d3e7498049b..db2d40c48c6 100644 --- a/components/console/helpers/questionhelper.rst +++ b/components/console/helpers/questionhelper.rst @@ -537,4 +537,4 @@ This way you can test any user interaction (even complex ones) by passing the ap On Windows systems Symfony uses a special binary to implement hidden questions. This means that those questions don't use the default ``Input`` - console object and therefore you can't test them on Windows. + console object and therefore you cannot test them on Windows. diff --git a/components/console/helpers/table.rst b/components/console/helpers/table.rst index 7c75b4808db..521282f451e 100644 --- a/components/console/helpers/table.rst +++ b/components/console/helpers/table.rst @@ -394,7 +394,7 @@ Modifying Rendered Tables ------------------------- The ``render()`` method requires passing the entire table contents. However, -sometimes that information is not available beforehand because it's generated +sometimes that information is not available beforehand because it is generated dynamically. In those cases, use the :method:`Symfony\\Component\\Console\\Helper\\Table::appendRow` method, which takes the same arguments as the ``addRow()`` method, to add rows at the bottom diff --git a/components/console/usage.rst b/components/console/usage.rst index e3a6601eec5..efaa2ad3933 100644 --- a/components/console/usage.rst +++ b/components/console/usage.rst @@ -148,7 +148,7 @@ can run it with: $ php application.php d:g Fabien - # as long as it's unambiguous, you can also mix upper and lower case + # as long as it is unambiguous, you can also mix upper and lower case # php application.php Demo:g Fabien # php application.php de:Gr Fabien # php application.php DE:Gre Fabien diff --git a/components/css_selector.rst b/components/css_selector.rst index 649a34293a4..d557c061aab 100644 --- a/components/css_selector.rst +++ b/components/css_selector.rst @@ -28,7 +28,7 @@ Usage Why Use CSS selectors? ~~~~~~~~~~~~~~~~~~~~~~ -When you're parsing an HTML or an XML document, by far the most powerful +When you are parsing an HTML or an XML document, by far the most powerful method is `XPath`_. XPath expressions are incredibly flexible, so there is almost always an diff --git a/components/dependency_injection/compilation.rst b/components/dependency_injection/compilation.rst index 2d471177c58..f3aee572f6a 100644 --- a/components/dependency_injection/compilation.rst +++ b/components/dependency_injection/compilation.rst @@ -429,7 +429,7 @@ been run, use:: You can also control the order in which compiler passes are run for each compilation phase. Use the optional third argument of ``addCompilerPass()`` to set the priority as an integer number. The default priority is ``0`` and the higher -its value, the earlier it's executed:: +its value, the earlier it is executed:: // ... // FirstPass is executed after SecondPass because its priority is lower diff --git a/components/dom_crawler.rst b/components/dom_crawler.rst index 14dee197db6..285c3ba1770 100644 --- a/components/dom_crawler.rst +++ b/components/dom_crawler.rst @@ -65,9 +65,9 @@ tree. The DomCrawler will attempt to automatically fix your HTML to match the official specification. For example, if you nest a ``

`` tag inside another ``

`` tag, it will be moved to be a sibling of the parent tag. - This is expected and is part of the HTML5 spec. But if you're getting + This is expected and is part of the HTML5 spec. But if you are getting unexpected behavior, this could be a cause. And while the DomCrawler - isn't meant to dump content, you can see the "fixed" version of your HTML + is not meant to dump content, you can see the "fixed" version of your HTML by :ref:`dumping it `. .. note:: @@ -153,8 +153,8 @@ and :method:`Symfony\\Component\\DomCrawler\\Crawler::filter`:: :method:`Symfony\\Component\\DomCrawler\\Crawler::setDefaultNamespacePrefix` method. - The default namespace is removed when loading the content if it's the only - namespace in the document. It's done to simplify the XPath queries. + The default namespace is removed when loading the content if it is the only + namespace in the document. It is done to simplify the XPath queries. Namespaces can be explicitly registered with the :method:`Symfony\\Component\\DomCrawler\\Crawler::registerNamespace` method:: @@ -285,7 +285,7 @@ Adding the Content The crawler supports multiple ways of adding the content, but they are mutually exclusive, so you can only use one of them to add content (e.g. if you pass the -content to the ``Crawler`` constructor, you can't call ``addContent()`` later):: +content to the ``Crawler`` constructor, you cannot call ``addContent()`` later):: $crawler = new Crawler(''); @@ -329,7 +329,7 @@ and :phpclass:`DOMNode` objects:: .. sidebar:: Manipulating and Dumping a ``Crawler`` These methods on the ``Crawler`` are intended to initially populate your - ``Crawler`` and aren't intended to be used to further manipulate a DOM + ``Crawler`` and are not intended to be used to further manipulate a DOM (though this is possible). However, since the ``Crawler`` is a set of :phpclass:`DOMElement` objects, you can use any method or property available on :phpclass:`DOMElement`, :phpclass:`DOMNode` or :phpclass:`DOMDocument`. @@ -585,14 +585,14 @@ and uploading files:: Using the Form Data ................... -What's the point of doing all of this? If you're testing internally, you +What's the point of doing all of this? If you are testing internally, you can grab the information off of your form as if it had just been submitted by using the PHP values:: $values = $form->getPhpValues(); $files = $form->getPhpFiles(); -If you're using an external HTTP client, you can use the form to grab all +If you are using an external HTTP client, you can use the form to grab all of the information you need to create a POST request for the form:: $uri = $form->getUri(); diff --git a/components/event_dispatcher.rst b/components/event_dispatcher.rst index 206fde3fc99..3b22278e8e4 100644 --- a/components/event_dispatcher.rst +++ b/components/event_dispatcher.rst @@ -32,7 +32,7 @@ truly extensible. Take an example from :doc:`the HttpKernel component `. Once a ``Response`` object has been created, it may be useful to allow other elements in the system to modify it (e.g. add some cache headers) before -it's actually used. To make this possible, the Symfony kernel throws an +(it is actually used. To make this possible, the Symfony kernel throws an event - ``kernel.response``. Here's how it works: * A *listener* (PHP object) tells a central *dispatcher* object that it @@ -70,10 +70,10 @@ Usage Events ~~~~~~ -When an event is dispatched, it's identified by a unique name (e.g. +When an event is dispatched, it is identified by a unique name (e.g. ``kernel.response``), which any number of listeners might be listening to. An :class:`Symfony\\Contracts\\EventDispatcher\\Event` instance is also -created and passed to all of the listeners. As you'll see later, the ``Event`` +created and passed to all of the listeners. As you will see later, the ``Event`` object itself often contains data about the event being dispatched. .. index:: @@ -158,7 +158,7 @@ The ``addListener()`` method takes up to three arguments: a string representing a function or an array representing an object method or a class method. - So far, you've seen how PHP objects can be registered as listeners. + So far, you have seen how PHP objects can be registered as listeners. You can also register PHP `Closures`_ as event listeners:: use Symfony\Contracts\EventDispatcher\Event; @@ -282,7 +282,7 @@ Creating an Event Class Suppose you want to create a new event - ``order.placed`` - that is dispatched each time a customer orders a product with your application. When dispatching -this event, you'll pass a custom event instance that has access to the placed +this event, you will pass a custom event instance that has access to the placed order. Start by creating this custom event class and documenting it:: namespace Acme\Store\Event; diff --git a/components/event_dispatcher/immutable_dispatcher.rst b/components/event_dispatcher/immutable_dispatcher.rst index 25940825065..18b12329ea3 100644 --- a/components/event_dispatcher/immutable_dispatcher.rst +++ b/components/event_dispatcher/immutable_dispatcher.rst @@ -31,7 +31,7 @@ Now, inject that into an ``ImmutableEventDispatcher``:: $immutableDispatcher = new ImmutableEventDispatcher($dispatcher); -You'll need to use this new dispatcher in your project. +You will need to use this new dispatcher in your project. If you are trying to execute one of the methods which modifies the dispatcher (e.g. ``addListener()``), a ``BadMethodCallException`` is thrown. diff --git a/components/expression_language.rst b/components/expression_language.rst index be84457995f..786376c3f0d 100644 --- a/components/expression_language.rst +++ b/components/expression_language.rst @@ -421,7 +421,7 @@ expressions (e.g. the request, the current user, etc.): .. caution:: When using variables in expressions, avoid passing untrusted data into the - array of variables. If you can't avoid that, sanitize non-alphanumeric + array of variables. If you cannot avoid that, sanitize non-alphanumeric characters in untrusted data to prevent malicious users from injecting control characters and altering the expression. @@ -501,7 +501,7 @@ Both ``evaluate()`` and ``compile()`` can handle ``ParsedExpression`` and AST Dumping and Editing ----------------------- -It's difficult to manipulate or inspect the expressions created with the ExpressionLanguage +It is difficult to manipulate or inspect the expressions created with the ExpressionLanguage component, because the expressions are plain strings. A better approach is to turn those expressions into an AST. In computer science, `AST`_ (*Abstract Syntax Tree*) is *"a tree representation of the structure of source code written diff --git a/components/filesystem.rst b/components/filesystem.rst index 3b6c92ad6fa..a247f53e5ab 100644 --- a/components/filesystem.rst +++ b/components/filesystem.rst @@ -296,7 +296,7 @@ exception on failure:: :method:`Symfony\\Component\\Filesystem\\Filesystem::dumpFile` saves the given contents into a file. It does this in an atomic manner: it writes a temporary -file first and then moves it to the new file location when it's finished. +file first and then moves it to the new file location when it is finished. This means that the user will always see either the complete old file or complete new file (but never a partially-written file):: diff --git a/components/finder.rst b/components/finder.rst index ecae414084a..9bd568245dd 100644 --- a/components/finder.rst +++ b/components/finder.rst @@ -85,7 +85,7 @@ Exclude directories from matching with the // directories passed as argument must be relative to the ones defined with the in() method $finder->in(__DIR__)->exclude('ruby'); -It's also possible to ignore directories that you don't have permission to read:: +It is also possible to ignore directories that you don't have permission to read:: $finder->ignoreUnreadableDirs()->in(__DIR__); diff --git a/components/form.rst b/components/form.rst index 882e720f357..061659d98fc 100644 --- a/components/form.rst +++ b/components/form.rst @@ -68,7 +68,7 @@ factory. Request Handling ~~~~~~~~~~~~~~~~ -To process form data, you'll need to call the :method:`Symfony\\Component\\Form\\Form::handleRequest` +To process form data, you will need to call the :method:`Symfony\\Component\\Form\\Form::handleRequest` method:: $form->handleRequest(); @@ -145,7 +145,7 @@ the CSRF generator and validated when binding the form. .. tip:: - If you're not using the HttpFoundation component, you can use + If you are not using the HttpFoundation component, you can use :class:`Symfony\\Component\\Security\\Csrf\\TokenStorage\\NativeSessionTokenStorage` instead, which relies on PHP's native session handling:: @@ -164,12 +164,12 @@ You can disable CSRF protection per form using the ``csrf_protection`` option:: Twig Templating ~~~~~~~~~~~~~~~ -If you're using the Form component to process HTML forms, you'll need a way to +If you are using the Form component to process HTML forms, you will need a way to render your form as HTML form fields (complete with field values, errors, and labels). If you use `Twig`_ as your template engine, the Form component offers a rich integration. -To use the integration, you'll need the twig bridge, which provides integration +To use the integration, you will need the twig bridge, which provides integration between Twig and several Symfony components: .. code-block:: terminal @@ -179,7 +179,7 @@ between Twig and several Symfony components: The TwigBridge integration provides you with several :ref:`Twig Functions ` that help you render the HTML widget, label, help and errors for each field -(as well as a few other things). To configure the integration, you'll need +(as well as a few other things). To configure the integration, you will need to bootstrap or access Twig and add the :class:`Symfony\\Bridge\\Twig\\Extension\\FormExtension`:: use Symfony\Bridge\Twig\Extension\FormExtension; @@ -242,7 +242,7 @@ For general details on rendering forms, see :doc:`/form/form_customization`. Translation ~~~~~~~~~~~ -If you're using the Twig integration with one of the default form theme files +If you are using the Twig integration with one of the default form theme files (e.g. ``form_div_layout.html.twig``), there is a Twig filter (``trans``) that is used for translating form labels, errors, option text and other strings. @@ -294,18 +294,18 @@ Validation ~~~~~~~~~~ The Form component comes with tight (but optional) integration with Symfony's -Validator component. If you're using a different solution for validation, +Validator component. If you are using a different solution for validation, no problem! Take the submitted/bound data of your form (which is an array or object) and pass it through your own validation system. To use the integration with Symfony's Validator component, first make sure -it's installed in your application: +it is installed in your application: .. code-block:: terminal $ composer require symfony/validator -If you're not familiar with Symfony's Validator component, read more about +If you are not familiar with Symfony's Validator component, read more about it: :doc:`/validation`. The Form component comes with a :class:`Symfony\\Component\\Form\\Extension\\Validator\\ValidatorExtension` class, which automatically applies validation to your data on bind. These @@ -359,7 +359,7 @@ and then access it whenever you need to build a form. ``$formFactory``. The point here is that you will probably need to create this object in some more "global" way so you can access it from anywhere. -Exactly how you gain access to your one form factory is up to you. If you're +Exactly how you gain access to your one form factory is up to you. If you are using a service container (like provided with the :doc:`DependencyInjection component `), then you should add the form factory to your container and grab it out whenever @@ -374,7 +374,7 @@ Creating a simple Form .. tip:: - If you're using the Symfony Framework, then the form factory is available + If you are using the Symfony Framework, then the form factory is available automatically as a service called ``form.factory``, you can inject it as ``Symfony\Component\Form\FormFactoryInterface``. Also, the default base controller class has a :method:`Symfony\\Bundle\\FrameworkBundle\\Controller\\AbstractController::createFormBuilder` @@ -436,13 +436,13 @@ for each new field you want to create. The first argument to ``add()`` is the name of your field, and the second is the fully qualified class name. The Form component comes with a lot of :doc:`built-in types `. -Now that you've built your form, learn how to :ref:`render ` +Now that you have built your form, learn how to :ref:`render ` it and :ref:`process the form submission `. Setting default Values ~~~~~~~~~~~~~~~~~~~~~~ -If you need your form to load with some default values (or you're building +If you need your form to load with some default values (or you are building an "edit" form), pass in the default data when creating your form builder: .. configuration-block:: @@ -519,8 +519,8 @@ done by passing a special form "view" object to your template (notice the That's it! By printing ``form_widget(form)``, each field in the form is rendered, along with a label and error message (if there is one). While this is -convenient, it's not very flexible (yet). Usually, you'll want to render each -form field individually so you can control how the form looks. You'll learn how +convenient,it is not very flexible (yet). Usually, you will want to render each +form field individually so you can control how the form looks. You will learn how to do that in the :doc:`form customization ` article. Changing a Form's Method and Action @@ -644,7 +644,7 @@ method: The form's ``createView()`` method should be called *after* ``handleRequest()`` is called. Otherwise, when using :doc:`form events `, changes done - in the ``*_SUBMIT`` events won't be applied to the view (like validation errors). + in the ``*_SUBMIT`` events will not be applied to the view (like validation errors). This defines a common form "workflow", which contains 3 different possibilities: @@ -760,7 +760,7 @@ Clearing Form Errors Any errors can be manually cleared using the :method:`Symfony\\Component\\Form\\ClearableErrorsInterface::clearErrors` -method. This is useful when you'd like to validate the form without showing +method. This is useful when you would like to validate the form without showing validation errors to the user (i.e. during a partial AJAX submission or :doc:`dynamic form modification `). diff --git a/components/http_foundation.rst b/components/http_foundation.rst index 062a21e4e87..b2ca0a737f0 100644 --- a/components/http_foundation.rst +++ b/components/http_foundation.rst @@ -583,7 +583,7 @@ represented by a PHP callable instead of a string:: been called before or the ``output_buffering`` ``php.ini`` option is enabled, you must call ``ob_flush()`` before ``flush()``. - Additionally, PHP isn't the only layer that can buffer output. Your web + Additionally, PHP is not the only layer that can buffer output. Your web server might also buffer based on its configuration. Some servers, such as nginx, let you disable buffering at the config level or by adding a special HTTP header in the response:: @@ -667,7 +667,7 @@ It is possible to delete the file after the response is sent with the :method:`Symfony\\Component\\HttpFoundation\\BinaryFileResponse::deleteFileAfterSend` method. Please note that this will not work when the ``X-Sendfile`` header is set. -If the size of the served file is unknown (e.g. because it's being generated on the fly, +If the size of the served file is unknown (e.g. because it is being generated on the fly, or because a PHP stream filter is registered on it, etc.), you can pass a ``Stream`` instance to ``BinaryFileResponse``. This will disable ``Range`` and ``Content-Length`` handling, switching to chunked encoding instead:: @@ -737,7 +737,7 @@ The ``JsonResponse`` class sets the ``Content-Type`` header to JSONP Callback ~~~~~~~~~~~~~~ -If you're using JSONP, you can set the callback function that the data should +If you are using JSONP, you can set the callback function that the data should be passed to:: $response->setCallback('handleResponse'); diff --git a/components/http_kernel.rst b/components/http_kernel.rst index 5108f1db35b..83b4580075e 100644 --- a/components/http_kernel.rst +++ b/components/http_kernel.rst @@ -8,7 +8,7 @@ The HttpKernel Component The HttpKernel component provides a structured process for converting a ``Request`` into a ``Response`` by making use of the EventDispatcher - component. It's flexible enough to create a full-stack framework (Symfony), + component. It is flexible enough to create a full-stack framework (Symfony), a micro-framework (Silex) or an advanced CMS system (Drupal). Installation @@ -98,7 +98,7 @@ Initially, using the :class:`Symfony\\Component\\HttpKernel\\HttpKernel` does not take many steps. You create an :doc:`event dispatcher ` and a :ref:`controller and argument resolver ` -(explained below). To complete your working kernel, you'll add more event +(explained below). To complete your working kernel, you will add more event listeners to the events discussed below:: use Symfony\Component\EventDispatcher\EventDispatcher; @@ -192,7 +192,7 @@ attributes). .. note:: When setting a response for the ``kernel.request`` event, the propagation - is stopped. This means listeners with lower priority won't be executed. + is stopped. This means listeners with lower priority will not be executed. .. sidebar:: ``kernel.request`` in the Symfony Framework @@ -405,7 +405,7 @@ return a ``Response``. .. note:: When setting a response for the ``kernel.view`` event, the propagation - is stopped. This means listeners with lower priority won't be executed. + is stopped. This means listeners with lower priority will not be executed. .. sidebar:: ``kernel.view`` in the Symfony Framework @@ -534,7 +534,7 @@ below for more details). .. note:: When setting a response for the ``kernel.exception`` event, the propagation - is stopped. This means listeners with lower priority won't be executed. + is stopped. This means listeners with lower priority will not be executed. .. sidebar:: ``kernel.exception`` in the Symfony Framework @@ -583,7 +583,7 @@ below for more details). Creating an Event Listener -------------------------- -As you've seen, you can create and attach event listeners to any of the events +As you have seen, you can create and attach event listeners to any of the events dispatched during the ``HttpKernel::handle()`` cycle. Typically a listener is a PHP class with a method that's executed, but it can be anything. For more information on creating and attaching event listeners, see :doc:`/components/event_dispatcher`. @@ -614,7 +614,7 @@ kernel.exception ``KernelEvents::EXCEPTION`` :class:`Sym A full Working Example ---------------------- -When using the HttpKernel component, you're free to attach any listeners +When using the HttpKernel component, you are free to attach any listeners to the core events, use any controller resolver that implements the :class:`Symfony\\Component\\HttpKernel\\Controller\\ControllerResolverInterface` and use any argument resolver that implements the @@ -669,7 +669,7 @@ Sub Requests In addition to the "main" request that's sent into ``HttpKernel::handle()``, you can also send a so-called "sub request". A sub request looks and acts like any other request, but typically serves to render just one small portion of -a page instead of a full page. You'll most commonly make sub-requests from +a page instead of a full page. You will most commonly make sub-requests from your controller (or perhaps from inside a template, that's being rendered by your controller). diff --git a/components/lock.rst b/components/lock.rst index c1ceabd4438..12b57b46eb5 100644 --- a/components/lock.rst +++ b/components/lock.rst @@ -8,7 +8,7 @@ The Lock Component The Lock Component creates and manages `locks`_, a mechanism to provide exclusive access to a shared resource. -If you're using the Symfony Framework, read the +If you are using the Symfony Framework, read the :doc:`Symfony Framework Lock documentation `. Installation @@ -151,8 +151,8 @@ the ``createLock()`` method. If needed, these locks can also be released early with the ``release()`` method. The trickiest part when working with expiring locks is choosing the right TTL. -If it's too short, other processes could acquire the lock before finishing the -job; if it's too long and the process crashes before calling the ``release()`` +If it is too short, other processes could acquire the lock before finishing the +job; if it is too long and the process crashes before calling the ``release()`` method, the resource will stay locked until the timeout:: // ... @@ -170,10 +170,10 @@ method, the resource will stay locked until the timeout:: .. tip:: - To avoid leaving the lock in a locked state, it's recommended to wrap the + To avoid leaving the lock in a locked state, it is recommended to wrap the job in a try/catch/finally block to always try to release the expiring lock. -In case of long-running tasks, it's better to start with a not too long TTL and +In case of long-running tasks, it is better to start with a not too long TTL and then use the :method:`Symfony\\Component\\Lock\\LockInterface::refresh` method to reset the TTL to its original value:: @@ -285,7 +285,7 @@ to acquire the lock in a blocking mode:: The `priority policy`_ of Symfony's shared locks depends on the underlying store (e.g. Redis store prioritizes readers vs writers). -When a read-only lock is acquired with the ``acquireRead()`` method, it's +When a read-only lock is acquired with the ``acquireRead()`` method, it is possible to **promote** the lock, and change it to a write lock, by calling the ``acquire()`` method:: @@ -299,7 +299,7 @@ possible to **promote** the lock, and change it to a write lock, by calling the $lock->acquire(true); // Promote the lock to a write lock $this->update($userId); -In the same way, it's possible to **demote** a write lock, and change it to a +In the same way, it is possible to **demote** a write lock, and change it to a read-only lock by calling the ``acquireRead()`` method. When the provided store does not implement the @@ -331,11 +331,11 @@ lose the lock it acquired automatically:: // Perform a very long process that might exceed TTL of the lock if ($lock->isAcquired()) { - // Still all good, no other instance has acquired the lock in the meantime, we're safe + // Still all good, no other instance has acquired the lock in the meantime, we are safe $this->commit(); } else { // Bummer! Our lock has apparently exceeded TTL and another process has started in - // the meantime so it's not safe for us to commit. + // the meantime so it is not safe for us to commit. $this->rollback(); throw new \Exception('Process failed'); } @@ -349,7 +349,7 @@ lose the lock it acquired automatically:: .. [1] Technically, the true owners of the lock are the ones that share the same instance of ``Key``, not ``Lock``. But from a user perspective, ``Key`` is internal and you will likely only be working - with the ``Lock`` instance so it's easier to think of the ``Lock`` instance as being the one that + with the ``Lock`` instance so it is easier to think of the ``Lock`` instance as being the one that is the owner of the lock. .. _lock-stores: @@ -402,7 +402,7 @@ when the PHP process ends):: .. caution:: Beware that some file systems (such as some types of NFS) do not support - locking. In those cases, it's better to use a directory on a local disk + locking. In those cases, it is better to use a directory on a local disk drive or a remote store. .. _lock-store-memcached: @@ -693,7 +693,7 @@ PHP process is terminated:: Reliability ----------- -The component guarantees that the same resource can't be locked twice as long as +The component guarantees that the same resource cannot be locked twice as long as the component is used in the following way. Remote Stores @@ -770,7 +770,7 @@ time of the machine changes, a lock could be released sooner than expected. .. caution:: - To guarantee that date won't change, the NTP service should be disabled + To guarantee that date will not change, the NTP service should be disabled and the date should be updated when the service is stopped. FlockStore @@ -801,7 +801,7 @@ Some file systems (such as some types of NFS) do not support locking. Files on the file system can be removed during a maintenance operation. For instance, to clean up the ``/tmp`` directory or after a reboot of the machine -when a directory uses ``tmpfs``. It's not an issue if the lock is released when +when a directory uses ``tmpfs``. It is not an issue if the lock is released when the process ended, but it is in case of ``Lock`` reused between requests. .. caution:: @@ -821,7 +821,7 @@ be lost without notifying the running processes. .. caution:: - To avoid that someone else acquires a lock after a restart, it's recommended + To avoid that someone else acquires a lock after a restart, it is recommended to delay service start and wait at least as long as the longest lock TTL. By default Memcached uses a LRU mechanism to remove old entries when the service @@ -829,7 +829,7 @@ needs space to add new items. .. caution:: - The number of items stored in Memcached must be under control. If it's not + The number of items stored in Memcached must be under control. If it is not possible, LRU should be disabled and Lock should be stored in a dedicated Memcached service away from Cache. @@ -867,7 +867,7 @@ about `Expire Data from Collections by Setting TTL`_ in MongoDB. .. tip:: - ``MongoDbStore`` will attempt to automatically create a TTL index. It's + ``MongoDbStore`` will attempt to automatically create a TTL index. It is recommended to set constructor option ``gcProbablity`` to ``0.0`` to disable this behavior if you have manually dealt with TTL index creation. @@ -933,7 +933,7 @@ be lost without notifying the running processes. .. caution:: - To avoid that someone else acquires a lock after a restart, it's recommended + To avoid that someone else acquires a lock after a restart, it is recommended to delay service start and wait at least as long as the longest lock TTL. .. tip:: @@ -953,11 +953,11 @@ removed by mistake. CombinedStore ~~~~~~~~~~~~~ -Combined stores allow the storage of locks across several backends. It's a common +Combined stores allow the storage of locks across several backends. It is a common mistake to think that the lock mechanism will be more reliable. This is wrong. The ``CombinedStore`` will be, at best, as reliable as the least reliable of all managed stores. As soon as one managed store returns erroneous information, -the ``CombinedStore`` won't be reliable. +the ``CombinedStore`` will not be reliable. .. caution:: @@ -966,7 +966,7 @@ the ``CombinedStore`` won't be reliable. .. tip:: - Instead of using a cluster of Redis or Memcached servers, it's better to use + Instead of using a cluster of Redis or Memcached servers, it is better to use a ``CombinedStore`` with a single server per managed store. SemaphoreStore diff --git a/components/messenger.rst b/components/messenger.rst index 0831bba736e..0d4a7a1071f 100644 --- a/components/messenger.rst +++ b/components/messenger.rst @@ -274,7 +274,7 @@ them to the application. Imagine you already processed some "orders" in your application using a ``NewOrder`` message. Now you want to integrate with a 3rd party or a legacy -application but you can't use an API and need to use a shared CSV file with new +application but you cannot use an API and need to use a shared CSV file with new orders. You will read this CSV file and dispatch a ``NewOrder`` message. All you need to diff --git a/components/mime.rst b/components/mime.rst index a641283716e..f6007bbaf57 100644 --- a/components/mime.rst +++ b/components/mime.rst @@ -67,7 +67,7 @@ create messages from Twig templates, embed images, inline CSS and more. Details on how to use those features can be found in the Mailer documentation: :ref:`Twig: HTML & CSS `. -But if you're using the Mime component without the Symfony framework, you'll need +But if you are using the Mime component without the Symfony framework, you will need to handle a few setup details. Twig Setup @@ -117,10 +117,10 @@ Creating Raw Email Messages --------------------------- This is useful for advanced applications that need absolute control over every -email part. It's not recommended for applications with regular email +email part. It is not recommended for applications with regular email requirements because it adds complexity for no real gain. -Before continuing, it's important to have a look at the low level structure of +Before continuing, it is important to have a look at the low level structure of an email message. Consider a message which includes some content as both text and HTML, a single PNG image embedded in those contents and a PDF file attached to it. The MIME standard allows structuring this message in different ways, but @@ -262,7 +262,7 @@ Another useful utility allows to guess the MIME type of any given file:: Guessing the MIME type is a time-consuming process that requires inspecting part of the file contents. Symfony applies multiple guessing mechanisms, one -of them based on the PHP `fileinfo extension`_. It's recommended to install +of them based on the PHP `fileinfo extension`_. It is recommended to install that extension to improve the guessing performance. Adding a MIME Type Guesser @@ -294,7 +294,7 @@ You can add your own MIME type guesser by creating a class that implements MIME type guessers must be :ref:`registered as services ` and :doc:`tagged ` with the ``mime.mime_type_guesser`` tag. -If you're using the +If you are using the :ref:`default services.yaml configuration `, this is already done for you, thanks to :ref:`autoconfiguration `. diff --git a/components/options_resolver.rst b/components/options_resolver.rst index cabaf199c2b..0fe9fa62f0a 100644 --- a/components/options_resolver.rst +++ b/components/options_resolver.rst @@ -81,7 +81,7 @@ like the following when using the ``Mailer`` class:: No error will be shown. In the best case, the bug will appear during testing, but the developer will spend time looking for the problem. In the worst case, -the bug might not appear until it's deployed to the live system. +the bug might not appear until it is deployed to the live system. Fortunately, the :class:`Symfony\\Component\\OptionsResolver\\OptionsResolver` class helps you to fix this problem:: @@ -136,7 +136,7 @@ code:: } } -It's a good practice to split the option configuration into a separate method:: +It is a good practice to split the option configuration into a separate method:: // ... class Mailer @@ -496,7 +496,7 @@ these options, you can return the desired default value:: .. note:: - The closure is only executed if the ``port`` option isn't set by the user + The closure is only executed if the ``port`` option is not set by the user or overwritten in a subclass. A previously set default value can be accessed by adding a second argument to @@ -542,7 +542,7 @@ 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 comes +it is not possible to know whether the user passed this value or if it comes from the default:: // ... diff --git a/components/phpunit_bridge.rst b/components/phpunit_bridge.rst index 62dc3d3cb20..fcef154e6d5 100644 --- a/components/phpunit_bridge.rst +++ b/components/phpunit_bridge.rst @@ -292,7 +292,7 @@ Here is a summary that should help you pick the right configuration: Baseline Deprecations ..................... -If your application has some deprecations that you can't fix for some reasons, +If your application has some deprecations that you cannot fix for some reasons, you can tell Symfony to ignore them. The trick is to create a file with the allowed deprecations and define it as the "deprecation baseline". Deprecations inside that file are ignored but the rest of deprecations are still reported. @@ -325,7 +325,7 @@ By default, the bridge will display a detailed output with the number of deprecations and where they arise. If this is too much for you, you can use ``SYMFONY_DEPRECATIONS_HELPER=verbose=0`` to turn the verbose output off. -It's also possible to change verbosity per deprecation type. For example, using +It is also possible to change verbosity per deprecation type. For example, using ``quiet[]=indirect&quiet[]=other`` will hide details for deprecations of types "indirect" and "other". @@ -904,7 +904,7 @@ its ``bin/simple-phpunit`` command. It has the following features: The script writes the modified PHPUnit it builds in a directory that can be configured by the ``SYMFONY_PHPUNIT_DIR`` env var, or in the same directory as -the ``simple-phpunit`` if it is not provided. It's also possible to set this +the ``simple-phpunit`` if it is not provided. It is also possible to set this env var in the ``phpunit.xml.dist`` file. If you have installed the bridge through Composer, you can run it by calling e.g.: @@ -915,12 +915,12 @@ If you have installed the bridge through Composer, you can run it by calling e.g .. tip:: - It's possible to change the PHPUnit version by setting the + It is possible to change the PHPUnit version by setting the ``SYMFONY_PHPUNIT_VERSION`` env var in the ``phpunit.xml.dist`` file (e.g. ````). This is the preferred method as it can be committed to your version control repository. - It's also possible to set ``SYMFONY_PHPUNIT_VERSION`` as a real env var + It is also possible to set ``SYMFONY_PHPUNIT_VERSION`` as a real env var (not defined in a :ref:`dotenv file `). In the same way, ``SYMFONY_MAX_PHPUNIT_VERSION`` will set the maximum version @@ -937,7 +937,7 @@ If you have installed the bridge through Composer, you can run it by calling e.g If you still need to use ``prophecy`` (but not ``symfony/yaml``), then set the ``SYMFONY_PHPUNIT_REMOVE`` env var to ``symfony/yaml``. - It's also possible to set this env var in the ``phpunit.xml.dist`` file. + It is also possible to set this env var in the ``phpunit.xml.dist`` file. .. tip:: diff --git a/components/process.rst b/components/process.rst index 2752f25c0c1..956482e08a9 100644 --- a/components/process.rst +++ b/components/process.rst @@ -80,7 +80,7 @@ for new output before going to the next iteration:: The ``mustRun()`` method is identical to ``run()``, except that it will throw a :class:`Symfony\\Component\\Process\\Exception\\ProcessFailedException` -if the process couldn't be executed successfully (i.e. the process exited +if the process could not be executed successfully (i.e. the process exited with a non-zero code):: use Symfony\Component\Process\Exception\ProcessFailedException; @@ -100,7 +100,7 @@ with a non-zero code):: You can get the last output time in seconds by using the :method:`Symfony\\Component\\Process\\Process::getLastOutputTime` method. - This method returns ``null`` if the process wasn't started! + This method returns ``null`` if the process was not started! Configuring Process Options --------------------------- @@ -202,7 +202,7 @@ anonymous function to the .. note:: - This feature won't work as expected in servers using PHP output buffering. + This feature will not work as expected in servers using PHP output buffering. In those cases, either disable the `output_buffering`_ PHP option or use the :phpfunction:`ob_flush` PHP function to force sending the output buffer. @@ -259,8 +259,8 @@ are done doing other stuff:: Beware also that if you do that, the said PHP-FPM process will not be available to serve any new request until the subprocess is finished. This - means you can quickly block your FPM pool if you're not careful enough. - That is why it's generally way better not to do any fancy things even + means you can quickly block your FPM pool if you are not careful enough. + That is why it is generally way better not to do any fancy things even after the request is sent, but to use a job queue instead. :method:`Symfony\\Component\\Process\\Process::wait` takes one optional argument: diff --git a/components/property_info.rst b/components/property_info.rst index 7f20064fb69..6947cd5cc6b 100644 --- a/components/property_info.rst +++ b/components/property_info.rst @@ -228,7 +228,7 @@ provide whether properties are readable or writable as booleans:: The :class:`Symfony\\Component\\PropertyInfo\\Extractor\\ReflectionExtractor` looks for getter/isser/setter/hasser method in addition to whether or not a property is public -to determine if it's accessible. This based on how the :doc:`PropertyAccess ` +to determine if it is accessible. This based on how the :doc:`PropertyAccess ` works. .. _property-info-initializable: @@ -437,7 +437,7 @@ with the ``property_info`` service in the Symfony Framework:: // the `serializer_groups` option must be configured (may be set to null) $serializerExtractor->getProperties($class, ['serializer_groups' => ['mygroup']]); -If ``serializer_groups`` is set to ``null``, serializer groups metadata won't be +If ``serializer_groups`` is set to ``null``, serializer groups metadata will not be checked but you will get only the properties considered by the Serializer Component (notably the ``@Ignore`` annotation is taken into account). diff --git a/components/runtime.rst b/components/runtime.rst index 7b187acaeee..b321f0dd200 100644 --- a/components/runtime.rst +++ b/components/runtime.rst @@ -54,10 +54,10 @@ the component. This file runs the following logic: .. caution:: If you use the Composer ``--no-plugins`` option, the ``autoload_runtime.php`` - file won't be created. + file will not be created. If you use the Composer ``--no-scripts`` option, make sure your Composer version - is ``>=2.1.3``; otherwise the ``autoload_runtime.php`` file won't be created. + is ``>=2.1.3``; otherwise the ``autoload_runtime.php`` file will not be created. To make a console application, the bootstrap code would look like:: @@ -488,7 +488,7 @@ always using this ``ReactPHPRunner``:: return new ReactPHPRunner($application, $this->port); } - // if it's not a PSR-15 application, use the GenericRuntime to + // if it is not a PSR-15 application, use the GenericRuntime to // run the application (see "Resolvable Applications" above) return parent::getRunner($application); } diff --git a/components/serializer.rst b/components/serializer.rst index 347d04dd72f..aad583867df 100644 --- a/components/serializer.rst +++ b/components/serializer.rst @@ -146,7 +146,7 @@ in this case :class:`Symfony\\Component\\Serializer\\Encoder\\JsonEncoder`. Deserializing an Object ----------------------- -You'll now learn how to do the exact opposite. This time, the information +You will now learn how to do the exact opposite. This time, the information of the ``Person`` class would be encoded in XML format:: use App\Model\Person; @@ -641,7 +641,7 @@ and :class:`Symfony\\Component\\Serializer\\Normalizer\\PropertyNormalizer`:: CamelCase to snake_case ~~~~~~~~~~~~~~~~~~~~~~~ -In many formats, it's common to use underscores to separate words (also known +In many formats, it is common to use underscores to separate words (also known as snake_case). However, in Symfony applications is common to use CamelCase to name properties (even though the `PSR-1 standard`_ doesn't recommend any specific case for property names). @@ -1313,7 +1313,7 @@ context option to ``false``:: Collecting Type Errors While Denormalizing ------------------------------------------ -When denormalizing a payload to an object with typed properties, you'll get an +When denormalizing a payload to an object with typed properties, you will get an exception if the payload contains properties that don't have the same type as the object. @@ -1629,7 +1629,7 @@ If you want to deserialize such a structure, you need to add the :class:`Symfony\\Component\\Serializer\\Normalizer\\ArrayDenormalizer` to the set of normalizers. By appending ``[]`` to the type parameter of the :method:`Symfony\\Component\\Serializer\\Serializer::deserialize` method, -you indicate that you're expecting an array instead of a single object:: +you indicate that you are expecting an array instead of a single object:: use Symfony\Component\Serializer\Encoder\JsonEncoder; use Symfony\Component\Serializer\Normalizer\ArrayDenormalizer; @@ -1648,7 +1648,7 @@ Handling Constructor Arguments ------------------------------ If the class constructor defines arguments, as usually happens with -`Value Objects`_, the serializer won't be able to create the object if some +`Value Objects`_, the serializer will not be able to create the object if some arguments are missing. In those cases, use the ``default_constructor_arguments`` context option:: diff --git a/components/string.rst b/components/string.rst index 17edd37d802..932a9377640 100644 --- a/components/string.rst +++ b/components/string.rst @@ -164,7 +164,7 @@ Each string object can be transformed into the other two types of objects:: // the optional $fromEncoding argument defines the encoding of the original string $foo = (new ByteString('さよなら'))->toCodePointString('ISO-2022-JP'); -If the conversion is not possible for any reason, you'll get an +If the conversion is not possible for any reason, you will get an :class:`Symfony\\Component\\String\\Exception\\InvalidArgumentException`. There is also a method to get the bytes stored at some position:: @@ -398,7 +398,7 @@ Methods to Join, Split, Truncate and Reverse u('Symfony is great')->slice(11); // 'great' u('Symfony is great')->slice(-5); // 'great' - // reduces the string to the length given as argument (if it's longer) + // reduces the string to the length given as argument (if it is longer) u('Lorem Ipsum')->truncate(3); // 'Lor' u('Lorem Ipsum')->truncate(80); // 'Lorem Ipsum' // the second argument is the character(s) added when a string is cut @@ -482,7 +482,7 @@ letter A with ring above"*) or a sequence of two code points (``U+0061`` = Slugger ------- -In some contexts, such as URLs and file/directory names, it's not safe to use +In some contexts, such as URLs and file/directory names, it is not safe to use any Unicode character. A *slugger* transforms a given string into another string that only includes safe ASCII characters:: @@ -594,7 +594,7 @@ class to convert English words from/to singular/plural with confidence:: $result = $inflector->pluralize('news'); // ['news'] $result = $inflector->pluralize('person'); // ['persons', 'people'] -The value returned by both methods is always an array because sometimes it's not +The value returned by both methods is always an array because sometimes it is not possible to determine a unique singular/plural form for the given word. .. _`ASCII`: https://en.wikipedia.org/wiki/ASCII diff --git a/components/uid.rst b/components/uid.rst index caac3034429..149e8afd10b 100644 --- a/components/uid.rst +++ b/components/uid.rst @@ -29,7 +29,7 @@ UUIDs `UUIDs`_ (*universally unique identifiers*) are one of the most popular UIDs in the software industry. UUIDs are 128-bit numbers usually represented as five groups of hexadecimal characters: ``xxxxxxxx-xxxx-Mxxx-Nxxx-xxxxxxxxxxxx`` -(the ``M`` digit is the UUID version and the ``N`` digit is the UUID variant). +(the ``M`` dig it is the UUID version and the ``N`` digit is the UUID variant). Generating UUIDs ~~~~~~~~~~~~~~~~ @@ -48,7 +48,7 @@ to create each type of UUID:: // UUID type 3 and 5 generate a UUID hashing the given namespace and name. Type 3 uses // MD5 hashes and Type 5 uses SHA-1. The namespace is another UUID (e.g. a Type 4 UUID) - // and the name is an arbitrary string (e.g. a product name; if it's unique). + // and the name is an arbitrary string (e.g. a product name; if it is unique). $namespace = Uuid::v4(); $name = $product->getUniqueName(); @@ -62,9 +62,9 @@ to create each type of UUID:: $uuid = Uuid::v3(Uuid::NAMESPACE_OID, $name); // same as: Uuid::v3('oid', $name); $uuid = Uuid::v3(Uuid::NAMESPACE_X500, $name); // same as: Uuid::v3('x500', $name); - // UUID type 6 is not part of the UUID standard. It's lexicographically sortable + // UUID type 6 is not part of the UUID standard. It is lexicographically sortable // (like ULIDs) and contains a 60-bit timestamp and 63 extra unique bits. - // It's defined in http://gh.peabody.io/uuidv6/ + // It is defined in http://gh.peabody.io/uuidv6/ $uuid = Uuid::v6(); // $uuid is an instance of Symfony\Component\Uid\UuidV6 .. versionadded:: 5.3 @@ -215,7 +215,7 @@ UUID objects created with the ``Uuid`` class can use the following methods $uuid = Uuid::v4(); $uuid instanceof UuidV4; // true - // getting the UUID datetime (it's only available in certain UUID types) + // getting the UUID datetime (it is only available in certain UUID types) $uuid = Uuid::v1(); $uuid->getDateTime(); // returns a \DateTimeImmutable instance @@ -295,7 +295,7 @@ entity primary keys:: When using built-in Doctrine repository methods (e.g. ``findOneBy()``), Doctrine knows how to convert these UUID types to build the SQL query (e.g. ``->findOneBy(['user' => $user->getUuid()])``). However, when using DQL -queries or building the query yourself, you'll need to set ``uuid`` as the type +queries or building the query yourself, you will need to set ``uuid`` as the type of the UUID parameters:: // src/Repository/ProductRepository.php @@ -501,7 +501,7 @@ entity primary keys:: When using built-in Doctrine repository methods (e.g. ``findOneBy()``), Doctrine knows how to convert these ULID types to build the SQL query (e.g. ``->findOneBy(['user' => $user->getUlid()])``). However, when using DQL -queries or building the query yourself, you'll need to set ``ulid`` as the type +queries or building the query yourself, you will need to set ``ulid`` as the type of the ULID parameters:: // src/Repository/ProductRepository.php diff --git a/components/using_components.rst b/components/using_components.rst index 31a0f24d1be..254b9fadbaa 100644 --- a/components/using_components.rst +++ b/components/using_components.rst @@ -7,7 +7,7 @@ How to Install and Use the Symfony Components ============================================= -If you're starting a new project (or already have a project) that will use +If you are starting a new project (or already have a project) that will use one or more components, the easiest way to integrate everything is with `Composer`_. Composer is smart enough to download the component(s) that you need and take care of autoloading so that you can begin using the libraries immediately. @@ -18,7 +18,7 @@ this applies to using any component. Using the Finder Component -------------------------- -**1.** If you're creating a new project, create a new empty directory for it. +**1.** If you are creating a new project, create a new empty directory for it. **2.** Open a terminal, step into this directory and use Composer to grab the library. diff --git a/components/validator.rst b/components/validator.rst index 8698934c0a0..a29a5857a80 100644 --- a/components/validator.rst +++ b/components/validator.rst @@ -66,7 +66,7 @@ Retrieving a Validator Instance ------------------------------- The Validator object (that implements :class:`Symfony\\Component\\Validator\\Validator\\ValidatorInterface`) is the main access -point of the Validator component. To create a new instance of it, it's +point of the Validator component. To create a new instance of it, it is recommended to use the :class:`Symfony\\Component\\Validator\\Validation` class:: use Symfony\Component\Validator\Validation; @@ -74,7 +74,7 @@ recommended to use the :class:`Symfony\\Component\\Validator\\Validation` class: $validator = Validation::createValidator(); This ``$validator`` object can validate simple variables such as strings, numbers -and arrays, but it can't validate objects. To do so, configure the +and arrays, but it cannot validate objects. To do so, configure the ``Validator`` as explained in the next sections. Learn More diff --git a/components/validator/resources.rst b/components/validator/resources.rst index 7af7d1a4622..14deb823b0d 100644 --- a/components/validator/resources.rst +++ b/components/validator/resources.rst @@ -14,7 +14,7 @@ The Validator component collects that metadata using a set of loaders. .. seealso:: - You'll learn how to define the metadata in :doc:`metadata`. + You will learn how to define the metadata in :doc:`metadata`. The StaticMethodLoader ---------------------- @@ -191,6 +191,6 @@ You can set this custom implementation using .. caution:: - Since you are using a custom metadata factory, you can't configure loaders + Since you are using a custom metadata factory, you cannot configure loaders and caches using the ``add*Mapping()`` methods anymore. You now have to inject them into your custom metadata factory yourself. diff --git a/components/var_dumper.rst b/components/var_dumper.rst index e7d3d381313..5cec5e1f82a 100644 --- a/components/var_dumper.rst +++ b/components/var_dumper.rst @@ -29,7 +29,7 @@ The dump() Function ------------------- The VarDumper component creates a global ``dump()`` function that you can -use instead of e.g. :phpfunction:`var_dump`. By using it, you'll gain: +use instead of e.g. :phpfunction:`var_dump`. By using it, you will gain: * Per object and resource types specialized view to e.g. filter out Doctrine internals while dumping a single proxy entity, or get more @@ -37,8 +37,8 @@ use instead of e.g. :phpfunction:`var_dump`. By using it, you'll gain: * Configurable output formats: HTML or colored command line output; * Ability to dump internal references, either soft ones (objects or resources) or hard ones (``=&`` on arrays or objects properties). - Repeated occurrences of the same object/array/resource won't appear - again and again anymore. Moreover, you'll be able to inspect the + Repeated occurrences of the same object/array/resource will not appear + again and again anymore. Moreover, you will be able to inspect the reference structure of your data; * Ability to operate in the context of an output buffering handler. @@ -73,7 +73,7 @@ current PHP SAPI: If you want to catch the dump output as a string, please read the :ref:`advanced section ` which contains examples of it. - You'll also learn how to change the format or redirect the output to + You will also learn how to change the format or redirect the output to wherever you want. .. tip:: @@ -104,7 +104,7 @@ with the debug output can be confusing. That's why this component provides a server to collect all the dumped data. Start the server with the ``server:dump`` command and whenever you call to -``dump()``, the dumped data won't be displayed in the output but sent to that +``dump()``, the dumped data will not be displayed in the output but sent to that server, which outputs it to its own console or to an HTML file: .. code-block:: terminal @@ -247,7 +247,7 @@ Choosing between both is mostly a matter of personal taste, still: shall not be modified: variables are not dumped inline, but in the web debug toolbar; * on the contrary, ``{{ dump(foo.bar) }}`` dumps inline and thus may or not - be suited to your use case (e.g. you shouldn't use it in an HTML + be suited to your use case (e.g. you should not use it in an HTML attribute or a `` This ``format`` key tells the date picker to use the date format that Symfony expects. -This can be tricky: if the date picker is misconfigured, Symfony won't understand +This can be tricky: if the date picker is misconfigured, Symfony will not understand the format and will throw a validation error. You can also configure the format that Symfony should expect via the `format`_ option. diff --git a/reference/forms/types/enum.rst b/reference/forms/types/enum.rst index c8bd18d2c04..df1c6a1cbee 100644 --- a/reference/forms/types/enum.rst +++ b/reference/forms/types/enum.rst @@ -29,7 +29,7 @@ field and defines the same options. Example Usage ------------- -Before using this field, you'll need to have some PHP enumeration (or "enum" for +Before using this field, you will need to have some PHP enumeration (or "enum" for short) defined somewhere in your application. This enum has to be of type "backed enum", where each keyword defines a scalar value such as a string:: @@ -57,7 +57,7 @@ the ``TextAlign`` enum. Use the `expanded`_ and `multiple`_ options to display these values as ```` or ````. The label displayed in the ``