You are browsing the Symfony 4 documentation, which changes significantly from Symfony 3.x. If your app doesn't use Symfony 4 yet, browse the Symfony 3.4 documentation.

Documentation Format

Documentation Format

The Symfony documentation uses reStructuredText as its markup language and Sphinx for generating the documentation in the formats read by the end users, such as HTML and PDF.

reStructuredText

reStructuredText is a plaintext markup syntax similar to Markdown, but much stricter with its syntax. If you are new to reStructuredText, take some time to familiarize with this format by reading the existing Symfony documentation source code.

If you want to learn more about this format, check out the reStructuredText Primer tutorial and the reStructuredText Reference.

Caution

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

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

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.

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

Note

Besides all of the major programming languages, the syntax highlighter supports all kinds of markup and configuration languages. Check out the list of supported languages on the syntax highlighter website.

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:

  • YAML
    1
    # Configuration in YAML
    
  • XML
    1
    <!-- Configuration in XML -->
    
  • PHP
    1
    // Configuration in PHP
    

The current list of supported formats are the following:

Markup Format Use It to Display
html HTML
xml XML
php PHP
yaml YAML
twig Pure Twig markup
html+twig Twig markup blended with HTML
html+php PHP code blended with HTML
ini INI
php-annotations PHP Annotations

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

This work, including the code samples, is licensed under a Creative Commons BY-SA 3.0 license.