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 reST snippet renders as follow:

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:`Spooling Email </email/spool>`

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 (namespace, class or method):

1
2
3
4
5

:namespace:`Symfony\\Component\\BrowserKit`

: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:: 3.x directive:

1
2
3

.. versionadded:: 3.4

    The special ``!`` template prefix was introduced in Symfony 3.4.

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

1
2
3
4

.. versionadded:: 3.4

    Support for annotation routing without an external bundle was introduced
    in Symfony 3.4. Prior, you needed to install the SensioFrameworkExtraBundle.

For a deprecation use the .. deprecated:: 3.X directive:

1
2
3
4

.. deprecated:: 3.3

    This technique is discouraged and the ``addClassesToCompile()`` method was
    deprecated in Symfony 3.3 because modern PHP versions make it unnecessary.

Whenever a new major version of Symfony is released (e.g. 3.0, 4.0, etc), a new branch of the documentation is created from the master branch. 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 4.0 were released today, 3.0 to 3.4 versionadded and deprecated tags would be removed from the new 4.0 branch.