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:

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:`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 or Behavior Changes

If you're documenting a brand new feature or a change that's been made in Symfony, you should precede your description of the change with a .. versionadded:: 2.X directive and a short description:

1
2
3
4

.. versionadded:: 2.7
    The ``askHiddenResponse`` method was introduced in Symfony 2.7.

You can also ask a question and hide the response. This is particularly [...]

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

1
2
3

.. versionadded:: 2.7
    The ``include()`` function is a new Twig feature that's available in
    Symfony 2.7. Prior, the ``{% include %}`` tag was used.

Whenever a new minor version of Symfony is released (e.g. 2.4, 2.5, etc), a new branch of the documentation is created from the master branch. At this point, all the versionadded tags for Symfony versions that have reached end-of-maintenance will be removed. For example, if Symfony 2.5 were released today, and 2.2 had recently reached its end-of-life, the 2.2 versionadded tags would be removed from the new 2.5 branch.