8000 Merge branch '2.8' into 3.1 · symfony/symfony-docs@a9e8d99 · GitHub
[go: up one dir, main page]
Skip to content

Commit a9e8d99

Browse files
xabbuhxabbuh
committed
Merge branch '2.8' into 3.1
* 2.8: (37 commits) Minor rewording for the security:checker article add missing dot at the end of sentence add labels for old headlines delivery adresses are separate XML element nodes Removed the description of the deprecated `delivery_address` option Removed any mention of the deprecated delivery_address option Removed the mention to the deprecated delivery_address option Fixed a minor syntax issue Fixed a minor syntax issue Update Swiftmailer configuration docs Added a tip about the TMPDIR env variable adding the namespace for ArrayInput use short config syntax for factories Minor fix and rewording Update file_permissions.rst Update console.rst Minor change Improved code example of `prepend` method Fixed the signature of prepend method in the code example Fixed tag namespace in the example of xml configuration ...
2 parents 3d469cd + 3223fb1 commit a9e8d99

File tree

17 files changed

+301
-45
lines changed

17 files changed

+301
-45
lines changed

‎best_practices/security.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -216,7 +216,7 @@ Checking Permissions without @Security
216216

217217
The above example with ``@Security`` only works because we're using the
218218
:ref:`ParamConverter <best-practices-paramconverter>`, which gives the expression
219-
access to the a ``post`` variable. If you don't use this, or have some other
219+
access to the ``post`` variable. If you don't use this, or have some other
220220
more advanced use-case, you can always do the same security check in PHP:
221221

222222
.. code-block:: php

‎bundles/prepend_extension.rst

Lines changed: 5 additions & 2 deletions
< 6D40 ul aria-label="File view" class="prc-SegmentedControl-SegmentedControl-e7570 mx-2" data-size="small">
    • Original file line numberDiff line numberDiff line change
    @@ -56,6 +56,7 @@ The following example illustrates how to prepend
    5656
    a configuration setting in multiple bundles as well as disable a flag in multiple bundles
    5757
    in case a specific other bundle is not registered::
    5858

    59+
    // src/Acme/HelloBundle/DependencyInjection/AcmeHelloExtension.php
    5960
    public function prepend(ContainerBuilder $container)
    6061
    {
    6162
    // get all bundles
    @@ -69,8 +70,10 @@ in case a specific other bundle is not registered::
    6970
    case 'acme_something':
    7071
    case 'acme_other':
    7172
    // set use_acme_goodbye to false in the config of
    72-
    // acme_something and acme_other note that if the user manually
    73-
    // configured use_acme_goodbye to true in the app/config/config.yml
    73+
    // acme_something and acme_other
    74+
    //
    75+
    // note that if the user manually configured
    76+
    // use_acme_goodbye to true in app/config/config.yml
    7477
    // then the setting would in the end be true and not false
    7578
    $container->prependExtensionConfig($name, $config);
    7679
    break;

    ‎components/dependency_injection/compilation.rst

    Lines changed: 2 additions & 2 deletions
    Original file line numberDiff line numberDiff line change
    @@ -204,7 +204,7 @@ The XML version of the config would then look like this:
    204204
    xsi:schemaLocation="http://www.example.com/symfony/schema/ http://www.example.com/symfony/schema/hello-1.0.xsd">
    205205
    206206
    <acme_demo:config>
    207-
    <acme_demo:foo>fooValue</acme_hello:foo>
    207+
    <acme_demo:foo>fooValue</acme_demo:foo>
    208208
    <acme_demo:bar>barValue</acme_demo:bar>
    209209
    </acme_demo:config>
    210210
    </container>
    @@ -292,7 +292,7 @@ method is called by implementing
    292292
    {
    293293
    // ...
    294294

    295-
    public function prepend()
    295+
    public function prepend(ContainerBuilder $container)
    296296
    {
    297297
    // ...
    298298

    ‎components/filesystem/lock_handler.rst

    Lines changed: 13 additions & 3 deletions
    Original file line numberDiff line numberDiff line change
    @@ -45,9 +45,19 @@ the file, so you can pass any value for this argument.
    4545
    to avoid name collisions, ``LockHandler`` also appends a hash to the name of
    4646
    the lock file.
    4747

    48-
    By default, the lock will be created in the temporary directory, but you can
    49-
    optionally select the directory where locks are created by passing it as the
    50-
    second argument of the constructor.
    48+
    By default, the lock will be created in the system's temporary directory, but
    49+
    you can optionally select the directory where locks are created by passing it as
    50+
    the second argument of the constructor.
    51+
    52+
    .. tip::
    53+
    54+
    Another way to configure the directory where the locks are created is to
    55+
    define a special environment variable, because PHP will use that value to
    56+
    override the default temporary directory. On Unix-based systems, define the
    57+
    ``TMPDIR`` variable. On Windows systems, define any of these variables:
    58+
    ``TMP``, ``TEMP`` or ``USERPROFILE`` (they are checked in this order). This
    59+
    technique is useful for example when deploying a third-party Symfony
    60+
    application whose code can't be modified.
    5161

    5262
    The :method:`Symfony\\Component\\Filesystem\\LockHandler::lock` method tries to
    5363
    acquire the lock. If the lock is acquired, the method returns ``true``,

    ‎console.rst

    Lines changed: 2 additions & 2 deletions
    Original file line numberDiff line numberDiff line change
    @@ -4,7 +4,7 @@
    44
    Console Commands
    55
    ================
    66

    7-
    The Symfony framework provide lots of commands through the ``bin/console`` script
    7+
    The Symfony framework provides lots of commands through the ``bin/console`` script
    88
    (e.g. the well-known ``bin/console cache:clear`` command). These commands are
    99
    created with the :doc:`Console component </components/console>`. You can also
    1010
    use it to create your own commands.
    @@ -176,7 +176,7 @@ instead::
    176176
    }
    177177
    }
    178178

    179-
    Now, once you created the required services and logic, the command will execute
    179+
    Now, once you have created the required services and logic, the command will execute
    180180
    the ``create()`` method of the ``app.user_manager`` service and the user will
    181181
    be created.
    182182

    ‎console/calling_commands.rst

    Lines changed: 3 additions & 0 deletions
    Original file line numberDiff line numberDiff line change
    @@ -10,6 +10,9 @@ generating Doctrine2 proxies, dumping Assetic assets, ...).
    1010

    1111
    Calling a command from another one is straightforward::
    1212

    13+
    use Symfony\Component\Console\Input\ArrayInput;
    14+
    // ...
    15+
    1316
    protected function execute(InputInterface $input, OutputInterface $output)
    1417
    {
    1518
    $command = $this->getApplication()->find('demo:greet');

    ‎email.rst

    Lines changed: 1 addition & 1 deletion
    Original file line numberDiff line numberDiff line change
    @@ -83,7 +83,7 @@ The following configuration attributes are available:
    8383

    8484
    * ``type`` (how to queue the messages, ``file`` or ``memory`` is supported, see :doc:`/email/spool`)
    8585
    * ``path`` (where to store the messages)
    86-
    * ``delivery_address`` (an email address where to send ALL emails)
    86+
    * ``delivery_addresses`` (an array of email addresses where to send ALL emails)
    8787
    * ``disable_delivery`` (set to true to disable delivery completely)
    8888

    8989
    Sending Emails

    ‎email/dev_environment.rst

    Lines changed: 15 additions & 10 deletions
    Original file line numberDiff line numberDiff line change
    @@ -53,20 +53,22 @@ will not be sent when you run tests, but will continue to be sent in the
    5353
    If you'd also like to disable deliver in the ``dev`` environment, simply
    5454
    add this same configuration to the ``config_dev.yml`` file.
    5555

    56-
    Sending to a Specified Address
    57-
    ------------------------------
    56+
    .. _sending-to-a-specified-address:
    5857

    59-
    You can also choose to have all email sent to a specific address, instead
    58+
    Sending to a Specified Address(es)
    59+
    ----------------------------------
    60+
    61+
    You can also choose to have all email sent to a specific address or a list of addresses, instead
    6062
    of the address actually specified when sending the message. This can be done
    61-
    via the ``delivery_address`` option:
    63+
    via the ``delivery_addresses`` option:
    6264

    6365
    .. configuration-block::
    6466

    6567
    .. code-block:: yaml
    6668
    6769
    # app/config/config_dev.yml
    6870
    swiftmailer:
    69-
    delivery_address: 'dev@example.com'
    71+
    delivery_addresses: ['dev@example.com']
    7072
    7173
    .. code-block:: xml
    7274
    @@ -78,14 +80,16 @@ via the ``delivery_address`` option:
    7880
    xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd
    7981
    http://symfony.com/schema/dic/swiftmailer http://symfony.com/schema/dic/swiftmailer/swiftmailer-1.0.xsd">
    8082
    81-
    <swiftmailer:config delivery-address="dev@example.com" />
    83+
    <swiftmailer:config>
    84+
    <swiftmailer:delivery-address>dev@example.com</swiftmailer:delivery-address>
    85+
    </swiftmailer:config>
    8286
    </container>
    8387
    8488
    .. code-block:: php
    8589
    8690
    // app/config/config_dev.php
    8791
    $container->loadFromExtension('swiftmailer', array(
    88-
    'delivery_address' => "dev@example.com",
    92+
    'delivery_addresses' => array("dev@example.com"),
    8993
    ));
    9094
    9195
    Now, suppose you're sending an email to ``recipient@example.com``.
    @@ -139,7 +143,7 @@ by adding the ``delivery_whitelist`` option:
    139143
    140144
    # app/config/config_dev.yml
    141145
    swiftmailer:
    142-
    delivery_address: dev@example.com
    146+
    delivery_addresses: ['dev@example.com']
    143147
    delivery_whitelist:
    144148
    # all email addresses matching these regexes will be delivered
    145149
    # like normal, as well as being sent to dev@example.com
    @@ -158,19 +162,20 @@ by adding the ``delivery_whitelist`` option:
    158162
    xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd
    159163
    http://symfony.com/schema/dic/swiftmailer http://symfony.com/schema/dic/swiftmailer/swiftmailer-1.0.xsd">
    160164
    161-
    <swiftmailer:config delivery-address="dev@example.com">
    165+
    <swiftmailer:config>
    162166
    <!-- all email addresses matching these regexes will be delivered
    163167
    like normal, as well as being sent to dev@example.com -->
    164168
    <swiftmailer:delivery-whitelist-pattern>/@specialdomain\.com$/</swiftmailer:delivery-whitelist-pattern>
    165169
    <swiftmailer:delivery-whitelist-pattern>/^admin@mydomain\.com$/</swiftmailer:delivery-whitelist-pattern>
    170+
    <swiftmailer:delivery-address>dev@example.com</swiftmailer:delivery-address>
    166171
    </swiftmailer:config>
    167172
    </container>
    168173
    169174
    .. code-block:: php
    170175
    171176
    // app/config/config_dev.php
    172177
    $container->loadFromExtension('swiftmailer', array(
    173-
    'delivery_address' => "dev@example.com",
    178+
    'delivery_addresses' => array("dev@example.com"),
    174179
    'delivery_whitelist' => array(
    175180
    // all email addresses matching these regexes will be delivered
    176181
    // like normal, as well as being sent to dev@example.com

    ‎frontend/custom_version_strategy.rst

    Lines changed: 201 additions & 0 deletions
    Original file line numberDiff line numberDiff line change
    @@ -0,0 +1,201 @@
    1+
    .. index::
    2+
    single: Asset; Custom Version Strategy
    3+
    4+
    How to Use a Custom Version Strategy for Assets
    5+
    ===============================================
    6+
    7+
    .. versionadded:: 2.7
    8+
    The Asset component was introduced in Symfony 2.7.
    9+
    10+
    Asset versioning is a technique that improves the performance of web
    11+
    applications by adding a version identifier to the URL of the static assets
    12+
    (CSS, JavaScript, images, etc.) When the content of the asset changes, its
    13+
    identifier is also modified to force the browser to download it again instead of
    14+
    reusing the cached asset.
    15+
    16+
    Symfony supports asset versioning thanks to the
    17+
    :ref:`version <reference-framework-assets-version>` and
    18+
    :ref:`version_format <reference-framework-assets-version-format>` configuration
    19+
    options. If your application requires a more advanced versioning, such as
    20+
    generating the version dynamically based on some external information, you can
    21+
    create your own version strategy.
    22+
    23+
    Creating your Own Asset Version Strategy
    24+
    ----------------------------------------
    25+
    26+
    The following example shows how to create a version strategy compatible with
    27+
    `gulp-buster`_. This tool defines a configuration file called ``busters.json``
    28+
    which maps each asset file to its content hash:
    29+
    30+
    .. code-block:: json
    31+
    32+
    {
    33+
    "js/script.js": "f9c7afd05729f10f55b689f36bb20172",
    34+
    "css/style.css": "91cd067f79a5839536b46c494c4272d8"
    35+
    }
    36+
    37+
    Implement VersionStrategyInterface
    38+
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    39+
    40+
    Asset version strategies are PHP classes that implement the
    41+
    :class:`Symfony\\Component\\Asset\\VersionStrategy\\VersionStrategyInterface`.
    42+
    In this example, the constructor of the class takes as arguments the path to
    43+
    the manifest file generated by `gulp-buster`_ and the format of the generated
    44+
    version string::
    45+
    46+
    // src/AppBundle/Asset/VersionStrategy/GulpBusterVersionStrategy.php
    47+
    namespace AppBundle\Asset\VersionStrategy;
    48+
    49+
    use Symfony\Component\Asset\VersionStrategy\VersionStrategyInterface;
    50+
    51+
    class GulpBusterVersionStrategy implements VersionStrategyInterface
    52+
    {
    53+
    /**
    54+
    * @var string
    55+
    */
    56+
    private $manifestPath;
    57+
    58+
    /**
    59+
    * @var string
    60+
    */
    61+
    private $format;
    62+
    63+
    /**
    64+
    * @var string[]
    65+
    */
    66+
    private $hashes;
    67+
    68+
    /**
    69+
    * @param string $manifestPath
    70+
    * @param string|null $format
    71+
    */
    72+
    public function __construct($manifestPath, $format = null)
    73+
    {
    74+
    $this->manifestPath = $manifestPath;
    75+
    $this->format = $format ?: '%s?%s';
    76+
    }
    77+
    78+
    public function getVersion($path)
    79+
    {
    80+
    if (!is_array($this->hashes)) {
    81+
    $this->hashes = $this->loadManifest();
    82+
    }
    83+
    84+
    return isset($this->hashes[$path]) ? $this->hashes[$path] : '';
    85+
    }
    86+
    87+
    public function applyVersion($path)
    88+
    {
    89+
    $version = $this->getVersion($path);
    90+
    91+
    if ('' === $version) {
    92+
    return $path;
    93+
    }
    94+
    95+
    $versionized = sprintf($this->format, ltrim($path, '/'), $version);
    96+
    97+
    if ($path && '/' === $path[0]) {
    98+
    return '/'.$versionized;
    99+
    }
    100+
    101+
    return $versionized;
    102+
    }
    103+
    104+
    private function loadManifest(array $options)
    105+
    {
    106+
    return json_decode(file_get_contents($this->manifestPath), true);
    107+
    }
    108+
    }
    109+
    110+
    Register the Strategy Service
    111+
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    112+
    113+
    After creating the strategy PHP class, register it as a Symfony service.
    114+
    115+
    .. configuration-block::
    116+
    117+
    .. code-block:: yaml
    118+
    119+
    # app/config/services.yml
    120+
    services:
    121+
    app.assets.versioning.gulp_buster:
    122+
    class: AppBundle\Asset\VersionStrategy\GulpBusterVersionStrategy
    123+
    arguments:
    124+
    - "%kernel.root_dir%/../busters.json"
    125+
    - "%%s?version=%%s"
    126+
    public: false
    127+
    128+
    .. code-block:: xml
    129+
    130+
    <!-- app/config/services.xml -->
    131+
    <?xml version="1.0" encoding="UTF-8" ?>
    132+
    <container xmlns="http://symfony.com/schema/dic/services"
    133+
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    134+
    xsi:schemaLocation="http://symfony.com/schema/dic/services
    135+
    http://symfony.com/schema/dic/services/services-1.0.xsd"
    136+
    >
    137+
    <services>
    138+
    <service id="app.assets.versioning.gulp_buster"
    139+
    class="AppBundle\Asset\VersionStrategy\GulpBusterVersionStrategy" public="false">
    140+
    <argument>%kernel.root_dir%/../busters.json</argument>
    141+
    <argument>%%s?version=%%s</argument>
    142+
    </service>
    143+
    </services>
    144+
    </container>
    145+
    146+
    .. code-block:: php
    147+
    148+
    // app/config/services.php
    149+
    use Symfony\Component\DependencyInjection\Definition;
    150+
    151+
    $definition = new Definition(
    152+
    'AppBundle\Asset\VersionStrategy\GulpBusterVersionStrategy',
    153+
    array(
    154+
    '%kernel.root_dir%/../busters.json',
    155+
    '%%s?version=%%s',
    156+
    )
    157+
    );
    158+
    $definition->setPublic(false);
    159+
    160+
    $container->setDefinition('app.assets.versioning.gulp_buster', $definition);
    161+
    162+
    Finally, enable the new asset versioning for all the application assets or just
    163+
    for some :ref:`asset package <reference-framework-assets-packages>` thanks to
    164+
    the :ref:`version_strategy <reference-framework-assets-version_strategy>` option:
    165+
    166+
    .. configuration-block::
    167+
    168+
    .. code-block:: yaml
    169+
    170+
    # app/config/config.yml
    171+
    framework:
    172+
    # ...
    173+
    assets:
    174+
    version_strategy: 'app.assets.versioning.gulp_buster'
    175+
    176+
    .. code-block:: xml
    177+
    178+
    <!-- app/config/config.xml -->
    179+
    <?xml version="1.0" encoding="UTF-8" ?>
    180+
    <container xmlns="http://symfony.com/schema/dic/services"
    181+
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    182+
    xmlns:framework="http://symfony.com/schema/dic/symfony"
    183+
    xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd
    184+
    http://symfony.com/schema/dic/symfony http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
    185+
    186+
    <framework:config>
    187+
    <framework:assets version-strategy="app.assets.versioning.gulp_buster" />
    188+
    </framework:config>
    189+
    </container>
    190+
    191+
    .. code-block:: php
    192+
    193+
    // app/config/config.php
    194+
    $container->loadFromExtension('framework', array(
    195+
    // ...
    196+
    'assets' => array(
    197+
    'version_strategy' => 'app.assets.versioning.gulp_buster',
    198+
    ),
    199+
    ));
    200+
    201+
    .. _`gulp-buster`: https://www.npmjs.com/package/gulp-buster

    0 commit comments

    Comments
     (0)
    0