8000 Merge branch '3.4' into 4.1 · javiereguiluz/symfony-docs@1855faf · GitHub
[go: up one dir, main page]
Skip to content

Commit 1855faf

Browse files
javiereguiluzjaviereguiluz
committed
Merge branch '3.4' into 4.1
* 3.4: Simplified the "Release Process" page [Workflow] Fix typo documentation Fix mismatched list items [symfony#9988] fix minor typos [symfony#10099] update XML and PHP config examples [symfony#9969] fix a minor typo [symfony#10022] fix a minor typo preUpdate Event Listener On Uploaded Imagery [symfony#10124] fix XML attribute name [symfony#10062] fix the code block [PHPUnitBridge] Explain how to show stack traces Fix docs on trusted hosts opcode optimizations
2 parents 7422ed1 + 3912063 commit 1855faf

File tree

13 files changed

+119
-171
lines changed
  • forms
  • twig_reference.rst
  • security
  • validation
  • workflow

    • 13 files changed

    +119
    -171
    lines changed

    ‎_images/contributing/release-process.jpg

    -308 KB
    Binary file not shown.

    ‎components/phpunit_bridge.rst

    Lines changed: 18 additions & 0 deletions
    Original file line numberDiff line numberDiff line change
    @@ -248,6 +248,24 @@ times (order matters)::
    248248
    @trigger_error('The second argument of the "Bar" method is deprecated.', E_USER_DEPRECATED);
    249249
    }
    250250

    251+
    Display the Full Stack Trace
    252+
    ----------------------------
    253+
    254+
    By default, the PHPUnit Bridge displays only deprecation messages.
    255+
    To show the full stack trace related to a deprecation, set the value of ``SYMFONY_DEPRECATIONS_HELPER``
    256+
    to a regular expression matching the deprecation message.
    257+
    258+
    For example, if the following deprecation notice is thrown::
    259+
    260+
    1x: Doctrine\Common\ClassLoader is deprecated.
    261+
    1x in EntityTypeTest::setUp from Symfony\Bridge\Doctrine\Tests\Form\Type
    262+
    263+
    Running the following command will display the full stack trace:
    264+
    265+
    .. code-block:: terminal
    266+
    267+
    $ SYMFONY_DEPRECATIONS_HELPER='/Doctrine\\Common\\ClassLoader is deprecated\./' ./vendor/bin/simple-phpunit
    268+
    251269
    Time-sensitive Tests
    252270
    --------------------
    253271

    ‎components/process.rst

    Lines changed: 2 additions & 2 deletions
    Original file line numberDiff line numberDiff line change
    @@ -122,8 +122,8 @@ with a non-zero code)::
    122122

    123123
    $process = new Process(array('/path/command', '--flag', 'arg 1', 'etc.'));
    124124

    125-
    If you need use stream redirections, conditional execution, or any other
    126-
    features provided by the shell of your operating system, you can also define
    125+
    If you need to use stream redirections, conditional execution, or any other
    126+
    feature provided by the shell of your operating system, you can also define
    127127
    commands as strings.
    128128

    129129
    Please note that each OS provides a different syntax for their command-lines

    ‎console.rst

    Lines changed: 1 addition & 1 deletion
    Original file line numberDiff line numberDiff line change
    @@ -69,7 +69,7 @@ method. Then you can optionally define a help message and the
    6969
    ;
    7070
    }
    7171

    72-
    The ``configure()`` command is called automatically at the end of the command
    72+
    The ``configure()`` method is called automatically at the end of the command
    7373
    constructor. If your command defines its own constructor, set the properties
    7474
    first and then call to the parent constructor, to make those properties
    7575
    available in the ``configure()`` method::

    ‎contributing/community/releases.rst

    Lines changed: 46 additions & 146 deletions
    Original file line numberDiff line numberDiff line change
    @@ -1,17 +1,25 @@
    11
    The Release Process
    22
    ===================
    33

    4-
    This document explains the **release process** of the Symfony project (i.e. the
    5-
    code hosted on the main ``symfony/symfony`` `Git repository`_).
    4+
    This document explains the process followed by the Symfony project to develop,
    5+
    release and maintain its different versions.
    66

    7-
    Symfony manages its releases through a *time-based model* and follows the
    8-
    `Semantic Versioning`_ strategy:
    7+
    Symfony releases follow the `semantic versioning`_ strategy and they are
    8+
    published through a *time-based model*:
    99

    10-
    * A new Symfony minor version (e.g. 2.8, 3.2, 4.1) comes out every *six months*:
    11-
    one in *May* and one in *November*;
    12-
    * A new Symfony major version (e.g., 3.0, 4.0) comes out every *two years* and
    13-
    it's released at the same time of the last minor version of the previous major
    14-
    version.
    10+
    * A new **Symfony patch version** (e.g. 2.8.15, 4.1.7) comes out roughly every
    11+
    month. It only contains bug fixes, so you can safely upgrade your apps;
    12+
    * A new **Symfony minor version** (e.g. 2.8, 3.2, 4.1) comes out every *six months*:
    13+
    one in *May* and one in *November*. It contains bug fixes and new features, but
    14+
    it doesn't include any breaking change, so you can safely upgrade your apps;
    15+
    * A new **Symfony major version** (e.g. 3.0, 4.0) comes out every *two years*.
    16+
    It can contain breaking changes, so you may need to do some changes in your
    17+
    apps before upgrading.
    18+
    19+
    .. tip::
    20+
    21+
    `Subscribe to Symfony Roadmap notifications`_ to receive an email when a new
    22+
    Symfony version is published or when a Symfony version reaches its end of life.
    1523

    1624
    .. _contributing-release-development:
    1725

    @@ -32,113 +40,36 @@ During the development phase, any new feature can be reverted if it won't be
    3240
    finished in time or if it won't be stable enough to be included in the current
    3341
    final release.
    3442

    43+
    .. tip::
    44+
    45+
    Check out the `Symfony Roadmap`_ to learn more about any specific version.
    46+
    3547
    .. _contributing-release-maintenance:
    48+
    .. _symfony-versions:
    49+
    .. _releases-lts:
    3650

    3751
    Maintenance
    3852
    -----------
    3953

    40-
    Each Symfony version is maintained for a fixed period of time, depending on the
    41-
    type of the release. This maintenance is divided into:
    42-
    43-
    * *Bug fixes and security fixes*: During this period, all issues can be fixed.
    44-
    The end of this period is referenced as being the *end of maintenance* of a
    45-
    release.
    46-
    47-
    * *Security fixes only*: During this period, only security related issues can
    48-
    be fixed. The end of this period is referenced as being the *end of life* of
    49-
    a release.
    50-
    51-
    .. note::
    52-
    53-
    The :doc:`maintenance document </contributing/code/maintenance>` describes
    54-
    the boundaries of acceptable changes during maintenance.
    55-
    56-
    Symfony Versions
    57-
    ----------------
    58-
    59-
    Standard Versions
    60-
    ~~~~~~~~~~~~~~~~~
    61-
    62-
    A **Standard Minor Version** is maintained for an *eight month* period for bug
    63-
    fixes, and for a *fourteen month* period for security issue fixes.
    64-
    65-
    In Symfony 2.x branch, the number of minor versions wasn't constrained, so that
    66-
    branch ended up with nine minor versions (from 2.0 to 2.8). Starting from
    67-
    3.x branch, the number of minor versions is limited to five (from X.0 to X.4).
    54+
    Starting from the Symfony 3.x branch, the number of minor versions is limited to
    55+
    five per branch (X.0, X.1, X.2, X.3 and X.4). The last minor version of a branch
    56+
    (e.g. 3.4, 4.4, 5.4) is considered a **long-term support version** and the other
    57+
    ones are considered **standard versions**:
    6858

    69-
    .. _releases-lts:
    70-
    71-
    Long Term Support Versions
    72-
    ~~~~~~~~~~~~~~~~~~~~~~~~~~
    73-
    74-
    Every two years, a new **Long Term Support Version** (usually abbreviated as "LTS")
    75-
    is published. Each LTS version is supported for a *three year* period for bug
    76-
    fixes, and for a *four year* period for security issue fixes.
    59+
    ======================= ===================== ================================
    60+
    Version Type Bugs are fixed for... Security issues are fixed for...
    61+
    ======================= ===================== ================================
    62+
    Standard E377 8 months 14 months
    63+
    Long-Term Support (LTS) 3 years 4 years
    64+
    ======================= ===================== ================================
    7765

    7866
    .. note::
    7967

    80-
    Paid support after the three year support provided by the community can
    81-
    also be bought from `SensioLabs`_.
    82-
    83-
    In the Symfony 2.x branch, the LTS versions are 2.3, 2.7 and 2.8. Starting from the 3.x
    84-
    branch, only the last minor version of each branch is considered LTS (e.g. 3.4,
    85-
    4.4, 5.4, etc.)
    86-
    87-
    Schedule
    88-
    --------
    89-
    90-
    Below is the schedule for the first few versions that use this release model:
    91-
    92-
    .. image:: /_images/contributing/release-process.jpg
    93-
    :align: center
    94-
    95-
    * **Yellow** represents the Development phase
    96-
    * **Blue** represents the Stabilization phase
    97-
    * **Green** represents the Maintenance period
    68+
    After the active maintenance of a Symfony version has ended, you can get
    69+
    `professional Symfony support`_ from SensioLabs, the company which sponsors
    70+
    the Symfony project.
    9871

    99-
    .. tip::
    100-
    101-
    If you want to learn more about the timeline of any given Symfony version,
    102-
    use the online `timeline calculator`_.
    103-
    104-
    .. tip::
    105-
    106-
    Whenever an important event related to Symfony versions happens (a version
    107-
    reaches end of maintenance or a new patch version is released for
    108-
    instance), you can automatically receive an email notification if you
    109-
    subscribed on the `roadmap notification`_ page.
    110-
    111-
    .. _version-history:
    112-
    113-
    ============ ============== ======= ======================== ===========
    114-
    Version Feature Freeze Release End of Maintenance End of Life
    115-
    ============ ============== ======= ======================== ===========
    116-
    `2.0`_ 05/2011 07/2011 03/2013 (20 months) 09/2013
    117-
    `2.1`_ 07/2012 09/2012 05/2013 (9 months) 11/2013
    118-
    `2.2`_ 01/2013 03/2013 11/2013 (8 months) 05/2014
    119-
    `2.3`_ (LTS) 03/2013 05/2013 05/2016 (36 months) 05/2017
    120-
    `2.4`_ 09/2013 11/2013 09/2014 (10 months [1]_) 01/2015
    121-
    `2.5`_ 03/2014 05/2014 01/2015 (8 months) 07/2015
    122-
    `2.6`_ 09/2014 11/2014 07/2015 (8 months) 01/2016
    123-
    `2.7`_ (LTS) 03/2015 05/2015 05/2018 (36 months) 05/2019
    124-
    `2.8`_ (LTS) 09/2015 11/2015 11/2018 (36 months [2]_) 11/2019
    125-
    `3.0`_ 09/2015 11/2015 07/2016 (8 months [3]_) 01/2017
    126-
    `3.1`_ 03/2016 05/2016 01/2017 (8 months) 07/2017
    127-
    `3.2`_ 09/2016 11/2016 07/2017 (8 months) 01/2018
    128-
    `3.3`_ 03/2017 05/2017 01/2018 (8 months) 07/2018
    129-
    `3.4`_ (LTS) 09/2017 11/2017 11/2020 (36 months) 11/2021
    130-
    `4.0`_ 09/2017 11/2017 07/2018 (8 months) 01/2019
    131-
    `4.1`_ 03/2018 05/2018 01/2019 (8 months) 07/2019
    132-
    `4.2`_ 09/2018 11/2018 07/2019 (8 months) 01/2020
    133-
    `4.3`_ 03/2019 05/2019 01/2020 (8 months) 07/2020
    134-
    `4.4`_ (LTS) 09/2019 11/2019 11/2022 (36 months) 11/2023
    135-
    `5.0`_ 09/2019 11/2019 07/2020 (8 months) 01/2021
    136-
    ... ... ... ... ...
    137-
    ============ ============== ======= ======================== ===========
    138-
    139-
    .. [1] Symfony 2.4 maintenance has been `extended to September 2014`_.
    140-
    .. [2] Symfony 2.8 is the last version of the Symfony 2.x branch.
    141-
    .. [3] Symfony 3.0 is the first version to use the new release process based on five minor releases.
    72+
    .. _deprecations:
    14273

    14374
    Backward Compatibility
    14475
    ----------------------
    @@ -147,20 +78,9 @@ Our :doc:`Backward Compatibility Promise </contributing/code/bc>` is very
    14778
    strict and allows developers to upgrade with confidence from one minor version
    14879
    of Symfony to the next one.
    14980

    150-
    Whenever keeping backward compatibility is not possible, the feature, the
    151-
    enhancement or the bug fix will be scheduled for the next major version.
    152-
    153-
    However, :doc:`Experimental Features </contributing/code/experimental>` are
    154-
    **not** part of the backward compatibility promise and their APIs can change
    155-
    from one minor version to the next. The changelog must explain the changes and
    156-
    how to upgrade.
    157-
    158-
    Deprecations
    159-
    ------------
    160-
    16181
    When a feature implementation cannot be replaced with a better one without
    162-
    breaking backward compatibility, there is still the possibility to deprecate
    163-
    the old implementation and add a new preferred one along side. Read the
    82+
    breaking backward compatibility, Symfony deprecates the old implementation and
    83+
    adds a new preferred one along side. Read the
    16484
    :ref:`conventions <contributing-code-conventions-deprecations>` document to
    16585
    learn more about how deprecations are handled in Symfony.
    16686

    @@ -179,7 +99,9 @@ This release process was adopted to give more *predictability* and
    17999
    * Coordinate the Symfony timeline with popular PHP projects that work well
    180100
    with Symfony and with projects using Symfony;
    181101
    * Give time to the Symfony ecosystem to catch up with the new versions
    182-
    (bundle authors, documentation writers, translators, ...).
    102+
    (bundle authors, documentation writers, translators, ...);
    103+
    * Give companies a strict and predictable timeline they can rely on to plan
    104+
    their own projects development.
    183105

    184106
    The six month period was chosen as two releases fit in a year. It also allows
    185107
    for plenty of time to work on new features and it allows for non-ready
    @@ -192,29 +114,7 @@ version: a new version is published every six months, and there is a two months
    192114
    period to upgrade. Companies wanting more stability use the LTS versions: a new
    193115
    version is published every two years and there is a year to upgrade.
    194116

    195-
    .. _Semantic Versioning: https://semver.org/
    196-
    .. _Git repository: https://github.com/symfony/symfony
    197-
    .. _SensioLabs: https://sensiolabs.com/
    198-
    .. _roadmap notification: https://symfony.com/roadmap
    199-
    .. _extended to September 2014: https://symfony.com/blog/extended-maintenance-for-symfony-2-4
    200-
    .. _timeline calculator: https://symfony.com/roadmap#checker
    201-
    .. _`2.0`: https://symfony.com/roadmap?version=2.0
    202-
    .. _`2.1`: https://symfony.com/roadmap?version=2.1
    203-
    .. _`2.2`: https://symfony.com/roadmap?version=2.2
    204-
    .. _`2.3`: https://symfony.com/roadmap?version=2.3
    205-
    .. _`2.4`: https://symfony.com/roadmap?version=2.4
    206-
    .. _`2.5`: https://symfony.com/roadmap?version=2.5
    207-
    .. _`2.6`: https://symfony.com/roadmap?version=2.6
    208-
    .. _`2.7`: https://symfony.com/roadmap?version=2.7
    209-
    .. _`2.8`: https://symfony.com/roadmap?version=2.8
    210-
    .. _`3.0`: https://symfony.com/roadmap?version=3.0
    211-
    .. _`3.1`: https://symfony.com/roadmap?version=3.1
    212-
    .. _`3.2`: https://symfony.com/roadmap?version=3.2
    213-
    .. _`3.3`: https://symfony.com/roadmap?version=3.3
    214-
    .. _`3.4`: https://symfony.com/roadmap?version=3.4
    215-
    .. _`4.0`: https://symfony.com/roadmap?version=4.0
    216-
    .. _`4.1`: https://symfony.com/roadmap?version=4.1
    217-
    .. _`4.2`: https://symfony.com/roadmap?version=4.2
    218-
    .. _`4.3`: https://symfony.com/roadmap?version=4.3
    219-
    .. _`4.4`: https://symfony.com/roadmap?version=4.4
    220-
    .. _`5.0`: https://symfony.com/roadmap?version=5.0
    117+
    .. _`semantic versioning`: https://semver.org/
    118+
    .. _`Subscribe to Symfony Roadmap notifications`: https://symfony.com/account
    119+
    .. _`Symfony Roadmap`: https://symfony.com/roadmap#checker
    120+
    .. _`professional Symfony support`: https://sensiolabs.com/

    ‎controller/argument_value_resolver.rst

    Lines changed: 21 additions & 3 deletions
    Original file line numberDiff line numberDiff line change
    @@ -80,9 +80,27 @@ type-hinted method arguments:
    8080
    .. code-block:: xml
    8181
    8282
    <!-- config/packages/sensio_framework_extra.xml -->
    83-
    <sensio-framework-extra:config>
    84-
    <request converters="true" auto-convert="true" />
    85-
    </sensio-framework-extra:config>
    83+
    <?xml version="1.0" encoding="UTF-8" ?>
    84+
    <container xmlns="http://symfony.com/schema/dic/services"
    85+
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    86+
    xmlns:sensio-framework-extra="http://symfony.com/schema/dic/symfony_extra"
    87+
    xsi:schemaLocation="http://symfony.com/schema/dic/services
    88+
    http://symfony.com/schema/dic/services/services-1.0.xsd">
    89+
    90+
    <sensio-framework-extra:config>
    91+
    <request converters="true" auto-convert="false" />
    92+
    </sensio-framework-extra:config>
    93+
    </container>
    94+
    95+
    .. code-block:: php
    96+
    97+
    // config/packages/sensio_framework_extra.php
    98+
    $container->loadFromExtension('sensio_framework_extra', array(
    99+
    'request' => array(
    100+
    'converters' => true,
    101+
    'auto_convert' => false,
    102+
    ),
    103+
    ));
    86104
    87105
    Adding a new value resolver requires creating a class that implements
    88106
    :class:`Symfony\\Component\\HttpKernel\\Controller\\ArgumentValueResolverInterface`

    ‎controller/upload_file.rst

    Lines changed: 5 additions & 0 deletions
    Original file line numberDiff line numberDiff line change
    @@ -316,6 +316,7 @@ automatically upload the file when persisting the entity::
    316316
    namespace App\EventListener;
    317317

    318318
    use Symfony\Component\HttpFoundation\File\UploadedFile;
    319+
    use Symfony\Component\HttpFoundation\File\File;
    319320
    use Doctrine\ORM\Event\LifecycleEventArgs;
    320321
    use Doctrine\ORM\Event\PreUpdateEventArgs;
    321322
    use App\Entity\Product;
    @@ -357,6 +358,10 @@ automatically upload the file when persisting the entity::
    357358
    if ($file instanceof UploadedFile) {
    358359
    $fileName = $this->uploader->upload($file);
    359360
    $entity->setBrochure($fileName);
    361+
    } elseif ($file instanceof File) {
    362+
    // prevents the full file path being saved on updates
    363+
    // as the path is set on the postLoad listener
    364+
    $entity->setBrochure($file->getFilename());
    360365
    }
    361366
    }
    362367
    }

    ‎reference/configuration/framework.rst

    Lines changed: 9 additions & 9 deletions
    Original file line numberDiff line numberDiff line change
    @@ -383,16 +383,16 @@ method might be vulnerable to some of these attacks because it depends on
    383383
    the configuration of your web server. One simple solution to avoid these
    384384
    attacks is to whitelist the hosts that your Symfony application can respond
    385385
    to. That's the purpose of this ``trusted_hosts`` option. If the incoming
    386-
    request's hostname doesn't match one in this list, the application won't
    387-
    respond and the user will receive a 400 response.
    386+
    request's hostname doesn't match one of the regular expressions in this list,
    387+
    the application won't respond and the user will receive a 400 response.
    388388

    389389
    .. configuration-block::
    390390

    391391
    .. code-block:: yaml
    392392
    393393
    # config/packages/framework.yaml
    394394
    framework:
    395-
    trusted_hosts: ['example.com', 'example.org']
    395+
    trusted_hosts: ['^example\.com$', '^example\.org$']
    396396
    397397
    .. code-block:: xml
    398398
    @@ -406,8 +406,8 @@ respond and the user will receive a 400 response.
    406406
    http://symfony.com/schema/dic/symfony http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
    407407
    408408
    <framework:config>
    409-
    <framework:trusted-host>example.com</framework:trusted-host>
    410-
    <framework:trusted-host>example.org</framework:trusted-host>
    409+
    <framework:trusted-host>^example\.com$</framework:trusted-host>
    410+
    <framework:trusted-host>^example\.org$</framework:trusted-host>
    411411
    <!-- ... -->
    412412
    </framework:config>
    413413
    </container>
    @@ -416,17 +416,17 @@ respond and the user will receive a 400 response.
    416416
    417417
    // config/packages/framework.php
    418418
    $container->loadFromExtension('framework', array(
    419-
    'trusted_hosts' => array('example.com', 'example.org'),
    419+
    'trusted_hosts' => array('^example\.com$', '^example\.org$'),
    420420
    ));
    421421
    422-
    Hosts can also be configured using regular expressions (e.g. ``^(.+\.)?example.com$``),
    423-
    which make it easier to respond to any subdomain.
    422+
    Hosts can also be configured to respond to any subdomain, via
    423+
    ``^(.+\.)?example\.com$`` for instance.
    424424

    425425
    In addition, you can also set the trusted hosts in the front controller
    426426
    using the ``Request::setTrustedHosts()`` method::
    427427

    428428
    // public/index.php
    429-
    Request::setTrustedHosts(array('^(.+\.)?example.com$', '^(.+\.)?example.org$'));
    429+
    Request::setTrustedHosts(array('^(.+\.)?example\.com$', '^(.+\.)?example\.org$'));
    430430

    431431
    The default value for this option is an empty array, meaning that the application
    432432
    can respond to any given host.

    ‎reference/forms/twig_reference.rst

    Lines changed: 1 addition & 1 deletion
    Original file line numberDiff line numberDiff line change
    @@ -209,7 +209,7 @@ This test will check if the current ``form`` does not have a parent form view.
    209209
    .. code-block:: twig
    210210
    211211
    {# DON'T DO THIS: this simple check can't differentiate between a form having
    212-
    a parent form view and a form defining a normal form field called 'parent' #}
    212+
    a parent form view and a form defining a nested form field called 'parent' #}
    213213
    214214
    {% if form.parent is null %}
    215215
    {{ form_errors(form) }}

    0 commit comments

    Comments
     (0)
    0