From 7054cf41bbcf737639c80a43180c024ddbe590dc Mon Sep 17 00:00:00 2001 From: Benjamin Clay Date: Sat, 29 Nov 2014 15:47:37 +0100 Subject: [PATCH 1/2] Ref #3903 - Normalize methods listings --- components/http_foundation/sessions.rst | 121 +++++++++--------- components/security/authorization.rst | 12 +- cookbook/form/create_custom_field_type.rst | 31 +++-- .../custom_authentication_provider.rst | 28 ++-- 4 files changed, 100 insertions(+), 92 deletions(-) diff --git a/components/http_foundation/sessions.rst b/components/http_foundation/sessions.rst index 1e3d262bd1a..de591f81fdc 100644 --- a/components/http_foundation/sessions.rst +++ b/components/http_foundation/sessions.rst @@ -107,10 +107,10 @@ Session Attributes Returns true if the attribute exists. :method:`Symfony\\Component\\HttpFoundation\\Session\\Session::replace` - Sets multiple attributes at once: takes a keyed array and sets each key => value pair; + Sets multiple attributes at once: takes a keyed array and sets each key => value pair. :method:`Symfony\\Component\\HttpFoundation\\Session\\Session::remove` - Deletes an attribute by key; + Deletes an attribute by key. :method:`Symfony\\Component\\HttpFoundation\\Session\\Session::clear` Clear all attributes. @@ -123,7 +123,7 @@ an array. A few methods exist for "Bag" management: :method:`Symfony\\Component\\HttpFoundation\\Session\\Session::getBag` Gets a :class:`Symfony\\Component\\HttpFoundation\\Session\\SessionBagInterface` by - bag name; + bag name. :method:`Symfony\\Component\\HttpFoundation\\Session\\Session::getFlashBag` Gets the :class:`Symfony\\Component\\HttpFoundation\\Session\\Flash\\FlashBagInterface`. @@ -132,6 +132,7 @@ an array. A few methods exist for "Bag" management: Session Metadata ................ + :method:`Symfony\\Component\\HttpFoundation\\Session\\Session::getMetadataBag` Gets the :class:`Symfony\\Component\\HttpFoundation\\Session\\Storage\\MetadataBag` which contains information about the session. @@ -157,16 +158,16 @@ bag types if necessary. :class:`Symfony\\Component\\HttpFoundation\\Session\\SessionBagInterface` has the following API which is intended mainly for internal purposes: -* :method:`Symfony\\Component\\HttpFoundation\\Session\\SessionBagInterface::getStorageKey`: - Returns the key which the bag will ultimately store its array under in ``$_SESSION``. - Generally this value can be left at its default and is for internal use. +:method:`Symfony\\Component\\HttpFoundation\\Session\\SessionBagInterface::getStorageKey` + Returns the key which the bag will ultimately store its array under in ``$_SESSION``. + Generally this value can be left at its default and is for internal use. -* :method:`Symfony\\Component\\HttpFoundation\\Session\\SessionBagInterface::initialize`: - This is called internally by Symfony session storage classes to link bag data - to the session. +:method:`Symfony\\Component\\HttpFoundation\\Session\\SessionBagInterface::initialize` + This is called internally by Symfony session storage classes to link bag data + to the session. -* :method:`Symfony\\Component\\HttpFoundation\\Session\\SessionBagInterface::getName`: - Returns the name of the session bag. +:method:`Symfony\\Component\\HttpFoundation\\Session\\SessionBagInterface::getName` + Returns the name of the session bag. Attributes ~~~~~~~~~~ @@ -175,11 +176,11 @@ The purpose of the bags implementing the :class:`Symfony\\Component\\HttpFoundat is to handle session attribute storage. This might include things like user ID, and remember me login settings or other user based state information. -* :class:`Symfony\\Component\\HttpFoundation\\Session\\Attribute\\AttributeBag` - This is the standard default implementation. +:class:`Symfony\\Component\\HttpFoundation\\Session\\Attribute\\AttributeBag` + This is the standard default implementation. -* :class:`Symfony\\Component\\HttpFoundation\\Session\\Attribute\\NamespacedAttributeBag` - This implementation allows for attributes to be stored in a structured namespace. +:class:`Symfony\\Component\\HttpFoundation\\Session\\Attribute\\NamespacedAttributeBag` + This implementation allows for attributes to be stored in a structured namespace. Any plain key-value storage system is limited in the extent to which complex data can be stored since each key must be unique. You can achieve @@ -210,29 +211,29 @@ This way you can easily access a key within the stored array directly and easily :class:`Symfony\\Component\\HttpFoundation\\Session\\Attribute\\AttributeBagInterface` has a simple API -* :method:`Symfony\\Component\\HttpFoundation\\Session\\Attribute\\AttributeBagInterface::set`: - Sets an attribute by key; +:method:`Symfony\\Component\\HttpFoundation\\Session\\Attribute\\AttributeBagInterface::set` + Sets an attribute by key. -* :method:`Symfony\\Component\\HttpFoundation\\Session\\Attribute\\AttributeBagInterface::get`: - Gets an attribute by key; +:method:`Symfony\\Component\\HttpFoundation\\Session\\Attribute\\AttributeBagInterface::get` + Gets an attribute by key. -* :method:`Symfony\\Component\\HttpFoundation\\Session\\Attribute\\AttributeBagInterface::all`: - Gets all attributes as an array of key => value; +:method:`Symfony\\Component\\HttpFoundation\\Session\\Attribute\\AttributeBagInterface::all` + Gets all attributes as an array of key => value. -* :method:`Symfony\\Component\\HttpFoundation\\Session\\Attribute\\AttributeBagInterface::has`: - Returns true if the attribute exists; +:method:`Symfony\\Component\\HttpFoundation\\Session\\Attribute\\AttributeBagInterface::has` + Returns true if the attribute exists. -* :method:`Symfony\\Component\\HttpFoundation\\Session\\Attribute\\AttributeBagInterface::keys`: - Returns an array of stored attribute keys; +:method:`Symfony\\Component\\HttpFoundation\\Session\\Attribute\\AttributeBagInterface::keys` + Returns an array of stored attribute keys. -* :method:`Symfony\\Component\\HttpFoundation\\Session\\Attribute\\AttributeBagInterface::replace`: - Sets multiple attributes at once: takes a keyed array and sets each key => value pair. +:method:`Symfony\\Component\\HttpFoundation\\Session\\Attribute\\AttributeBagInterface::replace` + Sets multiple attributes at once: takes a keyed array and sets each key => value pair. -* :method:`Symfony\\Component\\HttpFoundation\\Session\\Attribute\\AttributeBagInterface::remove`: - Deletes an attribute by key; +:method:`Symfony\\Component\\HttpFoundation\\Session\\Attribute\\AttributeBagInterface::remove` + Deletes an attribute by key. -* :method:`Symfony\\Component\\HttpFoundation\\Session\\Attribute\\AttributeBagInterface::clear`: - Clear the bag; +:method:`Symfony\\Component\\HttpFoundation\\Session\\Attribute\\AttributeBagInterface::clear` + Clear the bag. Flash Messages ~~~~~~~~~~~~~~ @@ -246,49 +247,49 @@ updated page or an error page. Flash messages set in the previous page request would be displayed immediately on the subsequent page load for that session. This is however just one application for flash messages. -* :class:`Symfony\\Component\\HttpFoundation\\Session\\Flash\\AutoExpireFlashBag` - In this implementation, messages set in one page-load will - be available for display only on the next page load. These messages will auto - expire regardless of if they are retrieved or not. +:class:`Symfony\\Component\\HttpFoundation\\Session\\Flash\\AutoExpireFlashBag` + In this implementation, messages set in one page-load will + be available for display only on the next page load. These messages will auto + expire regardless of if they are retrieved or not. -* :class:`Symfony\\Component\\HttpFoundation\\Session\\Flash\\FlashBag` - In this implementation, messages will remain in the session until - they are explicitly retrieved or cleared. This makes it possible to use ESI - caching. +:class:`Symfony\\Component\\HttpFoundation\\Session\\Flash\\FlashBag` + In this implementation, messages will remain in the session until + they are explicitly retrieved or cleared. This makes it possible to use ESI + caching. :class:`Symfony\\Component\\HttpFoundation\\Session\\Flash\\FlashBagInterface` has a simple API -* :method:`Symfony\\Component\\HttpFoundation\\Session\\Flash\\FlashBagInterface::add`: - Adds a flash message to the stack of specified type; +:method:`Symfony\\Component\\HttpFoundation\\Session\\Flash\\FlashBagInterface::add` + Adds a flash message to the stack of specified type. -* :method:`Symfony\\Component\\HttpFoundation\\Session\\Flash\\FlashBagInterface::set`: - Sets flashes by type; This method conveniently takes both single messages as - a ``string`` or multiple messages in an ``array``. +:method:`Symfony\\Component\\HttpFoundation\\Session\\Flash\\FlashBagInterface::set` + Sets flashes by type; This method conveniently takes both single messages as + a ``string`` or multiple messages in an ``array``. -* :method:`Symfony\\Component\\HttpFoundation\\Session\\Flash\\FlashBagInterface::get`: - Gets flashes by type and clears those flashes from the bag; +:method:`Symfony\\Component\\HttpFoundation\\Session\\Flash\\FlashBagInterface::get` + Gets flashes by type and clears those flashes from the bag. -* :method:`Symfony\\Component\\HttpFoundation\\Session\\Flash\\FlashBagInterface::setAll`: - Sets all flashes, accepts a keyed array of arrays ``type => array(messages)``; +:method:`Symfony\\Component\\HttpFoundation\\Session\\Flash\\FlashBagInterface::setAll` + Sets all flashes, accepts a keyed array of arrays ``type => array(messages)``. -* :method:`Symfony\\Component\\HttpFoundation\\Session\\Flash\\FlashBagInterface::all`: - Gets all flashes (as a keyed array of arrays) and clears the flashes from the bag; +:method:`Symfony\\Component\\HttpFoundation\\Session\\Flash\\FlashBagInterface::all` + Gets all flashes (as a keyed array of arrays) and clears the flashes from the bag. -* :method:`Symfony\\Component\\HttpFoundation\\Session\\Flash\\FlashBagInterface::peek`: - Gets flashes by type (read only); +:method:`Symfony\\Component\\HttpFoundation\\Session\\Flash\\FlashBagInterface::peek` + Gets flashes by type (read only). -* :method:`Symfony\\Component\\HttpFoundation\\Session\\Flash\\FlashBagInterface::peekAll`: - Gets all flashes (read only) as keyed array of arrays; +:method:`Symfony\\Component\\HttpFoundation\\Session\\Flash\\FlashBagInterface::peekAll` + Gets all flashes (read only) as keyed array of arrays. -* :method:`Symfony\\Component\\HttpFoundation\\Session\\Flash\\FlashBagInterface::has`: - Returns true if the type exists, false if not; +:method:`Symfony\\Component\\HttpFoundation\\Session\\Flash\\FlashBagInterface::has` + Returns true if the type exists, false if not. -* :method:`Symfony\\Component\\HttpFoundation\\Session\\Flash\\FlashBagInterface::keys`: - Returns an array of the stored flash types; +:method:`Symfony\\Component\\HttpFoundation\\Session\\Flash\\FlashBagInterface::keys` + Returns an array of the stored flash types. -* :method:`Symfony\\Component\\HttpFoundation\\Session\\Flash\\FlashBagInterface::clear`: - Clears the bag; +:method:`Symfony\\Component\\HttpFoundation\\Session\\Flash\\FlashBagInterface::clear` + Clears the bag. For simple applications it is usually sufficient to have one flash message per type, for example a confirmation notice after a form is submitted. However, diff --git a/components/security/authorization.rst b/components/security/authorization.rst index c5b357e5118..9c3000a429e 100644 --- a/components/security/authorization.rst +++ b/components/security/authorization.rst @@ -40,13 +40,13 @@ itself depends on multiple voters, and makes a final verdict based on all the votes (either positive, negative or neutral) it has received. It recognizes several strategies: -* ``affirmative`` (default) +``affirmative`` (default) grant access as soon as any voter returns an affirmative response; -* ``consensus`` +``consensus`` grant access if there are more voters granting access than there are denying; -* ``unanimous`` +``unanimous`` only grant access if none of the voters has denied access; .. code-block:: php @@ -85,14 +85,14 @@ of :class:`Symfony\\Component\\Security\\Core\\Authorization\\Voter\\VoterInterf which means they have to implement a few methods which allows the decision manager to use them: -* ``supportsAttribute($attribute)`` +``supportsAttribute($attribute)`` will be used to check if the voter knows how to handle the given attribute; -* ``supportsClass($class)`` +``supportsClass($class)`` will be used to check if the voter is able to grant or deny access for an object of the given class; -* ``vote(TokenInterface $token, $object, array $attributes)`` +``vote(TokenInterface $token, $object, array $attributes)`` this method will do the actual voting and return a value equal to one of the class constants of :class:`Symfony\\Component\\Security\\Core\\Authorization\\Voter\\VoterInterface`, i.e. ``VoterInterface::ACCESS_GRANTED``, ``VoterInterface::ACCESS_DENIED`` diff --git a/cookbook/form/create_custom_field_type.rst b/cookbook/form/create_custom_field_type.rst index 3cb5f33c265..891a274f7a8 100644 --- a/cookbook/form/create_custom_field_type.rst +++ b/cookbook/form/create_custom_field_type.rst @@ -60,20 +60,23 @@ all of the logic and rendering of that field type. To see some of the logic, check out the `ChoiceType`_ class. There are three methods that are particularly important: -* ``buildForm()`` - Each field type has a ``buildForm`` method, which is where - you configure and build any field(s). Notice that this is the same method - you use to setup *your* forms, and it works the same here. - -* ``buildView()`` - This method is used to set any extra variables you'll - need when rendering your field in a template. For example, in `ChoiceType`_, - a ``multiple`` variable is set and used in the template to set (or not - set) the ``multiple`` attribute on the ``select`` field. See `Creating a Template for the Field`_ - for more details. - -* ``setDefaultOptions()`` - This defines options for your form type that - can be used in ``buildForm()`` and ``buildView()``. There are a lot of - options common to all fields (see :doc:`/reference/forms/types/form`), - but you can create any others that you need here. +``buildForm()`` + Each field type has a ``buildForm`` method, which is where + you configure and build any field(s). Notice that this is the same method + you use to setup *your* forms, and it works the same here. + +``buildView()`` + This method is used to set any extra variables you'll + need when rendering your field in a template. For example, in `ChoiceType`_, + a ``multiple`` variable is set and used in the template to set (or not + set) the ``multiple`` attribute on the ``select`` field. See `Creating a Template for the Field`_ + for more details. + +``setDefaultOptions()`` + This defines options for your form type that + can be used in ``buildForm()`` and ``buildView()``. There are a lot of + options common to all fields (see :doc:`/reference/forms/types/form`), + but you can create any others that you need here. .. tip:: diff --git a/cookbook/security/custom_authentication_provider.rst b/cookbook/security/custom_authentication_provider.rst index be18a236549..ad7dd66c239 100644 --- a/cookbook/security/custom_authentication_provider.rst +++ b/cookbook/security/custom_authentication_provider.rst @@ -333,18 +333,22 @@ create a class which implements The :class:`Symfony\\Bundle\\SecurityBundle\\DependencyInjection\\Security\\Factory\\SecurityFactoryInterface` requires the following methods: -* ``create`` method, which adds the listener and authentication provider - to the DI container for the appropriate security context; - -* ``getPosition`` method, which must be of type ``pre_auth``, ``form``, ``http``, - and ``remember_me`` and defines the position at which the provider is called; - -* ``getKey`` method which defines the configuration key used to reference - the provider in the firewall configuration; - -* ``addConfiguration`` method, which is used to define the configuration - options underneath the configuration key in your security configuration. - Setting configuration options are explained later in this chapter. +``create`` + Method which adds the listener and authentication provider + to the DI container for the appropriate security context; + +``getPosition`` + Method which must be of type ``pre_auth``, ``form``, ``http``, + and ``remember_me`` and defines the position at which the provider is called; + +``getKey`` + Method which defines the configuration key used to reference + the provider in the firewall configuration; + +``addConfiguration`` + Method which is used to define the configuration + options underneath the configuration key in your security configuration. + Setting configuration options are explained later in this chapter. .. note:: From 0912b19ee7002ef81fcda4511bc5599fefa732e8 Mon Sep 17 00:00:00 2001 From: Benjamin Clay Date: Sun, 21 Dec 2014 12:58:42 +0100 Subject: [PATCH 2/2] Ref #3903 - new list normalized --- book/forms.rst | 23 +++++++++++-------- components/http_foundation/sessions.rst | 1 - .../custom_authentication_provider.rst | 6 ++--- 3 files changed, 16 insertions(+), 14 deletions(-) diff --git a/book/forms.rst b/book/forms.rst index 681ff57dc70..7463506118d 100644 --- a/book/forms.rst +++ b/book/forms.rst @@ -167,16 +167,19 @@ helper functions: That's it! Just three lines are needed to render the complete form: -* ``form_start(form)`` - Renders the start tag of the form, including the - correct enctype attribute when using file uploads; - -* ``form_widget(form)`` - Renders all of the fields, which includes the field - element itself, a label and any validation error messages for the field; - -* ``form_end()`` - Renders the end tag of the form and any fields that have not - yet been rendered, in case you rendered each field yourself. This is useful - for rendering hidden fields and taking advantage of the automatic - :ref:`CSRF Protection `. +``form_start(form)`` + Renders the start tag of the form, including the correct enctype attribute + when using file uploads. + +``form_widget(form)`` + Renders all of the fields, which includes the field element itself, a label + and any validation error messages for the field. + +``form_end()`` + Renders the end tag of the form and any fields that have not + yet been rendered, in case you rendered each field yourself. This is useful + for rendering hidden fields and taking advantage of the automatic + :ref:`CSRF Protection `. .. seealso:: diff --git a/components/http_foundation/sessions.rst b/components/http_foundation/sessions.rst index de591f81fdc..5c9d7accd94 100644 --- a/components/http_foundation/sessions.rst +++ b/components/http_foundation/sessions.rst @@ -132,7 +132,6 @@ an array. A few methods exist for "Bag" management: Session Metadata ................ - :method:`Symfony\\Component\\HttpFoundation\\Session\\Session::getMetadataBag` Gets the :class:`Symfony\\Component\\HttpFoundation\\Session\\Storage\\MetadataBag` which contains information about the session. diff --git a/cookbook/security/custom_authentication_provider.rst b/cookbook/security/custom_authentication_provider.rst index ad7dd66c239..e2f7706ca5b 100644 --- a/cookbook/security/custom_authentication_provider.rst +++ b/cookbook/security/custom_authentication_provider.rst @@ -335,15 +335,15 @@ requires the following methods: ``create`` Method which adds the listener and authentication provider - to the DI container for the appropriate security context; + to the DI container for the appropriate security context. ``getPosition`` Method which must be of type ``pre_auth``, ``form``, ``http``, - and ``remember_me`` and defines the position at which the provider is called; + and ``remember_me`` and defines the position at which the provider is called. ``getKey`` Method which defines the configuration key used to reference - the provider in the firewall configuration; + the provider in the firewall configuration. ``addConfiguration`` Method which is used to define the configuration