Skip to content
  • About
    • What is Symfony?
    • Community
    • News
    • Contributing
    • Support
  • Documentation
    • Symfony Docs
    • Symfony Book
    • Screencasts
    • Symfony Bundles
    • Symfony Cloud
    • Training
  • Services
    • SensioLabs Professional services to help you with Symfony
    • Platform.sh for Symfony Best platform to deploy Symfony apps
    • SymfonyInsight Automatic quality checks for your apps
    • Symfony Certification Prove your knowledge and boost your career
    • Blackfire Profile and monitor performance of your apps
  • Other
  • Blog
  • Download
sponsored by SensioLabs
  1. Home
  2. Documentation
  3. Contributing
  4. Documentation
  5. Documentation Standards
  • Documentation
  • Book
  • Reference
  • Bundles
  • Cloud

Table of Contents

  • Sphinx
    • Example
  • Code Examples
    • Formats
    • Example
  • Files and Directories
  • English Language Standards

Documentation Standards

Edit this page

Documentation Standards

Contributions must follow these standards to match the style and tone of the rest of the Symfony documentation.

Sphinx

  • The following characters are chosen for different heading levels: level 1 is = (equal sign), level 2 - (dash), level 3 ~ (tilde), level 4 . (dot) and level 5 " (double quote);
  • Each line should break approximately after the first word that crosses the 72nd character (so most lines end up being 72-78 characters);
  • The :: shorthand is preferred over .. code-block:: php to begin a PHP code block unless it results in the marker being on its own line (read the Sphinx documentation to see when you should use the shorthand);
  • Inline hyperlinks are not used. Separate the link and their target definition, which you add on the bottom of the page;
  • Inline markup should be closed on the same line as the open-string;

Example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
Example
=======

When you are working on the docs, you should follow the
`Symfony Documentation`_ standards.

Level 2
-------

A PHP example would be::

    echo 'Hello World';

Level 3
~~~~~~~

.. code-block:: php

    echo 'You cannot use the :: shortcut here';

.. _`Symfony Documentation`: https://symfony.com/doc

Code Examples

  • The code follows the Symfony Coding Standards as well as the Twig Coding Standards;
  • The code examples should look real for a web application context. Avoid abstract or trivial examples (foo, bar, demo, etc.);
  • The code should follow the Symfony Best Practices.
  • Use Acme when the code requires a vendor name;
  • Use example.com as the domain of sample URLs and example.org and example.net when additional domains are required. All of these domains are reserved by the IANA.
  • To avoid horizontal scrolling on code blocks, we prefer to break a line correctly if it crosses the 85th character;
  • When you fold one or more lines of code, place ... in a comment at the point of the fold. These comments are: // ... (PHP), # ... (Yaml/bash), {# ... #} (Twig), <!-- ... --> (XML/HTML), ; ... (INI), ... (text);
  • When you fold a part of a line, e.g. a variable value, put ... (without comment) at the place of the fold;
  • Description of the folded code: (optional)

    • If you fold several lines: the description of the fold can be placed after the ...;
    • If you fold only part of a line: the description can be placed before the line;
  • If useful to the reader, a PHP code example should start with the namespace declaration;
  • When referencing classes, be sure to show the use statements at the top of your code block. You don't need to show all use statements in every example, just show what is actually being used in the code block;
  • If useful, a codeblock should begin with a comment containing the filename of the file in the code block. Don't place a blank line after this comment, unless the next line is also a comment;
  • You should put a $ in front of every bash line.

Formats

Configuration examples should show all supported formats using configuration blocks. The supported formats (and their orders) are:

  • Configuration (including services): YAML, XML, PHP
  • Routing: Attributes, YAML, XML, PHP
  • Validation: Attributes, YAML, XML, PHP
  • Doctrine Mapping: Attributes, YAML, XML, PHP
  • Translation: XML, YAML, PHP
  • Code Examples (if applicable): PHP Symfony, PHP Standalone

Example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
// src/Foo/Bar.php
namespace Foo;

use Acme\Demo\Cat;
// ...

class Bar
{
    // ...

    public function foo($bar)
    {
        // set foo with a value of bar
        $foo = ...;

        $cat = new Cat($foo);

        // ... check if $bar has the correct value

        return $cat->baz($bar, ...);
    }
}

Caution

In YAML you should put a space after { and before } (e.g. { _controller: ... }), but this should not be done in Twig (e.g. {'hello' : 'value'}).

Files and Directories

  • When referencing directories, always add a trailing slash to avoid confusions with regular files (e.g. "execute the console script located at the bin/ directory").
  • When referencing file extensions explicitly, you should include a leading dot for every extension (e.g. "XML files use the .xml extension").
  • When you list a Symfony file/directory hierarchy, use your-project/ as the top-level directory. E.g.

    1
    2
    3
    4
    5
    your-project/
    ├─ app/
    ├─ src/
    ├─ vendor/
    └─ ...

English Language Standards

Symfony documentation uses the United States English dialect, commonly called American English. The American English Oxford Dictionary is used as the vocabulary reference.

In addition, documentation follows these rules:

  • Section titles: use a variant of the title case, where the first word is always capitalized and all other words are capitalized, except for the closed-class words (read Wikipedia article about headings and titles).

    E.g.: The Vitamins are in my Fresh California Raisins

  • Punctuation: avoid the use of Serial (Oxford) Commas;
  • Pronouns: avoid the use of nosism and always use you instead of we. (i.e. avoid the first person point of view: use the second instead);
  • Gender-neutral language: when referencing a hypothetical person, such as "a user with a session cookie", use gender-neutral pronouns (they/their/them). For example, instead of:

    • he or she, use they
    • him or her, use them
    • his or her, use their
    • his or hers, use theirs
    • himself or herself, use themselves
  • Avoid belittling words: Things that seem "obvious" or "simple" for the person documenting it, can be the exact opposite for the reader. To make sure everybody feels comfortable when reading the documentation, try to avoid words like:

    • basically
    • clearly
    • easy/easily
    • just
    • logically
    • merely
    • obviously
    • of course
    • quick/quickly
    • simply
    • trivial
  • Contractions are allowed: e.g. you can write you would as well as you'd, it is as well as it's, etc.
This work, including the code samples, is licensed under a Creative Commons BY-SA 3.0 license.
TOC
    Version
    We stand with Ukraine.
    Version:

    Symfony 6.2 is backed by

    Symfony 6.2 is backed by

    Be safe against critical risks to your projects and businesses

    Be safe against critical risks to your projects and businesses

    Measure & Improve Symfony Code Performance

    Measure & Improve Symfony Code Performance

    Symfony footer

    ↓ Our footer now uses the colors of the Ukrainian flag because Symfony stands with the people of Ukraine.

    Avatar of Adrian Philipp, a Symfony contributor

    Thanks Adrian Philipp for being a Symfony contributor

    1 commit • 2 lines changed

    View all contributors that help us make Symfony

    Become a Symfony contributor

    Be an active part of the community and contribute ideas, code and bug fixes. Both experts and newcomers are welcome.

    Learn how to contribute

    Symfony™ is a trademark of Symfony SAS. All rights reserved.

    • What is Symfony?

      • Symfony at a Glance
      • Symfony Components
      • Case Studies
      • Symfony Releases
      • Security Policy
      • Logo & Screenshots
      • Trademark & Licenses
      • symfony1 Legacy
    • Learn Symfony

      • Symfony Docs
      • Symfony Book
      • Reference
      • Bundles
      • Best Practices
      • Training
      • eLearning Platform
      • Certification
    • Screencasts

      • Learn Symfony
      • Learn PHP
      • Learn JavaScript
      • Learn Drupal
      • Learn RESTful APIs
    • Community

      • SymfonyConnect
      • Support
      • How to be Involved
      • Code of Conduct
      • Events & Meetups
      • Projects using Symfony
      • Downloads Stats
      • Contributors
      • Backers
    • Blog

      • Events & Meetups
      • A week of symfony
      • Case studies
      • Cloud
      • Community
      • Conferences
      • Diversity
      • Documentation
      • Living on the edge
      • Releases
      • Security Advisories
      • SymfonyInsight
      • Twig
      • SensioLabs
    • Services

      • SensioLabs services
      • Train developers
      • Manage your project quality
      • Improve your project performance
      • Host Symfony projects

      Deployed on

    Follow Symfony

    Search by Algolia