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

Commit 1c962a6

Browse files
xabbuhxabbuh
committed
Merge branch '2.7' into 2.8
* 2.7: (31 commits) fix a typo [#7115] fix headlines Better explain the most common problems when testing emails Clarify the mappings that require no method prefix. Make some long lines shorter to fit our soft limit of 80 chars per line Microsoft Azure update step by step article and screenshots for the new Microsoft Azure Portal Minor rewords in the text and the code example Update questionhelper.rst Add docs about console question answer normalizing. [#7105] add XML and PHP service config examples Minor rewordings When talking about generic responses, don't spell it as Response (which is a Symfony class) xabbuh review fix typo fix yml marker to yaml add documentation about access denied handler Update outdated link to AWS ELB security groups Added missing comma Reworded the caution about open redirects Warn user about open redirects ...
2 parents 4e94fa3 + 1c7ddc9 commit 1c962a6
  • questionhelper.rst
  • css_selector.rst
  • dependency_injection
  • dom_crawler.rst
  • event_dispatcher
  • event_dispatcher.rst
  • filesystem
  • form.rst
  • http_foundation.rst
  • http_kernel.rst
  • phpunit_bridge.rst
  • process.rst
  • property_access.rst
  • templating
  • templating.rst
  • translation.rst
  • validator
  • var_dumper.rst
  • configuration
  • configuration.rst
  • console
  • contributing
  • controller
  • controller.rst
  • deployment
  • doctrine
  • email
  • event_dispatcher
  • expressions.rst
  • form
  • forms.rst
  • http_cache
  • introduction
  • performance.rst
  • quick_tour
  • reference
  • request
  • routing
  • routing.rst
  • security
  • security.rst
  • service_container
  • service_container.rst
  • templating
  • templating.rst
  • testing.rst
  • validation
  • validation.rst

    • Some content is hidden

    Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

    123 files changed

    +502
    -343
    lines changed

    ‎_images/deployment/azure-website/step-01.png

    189 KB
    Loading

    ‎_images/deployment/azure-website/step-02.png

    -27 KB
    Loading

    ‎_images/deployment/azure-website/step-03.png

    82.2 KB
    Loading

    ‎_images/deployment/azure-website/step-04.png

    75 KB
    Loading

    ‎_images/deployment/azure-website/step-05.png

    51.9 KB
    Loading

    ‎_images/deployment/azure-website/step-06.png

    17.5 KB
    Loading

    ‎_images/deployment/azure-website/step-07.png

    76.3 KB
    Loading

    ‎_images/deployment/azure-website/step-08.png

    50.8 KB
    Loading

    ‎_images/deployment/azure-website/step-09.png

    -43.7 KB
    Loading

    ‎_images/deployment/azure-website/step-10.png

    31.7 KB
    Loading

    ‎_images/deployment/azure-website/step-11.png

    119 KB
    Loading

    ‎_images/deployment/azure-website/step-12.png

    27.6 KB
    Loading

    ‎_images/deployment/azure-website/step-13.png

    43.8 KB
    Loading

    ‎_images/deployment/azure-website/step-14.png

    212 KB
    Loading

    ‎_images/deployment/azure-website/step-15.png

    -145 KB
    Loading

    ‎_images/deployment/azure-website/step-16.png

    -376 Bytes
    Loading

    ‎_images/deployment/azure-website/step-17.png

    -120 KB
    Binary file not shown.

    ‎_images/deployment/azure-website/step-18.png

    -121 KB
    Binary file not shown.

    ‎best_practices/security.rst

    Lines changed: 2 additions & 2 deletions
    Original file line numberDiff line numberDiff line change
    @@ -129,7 +129,7 @@ Using Expressions for Complex Security Restrictions
    129129

    130130
    If your security logic is a little bit more complex, you can use an :doc:`expression </components/expression_language>`
    131131
    inside ``@Security``. In the following example, a user can only access the
    132-
    controller if their email matches the value returned by the ``getAuthorEmail``
    132+
    controller if their email matches the value returned by the ``getAuthorEmail()``
    133133
    method on the ``Post`` object:
    134134

    135135
    .. code-block:: php
    @@ -258,7 +258,7 @@ of magnitude easier than :doc:`ACLs </security/acl>` and will give
    258258
    you the flexibility you need in almost all cases.
    259259

    260260
    First, create a voter class. The following example shows a voter that implements
    261-
    the same ``getAuthorEmail`` logic you used above:
    261+
    the same ``getAuthorEmail()`` logic you used above:
    262262

    263263
    .. code-block:: php
    264264

    ‎bundles/extension.rst

    Lines changed: 1 addition & 1 deletion
    10000
    Original file line numberDiff line numberDiff line change
    @@ -90,7 +90,7 @@ but it is more common if you put these definitions in a configuration file
    9090
    the extension!
    9191

    9292
    For instance, assume you have a file called ``services.xml`` in the
    93-
    ``Resources/config`` directory of your bundle, your load method looks like::
    93+
    ``Resources/config`` directory of your bundle, your ``load()`` method looks like::
    9494

    9595
    use Symfony\Component\DependencyInjection\Loader\XmlFileLoader;
    9696
    use Symfony\Component\Config\FileLocator;

    ‎bundles/inheritance.rst

    Lines changed: 7 additions & 6 deletions
    Original file line numberDiff line numberDiff line change
    @@ -10,11 +10,12 @@ in one of your own bundles. Symfony gives you a very convenient way to override
    1010
    things like controllers, templates, and other files in a bundle's
    1111
    ``Resources/`` directory.
    1212

    13-
    For example, suppose that you're installing the `FOSUserBundle`_, but you
    14-
    want to override its base ``layout.html.twig`` template, as well as one of
    15-
    its controllers. Suppose also that you have your own UserBundle where you want
    16-
    the overridden files to live. Start by registering the FOSUserBundle as the
    17-
    "parent" of your bundle::
    13+
    For example, suppose that you have installed `FOSUserBundle`_, but you want to
    14+
    override its base ``layout.html.twig`` template, as well as one of its
    15+
    controllers.
    16+
    17+
    First, create a new bundle called UserBundle and enable it in your application.
    18+
    Then, register the third-party FOSUserBundle as the "parent" of your bundle::
    1819

    1920
    // src/UserBundle/UserBundle.php
    2021
    namespace UserBundle;
    @@ -40,7 +41,7 @@ simply by creating a file with the same name.
    4041
    Overriding Controllers
    4142
    ~~~~~~~~~~~~~~~~~~~~~~
    4243

    43-
    Suppose you want to add some functionality to the ``registerAction`` of a
    44+
    Suppose you want to add some functionality to the ``registerAction()`` of a
    4445
    ``RegistrationController`` that lives inside FOSUserBundle. To do so,
    4546
    just create your own ``RegistrationController.php`` file, override the bundle's
    4647
    original method, and change its functionality::

    ‎changelog.rst

    Lines changed: 5 additions & 1 deletion
    Original file line numberDiff line numberDiff line change
    @@ -1,5 +1,9 @@
    11
    .. index::
    22
    single: CHANGELOG
    3+
    4+
    .. !! CAUTION !!
    5+
    This file is automatically generated. Do not add new changelog
    6+
    items when preparing a pull request.
    37
    48
    The Documentation Changelog
    59
    ===========================
    @@ -282,7 +286,7 @@ Minor Documentation Changes
    282286
    * `#30 <https://github.com/symfony/symfony-docs/pull/30>`_ Moved the rest of the book chapters (javiereguiluz)
    283287
    * `#24 <https://github.com/symfony/symfony-docs/pull/24>`_ Moved book chapters out of the book (javiereguiluz)
    284288
    * `#20 <https://github.com/symfony/symfony-docs/pull/20>`_ Creating the Controller topic (xabbuh)
    285-
    * `#6747 <https://github.com/symfony/symfony-docs/pull/6747>`_ Correcting reference to ``isSuccessful`` method for Process (aedmonds)
    289+
    * `#6747 <https://github.com/symfony/symfony-docs/pull/6747>`_ Correcting reference to ``isSuccessful()`` method for Process (aedmonds)
    286290
    * `#6600 <https://github.com/symfony/symfony-docs/pull/6600>`_ Removing some extra details from #6444 (weaverryan)
    287291
    * `#6715 <https://github.com/symfony/symfony-docs/pull/6715>`_ [Book] Remove DI extension info and link the cookbook article instead (WouterJ)
    288292
    * `#6745 <https://github.com/symfony/symfony-docs/pull/6745>`_ Branch fix (Talita Kocjan Zager, weaverryan)

    ‎components/config/definition.rst

    Lines changed: 3 additions & 3 deletions
    Original file line numberDiff line numberDiff line change
    @@ -475,7 +475,7 @@ methods::
    475475
    ->defaultFalse()
    476476
    ;
    477477

    478-
    The ``canBeDisabled`` method looks about the same except that the section
    478+
    The ``canBeDisabled()`` method looks about the same except that the section
    479479
    would be enabled by default.
    480480

    481481
    Merging Options
    @@ -655,7 +655,7 @@ a second argument::
    655655
    ->end()
    656656
    ;
    657657

    658-
    As well as fixing this, ``fixXmlConfig`` ensures that single XML elements
    658+
    As well as fixing this, ``fixXmlConfig()`` ensures that single XML elements
    659659
    are still turned into an array. So you may have:
    660660

    661661
    .. code-block:: xml
    @@ -671,7 +671,7 @@ and sometimes only:
    671671
    672672
    By default ``connection`` would be an array in the first case and a string
    673673
    in the second making it difficult to validate. You can ensure it is always
    674-
    an array with ``fixXmlConfig``.
    674+
    an array with ``fixXmlConfig()``.
    675675

    676676
    You can further control the normalization process if you need to. For example,
    677677
    you may want to allow a string to be set and used as a particular key or

    ‎components/console/changing_default_command.rst

    Lines changed: 1 addition & 1 deletion
    Original file line numberDiff line numberDiff line change
    @@ -6,7 +6,7 @@ Changing the Default Command
    66

    77
    The Console component will always run the ``ListCommand`` when no command name is
    88
    passed. In order to change the default command you just need to pass the command
    9-
    name to the ``setDefaultCommand`` method::
    9+
    name to the ``setDefaultCommand()`` method::
    1010

    1111
    namespace Acme\Console\Command;
    1212

    ‎components/console/helpers/dialoghelper.rst

    Lines changed: 2 additions & 2 deletions
    Original file line numberDiff line numberDiff line change
    @@ -177,8 +177,8 @@ Let the User Choose from a List of Answers
    177177
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    178178

    179179
    If you have a predefined set of answers the user can choose from, you
    180-
    could use the ``ask`` method described above or, to make sure the user
    181-
    provided a correct answer, the ``askAndValidate`` method. Both have
    180+
    could use the ``ask()`` method described above or, to make sure the user
    181+
    provided a correct answer, the ``askAndValidate()`` method. Both have
    182182
    the disadvantage that you need to handle incorrect values yourself.
    183183

    184184
    Instead, you can use the

    ‎components/console/helpers/progresshelper.rst

    Lines changed: 1 addition & 1 deletion
    Original file line numberDiff line numberDiff line change
    @@ -5,7 +5,7 @@ Progress Helper
    55
    ===============
    66

    77
    .. versionadded:: 2.3
    8-
    The ``setCurrent`` method was introduced in Symfony 2.3.
    8+
    The ``setCurrent()`` method was introduced in Symfony 2.3.
    99

    1010
    .. caution::
    1111

    ‎components/console/helpers/questionhelper.rst

    Lines changed: 34 additions & 1 deletion
    Original file line numberDiff line numberDiff line change
    @@ -209,6 +209,38 @@ convenient for passwords::
    209209
    like in the example above. In this case, a ``RuntimeException``
    210210
    would be thrown.
    211211

    212+
    Normalizing the Answer
    213+
    ----------------------
    214+
    215+
    Before validating the answer, you can "normalize" it to fix minor errors or
    216+
    tweak it as needed. For instance, in a previous example you asked for the bundle
    217+
    name. In case the user adds white spaces around the name by mistake, you can
    218+
    trim the name before validating it. To do so, configure a normalizer using the
    219+
    :method:`Symfony\\Component\\Console\\Question\\Question::setNormalizer`
    220+
    method::
    221+
    222+
    use Symfony\Component\Console\Question\Question;
    223+
    224+
    // ...
    225+
    public function execute(InputInterface $input, OutputInterface $output)
    226+
    {
    227+
    // ...
    228+
    $question = new Question('Please enter the name of the bundle', 'AppBundle');
    229+
    $question->setNormalizer(function ($value) {
    230+
    // $value can be null here
    231+
    return $value ? trim($value) : '';
    232+
    });
    233+
    234+
    $name = $helper->ask($input, $output, $question);
    235+
    }
    236+
    237+
    238+
    .. caution::
    239+
    240+
    The normalizer is called first and the returned value is used as the input
    241+
    of the validator. If the answer is invalid, don't throw exceptions in the
    242+
    normalizer and let the validator handle those errors.
    243+
    212244
    Validating the Answer
    213245
    ---------------------
    214246

    @@ -226,11 +258,12 @@ method::
    226258
    // ...
    227259
    $question = new Question('Please enter the name of the bundle', 'AcmeDemoBundle');
    228260
    $question->setValidator(function ($answer) {
    229-
    if ('Bundle' !== substr($answer, -6)) {
    261+
    if (!is_string($answer) || 'Bundle' !== substr($answer, -6)) {
    230262
    throw new \RuntimeException(
    231263
    'The name of the bundle should be suffixed with \'Bundle\''
    232264
    );
    233265
    }
    266+
    234267
    return $answer;
    235268
    });
    236269
    $question->setMaxAttempts(2);

    ‎components/css_selector.rst

    Lines changed: 1 addition & 1 deletion
    Original file line numberDiff line numberDiff line change
    @@ -34,7 +34,7 @@ long and unwieldy expressions.
    3434

    3535
    Many developers -- particularly web developers -- are more comfortable
    3636
    using CSS selectors to find elements. As well as working in stylesheets,
    37-
    CSS selectors are used in JavaScript with the ``querySelectorAll`` function
    37+
    CSS selectors are used in JavaScript with the ``querySelectorAll()`` function
    3838
    and in popular JavaScript libraries such as jQuery, Prototype and MooTools.
    3939

    4040
    CSS selectors are less powerful than XPath, but far easier to write, read

    ‎components/dependency_injection/compilation.rst

    Lines changed: 7 additions & 7 deletions
    Original file line numberDiff line numberDiff line change
    @@ -44,16 +44,16 @@ and can be registered with the container with::
    4444

    4545
    $container->registerExtension($extension);
    4646

    47-
    The main work of the extension is done in the ``load`` method. In the ``load``
    47+
    The main work of the extension is done in the ``load()`` method. In the ``load()``
    4848
    method you can load configuration from one or more configuration files as
    4949
    well as manipulate the container definitions using the methods shown in
    5050
    :doc:`/service_container/definitions`.
    5151

    52-
    The ``load`` method is passed a fresh container to set up, which is then
    52+
    The ``load()`` method is passed a fresh container to set up, which is then
    5353
    merged afterwards into the container it is registered with. This allows
    5454
    you to have several extensions managing container definitions independently.
    5555
    The extensions do not add to the containers configuration when they are
    56-
    added but are processed when the container's ``compile`` method is called.
    56+
    added but are processed when the container's ``compile()`` method is called.
    5757

    5858
    A very simple extension may just load configuration files into the container::
    5959

    @@ -85,7 +85,7 @@ sections of config files loaded directly into the container as being for
    8585
    a particular extension. These sections on the config will not be processed
    8686
    directly by the container but by the relevant Extension.
    8787

    88-
    The Extension must specify a ``getAlias`` method to implement the interface::
    88+
    The Extension must specify a ``getAlias()`` method to implement the interface::
    8989

    9090
    // ...
    9191

    @@ -100,7 +100,7 @@ The Extension must specify a ``getAlias`` method to implement the interface::
    100100
    }
    101101

    102102
    For YAML configuration files specifying the alias for the extension as a
    103-
    key will mean that those values are passed to the Extension's ``load`` method:
    103+
    key will mean that those values are passed to the Extension's ``load()`` method:
    104104

    105105
    .. code-block:: yaml
    106106
    @@ -133,7 +133,7 @@ are loaded::
    133133
    or an exception will be thrown.
    134134

    135135
    The values from those sections of the config files are passed into the first
    136-
    argument of the ``load`` method of the extension::
    136+
    argument of the ``load()`` method of the extension::
    137137

    138138
    public function load(array $configs, ContainerBuilder $container)
    139139
    {
    @@ -190,7 +190,7 @@ the XML configuration::
    190190

    191191
    .. note::
    192192

    193-
    XSD validation is optional, returning ``false`` from the ``getXsdValidationBasePath``
    193+
    XSD validation is optional, returning ``false`` from the ``getXsdValidationBasePath()``
    194194
    method will disable it.
    195195

    196196
    The XML version of the config would then look like this:

    ‎components/dom_crawler.rst

    Lines changed: 2 additions & 2 deletions
    Original file line numberDiff line numberDiff line change
    @@ -285,13 +285,13 @@ and :phpclass:`DOMNode` objects:
    285285

    286286
    $html = $crawler->html();
    287287

    288-
    The ``html`` method is new in Symfony 2.3.
    288+
    The ``html()`` method is new in Symfony 2.3.
    289289

    290290
    Links
    291291
    ~~~~~
    292292

    293293
    To find a link by name (or a clickable image by its ``alt`` attribute), use
    294-
    the ``selectLink`` method on an existing crawler. This returns a Crawler
    294+
    the ``selectLink()`` method on an existing crawler. This returns a Crawler
    295295
    instance with just the selected link(s). Calling ``link()`` gives you a special
    296296
    :class:`Symfony\\Component\\DomCrawler\\Link` object::
    297297

    ‎components/event_dispatcher.rst

    Lines changed: 1 addition & 1 deletion
    Original file line numberDiff line numberDiff line change
    @@ -152,7 +152,7 @@ The ``addListener()`` method takes up to three arguments:
    152152
    A `PHP callable`_ is a PHP variable that can be used by the
    153153
    ``call_user_func()`` function and returns ``true`` when passed to the
    154154
    ``is_callable()`` function. It can be a ``\Closure`` instance, an object
    155-
    implementing an ``__invoke`` method (which is what closures are in fact),
    155+
    implementing an ``__invoke()`` method (which is what closures are in fact),
    156156
    a string representing a function or an array representing an object
    157157
    method or a class method.
    158158

    ‎components/event_dispatcher/immutable_dispatcher.rst

    Lines changed: 1 addit 97AE ion & 1 deletion
    Original file line numberDiff line numberDiff line change
    @@ -35,4 +35,4 @@ Now, inject that into an ``ImmutableEventDispatcher``::
    3535
    You'll need to use this new dispatcher in your project.
    3636

    3737
    If you are trying to execute one of the methods which modifies the dispatcher
    38-
    (e.g. ``addListener``), a ``BadMethodCallException`` is thrown.
    38+
    (e.g. ``addListener()``), a ``BadMethodCallException`` is thrown.

    ‎components/filesystem/lock_handler.rst

    Lines changed: 1 addition & 1 deletion
    Original file line numberDiff line numberDiff line change
    @@ -51,7 +51,7 @@ second argument of the constructor.
    5151

    5252
    The :method:`Symfony\\Component\\Filesystem\\LockHandler::lock` method tries to
    5353
    acquire the lock. If the lock is acquired, the method returns ``true``,
    54-
    ``false`` otherwise. If the ``lock`` method is called several times on the same
    54+
    ``false`` otherwise. If the ``lock()`` method is called several times on the same
    5555
    instance it will always return ``true`` if the lock was acquired on the first
    5656
    call.
    5757

    ‎components/form.rst

    Lines changed: 4 additions & 4 deletions
    Original file line numberDiff line numberDiff line change
    @@ -369,7 +369,7 @@ Creating a simple Form
    369369
    If you're using the Symfony Framework, then the form factory is available
    370370
    automatically as a service called ``form.factory``. Also, the default
    371371
    base controller class has a :method:`Symfony\\Bundle\\FrameworkBundle\\Controller::createFormBuilder`
    372-
    method, which is a shortcut to fetch the form factory and call ``createBuilder``
    372+
    method, which is a shortcut to fetch the form factory and call ``createBuilder()``
    373373
    on it.
    374374

    375375
    Creating a form is done via a :class:`Symfony\\Component\\Form\\FormBuilder`
    @@ -426,8 +426,8 @@ is created from the form factory.
    426426
    }
    427427
    }
    428428
    429-
    As you can see, creating a form is like writing a recipe: you call ``add``
    430-
    for each new field you want to create. The first argument to ``add`` is the
    429+
    As you can see, creating a form is like writing a recipe: you call ``add()``
    430+
    for each new field you want to create. The first argument to ``add()`` is the
    431431
    name of your field, and the second is the fully qualified class name. If you
    432432
    use PHP 5.5 or above, you can use ``::class`` constant of a form type. The Form
    433433
    component comes with a lot of :doc:`built-in types </reference/forms/types>`.
    @@ -726,7 +726,7 @@ method to access the list of errors. It returns a
    726726

    727727
    $errorsAsArray = iterator_to_array($form->getErrors());
    728728

    729-
    This is useful, for example, if you want to use PHP's ``array_`` function
    729+
    This is useful, for example, if you want to use PHP's ``array_*()`` function
    730730
    on the form errors.
    731731

    732732
    Learn more

    ‎components/http_foundation.rst

    Lines changed: 1 addition & 1 deletion
    Original file line numberDiff line numberDiff line change
    @@ -11,7 +11,7 @@ The HttpFoundation Component
    1111

    1212
    In PHP, the request is represented by some global variables (``$_GET``,
    1313
    ``$_POST``, ``$_FILES``, ``$_COOKIE``, ``$_SESSION``, ...) and the response is
    14-
    generated by some functions (``echo``, ``header``, ``setcookie``, ...).
    14+
    generated by some functions (``echo``, ``header()``, ``setcookie()``, ...).
    1515

    1616
    The Symfony HttpFoundation component replaces these default PHP global
    1717
    variables and functions by an object-oriented layer.

    0 commit comments

    Comments
     (0)
    0