Syntax Highlighting

PHP is the default syntax highlighter applied to all code blocks. You can change it with the code-block directive:

1
2
3

.. code-block:: yaml

    { foo: bar, bar: { foo: bar, bar: baz } }

Configuration Blocks

Whenever you include a configuration sample, use the configuration-block directive to show the configuration in all supported configuration formats (PHP, YAML and XML). Example:

1
2
3
4
5
6
7
8
9
10
11
12
13

.. configuration-block::

    .. code-block:: yaml

        # Configuration in YAML

    .. code-block:: xml

        <!-- Configuration in XML -->

    .. code-block:: php

        // Configuration in PHP

The previous reStructuredText snippet renders as follow:

1

# Configuration in YAML

1

<!-- Configuration in XML -->

1

// Configuration in PHP

The current list of supported formats are the following:

Adding Links

The most common type of links are internal links to other documentation pages, which use the following syntax:

1

:doc:`/absolute/path/to/page`

The page name should not include the file extension (.rst). For example:

1
2
3
4
5

:doc:`/controller`

:doc:`/components/event_dispatcher`

:doc:`/configuration/environments`

The title of the linked page will be automatically used as the text of the link. If you want to modify that title, use this alternative syntax:

1

:doc:`Doctrine Associations </doctrine/associations>`

1
2
3
4
5

:doc:`controller`

:doc:`event_dispatcher`

:doc:`environments`

Links to the API follow a different syntax, where you must specify the type of the linked resource (class or method):

1
2
3

:class:`Symfony\\Component\\Routing\\Matcher\\ApacheUrlMatcher`

:method:`Symfony\\Component\\HttpKernel\\Bundle\\Bundle::build`

Links to the PHP documentation follow a pretty similar syntax:

1
2
3
4
5

:phpclass:`SimpleXMLElement`

:phpmethod:`DateTime::createFromFormat`

:phpfunction:`iterator_to_array`

New Features, Behavior Changes or Deprecations

If you are documenting a brand new feature, a change or a deprecation that's been made in Symfony, you should precede your description of the change with the corresponding directive and a short description:

For a new feature or a behavior change use the .. versionadded:: 4.x directive:

1
2
3

.. versionadded:: 4.2

    Named autowiring aliases have been introduced in Symfony 4.2.

If you are documenting a behavior change, it may be helpful to briefly describe how the behavior has changed:

1
2
3
4

.. versionadded:: 4.2

   Support for ICU MessageFormat was introduced in Symfony 4.2. Prior to this,
   pluralization was managed by the ``transChoice`` method.

For a deprecation use the .. deprecated:: 4.x directive:

1
2
3

.. deprecated:: 4.2

    Not passing the root node name to ``TreeBuilder`` was deprecated in Symfony 4.2.

Whenever a new major version of Symfony is released (e.g. 5.0, 6.0, etc), a new branch of the documentation is created from the x.4 branch of the previous major version. At this point, all the versionadded and deprecated tags for Symfony versions that have a lower major version will be removed. For example, if Symfony 5.0 were released today, 4.0 to 4.4 versionadded and deprecated tags would be removed from the new 5.0 branch.