diff --git a/best_practices/controllers.rst b/best_practices/controllers.rst index 8eab4f822ad..b96facacae3 100644 --- a/best_practices/controllers.rst +++ b/best_practices/controllers.rst @@ -48,7 +48,7 @@ configuration to the main routing configuration file: This configuration will load annotations from any controller stored inside the ``src/AppBundle/Controller/`` directory and even from its subdirectories. -So if your application defines lots of controllers, it's perfectly ok to +So if your application defines lots of controllers, it's perfectly OK to reorganize them into subdirectories: .. code-block:: text diff --git a/best_practices/templates.rst b/best_practices/templates.rst index 4f2c50c8e78..b1327a72fdf 100644 --- a/best_practices/templates.rst +++ b/best_practices/templates.rst @@ -30,8 +30,8 @@ Template Locations Store all your application's templates in ``app/Resources/views/`` directory. Traditionally, Symfony developers stored the application templates in the -``Resources/views/`` directory of each bundle. Then they used the Twig namespaced -path to refer to them (e.g. ``@AcmeDemo/Default/index.html.twig``). +``Resources/views/`` directory of each bundle. Then they used Twig namespaces +to refer to them (e.g. ``@AcmeDemo/Default/index.html.twig``). But for the templates used in your application, it's much more convenient to store them in the ``app/Resources/views/`` directory. For starters, this @@ -51,7 +51,7 @@ scattered through lots of bundles. .. best-practice:: - Use lowercased snake_case for directory and template names. + Use lowercase snake_case for directory and template names. .. best-practice:: diff --git a/bundles/best_practices.rst b/bundles/best_practices.rst index f9fbda249a9..fa0a4e9f6a1 100644 --- a/bundles/best_practices.rst +++ b/bundles/best_practices.rst @@ -37,7 +37,7 @@ A namespace becomes a bundle as soon as you add a bundle class to it. The bundle class name must follow these simple rules: * Use only alphanumeric characters and underscores; -* Use a StudlyCaps name (i.e. camelCase with the first letter uppercased); +* Use a StudlyCaps name (i.e. camelCase with an uppercase first letter); * Use a descriptive and short name (no more than two words); * Prefix the name with the concatenation of the vendor (and optionally the category namespaces); diff --git a/components/asset.rst b/components/asset.rst index 451004ad383..a2e1bf69327 100644 --- a/components/asset.rst +++ b/components/asset.rst @@ -119,8 +119,9 @@ suffix to any asset path:: echo $package->getUrl('image.png'); // result: image.png?v1 -In case you want to modify the version format, pass a sprintf-compatible format -string as the second argument of the ``StaticVersionStrategy`` constructor:: +In case you want to modify the version format, pass a ``sprintf``-compatible +format string as the second argument of the ``StaticVersionStrategy`` +constructor:: // puts the 'version' word before the version value $package = new Package(new StaticVersionStrategy('v1', '%s?version=%s')); diff --git a/components/cache/adapters/php_array_cache_adapter.rst b/components/cache/adapters/php_array_cache_adapter.rst index e6da6b0f2e3..a0e351b7f7a 100644 --- a/components/cache/adapters/php_array_cache_adapter.rst +++ b/components/cache/adapters/php_array_cache_adapter.rst @@ -34,5 +34,5 @@ that is optimized and preloaded into OPcache memory storage:: .. note:: - This adapter requires PHP 7.x and should be used with the php.ini setting - ``opcache.enable`` on. + This adapter requires PHP 7.x and should be used with the ``php.ini`` + setting ``opcache.enable=On``. diff --git a/components/class_loader/class_loader.rst b/components/class_loader/class_loader.rst index 0562722ba58..e82485c03c0 100644 --- a/components/class_loader/class_loader.rst +++ b/components/class_loader/class_loader.rst @@ -55,8 +55,8 @@ your classes:: ]); Classes from a sub-namespace or a sub-hierarchy of `PEAR`_ classes can be -looked for in a location list to ease the vendoring of a sub-set of classes -for large projects:: +looked for in a location list to ease the splitting a sub-set of classes into +another package for large projects:: $loader->addPrefixes([ 'Doctrine\Common' => __DIR__.'/vendor/doctrine/common/lib', diff --git a/components/config.rst b/components/config.rst index fbc39bf02e6..ce58f64fc7e 100644 --- a/components/config.rst +++ b/components/config.rst @@ -6,7 +6,7 @@ The Config Component ==================== The Config component provides several classes to help you find, load, - combine, autofill and validate configuration values of any kind, whatever + combine, fill and validate configuration values of any kind, whatever their source may be (YAML, XML, INI files, or for instance a database). Installation diff --git a/components/console/helpers/processhelper.rst b/components/console/helpers/processhelper.rst index 5fba8efc819..45572d90a66 100644 --- a/components/console/helpers/processhelper.rst +++ b/components/console/helpers/processhelper.rst @@ -9,7 +9,7 @@ useful information about process status. To display process details, use the :class:`Symfony\\Component\\Console\\Helper\\ProcessHelper` and run your command with verbosity. For example, running the following code with -a very verbose verbosity (e.g. -vv):: +a very verbose verbosity (e.g. ``-vv``):: use Symfony\Component\Process\Process; diff --git a/components/console/helpers/progressbar.rst b/components/console/helpers/progressbar.rst index a309885dc96..4a892603717 100644 --- a/components/console/helpers/progressbar.rst +++ b/components/console/helpers/progressbar.rst @@ -237,7 +237,7 @@ the example above. Bar Settings ~~~~~~~~~~~~ -Amongst the placeholders, ``bar`` is a bit special as all the characters used +Among the placeholders, ``bar`` is a bit special as all the characters used to display it can be customized:: // the finished part of the bar diff --git a/components/console/helpers/questionhelper.rst b/components/console/helpers/questionhelper.rst index 1c405d9e313..8e907bf04bd 100644 --- a/components/console/helpers/questionhelper.rst +++ b/components/console/helpers/questionhelper.rst @@ -203,7 +203,7 @@ convenient for passwords:: .. caution:: When you ask for a hidden response, Symfony will use either a binary, change - stty mode or use another trick to hide the response. If none is available, + ``stty`` mode or use another trick to hide the response. If none is available, it will fallback and allow the response to be visible unless you set this behavior to ``false`` using :method:`Symfony\\Component\\Console\\Question\\Question::setHiddenFallback` diff --git a/components/console/usage.rst b/components/console/usage.rst index 2232fbd3a6f..b51716280af 100644 --- a/components/console/usage.rst +++ b/components/console/usage.rst @@ -10,7 +10,7 @@ built-in options as well as a couple of built-in commands for the Console compon .. note:: These examples assume you have added a file ``application.php`` to run at - the cli:: + the CLI:: #!/usr/bin/env php $tag = $crawler->filterXPath('//body/*')->nodeName(); diff --git a/components/expression_language.rst b/components/expression_language.rst index 7c457d0d529..db1fbb99955 100644 --- a/components/expression_language.rst +++ b/components/expression_language.rst @@ -102,9 +102,9 @@ PHP type (including objects):: [ 'fruit' => $apple, ] - )); + )); // displays "Honeycrisp" -This will print "Honeycrisp". For more information, see the :doc:`/components/expression_language/syntax` +For more information, see the :doc:`/components/expression_language/syntax` entry, especially :ref:`component-expression-objects` and :ref:`component-expression-arrays`. Caching diff --git a/components/filesystem.rst b/components/filesystem.rst index cb6d89952d8..9a0c3579974 100644 --- a/components/filesystem.rst +++ b/components/filesystem.rst @@ -44,8 +44,8 @@ endpoint for filesystem operations:: string, an array or any object implementing :phpclass:`Traversable` as the target argument. -mkdir -~~~~~ +``mkdir`` +~~~~~~~~~ :method:`Symfony\\Component\\Filesystem\\Filesystem::mkdir` creates a directory recursively. On POSIX filesystems, directories are created with a default mode value @@ -65,12 +65,12 @@ On POSIX filesystems, directories are created with a default mode value .. note:: The directory permissions are affected by the current `umask`_. - Set the umask for your webserver, use PHP's :phpfunction:`umask` + Set the ``umask`` for your webserver, use PHP's :phpfunction:`umask` function or use the :phpfunction:`chmod` function after the directory has been created. -exists -~~~~~~ +``exists`` +~~~~~~~~~~ :method:`Symfony\\Component\\Filesystem\\Filesystem::exists` checks for the presence of one or more files or directories and returns ``false`` if any of @@ -88,8 +88,8 @@ them is missing:: You can pass an array or any :phpclass:`Traversable` object as the first argument. -copy -~~~~ +``copy`` +~~~~~~~~ :method:`Symfony\\Component\\Filesystem\\Filesystem::copy` makes a copy of a single file (use :method:`Symfony\\Component\\Filesystem\\Filesystem::mirror` to @@ -103,8 +103,8 @@ by the third boolean argument:: // image.jpg will be overridden $filesystem->copy('image-ICC.jpg', 'image.jpg', true); -touch -~~~~~ +``touch`` +~~~~~~~~~ :method:`Symfony\\Component\\Filesystem\\Filesystem::touch` sets access and modification time for a file. The current time is used by default. You can set @@ -122,8 +122,8 @@ your own with the second argument. The third argument is the access time:: You can pass an array or any :phpclass:`Traversable` object as the first argument. -chown -~~~~~ +``chown`` +~~~~~~~~~ :method:`Symfony\\Component\\Filesystem\\Filesystem::chown` changes the owner of a file. The third argument is a boolean recursive option:: @@ -138,8 +138,8 @@ a file. The third argument is a boolean recursive option:: You can pass an array or any :phpclass:`Traversable` object as the first argument. -chgrp -~~~~~ +``chgrp`` +~~~~~~~~~ :method:`Symfony\\Component\\Filesystem\\Filesystem::chgrp` changes the group of a file. The third argument is a boolean recursive option:: @@ -154,8 +154,8 @@ a file. The third argument is a boolean recursive option:: You can pass an array or any :phpclass:`Traversable` object as the first argument. -chmod -~~~~~ +``chmod`` +~~~~~~~~~ :method:`Symfony\\Component\\Filesystem\\Filesystem::chmod` changes the mode or permissions of a file. The fourth argument is a boolean recursive option:: @@ -170,8 +170,8 @@ permissions of a file. The fourth argument is a boolean recursive option:: You can pass an array or any :phpclass:`Traversable` object as the first argument. -remove -~~~~~~ +``remove`` +~~~~~~~~~~ :method:`Symfony\\Component\\Filesystem\\Filesystem::remove` deletes files, directories and symlinks:: @@ -183,8 +183,8 @@ directories and symlinks:: You can pass an array or any :phpclass:`Traversable` object as the first argument. -rename -~~~~~~ +``rename`` +~~~~~~~~~~ :method:`Symfony\\Component\\Filesystem\\Filesystem::rename` changes the name of a single file or directory:: @@ -194,8 +194,8 @@ of a single file or directory:: // renames a directory $filesystem->rename('/tmp/files', '/path/to/store/files'); -symlink -~~~~~~~ +``symlink`` +~~~~~~~~~~~ :method:`Symfony\\Component\\Filesystem\\Filesystem::symlink` creates a symbolic link from the target to the destination. If the filesystem does not @@ -207,8 +207,8 @@ support symbolic links, a third boolean argument is available:: // does not support symbolic links $filesystem->symlink('/path/to/source', '/path/to/destination', true); -readlink -~~~~~~~~ +``readlink`` +~~~~~~~~~~~~ .. versionadded:: 3.2 @@ -242,8 +242,8 @@ Its behavior is the following:: * if ``$path`` does not exist, it returns null. * if ``$path`` exists, it returns its absolute fully resolved final version. -makePathRelative -~~~~~~~~~~~~~~~~ +``makePathRelative`` +~~~~~~~~~~~~~~~~~~~~ :method:`Symfony\\Component\\Filesystem\\Filesystem::makePathRelative` takes two absolute paths and returns the relative path from the second path to the first one:: @@ -256,8 +256,8 @@ absolute paths and returns the relative path from the second path to the first o // returns 'videos/' $filesystem->makePathRelative('/tmp/videos', '/tmp') -mirror -~~~~~~ +``mirror`` +~~~~~~~~~~ :method:`Symfony\\Component\\Filesystem\\Filesystem::mirror` copies all the contents of the source directory into the target one (use the @@ -266,8 +266,8 @@ files):: $filesystem->mirror('/path/to/source', '/path/to/target'); -isAbsolutePath -~~~~~~~~~~~~~~ +``isAbsolutePath`` +~~~~~~~~~~~~~~~~~~ :method:`Symfony\\Component\\Filesystem\\Filesystem::isAbsolutePath` returns ``true`` if the given path is absolute, ``false`` otherwise:: @@ -281,16 +281,18 @@ isAbsolutePath // returns false $filesystem->isAbsolutePath('../dir'); -tempnam -~~~~~~~ +``tempnam`` +~~~~~~~~~~~ -:method:`Symfony\\Component\\Filesystem\\Filesystem::tempnam` creates a temporary file with a unique filename, and returns its path, or throw an exception on failure:: +:method:`Symfony\\Component\\Filesystem\\Filesystem::tempnam` creates a +temporary file with a unique filename, and returns its path, or throw an +exception on failure:: // returns a path like : /tmp/prefix_wyjgtF $filesystem->tempnam('/tmp', 'prefix_'); -dumpFile -~~~~~~~~ +``dumpFile`` +~~~~~~~~~~~~ :method:`Symfony\\Component\\Filesystem\\Filesystem::dumpFile` saves the given contents into a file. It does this in an atomic manner: it writes a temporary @@ -302,8 +304,8 @@ complete new file (but never a partially-written file):: The ``file.txt`` file contains ``Hello World`` now. -appendToFile -~~~~~~~~~~~~ +``appendToFile`` +~~~~~~~~~~~~~~~~ .. versionadded:: 3.3 diff --git a/components/intl.rst b/components/intl.rst index f9df0fee0ca..eec1c2c9573 100644 --- a/components/intl.rst +++ b/components/intl.rst @@ -86,7 +86,7 @@ TextBundleWriter The :class:`Symfony\\Component\\Intl\\ResourceBundle\\Writer\\TextBundleWriter` writes an array or an array-like object to a plain-text resource bundle. The -resulting .txt file can be converted to a binary .res file with the +resulting ``.txt`` file can be converted to a binary ``.res`` file with the :class:`Symfony\\Component\\Intl\\ResourceBundle\\Compiler\\BundleCompiler` class:: @@ -105,7 +105,7 @@ class:: $compiler = new BundleCompiler(); $compiler->compile('/path/to/bundle', '/path/to/binary/bundle'); -The command "genrb" must be available for the +The command ``genrb`` must be available for the :class:`Symfony\\Component\\Intl\\ResourceBundle\\Compiler\\BundleCompiler` to work. If the command is located in a non-standard location, you can pass its path to the diff --git a/components/process.rst b/components/process.rst index 05631d8c267..5b3c66d3924 100644 --- a/components/process.rst +++ b/components/process.rst @@ -51,7 +51,7 @@ the contents of the output and the contents of the error output. You can also use the :class:`Symfony\\Component\\Process\\Process` class with the -foreach construct to get the output while it is generated. By default, the loop waits +for each construct to get the output while it is generated. By default, the loop waits for new output before going to the next iteration:: $process = new Process(['ls', '-lsa']); @@ -137,7 +137,7 @@ with a non-zero code):: Getting real-time Process Output -------------------------------- -When executing a long running command (like rsync-ing files to a remote +When executing a long running command (like ``rsync`` to a remote server), you can give feedback to the end user in real-time by passing an anonymous function to the :method:`Symfony\\Component\\Process\\Process::run` method:: @@ -237,7 +237,7 @@ Streaming to the Standard Input of a Process Before a process is started, you can specify its standard input using either the :method:`Symfony\\Component\\Process\\Process::setInput` method or the 4th argument of the constructor. The provided input can be a string, a stream resource or a -Traversable object:: +``Traversable`` object:: $process = new Process('cat'); $process->setInput('foobar'); @@ -267,7 +267,7 @@ provides the :class:`Symfony\\Component\\Process\\InputStream` class:: echo $process->getOutput(); The :method:`Symfony\\Component\\Process\\InputStream::write` method accepts scalars, -stream resources or Traversable objects as argument. As shown in the above example, +stream resources or ``Traversable`` objects as argument. As shown in the above example, you need to explicitly call the :method:`Symfony\\Component\\Process\\InputStream::close` method when you are done writing to the standard input of the subprocess. diff --git a/components/property_access.rst b/components/property_access.rst index bd08aacd91a..9e11d67c011 100644 --- a/components/property_access.rst +++ b/components/property_access.rst @@ -112,9 +112,9 @@ Using Getters ~~~~~~~~~~~~~ The ``getValue()`` method also supports reading using getters. The method will -be created using common naming conventions for getters. It camelizes the -property name (``first_name`` becomes ``FirstName``) and prefixes it with -``get``. So the actual method becomes ``getFirstName()``:: +be created using common naming conventions for getters. It transform the +property name to camelCase (``first_name`` becomes ``FirstName``) and prefixes +it with ``get``. So the actual method becomes ``getFirstName()``:: // ... class Person diff --git a/components/property_info.rst b/components/property_info.rst index 2c7ca078047..05814ddb884 100644 --- a/components/property_info.rst +++ b/components/property_info.rst @@ -288,8 +288,8 @@ Each object will provide 6 attributes, available in the 6 methods: .. _`components-property-info-type-builtin`: -Type::getBuiltInType() -~~~~~~~~~~~~~~~~~~~~~~ +``Type::getBuiltInType()`` +~~~~~~~~~~~~~~~~~~~~~~~~~~ The :method:`Type::getBuiltinType() ` method returns the built-in PHP data type, which can be one of these @@ -299,22 +299,22 @@ string values: ``array``, ``bool``, ``callable``, ``float``, ``int``, Constants inside the :class:`Symfony\\Component\\PropertyInfo\\Type` class, in the form ``Type::BUILTIN_TYPE_*``, are provided for convenience. -Type::isNullable() -~~~~~~~~~~~~~~~~~~ +``Type::isNullable()`` +~~~~~~~~~~~~~~~~~~~~~~ The :method:`Type::isNullable() ` method will return a boolean value indicating whether the property parameter can be set to ``null``. -Type::getClassName() -~~~~~~~~~~~~~~~~~~~~ +``Type::getClassName()`` +~~~~~~~~~~~~~~~~~~~~~~~~ If the :ref:`built-in PHP data type ` is ``object``, the :method:`Type::getClassName() ` method will return the fully-qualified class or interface name accepted. -Type::isCollection() -~~~~~~~~~~~~~~~~~~~~ +``Type::isCollection()`` +~~~~~~~~~~~~~~~~~~~~~~~~ The :method:`Type::isCollection() ` method will return a boolean value indicating if the property parameter is @@ -326,8 +326,8 @@ this returns ``true`` if: * The mutator method the property is derived from has a prefix of ``add`` or ``remove`` (which are defined as the list of array mutator prefixes). -Type::getCollectionKeyType() & Type::getCollectionValueType() -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +``Type::getCollectionKeyType()`` & ``Type::getCollectionValueType()`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ If the property is a collection, additional type objects may be returned for both the key and value types of the collection (if the information is diff --git a/components/security/authorization.rst b/components/security/authorization.rst index f267bd149ce..7d5cf3af9e2 100644 --- a/components/security/authorization.rst +++ b/components/security/authorization.rst @@ -140,7 +140,7 @@ RoleHierarchyVoter The :class:`Symfony\\Component\\Security\\Core\\Authorization\\Voter\\RoleHierarchyVoter` extends :class:`Symfony\\Component\\Security\\Core\\Authorization\\Voter\\RoleVoter` and provides some additional functionality: it knows how to handle a -hierarchy of roles. For instance, a ``ROLE_SUPER_ADMIN`` role may have subroles +hierarchy of roles. For instance, a ``ROLE_SUPER_ADMIN`` role may have sub-roles ``ROLE_ADMIN`` and ``ROLE_USER``, so that when a certain object requires the user to have the ``ROLE_ADMIN`` role, it grants access to users who in fact have the ``ROLE_ADMIN`` role, but also to users having the ``ROLE_SUPER_ADMIN`` diff --git a/components/serializer.rst b/components/serializer.rst index 6acc8e5b18e..9b26a698a72 100644 --- a/components/serializer.rst +++ b/components/serializer.rst @@ -587,8 +587,8 @@ There are several types of normalizers available: Objects are normalized to a map of property names and values (names are generated removing the ``get``, ``set``, ``has``, ``is`` or ``remove`` prefix from - the method name and lowercasing the first letter; e.g. ``getFirstName()`` -> - ``firstName``). + the method name and transforming the first letter to lowercase; e.g. + ``getFirstName()`` -> ``firstName``). The ``ObjectNormalizer`` is the most powerful normalizer. It is configured by default when using the Symfony Standard Edition with the serializer enabled. @@ -599,8 +599,8 @@ There are several types of normalizers available: the constructor and the "setters" (public methods starting with "set"). Objects are normalized to a map of property names and values (names are - generated removing the ``get`` prefix from the method name and lowercasing - the first letter; e.g. ``getFirstName()`` -> ``firstName``). + generated removing the ``get`` prefix from the method name and transforming + the first letter to lowercase; e.g. ``getFirstName()`` -> ``firstName``). :class:`Symfony\\Component\\Serializer\\Normalizer\\PropertyNormalizer` This normalizer directly reads and writes public properties as well as diff --git a/components/stopwatch.rst b/components/stopwatch.rst index 01901a1a396..f89e8581b2b 100644 --- a/components/stopwatch.rst +++ b/components/stopwatch.rst @@ -21,7 +21,7 @@ Usage The Stopwatch component provides a consistent way to measure execution time of certain parts of code so that you don't constantly have to parse -microtime by yourself. Instead, use the simple +:phpfunction:`microtime` by yourself. Instead, use the simple :class:`Symfony\\Component\\Stopwatch\\Stopwatch` class:: use Symfony\Component\Stopwatch\Stopwatch; diff --git a/components/templating/slotshelper.rst b/components/templating/slotshelper.rst index a5c1bd134ff..42c088c9fd9 100644 --- a/components/templating/slotshelper.rst +++ b/components/templating/slotshelper.rst @@ -38,7 +38,7 @@ optional second argument, which is the default value to use if the slot is not available. The ``_content`` slot is a special slot set by the ``PhpEngine``. It contains -the content of the subtemplate. +the content of the sub-template. .. caution:: diff --git a/components/translation/custom_formats.rst b/components/translation/custom_formats.rst index faa305f49f2..5ebd3fe8599 100644 --- a/components/translation/custom_formats.rst +++ b/components/translation/custom_formats.rst @@ -46,10 +46,10 @@ create the catalog that will be returned:: } } - $messageCatalogue = new MessageCatalogue($locale); - $messageCatalogue->add($messages, $domain); + $messageCatalog = new MessageCatalogue($locale); + $messageCatalog->add($messages, $domain); - return $messageCatalogue; + return $messageCatalog; } } @@ -102,7 +102,7 @@ will save a few lines:: } } -.. sidebar:: Format a message catalogue +.. sidebar:: Format a message catalog In some cases, you want to send the dump contents as a response instead of writing them in files. To do this, you can use the ``formatCatalogue`` diff --git a/components/translation/usage.rst b/components/translation/usage.rst index 9cb41aa184c..65f3442c75d 100644 --- a/components/translation/usage.rst +++ b/components/translation/usage.rst @@ -411,17 +411,19 @@ use for translation:: 'fr_FR' ); -Retrieving the Message Catalogue --------------------------------- +.. _retrieving-the-message-catalogue: -In case you want to use the same translation catalogue outside your application +Retrieving the Message Catalog +------------------------------ + +In case you want to use the same translation catalog outside your application (e.g. use translation on the client side), it's possible to fetch raw translation messages. Just specify the required locale:: - $catalogue = $translator->getCatalogue('fr_FR'); - $messages = $catalogue->all(); - while ($catalogue = $catalogue->getFallbackCatalogue()) { - $messages = array_replace_recursive($catalogue->all(), $messages); + $catalog = $translator->getCatalogue('fr_FR'); + $messages = $catalog->all(); + while ($catalog = $catalog->getFallbackCatalogue()) { + $messages = array_replace_recursive($catalog->all(), $messages); } The ``$messages`` variable will have the following structure:: @@ -472,24 +474,24 @@ loaded/dumped when using this component inside a Symfony application: When using the standalone Translation component, call the ``setMetadata()`` -method of the catalogue and pass the notes as arrays. This is for example the +method of the catalog and pass the notes as arrays. This is for example the code needed to generate the previous XLIFF file:: use Symfony\Component\Translation\Dumper\XliffFileDumper; use Symfony\Component\Translation\MessageCatalogue; - $catalogue = new MessageCatalogue('en_US'); - $catalogue->add([ + $catalog = new MessageCatalogue('en_US'); + $catalog->add([ 'original-content' => 'translated-content', ]); - $catalogue->setMetadata('original-content', ['notes' => [ + $catalog->setMetadata('original-content', ['notes' => [ ['category' => 'state', 'content' => 'new'], ['category' => 'approved', 'content' => 'true'], ['category' => 'section', 'content' => 'user login', 'priority' => '1'], ]]); $dumper = new XliffFileDumper(); - $dumper->formatCatalogue($catalogue, 'messages', [ + $dumper->formatCatalogue($catalog, 'messages', [ 'default_locale' => 'fr_FR', 'xliff_version' => '2.0' ]); diff --git a/components/var_dumper/advanced.rst b/components/var_dumper/advanced.rst index a97d9a4b498..88edcefc05a 100644 --- a/components/var_dumper/advanced.rst +++ b/components/var_dumper/advanced.rst @@ -85,7 +85,7 @@ Before dumping it, you can further limit the resulting Removes internal objects' handles for sparser output (useful for tests). :method:`Symfony\\Component\\VarDumper\\Cloner\\Data::seek` - Selects only subparts of already cloned arrays, objects or resources. + Selects only sub-parts of already cloned arrays, objects or resources. .. versionadded:: 3.2 @@ -345,7 +345,7 @@ Casters are responsible for returning the properties of the object or resource being cloned in an array. They are callables that accept five arguments: * the object or resource being casted; -* an array modelled for objects after PHP's native ``(array)`` cast operator; +* an array modeled for objects after PHP's native ``(array)`` cast operator; * a :class:`Symfony\\Component\\VarDumper\\Cloner\\Stub` object representing the main properties of the object (class, type, etc.); * true/false when the caster is called nested in a structure or not; diff --git a/components/yaml.rst b/components/yaml.rst index bd7480880d8..8155109dbdd 100644 --- a/components/yaml.rst +++ b/components/yaml.rst @@ -69,7 +69,7 @@ level configuration for pretty outputs. Types Support ~~~~~~~~~~~~~ -It supports most of the YAML built-in types like dates, integers, octals, +It supports most of the YAML built-in types like dates, integers, octal numbers, booleans, and much more... Full Merge Key Support @@ -153,8 +153,10 @@ array to its YAML representation:: If an error occurs during the dump, the parser throws a :class:`Symfony\\Component\\Yaml\\Exception\\DumpException` exception. -Array Expansion and Inlining -............................ +.. _array-expansion-and-inlining: + +Expanded and Inlined Arrays +........................... The YAML format supports two kind of representation for arrays, the expanded one, and the inline one. By default, the dumper uses the expanded diff --git a/configuration/external_parameters.rst b/configuration/external_parameters.rst index 5449225d160..632e9b851bd 100644 --- a/configuration/external_parameters.rst +++ b/configuration/external_parameters.rst @@ -277,7 +277,7 @@ Symfony provides the following env var processors: Casts ``FOO`` to a float. ``env(const:FOO)`` - Finds the const value named in ``FOO``: + Finds the constant value named in ``FOO``: .. configuration-block:: diff --git a/configuration/micro_kernel_trait.rst b/configuration/micro_kernel_trait.rst index a09ed4f8274..c1d6ad00d76 100644 --- a/configuration/micro_kernel_trait.rst +++ b/configuration/micro_kernel_trait.rst @@ -344,7 +344,7 @@ As before you can use the :doc:`Symfony Local Web Server cd web/ $ symfony server:start -Then see webpage in browser: +Then see page in browser: http://localhost:8000/random/10 diff --git a/configuration/multiple_kernels.rst b/configuration/multiple_kernels.rst index 4157e5c0372..5576efee50f 100644 --- a/configuration/multiple_kernels.rst +++ b/configuration/multiple_kernels.rst @@ -148,10 +148,9 @@ The ``bin/console`` script used to run Symfony commands always uses the default to execute console commands using the new kernel, duplicate the ``bin/console`` script and rename it (e.g. ``bin/api``). -Then, replace the ``AppKernel`` instantiation by your own kernel instantiation -(e.g. ``ApiKernel``) and now you can execute commands using the new kernel -(e.g. ``php bin/api cache:clear``) Now you can use execute commands using the -new kernel. +Then, replace the ``AppKernel`` instance by your own kernel instance (e.g. +``ApiKernel``). Now you can execute commands using the new kernel (e.g. +``php bin/api cache:clear``). .. note:: diff --git a/console/coloring.rst b/console/coloring.rst index 561335e533f..093538ad8d5 100644 --- a/console/coloring.rst +++ b/console/coloring.rst @@ -54,7 +54,7 @@ are swapped) and ``conceal`` (sets the foreground color to transparent, making the typed text invisible - although it can be selected and copied; this option is commonly used when asking the user to type sensitive information). -You can also set these colors and options directly inside the tagname:: +You can also set these colors and options directly inside the tag name:: // green text $output->writeln('foo'); diff --git a/contributing/code/conventions.rst b/contributing/code/conventions.rst index f7584ab753b..834cb223bfe 100644 --- a/contributing/code/conventions.rst +++ b/contributing/code/conventions.rst @@ -72,10 +72,10 @@ must be used instead (where ``XXX`` is the name of the related thing): .. note:: - While "setXXX" and "replaceXXX" are very similar, there is one notable - difference: "setXXX" may replace, or add new elements to the relation. - "replaceXXX", on the other hand, cannot add new elements. If an unrecognized - key is passed to "replaceXXX" it must throw an exception. + While ``setXXX()`` and ``replaceXXX()`` are very similar, there is one notable + difference: ``setXXX()`` may replace, or add new elements to the relation. + ``replaceXXX()``, on the other hand, cannot add new elements. If an unrecognized + key is passed to ``replaceXXX()`` it must throw an exception. .. _contributing-code-conventions-deprecations: @@ -97,7 +97,7 @@ contain deprecated methods. A new method cannot be introduced as deprecated. -A feature is marked as deprecated by adding a ``@deprecated`` phpdoc to +A feature is marked as deprecated by adding a ``@deprecated`` PHPdoc to relevant classes, methods, properties, ...:: /** diff --git a/contributing/code/pull_requests.rst b/contributing/code/pull_requests.rst index 6957c5d043d..2ca6a46fa45 100644 --- a/contributing/code/pull_requests.rst +++ b/contributing/code/pull_requests.rst @@ -11,7 +11,7 @@ Before working on a change, check to see if someone else also raised the topic or maybe even started working on a PR by `searching on GitHub`_. If you are unsure or if you have any questions during this entire process, -please ask your questions on the #contribs channel on `Symfony Slack`_. +please ask your questions on the ``#contribs`` channel on `Symfony Slack`_. .. _step-1-setup-your-environment: @@ -380,7 +380,7 @@ We ask all contributors to follow some to ensure a constructive feedback process. If you think someone fails to keep this advice in mind and you want another -perspective, please join the #contribs channel on `Symfony Slack`_. If you +perspective, please join the ``#contribs`` channel on `Symfony Slack`_. If you receive feedback you find abusive please contact the :doc:`CARE team `. @@ -405,8 +405,8 @@ PR. Before re-submitting the PR, rebase with ``upstream/master`` or .. note:: When doing a ``push --force``, always specify the branch name explicitly - to avoid messing other branches in the repo (``--force`` tells Git that - you really want to mess with things so do it carefully). + to avoid messing other branches in the repository (``--force`` tells Git + that you really want to mess with things so do it carefully). Moderators earlier asked you to "squash" your commits. This means you will convert many commits to one commit. This is no longer necessary today, because diff --git a/contributing/code/security.rst b/contributing/code/security.rst index b7cee879de6..557e4c13501 100644 --- a/contributing/code/security.rst +++ b/contributing/code/security.rst @@ -19,7 +19,7 @@ Resolving Process For each report, we first try to confirm the vulnerability. When it is confirmed, the core team works on a solution following these steps: -#. Send an acknowledgement to the reporter; +#. Send an acknowledgment to the reporter; #. Work on a patch; #. Get a CVE identifier from `mitre.org`_; #. Write a security announcement for the official Symfony `blog`_ about the diff --git a/contributing/code/standards.rst b/contributing/code/standards.rst index e81d195ab71..cdad03426c1 100644 --- a/contributing/code/standards.rst +++ b/contributing/code/standards.rst @@ -238,7 +238,7 @@ Service Naming Conventions its class (e.g. ``App\EventSubscriber\UserSubscriber``); * If there are multiple services for the same class, use the FQCN for the main - service and use lowercased and underscored names for the rest of services. + service and use lowercase and underscored names for the rest of services. Optionally divide them in groups separated with dots (e.g. ``something.service_name``, ``fos_user.something.service_name``); diff --git a/contributing/community/review-comments.rst b/contributing/community/review-comments.rst index de5a18e4d80..6336f92dcbb 100644 --- a/contributing/community/review-comments.rst +++ b/contributing/community/review-comments.rst @@ -74,12 +74,12 @@ Assume everyone is intelligent and well-meaning. .. tip:: - Good questions avoid judgement and avoid assumptions about the author's perspective. + Good questions avoid judgment and avoid assumptions about the author's perspective. Maybe you can ask for clarification? Suggest an alternative? Or provide a simple explanation *why* you disagree with their proposal. - * ``This looks wrong. Are you sure it's correct?`` (eg. typo/syntax error) + * ``This looks wrong. Are you sure it's correct?`` (e.g. typo/syntax error) * ``What do you think of "RequestFactory" instead of RequestCreator?`` @@ -157,7 +157,7 @@ Sometimes when people receive feedback they may get defensive. In that case, it is better to try to approach the discussion in a different way, to not escalate further. -If you want someone to mediate, please join the #contribs channel on `Symfony Slack`_, +If you want someone to mediate, please join the ``#contribs`` channel on `Symfony Slack`_, to have a safe environment and keep working together on the common goals. Using Humor diff --git a/contributing/diversity/governance.rst b/contributing/diversity/governance.rst index 7e27f139b05..8dd302ccc0a 100644 --- a/contributing/diversity/governance.rst +++ b/contributing/diversity/governance.rst @@ -40,7 +40,7 @@ The project leader (Fabien Potencier) will have the right to veto any actionable item, regardless of the vote of the initiative's guidance team. The project leader may, at their discretion, also appoint other people from among the initiative's guidance team to also have the right to veto - in such a case these -people are expected to use appropriate judgement to know when to use a "no" vote +people are expected to use appropriate judgment to know when to use a "no" vote or a veto. Any single veto will reject an actionable item. The purpose of having members with the right to veto is to prevent a "people's diff --git a/contributing/documentation/format.rst b/contributing/documentation/format.rst index 2648204ca45..c1a082d31e4 100644 --- a/contributing/documentation/format.rst +++ b/contributing/documentation/format.rst @@ -29,7 +29,7 @@ Sphinx Sphinx_ is a build system that provides tools to create documentation from reStructuredText documents. As such, it adds new directives and interpreted text -roles to the standard reST markup. Read more about the `Sphinx Markup Constructs`_. +roles to the standard reStructuredText markup. Read more about the `Sphinx Markup Constructs`_. Syntax Highlighting ~~~~~~~~~~~~~~~~~~~ @@ -74,7 +74,7 @@ directive to show the configuration in all supported configuration formats // Configuration in PHP -The previous reST snippet renders as follow: +The previous reStructuredText snippet renders as follow: .. configuration-block:: diff --git a/contributing/documentation/overview.rst b/contributing/documentation/overview.rst index 19dd6d030ce..7fd6aa55d5b 100644 --- a/contributing/documentation/overview.rst +++ b/contributing/documentation/overview.rst @@ -121,7 +121,7 @@ branch of the ``upstream`` remote, which is the original Symfony Docs repository Fixes should always be based on the **oldest maintained branch** which contains the error. Nowadays this is the ``3.4`` branch. If you are instead documenting a new feature, switch to the first Symfony version that included it, e.g. -``upstream/3.1``. Not sure? That's ok! Just use the ``upstream/master`` branch. +``upstream/3.1``. Not sure? That's OK! Just use the ``upstream/master`` branch. **Step 5.** Now make your changes in the documentation. Add, tweak, reword and even remove any content and do your best to comply with the diff --git a/controller/argument_value_resolver.rst b/controller/argument_value_resolver.rst index 2016761dd6b..61239377dcb 100644 --- a/controller/argument_value_resolver.rst +++ b/controller/argument_value_resolver.rst @@ -234,7 +234,7 @@ priority of 100. As this one is responsible for fetching attributes from the ``Request``, it's recommended to trigger your custom value resolver with a lower priority. This makes sure the argument resolvers are not triggered when the attribute is present. For instance, when passing the user along a -subrequests. +sub-requests. .. tip:: diff --git a/controller/upload_file.rst b/controller/upload_file.rst index fa2f5fede85..179dbe5dd0d 100644 --- a/controller/upload_file.rst +++ b/controller/upload_file.rst @@ -341,7 +341,7 @@ domain logic. Moreover, Doctrine listeners are often dependent on internal Doctrine behavior which may change in future versions. Also, they can introduce performance issues -unawarely (because your listener persists entities which cause other entities to +unwillingly (because your listener persists entities which cause other entities to be changed and persisted). As an alternative, you can use :doc:`Symfony events, listeners and subscribers `.