Warning

If you are familiar with Markdown, be careful as things are sometimes verysimilar but different:

• Lists start at the beginning of a line (no indentation is allowed);
• Inline code blocks use double-ticks (``like this``).

Syntax Highlighting

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

123

.. code-block:: yaml    { foo: bar, bar: { foo: bar, bar: baz } }

Configuration Blocks

Whenever you include a configuration sample, use theconfiguration-blockdirective to show the configuration in all supported configuration formats(PHP,YAML andXML). Example:

12345678910111213

.. 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

All code examples assume that you are using that feature inside a Symfonyapplication. If you ever need to also show how to use it when working withstandalone components in any PHP application, use the special formatsphp-symfony andphp-standalone, which will be rendered like this:

1

// PHP code using features provided by the Symfony framework

1

// PHP code using standalone components

The current list of supported formats are the following:

Displaying Tabs

It is possible to display tabs in the documentation. They look similar toconfiguration blocks when rendered, but tabs can hold any type of content:

12345678910111213141516

.. tabs:: UX Installation    .. tab:: Webpack Encore        Introduction to Webpack        .. code-block:: yaml            webpack:                # ...    .. tab:: AssetMapper        Introduction to AssetMapper        Something else about AssetMapper

Adding Links

The most common type of links areinternal 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:

12345

: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>`

12345

:doc:`controller`:doc:`event_dispatcher`:doc:`environments`

Links to specific page sections follow a different syntax. First, define atarget above section you will link to (syntax:.. _ + target name +:):

123456789

# /service_container/autowiring.rst# define the target.. _autowiring-calls:Autowiring other Methods (e.g. Setters and Public Typed Properties)-------------------------------------------------------------------// section content ...

Then, use the:ref:: directive to link to that section from another file:

123

# /reference/attributes.rst:ref:`Required <autowiring-calls>`

Links to the API follow a different syntax, where you must specify the typeof the linked resource (class ormethod):

123

:class:`Symfony\\Component\\Routing\\Matcher\\ApacheUrlMatcher`:method:`Symfony\\Component\\HttpKernel\\Bundle\\Bundle::build`

Links to the PHP documentation follow a pretty similar syntax:

12345

: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'sbeen made in Symfony, you should precede your description of the change withthe corresponding directive and a short description:

For a new feature or a behavior change use the.. versionadded:: 7.xdirective:

123

.. versionadded:: 7.2    ... ... ... was introduced in Symfony 7.2.

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

1234

.. versionadded:: 7.2   ... ... ... was introduced in Symfony 7.2. Prior to this,   ... ... ... ... ... ... ... ... .

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

123

.. deprecated:: 7.2    ... ... ... was deprecated in Symfony 7.2.

Whenever a new major version of Symfony is released (e.g. 8.0, 9.0, etc), a newbranch of the documentation is created from thex.4 branch of the previousmajor version. At this point, all theversionadded anddeprecated tagsfor Symfony versions that have a lower major version will be removed. Forexample, if Symfony 8.0 were released today, 7.0 to 7.4versionadded anddeprecated tags would be removed from the new8.0 branch.

Measure & Improve Symfony Code Performance

Online exam, become Symfony certified today