diff --git a/components/serializer.rst b/components/serializer.rst index 37645d83f71..e86d828b315 100644 --- a/components/serializer.rst +++ b/components/serializer.rst @@ -224,7 +224,7 @@ and :class:`Symfony\\Component\\Serializer\\Normalizer\\PropertyNormalizer`:: $nameConverter = new OrgPrefixNameConverter(); $normalizer = new PropertyNormalizer(null, $nameConverter); - $serializer = new Serializer(array(new JsonEncoder()), array($normalizer)); + $serializer = new Serializer(array($normalizer), array(new JsonEncoder())); $obj = new Company(); $obj->name = 'Acme Inc.'; diff --git a/contributing/code/standards.rst b/contributing/code/standards.rst index c187890183f..17f8f72a637 100644 --- a/contributing/code/standards.rst +++ b/contributing/code/standards.rst @@ -165,10 +165,7 @@ Service Naming Conventions * Use lowercase letters for service and parameter names; -* A group name uses the underscore notation; - -* Each service has a corresponding parameter containing the class name, - following the ``SERVICE NAME.class`` convention. +* A group name uses the underscore notation. Documentation ------------- diff --git a/cookbook/logging/monolog_email.rst b/cookbook/logging/monolog_email.rst index af57caf09ad..1aafe4560af 100644 --- a/cookbook/logging/monolog_email.rst +++ b/cookbook/logging/monolog_email.rst @@ -7,7 +7,7 @@ How to Configure Monolog to Email Errors Monolog_ can be configured to send an email when an error occurs with an application. The configuration for this requires a few nested handlers in order to avoid receiving too many emails. This configuration looks -complicated at first but each handler is fairly straight forward when +complicated at first but each handler is fairly straightforward when it is broken down. .. configuration-block:: diff --git a/cookbook/security/form_login_setup.rst b/cookbook/security/form_login_setup.rst index 4d41cb5798e..1f9bb881730 100644 --- a/cookbook/security/form_login_setup.rst +++ b/cookbook/security/form_login_setup.rst @@ -215,7 +215,7 @@ Finally, create the template: {# ... you will probably extends your base template, like base.html.twig #} {% if error %} -
{{ error.messageKey|trans(error.messageData) }}
+
{{ error.messageKey|trans(error.messageData, 'security') }}
{% endif %}
diff --git a/cookbook/security/voters_data_permission.rst b/cookbook/security/voters_data_permission.rst index 31bf0b3de99..3d46160ac02 100644 --- a/cookbook/security/voters_data_permission.rst +++ b/cookbook/security/voters_data_permission.rst @@ -203,7 +203,6 @@ from the authorization checker is called. use Symfony\Bundle\FrameworkBundle\Controller\Controller; use Symfony\Component\HttpFoundation\Response; - use Symfony\Component\Security\Core\Exception\AccessDeniedException; class PostController extends Controller { @@ -213,9 +212,14 @@ from the authorization checker is called. $post = ...; // keep in mind, this will call all registered security voters - if (false === $this->get('security.authorization_checker')->isGranted('view', $post)) { - throw new AccessDeniedException('Unauthorised access!'); - } + $this->denyAccessUnlessGranted('view', $post, 'Unauthorized access!'); + + // the equivalent code without using the denyAccessUnlessGranted() shortcut + // use Symfony\Component\Security\Core\Exception\AccessDeniedException; + // + // if (false === $this->get('security.authorization_checker')->isGranted('view', $post)) { + // throw new AccessDeniedException('Unauthorized access!'); + // } return new Response('

'.$post->getName().'

'); } @@ -225,4 +229,8 @@ from the authorization checker is called. The ``security.authorization_checker`` service was introduced in Symfony 2.6. Prior to Symfony 2.6, you had to use the ``isGranted()`` method of the ``security.context`` service. +.. versionadded:: 2.6 + The ``denyAccessUnlessGranted()`` method was introduced in Symfony 2.6 as a shortcut. + It uses ``security.authorization_checker`` and throws an ``AccessDeniedException`` if needed. + It's that easy! diff --git a/quick_tour/the_big_picture.rst b/quick_tour/the_big_picture.rst index 68649076bc7..f63f7473c1a 100644 --- a/quick_tour/the_big_picture.rst +++ b/quick_tour/the_big_picture.rst @@ -156,7 +156,7 @@ because that will be explained in the next section):: class DefaultController extends Controller { /** - * @Route("/", name="homepage") + * @Route("/app/example", name="homepage") */ public function indexAction() { @@ -198,7 +198,7 @@ at the three lines of code above the ``indexAction`` method:: class DefaultController extends Controller { /** - * @Route("/", name="homepage") + * @Route("/app/example", name="homepage") */ public function indexAction() { @@ -219,10 +219,10 @@ the application homepage. The second value of ``@Route()`` (e.g. ``name="homepage"``) is optional and sets the name of this route. For now this name is not needed, but later it'll be useful for linking pages. -Considering all this, the ``@Route("/", name="homepage")`` annotation creates -a new route called ``homepage`` which makes Symfony execute the ``index`` -action of the ``Default`` controller when the user browses the ``/`` path -of the application. +Considering all this, the ``@Route("/app/example", name="homepage")`` annotation +creates a new route called ``homepage`` which makes Symfony execute the +``index`` action of the ``Default`` controller when the user browses the +``/app/example`` path of the application. .. tip:: diff --git a/reference/constraints/All.rst b/reference/constraints/All.rst index f9f37b51a2c..df343bac5ee 100644 --- a/reference/constraints/All.rst +++ b/reference/constraints/All.rst @@ -4,21 +4,21 @@ All When applied to an array (or Traversable object), this constraint allows you to apply a collection of constraints to each element of the array. -+----------------+------------------------------------------------------------------------+ -| Applies to | :ref:`property or method ` | -+----------------+------------------------------------------------------------------------+ -| Options | - `constraints`_ | -| | - `payload`_ | -+----------------+------------------------------------------------------------------------+ -| Class | :class:`Symfony\\Component\\Validator\\Constraints\\All` | -+----------------+------------------------------------------------------------------------+ -| Validator | :class:`Symfony\\Component\\Validator\\Constraints\\AllValidator` | -+----------------+------------------------------------------------------------------------+ ++----------------+-------------------------------------------------------------------+ +| Applies to | :ref:`property or method ` | ++----------------+-------------------------------------------------------------------+ +| Options | - `constraints`_ | +| | - `payload`_ | ++----------------+-------------------------------------------------------------------+ +| Class | :class:`Symfony\\Component\\Validator\\Constraints\\All` | ++----------------+-------------------------------------------------------------------+ +| Validator | :class:`Symfony\\Component\\Validator\\Constraints\\AllValidator` | ++----------------+-------------------------------------------------------------------+ Basic Usage ----------- -Suppose that you have an array of strings, and you want to validate each +Suppose that you have an array of strings and you want to validate each entry in that array: .. configuration-block:: diff --git a/reference/constraints/Blank.rst b/reference/constraints/Blank.rst index b83f40e0190..09852e3af8a 100644 --- a/reference/constraints/Blank.rst +++ b/reference/constraints/Blank.rst @@ -3,19 +3,19 @@ Blank Validates that a value is blank, defined as equal to a blank string or equal to ``null``. To force that a value strictly be equal to ``null``, see the -:doc:`/reference/constraints/Null` constraint. To force that a value is *not* -blank, see :doc:`/reference/constraints/NotBlank`. - -+----------------+-----------------------------------------------------------------------+ -| Applies to | :ref:`property or method ` | -+----------------+-----------------------------------------------------------------------+ -| Options | - `message`_ | -| | - `payload`_ | -+----------------+-----------------------------------------------------------------------+ -| Class | :class:`Symfony\\Component\\Validator\\Constraints\\Blank` | -+----------------+-----------------------------------------------------------------------+ -| Validator | :class:`Symfony\\Component\\Validator\\Constraints\\BlankValidator` | -+----------------+-----------------------------------------------------------------------+ +:doc:`/reference/constraints/Null` constraint. To force that a value is +*not* blank, see :doc:`/reference/constraints/NotBlank`. + ++----------------+---------------------------------------------------------------------+ +| Applies to | :ref:`property or method ` | ++----------------+---------------------------------------------------------------------+ +| Options | - `message`_ | +| | - `payload`_ | ++----------------+---------------------------------------------------------------------+ +| Class | :class:`Symfony\\Component\\Validator\\Constraints\\Blank` | ++----------------+---------------------------------------------------------------------+ +| Validator | :class:`Symfony\\Component\\Validator\\Constraints\\BlankValidator` | ++----------------+---------------------------------------------------------------------+ Basic Usage ----------- diff --git a/reference/constraints/Callback.rst b/reference/constraints/Callback.rst index a43248ad449..744c79980e6 100644 --- a/reference/constraints/Callback.rst +++ b/reference/constraints/Callback.rst @@ -2,10 +2,10 @@ Callback ======== The purpose of the Callback constraint is to create completely custom -validation rules and to assign any validation errors to specific fields on -your object. If you're using validation with forms, this means that you can -make these custom errors display next to a specific field, instead of simply -at the top of your form. +validation rules and to assign any validation errors to specific fields +on your object. If you're using validation with forms, this means that you +can make these custom errors display next to a specific field, instead of +simply at the top of your form. This process works by specifying one or more *callback* methods, each of which will be called during the validation process. Each of those methods @@ -93,9 +93,9 @@ Configuration The Callback Method ------------------- -The callback method is passed a special ``ExecutionContextInterface`` object. You -can set "violations" directly on this object and determine to which field -those errors should be attributed:: +The callback method is passed a special ``ExecutionContextInterface`` object. +You can set "violations" directly on this object and determine to which +field those errors should be attributed:: // ... use Symfony\Component\Validator\Context\ExecutionContextInterface; @@ -160,10 +160,10 @@ have access to the object instance, they receive the object as the first argumen External Callbacks and Closures ------------------------------- -If you want to execute a static callback method that is not located in the class -of the validated object, you can configure the constraint to invoke an array -callable as supported by PHP's :phpfunction:`call_user_func` function. Suppose -your validation function is ``Vendor\Package\Validator::validate()``:: +If you want to execute a static callback method that is not located in the +class of the validated object, you can configure the constraint to invoke +an array callable as supported by PHP's :phpfunction:`call_user_func` function. +Suppose your validation function is ``Vendor\Package\Validator::validate()``:: namespace Vendor\Package; @@ -243,8 +243,8 @@ You can then use the following configuration to invoke this validator: .. note:: - The Callback constraint does *not* support global callback functions nor - is it possible to specify a global function or a :term:`service` method + The Callback constraint does *not* support global callback functions + nor is it possible to specify a global function or a :term:`service` method as callback. To validate using a service, you should :doc:`create a custom validation constraint ` and add that new constraint to your class. diff --git a/reference/constraints/CardScheme.rst b/reference/constraints/CardScheme.rst index 38ee81c15b8..05f1175dfac 100644 --- a/reference/constraints/CardScheme.rst +++ b/reference/constraints/CardScheme.rst @@ -1,9 +1,9 @@ CardScheme ========== -This constraint ensures that a credit card number is valid for a given credit card -company. It can be used to validate the number before trying to initiate a payment -through a payment gateway. +This constraint ensures that a credit card number is valid for a given credit +card company. It can be used to validate the number before trying to initiate +a payment through a payment gateway. +----------------+--------------------------------------------------------------------------+ | Applies to | :ref:`property or method ` | @@ -35,7 +35,10 @@ on an object that will contain a credit card number. class Transaction { /** - * @Assert\CardScheme(schemes = {"VISA"}, message = "Your credit card number is invalid.") + * @Assert\CardScheme( + * schemes={"VISA"}, + * message="Your credit card number is invalid." + * ) */ protected $cardNumber; } @@ -101,9 +104,9 @@ schemes **type**: ``mixed`` [:ref:`default option `] -This option is required and represents the name of the number scheme used to -validate the credit card number, it can either be a string or an array. Valid -values are: +This option is required and represents the name of the number scheme used +to validate the credit card number, it can either be a string or an array. +Valid values are: * ``AMEX`` * ``CHINA_UNIONPAY`` @@ -116,7 +119,8 @@ values are: * ``MASTERCARD`` * ``VISA`` -For more information about the used schemes, see `Wikipedia: Issuer identification number (IIN)`_. +For more information about the used schemes, see +`Wikipedia: Issuer identification number (IIN)`_. message ~~~~~~~ diff --git a/reference/constraints/Choice.rst b/reference/constraints/Choice.rst index 50840e22769..a2019f03282 100644 --- a/reference/constraints/Choice.rst +++ b/reference/constraints/Choice.rst @@ -5,25 +5,25 @@ This constraint is used to ensure that the given value is one of a given set of *valid* choices. It can also be used to validate that each item in an array of items is one of those valid choices. -+----------------+-----------------------------------------------------------------------+ -| Applies to | :ref:`property or method ` | -+----------------+-----------------------------------------------------------------------+ -| Options | - `choices`_ | -| | - `callback`_ | -| | - `multiple`_ | -| | - `min`_ | -| | - `max`_ | -| | - `message`_ | -| | - `multipleMessage`_ | -| | - `minMessage`_ | -| | - `maxMessage`_ | -| | - `strict`_ | -| | - `payload`_ | -+----------------+-----------------------------------------------------------------------+ -| Class | :class:`Symfony\\Component\\Validator\\Constraints\\Choice` | -+----------------+-----------------------------------------------------------------------+ -| Validator | :class:`Symfony\\Component\\Validator\\Constraints\\ChoiceValidator` | -+----------------+-----------------------------------------------------------------------+ ++----------------+----------------------------------------------------------------------+ +| Applies to | :ref:`property or method ` | ++----------------+----------------------------------------------------------------------+ +| Options | - `choices`_ | +| | - `callback`_ | +| | - `multiple`_ | +| | - `min`_ | +| | - `max`_ | +| | - `message`_ | +| | - `multipleMessage`_ | +| | - `minMessage`_ | +| | - `maxMessage`_ | +| | - `strict`_ | +| | - `payload`_ | ++----------------+----------------------------------------------------------------------+ +| Class | :class:`Symfony\\Component\\Validator\\Constraints\\Choice` | ++----------------+----------------------------------------------------------------------+ +| Validator | :class:`Symfony\\Component\\Validator\\Constraints\\ChoiceValidator` | ++----------------+----------------------------------------------------------------------+ Basic Usage ----------- @@ -276,8 +276,8 @@ callback **type**: ``string|array|Closure`` This is a callback method that can be used instead of the `choices`_ option -to return the choices array. See `Supplying the Choices with a Callback Function`_ -for details on its usage. +to return the choices array. See +`Supplying the Choices with a Callback Function`_ for details on its usage. multiple ~~~~~~~~ @@ -314,16 +314,17 @@ message **type**: ``string`` **default**: ``The value you selected is not a valid choice.`` -This is the message that you will receive if the ``multiple`` option is set -to ``false``, and the underlying value is not in the valid array of choices. +This is the message that you will receive if the ``multiple`` option is +set to ``false`` and the underlying value is not in the valid array of +choices. multipleMessage ~~~~~~~~~~~~~~~ **type**: ``string`` **default**: ``One or more of the given values is invalid.`` -This is the message that you will receive if the ``multiple`` option is set -to ``true``, and one of the values on the underlying array being checked +This is the message that you will receive if the ``multiple`` option is +set to ``true`` and one of the values on the underlying array being checked is not in the array of valid choices. minMessage @@ -348,7 +349,7 @@ strict **type**: ``Boolean`` **default**: ``false`` If true, the validator will also check the type of the input value. Specifically, -this value is passed to as the third argument to the PHP :phpfunction:`in_array` method -when checking to see if a value is in the valid choices array. +this value is passed to as the third argument to the PHP :phpfunction:`in_array` +method when checking to see if a value is in the valid choices array. .. include:: /reference/constraints/_payload-option.rst.inc diff --git a/reference/constraints/Collection.rst b/reference/constraints/Collection.rst index 019d6acd97a..3fc73dca6b9 100644 --- a/reference/constraints/Collection.rst +++ b/reference/constraints/Collection.rst @@ -5,7 +5,8 @@ This constraint is used when the underlying data is a collection (i.e. an array or an object that implements ``Traversable`` and ``ArrayAccess``), but you'd like to validate different keys of that collection in different ways. For example, you might validate the ``email`` key using the ``Email`` -constraint and the ``inventory`` key of the collection with the ``Range`` constraint. +constraint and the ``inventory`` key of the collection with the ``Range`` +constraint. This constraint can also make sure that certain collection keys are present and that extra keys are not present. @@ -28,8 +29,8 @@ and that extra keys are not present. Basic Usage ----------- -The ``Collection`` constraint allows you to validate the different keys of -a collection individually. Take the following example:: +The ``Collection`` constraint allows you to validate the different keys +of a collection individually. Take the following example:: // src/Acme/BlogBundle/Entity/Author.php namespace Acme\BlogBundle\Entity; @@ -48,8 +49,9 @@ a collection individually. Take the following example:: } To validate that the ``personal_email`` element of the ``profileData`` array -property is a valid email address and that the ``short_bio`` element is not -blank but is no longer than 100 characters in length, you would do the following: +property is a valid email address and that the ``short_bio`` element is +not blank but is no longer than 100 characters in length, you would do the +following: .. configuration-block:: @@ -162,31 +164,33 @@ Presence and Absence of Fields ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ By default, this constraint validates more than simply whether or not the -individual fields in the collection pass their assigned constraints. In fact, -if any keys of a collection are missing or if there are any unrecognized +individual fields in the collection pass their assigned constraints. In +fact, if any keys of a collection are missing or if there are any unrecognized keys in the collection, validation errors will be thrown. -If you would like to allow for keys to be absent from the collection or if -you would like "extra" keys to be allowed in the collection, you can modify -the `allowMissingFields`_ and `allowExtraFields`_ options respectively. In -the above example, the ``allowMissingFields`` option was set to true, meaning -that if either of the ``personal_email`` or ``short_bio`` elements were missing -from the ``$personalData`` property, no validation error would occur. +If you would like to allow for keys to be absent from the collection or +if you would like "extra" keys to be allowed in the collection, you can +modify the `allowMissingFields`_ and `allowExtraFields`_ options respectively. +In the above example, the ``allowMissingFields`` option was set to true, +meaning that if either of the ``personal_email`` or ``short_bio`` elements +were missing from the ``$personalData`` property, no validation error would +occur. -Required and optional Field Constraints +Required and Optional Field Constraints ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. versionadded:: 2.3 The ``Required`` and ``Optional`` constraints were moved to the namespace ``Symfony\Component\Validator\Constraints\`` in Symfony 2.3. -Constraints for fields within a collection can be wrapped in the ``Required`` or -``Optional`` constraint to control whether they should always be applied (``Required``) -or only applied when the field is present (``Optional``). +Constraints for fields within a collection can be wrapped in the ``Required`` +or ``Optional`` constraint to control whether they should always be applied +(``Required``) or only applied when the field is present (``Optional``). -For instance, if you want to require that the ``personal_email`` field of the -``profileData`` array is not blank and is a valid email but the ``alternate_email`` -field is optional but must be a valid email if supplied, you can do the following: +For instance, if you want to require that the ``personal_email`` field of +the ``profileData`` array is not blank and is a valid email but the +``alternate_email`` field is optional but must be a valid email if supplied, +you can do the following: .. configuration-block:: @@ -271,7 +275,9 @@ field is optional but must be a valid email if supplied, you can do the followin { $metadata->addPropertyConstraint('profileData', new Assert\Collection(array( 'fields' => array( - 'personal_email' => new Assert\Required(array(new Assert\NotBlank(), new Assert\Email())), + 'personal_email' => new Assert\Required( + array(new Assert\NotBlank(), new Assert\Email()) + ), 'alternate_email' => new Assert\Optional(new Assert\Email()), ), ))); @@ -292,7 +298,7 @@ fields **type**: ``array`` [:ref:`default option `] -This option is required, and is an associative array defining all of the +This option is required and is an associative array defining all of the keys in the collection and, for each key, exactly which validator(s) should be executed against that element of the collection. @@ -310,7 +316,8 @@ extraFieldsMessage **type**: ``Boolean`` **default**: ``The fields {{ fields }} were not expected.`` -The message shown if `allowExtraFields`_ is false and an extra field is detected. +The message shown if `allowExtraFields`_ is false and an extra field is +detected. allowMissingFields ~~~~~~~~~~~~~~~~~~ @@ -318,8 +325,8 @@ allowMissingFields **type**: ``Boolean`` **default**: false If this option is set to ``false`` and one or more fields from the `fields`_ -option are not present in the underlying collection, a validation error will -be returned. If set to ``true``, it's ok if some fields in the `fields`_ +option are not present in the underlying collection, a validation error +will be returned. If set to ``true``, it's ok if some fields in the `fields`_ option are not present in the underlying collection. missingFieldsMessage diff --git a/reference/constraints/Count.rst b/reference/constraints/Count.rst index 9b391832101..5117635cea9 100644 --- a/reference/constraints/Count.rst +++ b/reference/constraints/Count.rst @@ -1,8 +1,8 @@ Count ===== -Validates that a given collection's (i.e. an array or an object that implements Countable) -element count is *between* some minimum and maximum value. +Validates that a given collection's (i.e. an array or an object that implements +Countable) element count is *between* some minimum and maximum value. +----------------+---------------------------------------------------------------------+ | Applies to | :ref:`property or method ` | @@ -108,37 +108,39 @@ min **type**: ``integer`` -This required option is the "min" count value. Validation will fail if the given -collection elements count is **less** than this min value. +This required option is the "min" count value. Validation will fail if the +given collection elements count is **less** than this min value. max ~~~ **type**: ``integer`` -This required option is the "max" count value. Validation will fail if the given -collection elements count is **greater** than this max value. +This required option is the "max" count value. Validation will fail if the +given collection elements count is **greater** than this max value. minMessage ~~~~~~~~~~ **type**: ``string`` **default**: ``This collection should contain {{ limit }} elements or more.`` -The message that will be shown if the underlying collection elements count is less than the `min`_ option. +The message that will be shown if the underlying collection elements count +is less than the `min`_ option. maxMessage ~~~~~~~~~~ **type**: ``string`` **default**: ``This collection should contain {{ limit }} elements or less.`` -The message that will be shown if the underlying collection elements count is more than the `max`_ option. +The message that will be shown if the underlying collection elements count +is more than the `max`_ option. exactMessage ~~~~~~~~~~~~ **type**: ``string`` **default**: ``This collection should contain exactly {{ limit }} elements.`` -The message that will be shown if min and max values are equal and the underlying collection elements -count is not exactly this value. +The message that will be shown if min and max values are equal and the underlying +collection elements count is not exactly this value. .. include:: /reference/constraints/_payload-option.rst.inc diff --git a/reference/constraints/Currency.rst b/reference/constraints/Currency.rst index d6222b4205e..7a7e85805a6 100644 --- a/reference/constraints/Currency.rst +++ b/reference/constraints/Currency.rst @@ -20,8 +20,8 @@ Validates that a value is a valid `3-letter ISO 4217`_ currency name. Basic Usage ----------- -If you want to ensure that the ``currency`` property of an ``Order`` is a valid -currency, you could do the following: +If you want to ensure that the ``currency`` property of an ``Order`` is +a valid currency, you could do the following: .. configuration-block:: diff --git a/reference/constraints/EqualTo.rst b/reference/constraints/EqualTo.rst index eaa32e6aa87..b3cefc8a52b 100644 --- a/reference/constraints/EqualTo.rst +++ b/reference/constraints/EqualTo.rst @@ -4,8 +4,8 @@ EqualTo .. versionadded:: 2.3 The ``EqualTo`` constraint was introduced in Symfony 2.3. -Validates that a value is equal to another value, defined in the options. To -force that a value is *not* equal, see :doc:`/reference/constraints/NotEqualTo`. +Validates that a value is equal to another value, defined in the options. +To force that a value is *not* equal, see :doc:`/reference/constraints/NotEqualTo`. .. caution:: diff --git a/reference/constraints/File.rst b/reference/constraints/File.rst index e73c49c4b13..62a7ccecabb 100644 --- a/reference/constraints/File.rst +++ b/reference/constraints/File.rst @@ -3,8 +3,8 @@ File Validates that a value is a valid "file", which can be one of the following: -* A string (or object with a ``__toString()`` method) path to an existing file; - +* A string (or object with a ``__toString()`` method) path to an existing + file; * A valid :class:`Symfony\\Component\\HttpFoundation\\File\\File` object (including objects of class :class:`Symfony\\Component\\HttpFoundation\\File\\UploadedFile`). @@ -41,10 +41,10 @@ Basic Usage ----------- This constraint is most commonly used on a property that will be rendered -in a form as a :doc:`file ` form type. For example, -suppose you're creating an author form where you can upload a "bio" PDF for -the author. In your form, the ``bioFile`` property would be a ``file`` type. -The ``Author`` class might look as follows:: +in a form as a :doc:`file ` form type. For +example, suppose you're creating an author form where you can upload a "bio" +PDF for the author. In your form, the ``bioFile`` property would be a ``file`` +type. The ``Author`` class might look as follows:: // src/Acme/BlogBundle/Entity/Author.php namespace Acme\BlogBundle\Entity; @@ -66,7 +66,7 @@ The ``Author`` class might look as follows:: } } -To guarantee that the ``bioFile`` ``File`` object is valid, and that it is +To guarantee that the ``bioFile`` ``File`` object is valid and that it is below a certain file size and a valid PDF, add the following: .. configuration-block:: @@ -161,8 +161,9 @@ maxSize **type**: ``mixed`` -If set, the size of the underlying file must be below this file size in order -to be valid. The size of the file can be given in one of the following formats: +If set, the size of the underlying file must be below this file size in +order to be valid. The size of the file can be given in one of the following +formats: +--------+-----------+-----------------+------+ | Suffix | Unit Name | value | e.g. | @@ -274,8 +275,8 @@ uploadErrorMessage **type**: ``string`` **default**: ``The file could not be uploaded.`` The message that is displayed if the uploaded file could not be uploaded -for some unknown reason, such as the file upload failed or it couldn't be written -to disk. +for some unknown reason, such as the file upload failed or it couldn't be +written to disk. .. include:: /reference/constraints/_payload-option.rst.inc diff --git a/reference/constraints/GreaterThan.rst b/reference/constraints/GreaterThan.rst index 06681203163..b1066c6b1f4 100644 --- a/reference/constraints/GreaterThan.rst +++ b/reference/constraints/GreaterThan.rst @@ -4,8 +4,8 @@ GreaterThan .. versionadded:: 2.3 The ``GreaterThan`` constraint was introduced in Symfony 2.3. -Validates that a value is greater than another value, defined in the options. To -force that a value is greater than or equal to another value, see +Validates that a value is greater than another value, defined in the options. +To force that a value is greater than or equal to another value, see :doc:`/reference/constraints/GreaterThanOrEqual`. To force a value is less than another value, see :doc:`/reference/constraints/LessThan`. @@ -24,8 +24,8 @@ than another value, see :doc:`/reference/constraints/LessThan`. Basic Usage ----------- -If you want to ensure that the ``age`` of a ``Person`` class is greater than -``18``, you could do the following: +If you want to ensure that the ``age`` of a ``Person`` class is greater +than ``18``, you could do the following: .. configuration-block:: @@ -100,7 +100,7 @@ message **type**: ``string`` **default**: ``This value should be greater than {{ compared_value }}.`` -This is the message that will be shown if the value is not greater than the -comparison value. +This is the message that will be shown if the value is not greater than +the comparison value. .. include:: /reference/constraints/_payload-option.rst.inc diff --git a/reference/constraints/GreaterThanOrEqual.rst b/reference/constraints/GreaterThanOrEqual.rst index f41d12d237e..cc868390490 100644 --- a/reference/constraints/GreaterThanOrEqual.rst +++ b/reference/constraints/GreaterThanOrEqual.rst @@ -4,8 +4,8 @@ GreaterThanOrEqual .. versionadded:: 2.3 The ``GreaterThanOrEqual`` constraint was introduced in Symfony 2.3. -Validates that a value is greater than or equal to another value, defined in -the options. To force that a value is greater than another value, see +Validates that a value is greater than or equal to another value, defined +in the options. To force that a value is greater than another value, see :doc:`/reference/constraints/GreaterThan`. +----------------+----------------------------------------------------------------------------------+ @@ -23,8 +23,8 @@ the options. To force that a value is greater than another value, see Basic Usage ----------- -If you want to ensure that the ``age`` of a ``Person`` class is greater than -or equal to ``18``, you could do the following: +If you want to ensure that the ``age`` of a ``Person`` class is greater +than or equal to ``18``, you could do the following: .. configuration-block:: @@ -99,7 +99,7 @@ message **type**: ``string`` **default**: ``This value should be greater than or equal to {{ compared_value }}.`` -This is the message that will be shown if the value is not greater than or equal -to the comparison value. +This is the message that will be shown if the value is not greater than +or equal to the comparison value. .. include:: /reference/constraints/_payload-option.rst.inc diff --git a/reference/constraints/Iban.rst b/reference/constraints/Iban.rst index 8202175babf..c8b88aa6007 100644 --- a/reference/constraints/Iban.rst +++ b/reference/constraints/Iban.rst @@ -4,10 +4,10 @@ Iban .. versionadded:: 2.3 The Iban constraint was introduced in Symfony 2.3. -This constraint is used to ensure that a bank account number has the proper format of -an `International Bank Account Number (IBAN)`_. IBAN is an internationally agreed means -of identifying bank accounts across national borders with a reduced risk of propagating -transcription errors. +This constraint is used to ensure that a bank account number has the proper +format of an `International Bank Account Number (IBAN)`_. IBAN is an +internationally agreed means of identifying bank accounts across national +borders with a reduced risk of propagating transcription errors. +----------------+-----------------------------------------------------------------------+ | Applies to | :ref:`property or method` | @@ -38,7 +38,9 @@ will contain an International Bank Account Number. class Transaction { /** - * @Assert\Iban(message = "This is not a valid International Bank Account Number (IBAN).") + * @Assert\Iban( + * message="This is not a valid International Bank Account Number (IBAN)." + * ) */ protected $bankAccountNumber; } @@ -63,7 +65,9 @@ will contain an International Bank Account Number. - + diff --git a/reference/constraints/Image.rst b/reference/constraints/Image.rst index e128a192987..8ca322d947a 100644 --- a/reference/constraints/Image.rst +++ b/reference/constraints/Image.rst @@ -2,14 +2,14 @@ Image ===== The Image constraint works exactly like the :doc:`File ` -constraint, except that its `mimeTypes`_ and `mimeTypesMessage` options are -automatically setup to work for image files specifically. +constraint, except that its `mimeTypes`_ and `mimeTypesMessage`_ options +are automatically setup to work for image files specifically. Additionally it has options so you can validate against the width and height of the image. -See the :doc:`File ` constraint for the bulk of -the documentation on this constraint. +See the :doc:`File ` constraint for the bulk +of the documentation on this constraint. +----------------+-----------------------------------------------------------------------+ | Applies to | :ref:`property or method ` | @@ -46,10 +46,10 @@ Basic Usage ----------- This constraint is most commonly used on a property that will be rendered -in a form as a :doc:`file ` form type. For example, -suppose you're creating an author form where you can upload a "headshot" -image for the author. In your form, the ``headshot`` property would be a -``file`` type. The ``Author`` class might look as follows:: +in a form as a :doc:`file ` form type. For +example, suppose you're creating an author form where you can upload a +"headshot" image for the author. In your form, the ``headshot`` property +would be a ``file`` type. The ``Author`` class might look as follows:: // src/Acme/BlogBundle/Entity/Author.php namespace Acme\BlogBundle\Entity; @@ -71,8 +71,8 @@ image for the author. In your form, the ``headshot`` property would be a } } -To guarantee that the ``headshot`` ``File`` object is a valid image and that -it is between a certain size, add the following: +To guarantee that the ``headshot`` ``File`` object is a valid image and +that it is between a certain size, add the following: .. configuration-block:: diff --git a/reference/constraints/Ip.rst b/reference/constraints/Ip.rst index 834e696bce2..ed480668ff1 100644 --- a/reference/constraints/Ip.rst +++ b/reference/constraints/Ip.rst @@ -89,27 +89,39 @@ of a variety of different values: **All ranges** -* ``4`` - Validates for IPv4 addresses -* ``6`` - Validates for IPv6 addresses -* ``all`` - Validates all IP formats +``4`` + Validates for IPv4 addresses +``6`` + Validates for IPv6 addresses +``all`` + Validates all IP formats **No private ranges** -* ``4_no_priv`` - Validates for IPv4 but without private IP ranges -* ``6_no_priv`` - Validates for IPv6 but without private IP ranges -* ``all_no_priv`` - Validates for all IP formats but without private IP ranges +``4_no_priv`` + Validates for IPv4 but without private IP ranges +``6_no_priv`` + Validates for IPv6 but without private IP ranges +``all_no_priv`` + Validates for all IP formats but without private IP ranges **No reserved ranges** -* ``4_no_res`` - Validates for IPv4 but without reserved IP ranges -* ``6_no_res`` - Validates for IPv6 but without reserved IP ranges -* ``all_no_res`` - Validates for all IP formats but without reserved IP ranges +``4_no_res`` + Validates for IPv4 but without reserved IP ranges +``6_no_res`` + Validates for IPv6 but without reserved IP ranges +``all_no_res`` + Validates for all IP formats but without reserved IP ranges **Only public ranges** -* ``4_public`` - Validates for IPv4 but without private and reserved ranges -* ``6_public`` - Validates for IPv6 but without private and reserved ranges -* ``all_public`` - Validates for all IP formats but without private and reserved ranges +``4_public`` + Validates for IPv4 but without private and reserved ranges +``6_public`` + Validates for IPv6 but without private and reserved ranges +``all_public`` + Validates for all IP formats but without private and reserved ranges message ~~~~~~~ diff --git a/reference/constraints/Isbn.rst b/reference/constraints/Isbn.rst index 9f9445383ef..66c444ee7db 100644 --- a/reference/constraints/Isbn.rst +++ b/reference/constraints/Isbn.rst @@ -33,7 +33,7 @@ Basic Usage ----------- To use the ``Isbn`` validator, simply apply it to a property or method -on an object that will contain an ISBN. +on an object that will contain an ISBN. .. configuration-block:: @@ -113,16 +113,16 @@ type **type**: ``string`` **default**: ``null`` -The type of ISBN to validate against. -Valid values are ``isbn10``, ``isbn13`` and ``null`` to accept any kind of ISBN. +The type of ISBN to validate against. Valid values are ``isbn10``, ``isbn13`` +and ``null`` to accept any kind of ISBN. message ~~~~~~~ **type**: ``string`` **default**: ``null`` -The message that will be shown if the value is not valid. -If not ``null``, this message has priority over all the other messages. +The message that will be shown if the value is not valid. If not ``null``, +this message has priority over all the other messages. isbn10Message ~~~~~~~~~~~~~ diff --git a/reference/constraints/Issn.rst b/reference/constraints/Issn.rst index 9ce74cf3262..0623d1261de 100644 --- a/reference/constraints/Issn.rst +++ b/reference/constraints/Issn.rst @@ -4,7 +4,8 @@ Issn .. versionadded:: 2.3 The Issn constraint was introduced in Symfony 2.3. -Validates that a value is a valid `International Standard Serial Number (ISSN)`_. +Validates that a value is a valid +`International Standard Serial Number (ISSN)`_. +----------------+-----------------------------------------------------------------------+ | Applies to | :ref:`property or method` | diff --git a/reference/constraints/Length.rst b/reference/constraints/Length.rst index 9c7029ee3d9..8efd450f9e8 100644 --- a/reference/constraints/Length.rst +++ b/reference/constraints/Length.rst @@ -1,7 +1,8 @@ Length ====== -Validates that a given string length is *between* some minimum and maximum value. +Validates that a given string length is *between* some minimum and maximum +value. +----------------+----------------------------------------------------------------------+ | Applies to | :ref:`property or method ` | @@ -22,8 +23,8 @@ Validates that a given string length is *between* some minimum and maximum value Basic Usage ----------- -To verify that the ``firstName`` field length of a class is between "2" and -"50", you might add the following: +To verify that the ``firstName`` field length of a class is between "2" +and "50", you might add the following: .. configuration-block:: @@ -72,8 +73,12 @@ To verify that the ``firstName`` field length of a class is between "2" and - - + + @@ -108,40 +113,42 @@ min **type**: ``integer`` -This required option is the "min" length value. Validation will fail if the given -value's length is **less** than this min value. +This required option is the "min" length value. Validation will fail if +the given value's length is **less** than this min value. max ~~~ **type**: ``integer`` -This required option is the "max" length value. Validation will fail if the given -value's length is **greater** than this max value. +This required option is the "max" length value. Validation will fail if +the given value's length is **greater** than this max value. charset ~~~~~~~ **type**: ``string`` **default**: ``UTF-8`` -The charset to be used when computing value's length. The :phpfunction:`grapheme_strlen` PHP -function is used if available. If not, the :phpfunction:`mb_strlen` PHP function -is used if available. If neither are available, the :phpfunction:`strlen` PHP function -is used. +The charset to be used when computing value's length. The +:phpfunction:`grapheme_strlen` PHP function is used if available. If not, +the :phpfunction:`mb_strlen` PHP function is used if available. If neither +are available, the :phpfunction:`strlen` PHP function is used. minMessage ~~~~~~~~~~ **type**: ``string`` **default**: ``This value is too short. It should have {{ limit }} characters or more.`` -The message that will be shown if the underlying value's length is less than the `min`_ option. +The message that will be shown if the underlying value's length is less +than the `min`_ option. maxMessage ~~~~~~~~~~ **type**: ``string`` **default**: ``This value is too long. It should have {{ limit }} characters or less.`` -The message that will be shown if the underlying value's length is more than the `max`_ option. +The message that will be shown if the underlying value's length is more +than the `max`_ option. exactMessage ~~~~~~~~~~~~ diff --git a/reference/constraints/LessThan.rst b/reference/constraints/LessThan.rst index 3b1b3135f98..d14e289fd0c 100644 --- a/reference/constraints/LessThan.rst +++ b/reference/constraints/LessThan.rst @@ -4,8 +4,8 @@ LessThan .. versionadded:: 2.3 The ``LessThan`` constraint was introduced in Symfony 2.3. -Validates that a value is less than another value, defined in the options. To -force that a value is less than or equal to another value, see +Validates that a value is less than another value, defined in the options. +To force that a value is less than or equal to another value, see :doc:`/reference/constraints/LessThanOrEqual`. To force a value is greater than another value, see :doc:`/reference/constraints/GreaterThan`. diff --git a/reference/constraints/LessThanOrEqual.rst b/reference/constraints/LessThanOrEqual.rst index 024f2100e40..c75266bbc52 100644 --- a/reference/constraints/LessThanOrEqual.rst +++ b/reference/constraints/LessThanOrEqual.rst @@ -4,8 +4,8 @@ LessThanOrEqual .. versionadded:: 2.3 The ``LessThanOrEqual`` constraint was introduced in Symfony 2.3. -Validates that a value is less than or equal to another value, defined in the -options. To force that a value is less than another value, see +Validates that a value is less than or equal to another value, defined in +the options. To force that a value is less than another value, see :doc:`/reference/constraints/LessThan`. +----------------+-------------------------------------------------------------------------------+ @@ -23,8 +23,8 @@ options. To force that a value is less than another value, see Basic Usage ----------- -If you want to ensure that the ``age`` of a ``Person`` class is less than or -equal to ``80``, you could do the following: +If you want to ensure that the ``age`` of a ``Person`` class is less than +or equal to ``80``, you could do the following: .. configuration-block:: @@ -99,7 +99,7 @@ message **type**: ``string`` **default**: ``This value should be less than or equal to {{ compared_value }}.`` -This is the message that will be shown if the value is not less than or equal -to the comparison value. +This is the message that will be shown if the value is not less than or +equal to the comparison value. .. include:: /reference/constraints/_payload-option.rst.inc diff --git a/reference/constraints/Locale.rst b/reference/constraints/Locale.rst index 96fae2f4cc0..53fe87960d4 100644 --- a/reference/constraints/Locale.rst +++ b/reference/constraints/Locale.rst @@ -3,9 +3,10 @@ Locale Validates that a value is a valid locale. -The "value" for each locale is either the two letter `ISO 639-1`_ *language* code -(e.g. ``fr``), or the language code followed by an underscore (``_``), then -the `ISO 3166-1 alpha-2`_ *country* code (e.g. ``fr_FR`` for French/France). +The "value" for each locale is either the two letter `ISO 639-1`_ *language* +code (e.g. ``fr``), or the language code followed by an underscore (``_``), +then the `ISO 3166-1 alpha-2`_ *country* code (e.g. ``fr_FR`` for +French/France). +----------------+------------------------------------------------------------------------+ | Applies to | :ref:`property or method ` | diff --git a/reference/constraints/Luhn.rst b/reference/constraints/Luhn.rst index efc2ae716ba..c3e1e919ef0 100644 --- a/reference/constraints/Luhn.rst +++ b/reference/constraints/Luhn.rst @@ -1,9 +1,9 @@ Luhn ==== -This constraint is used to ensure that a credit card number passes the `Luhn algorithm`_. -It is useful as a first step to validating a credit card: before communicating with a -payment gateway. +This constraint is used to ensure that a credit card number passes the +`Luhn algorithm`_. It is useful as a first step to validating a credit +card: before communicating with a payment gateway. +----------------+-----------------------------------------------------------------------+ | Applies to | :ref:`property or method ` | diff --git a/reference/constraints/NotBlank.rst b/reference/constraints/NotBlank.rst index 82bc7175007..16e46b7d899 100644 --- a/reference/constraints/NotBlank.rst +++ b/reference/constraints/NotBlank.rst @@ -2,8 +2,8 @@ NotBlank ======== Validates that a value is not blank, defined as not equal to a blank string -and also not equal to ``null``. To force that a value is simply not equal to -``null``, see the :doc:`/reference/constraints/NotNull` constraint. +and also not equal to ``null``. To force that a value is simply not equal +to ``null``, see the :doc:`/reference/constraints/NotNull` constraint. +----------------+------------------------------------------------------------------------+ | Applies to | :ref:`property or method ` | @@ -19,8 +19,8 @@ and also not equal to ``null``. To force that a value is simply not equal to Basic Usage ----------- -If you wanted to ensure that the ``firstName`` property of an ``Author`` class -were not blank, you could do the following: +If you wanted to ensure that the ``firstName`` property of an ``Author`` +class were not blank, you could do the following: .. configuration-block:: diff --git a/reference/constraints/NotEqualTo.rst b/reference/constraints/NotEqualTo.rst index 3ab71af1804..7451e2eed5c 100644 --- a/reference/constraints/NotEqualTo.rst +++ b/reference/constraints/NotEqualTo.rst @@ -29,8 +29,8 @@ options. To force that a value is equal, see Basic Usage ----------- -If you want to ensure that the ``age`` of a ``Person`` class is not equal to -``15``, you could do the following: +If you want to ensure that the ``age`` of a ``Person`` class is not equal +to ``15``, you could do the following: .. configuration-block:: diff --git a/reference/constraints/NotIdenticalTo.rst b/reference/constraints/NotIdenticalTo.rst index c3a2f52bfe8..e54ec81634f 100644 --- a/reference/constraints/NotIdenticalTo.rst +++ b/reference/constraints/NotIdenticalTo.rst @@ -4,15 +4,15 @@ NotIdenticalTo .. versionadded:: 2.3 The ``NotIdenticalTo`` constraint was introduced in Symfony 2.3. -Validates that a value is **not** identical to another value, defined in the -options. To force that a value is identical, see +Validates that a value is **not** identical to another value, defined in +the options. To force that a value is identical, see :doc:`/reference/constraints/IdenticalTo`. .. caution:: This constraint compares using ``!==``, so ``3`` and ``"3"`` are - considered not equal. Use :doc:`/reference/constraints/NotEqualTo` to compare - with ``!=``. + considered not equal. Use :doc:`/reference/constraints/NotEqualTo` to + compare with ``!=``. +----------------+-----------------------------------------------------------------------------+ | Applies to | :ref:`property or method` | @@ -29,8 +29,8 @@ options. To force that a value is identical, see Basic Usage ----------- -If you want to ensure that the ``age`` of a ``Person`` class is *not* equal to -``15`` and *not* an integer, you could do the following: +If you want to ensure that the ``age`` of a ``Person`` class is *not* equal +to ``15`` and *not* an integer, you could do the following: .. configuration-block:: diff --git a/reference/constraints/NotNull.rst b/reference/constraints/NotNull.rst index 6f70f40e236..ce7b312c2c2 100644 --- a/reference/constraints/NotNull.rst +++ b/reference/constraints/NotNull.rst @@ -19,8 +19,8 @@ constraint. Basic Usage ----------- -If you wanted to ensure that the ``firstName`` property of an ``Author`` class -were not strictly equal to ``null``, you would: +If you wanted to ensure that the ``firstName`` property of an ``Author`` +class were not strictly equal to ``null``, you would: .. configuration-block:: diff --git a/reference/constraints/Range.rst b/reference/constraints/Range.rst index 1dc8d5d1bd7..b588cc31cca 100644 --- a/reference/constraints/Range.rst +++ b/reference/constraints/Range.rst @@ -21,8 +21,8 @@ Validates that a given number is *between* some minimum and maximum number. Basic Usage ----------- -To verify that the "height" field of a class is between "120" and "180", you might add -the following: +To verify that the "height" field of a class is between "120" and "180", +you might add the following: .. configuration-block:: @@ -123,16 +123,16 @@ minMessage **type**: ``string`` **default**: ``This value should be {{ limit }} or more.`` -The message that will be shown if the underlying value is less than the `min`_ -option. +The message that will be shown if the underlying value is less than the +`min`_ option. maxMessage ~~~~~~~~~~ **type**: ``string`` **default**: ``This value should be {{ limit }} or less.`` -The message that will be shown if the underlying value is more than the `max`_ -option. +The message that will be shown if the underlying value is more than the +`max`_ option. invalidMessage ~~~~~~~~~~~~~~ diff --git a/reference/constraints/Regex.rst b/reference/constraints/Regex.rst index c92a314c4e9..ca1d953fbe8 100644 --- a/reference/constraints/Regex.rst +++ b/reference/constraints/Regex.rst @@ -20,10 +20,10 @@ Validates that a value matches a regular expression. Basic Usage ----------- -Suppose you have a ``description`` field and you want to verify that it begins -with a valid word character. The regular expression to test for this would -be ``/^\w+/``, indicating that you're looking for at least one or more word -characters at the beginning of your string: +Suppose you have a ``description`` field and you want to verify that it +begins with a valid word character. The regular expression to test for this +would be ``/^\w+/``, indicating that you're looking for at least one or +more word characters at the beginning of your string: .. configuration-block:: @@ -85,10 +85,10 @@ characters at the beginning of your string: } } -Alternatively, you can set the `match`_ option to ``false`` in order to assert -that a given string does *not* match. In the following example, you'll assert -that the ``firstName`` field does not contain any numbers and give it a custom -message: +Alternatively, you can set the `match`_ option to ``false`` in order to +assert that a given string does *not* match. In the following example, you'll +assert that the ``firstName`` field does not contain any numbers and give +it a custom message: .. configuration-block:: @@ -171,9 +171,9 @@ pattern This required option is the regular expression pattern that the input will be matched against. By default, this validator will fail if the input string -does *not* match this regular expression (via the :phpfunction:`preg_match` PHP function). -However, if `match`_ is set to false, then validation will fail if the input -string *does* match this pattern. +does *not* match this regular expression (via the :phpfunction:`preg_match` +PHP function). However, if `match`_ is set to false, then validation will +fail if the input string *does* match this pattern. htmlPattern ~~~~~~~~~~~ @@ -183,12 +183,13 @@ htmlPattern This option specifies the pattern to use in the HTML5 ``pattern`` attribute. You usually don't need to specify this option because by default, the constraint will convert the pattern given in the `pattern`_ option into an HTML5 compatible -pattern. This means that the delimiters are removed (e.g. ``/[a-z]+/`` becomes ``[a-z]+``). +pattern. This means that the delimiters are removed (e.g. ``/[a-z]+/`` becomes +``[a-z]+``). However, there are some other incompatibilities between both patterns which cannot be fixed by the constraint. For instance, the HTML5 ``pattern`` attribute -does not support flags. If you have a pattern like ``/[a-z]+/i``, you need -to specify the HTML5 compatible pattern in the ``htmlPattern`` option: +does not support flags. If you have a pattern like ``/[a-z]+/i``, you +need to specify the HTML5 compatible pattern in the ``htmlPattern`` option: .. configuration-block:: @@ -266,8 +267,8 @@ match If ``true`` (or not set), this validator will pass if the given string matches the given `pattern`_ regular expression. However, when this option is set -to ``false``, the opposite will occur: validation will pass only if the given -string does **not** match the `pattern`_ regular expression. +to ``false``, the opposite will occur: validation will pass only if the +given string does **not** match the `pattern`_ regular expression. message ~~~~~~~ diff --git a/reference/constraints/True.rst b/reference/constraints/True.rst index 2b41004b300..690a82711a5 100644 --- a/reference/constraints/True.rst +++ b/reference/constraints/True.rst @@ -22,11 +22,9 @@ Basic Usage ----------- This constraint can be applied to properties (e.g. a ``termsAccepted`` property -on a registration model) or to a "getter" method. It's most powerful in the -latter case, where you can assert that a method returns a true value. For -example, suppose you have the following method: - -.. code-block:: php +on a registration model) or to a "getter" method. It's most powerful in +the latter case, where you can assert that a method returns a true value. +For example, suppose you have the following method:: // src/Acme/BlogBundle/Entity/Author.php namespace Acme\BlogBundle\Entity; diff --git a/reference/constraints/Type.rst b/reference/constraints/Type.rst index 2be82188914..7d2f512baeb 100644 --- a/reference/constraints/Type.rst +++ b/reference/constraints/Type.rst @@ -2,8 +2,8 @@ Type ==== Validates that a value is of a specific data type. For example, if a variable -should be an array, you can use this constraint with the ``array`` type option -to validate this. +should be an array, you can use this constraint with the ``array`` type +option to validate this. +----------------+---------------------------------------------------------------------+ | Applies to | :ref:`property or method ` | @@ -32,7 +32,10 @@ Basic Usage class Author { /** - * @Assert\Type(type="integer", message="The value {{ value }} is not a valid {{ type }}.") + * @Assert\Type( + * type="integer", + * message="The value {{ value }} is not a valid {{ type }}." + * ) */ protected $age; } @@ -94,8 +97,8 @@ type **type**: ``string`` [:ref:`default option `] -This required option is the fully qualified class name or one of the PHP datatypes -as determined by PHP's ``is_`` functions. +This required option is the fully qualified class name or one of the PHP +datatypes as determined by PHP's ``is_`` functions. * :phpfunction:`array ` * :phpfunction:`bool ` @@ -113,8 +116,9 @@ as determined by PHP's ``is_`` functions. * :phpfunction:`scalar ` * :phpfunction:`string ` -Also, you can use ``ctype_`` functions from corresponding `built-in PHP extension `_. -Consider `a list of ctype functions `_: +Also, you can use ``ctype_`` functions from corresponding +`built-in PHP extension `_. Consider +`a list of ctype functions `_: * :phpfunction:`alnum ` * :phpfunction:`alpha ` @@ -128,7 +132,8 @@ Consider `a list of ctype functions `_: * :phpfunction:`upper ` * :phpfunction:`xdigit ` -Make sure that the proper :phpfunction:`locale ` is set before using one of these. +Make sure that the proper :phpfunction:`locale ` is set before +using one of these. message ~~~~~~~ diff --git a/reference/constraints/UniqueEntity.rst b/reference/constraints/UniqueEntity.rst index c20f42fed64..639177308ef 100644 --- a/reference/constraints/UniqueEntity.rst +++ b/reference/constraints/UniqueEntity.rst @@ -24,10 +24,10 @@ using an email address that already exists in the system. Basic Usage ----------- -Suppose you have an AcmeUserBundle bundle with a ``User`` entity that has an -``email`` field. You can use the ``UniqueEntity`` constraint to guarantee that -the ``email`` field remains unique between all of the constraints in your user -table: +Suppose you have an AcmeUserBundle bundle with a ``User`` entity that has +an ``email`` field. You can use the ``UniqueEntity`` constraint to guarantee +that the ``email`` field remains unique between all of the constraints in +your user table: .. configuration-block:: @@ -140,28 +140,28 @@ em **type**: ``string`` -The name of the entity manager to use for making the query to determine the -uniqueness. If it's left blank, the correct entity manager will be determined -for this class. For that reason, this option should probably not need to be -used. +The name of the entity manager to use for making the query to determine +the uniqueness. If it's left blank, the correct entity manager will be +determined for this class. For that reason, this option should probably +not need to be used. repositoryMethod ~~~~~~~~~~~~~~~~ **type**: ``string`` **default**: ``findBy`` -The name of the repository method to use for making the query to determine the -uniqueness. If it's left blank, the ``findBy`` method will be used. This -method should return a countable result. +The name of the repository method to use for making the query to determine +the uniqueness. If it's left blank, the ``findBy`` method will be used. +This method should return a countable result. errorPath ~~~~~~~~~ **type**: ``string`` **default**: The name of the first field in `fields`_ -If the entity violates the constraint the error message is bound to the first -field in `fields`_. If there is more than one field, you may want to map -the error message to another field. +If the entity violates the constraint the error message is bound to the +first field in `fields`_. If there is more than one field, you may want +to map the error message to another field. Consider this example: diff --git a/reference/constraints/Url.rst b/reference/constraints/Url.rst index 85d368ef4df..a1ca08a4a34 100644 --- a/reference/constraints/Url.rst +++ b/reference/constraints/Url.rst @@ -91,6 +91,6 @@ protocols The protocols that will be considered to be valid. For example, if you also needed ``ftp://`` type URLs to be valid, you'd redefine the ``protocols`` -array, listing ``http``, ``https``, and also ``ftp``. +array, listing ``http``, ``https`` and also ``ftp``. .. include:: /reference/constraints/_payload-option.rst.inc diff --git a/reference/constraints/UserPassword.rst b/reference/constraints/UserPassword.rst index d7ecec0412d..fc99044befb 100644 --- a/reference/constraints/UserPassword.rst +++ b/reference/constraints/UserPassword.rst @@ -2,13 +2,13 @@ UserPassword ============ This validates that an input value is equal to the current authenticated -user's password. This is useful in a form where a user can change their password, -but needs to enter their old password for security. +user's password. This is useful in a form where a user can change their +password, but needs to enter their old password for security. .. note:: - This should **not** be used to validate a login form, since this is done - automatically by the security system. + This should **not** be used to validate a login form, since this is + done automatically by the security system. +----------------+--------------------------------------------------------------------------------------------+ | Applies to | :ref:`property or method ` | @@ -24,10 +24,10 @@ but needs to enter their old password for security. Basic Usage ----------- -Suppose you have a `PasswordChange` class, that's used in a form where the -user can change their password by entering their old password and a new password. -This constraint will validate that the old password matches the user's current -password: +Suppose you have a ``PasswordChange`` class, that's used in a form where +the user can change their password by entering their old password and a +new password. This constraint will validate that the old password matches +the user's current password: .. configuration-block:: @@ -67,7 +67,9 @@ password: - + @@ -86,9 +88,12 @@ password: { public static function loadValidatorData(ClassMetadata $metadata) { - $metadata->addPropertyConstraint('oldPassword', new SecurityAssert\UserPassword(array( - 'message' => 'Wrong value for your current password', - ))); + $metadata->addPropertyConstraint( + 'oldPassword', + new SecurityAssert\UserPassword(array( + 'message' => 'Wrong value for your current password', + )) + ); } } diff --git a/reference/constraints/Valid.rst b/reference/constraints/Valid.rst index afbaedeab48..42cb44dc8a6 100644 --- a/reference/constraints/Valid.rst +++ b/reference/constraints/Valid.rst @@ -2,8 +2,8 @@ Valid ===== This constraint is used to enable validation on objects that are embedded -as properties on an object being validated. This allows you to validate an -object and all sub-objects associated with it. +as properties on an object being validated. This allows you to validate +an object and all sub-objects associated with it. +----------------+---------------------------------------------------------------------+ | Applies to | :ref:`property or method ` | @@ -21,8 +21,8 @@ Basic Usage ----------- In the following example, create two classes ``Author`` and ``Address`` -that both have constraints on their properties. Furthermore, ``Author`` stores -an ``Address`` instance in the ``$address`` property. +that both have constraints on their properties. Furthermore, ``Author`` +stores an ``Address`` instance in the ``$address`` property. .. code-block:: php @@ -186,9 +186,9 @@ an ``Address`` instance in the ``$address`` property. } } -With this mapping, it is possible to successfully validate an author with an -invalid address. To prevent that, add the ``Valid`` constraint to the ``$address`` -property. +With this mapping, it is possible to successfully validate an author with +an invalid address. To prevent that, add the ``Valid`` constraint to the +``$address`` property. .. configuration-block:: @@ -248,8 +248,8 @@ property. } } -If you validate an author with an invalid address now, you can see that the -validation of the ``Address`` fields failed. +If you validate an author with an invalid address now, you can see that +the validation of the ``Address`` fields failed. .. code-block:: text @@ -265,8 +265,8 @@ traverse **type**: ``boolean`` **default**: ``true`` If this constraint is applied to a property that holds an array of objects, -then each object in that array will be validated only if this option is set -to ``true``. +then each object in that array will be validated only if this option is +set to ``true``. deep ~~~~ @@ -274,7 +274,7 @@ deep **type**: ``boolean`` **default**: ``false`` If this constraint is applied to a property that holds an array of objects, -then each object in that array will be validated recursively if this option is set -to ``true``. +then each object in that array will be validated recursively if this option +is set to ``true``. .. include:: /reference/constraints/_payload-option.rst.inc diff --git a/reference/constraints/_comparison-value-option.rst.inc b/reference/constraints/_comparison-value-option.rst.inc index 4b24250cec5..cb7e07045a5 100644 --- a/reference/constraints/_comparison-value-option.rst.inc +++ b/reference/constraints/_comparison-value-option.rst.inc @@ -1,7 +1,7 @@ value ~~~~~ -**type**: ``mixed`` [:ref:`default option`] +**type**: ``mixed`` [:ref:`default option `] This option is required. It defines the value to compare to. It can be a string, number or object. diff --git a/reference/dic_tags.rst b/reference/dic_tags.rst index 98a55ec5ebb..2022c330fe2 100644 --- a/reference/dic_tags.rst +++ b/reference/dic_tags.rst @@ -2,9 +2,9 @@ The Dependency Injection Tags ============================= Dependency Injection Tags are little strings that can be applied to a service -to "flag" it to be used in some special way. For example, if you have a service -that you would like to register as a listener to one of Symfony's core events, -you can flag it with the ``kernel.event_listener`` tag. +to "flag" it to be used in some special way. For example, if you have a +service that you would like to register as a listener to one of Symfony's +core events, you can flag it with the ``kernel.event_listener`` tag. You can learn a little bit more about "tags" by reading the ":ref:`book-service-container-tags`" section of the Service Container chapter. @@ -274,12 +274,13 @@ form.type_extension **Purpose**: Create a custom "form extension" -Form type extensions are a way for you took "hook into" the creation of any -field in your form. For example, the addition of the CSRF token is done via -a form type extension (:class:`Symfony\\Component\\Form\\Extension\\Csrf\\Type\\FormTypeCsrfExtension`). +Form type extensions are a way for you took "hook into" the creation of +any field in your form. For example, the addition of the CSRF token is done +via a form type extension +(:class:`Symfony\\Component\\Form\\Extension\\Csrf\\Type\\FormTypeCsrfExtension`). -A form type extension can modify any part of any field in your form. To create -a form type extension, first create a class that implements the +A form type extension can modify any part of any field in your form. To +create a form type extension, first create a class that implements the :class:`Symfony\\Component\\Form\\FormTypeExtensionInterface` interface. For simplicity, you'll often extend an :class:`Symfony\\Component\\Form\\AbstractTypeExtension` class instead of @@ -296,8 +297,8 @@ the interface directly:: // like buildForm(), buildView(), finishView(), configureOptions() } -In order for Symfony to know about your form extension and use it, give it -the ``form.type_extension`` tag: +In order for Symfony to know about your form extension and use it, give +it the ``form.type_extension`` tag: .. configuration-block:: @@ -329,13 +330,16 @@ the ``form.type_extension`` tag: .. code-block:: php $container - ->register('main.form.type.my_form_type_extension', 'Acme\MainBundle\Form\Type\MyFormTypeExtension') + ->register( + 'main.form.type.my_form_type_extension', + 'Acme\MainBundle\Form\Type\MyFormTypeExtension' + ) ->addTag('form.type_extension', array('alias' => 'field')) ; The ``alias`` key of the tag is the type of field that this extension should -be applied to. For example, to apply the extension to any form/field, use the -"form" value. +be applied to. For example, to apply the extension to any form/field, use +the "form" value. .. _reference-dic-type_guesser: @@ -357,7 +361,8 @@ metadata and Doctrine metadata (if you're using Doctrine) or Propel metadata kernel.cache_clearer -------------------- -**Purpose**: Register your service to be called during the cache clearing process +**Purpose**: Register your service to be called during the cache clearing +process Cache clearing occurs whenever you call ``cache:clear`` command. If your bundle caches files, you should add custom cache clearer for clearing those @@ -416,14 +421,15 @@ Then register this class and tag it with ``kernel.cache_clearer``: kernel.cache_warmer ------------------- -**Purpose**: Register your service to be called during the cache warming process +**Purpose**: Register your service to be called during the cache warming +process Cache warming occurs whenever you run the ``cache:warmup`` or ``cache:clear`` -task (unless you pass ``--no-warmup`` to ``cache:clear``). It is also run when -handling the request, if it wasn't done by one of the commands yet. The purpose is -to initialize any cache that will be needed by the application and prevent -the first user from any significant "cache hit" where the cache is generated -dynamically. +task (unless you pass ``--no-warmup`` to ``cache:clear``). It is also run +when handling the request, if it wasn't done by one of the commands yet. +The purpose is to initialize any cache that will be needed by the application +and prevent the first user from any significant "cache hit" where the cache +is generated dynamically. To register your own cache warmer, first create a service that implements the :class:`Symfony\\Component\\HttpKernel\\CacheWarmer\\CacheWarmerInterface` interface:: @@ -451,7 +457,8 @@ application without calling this cache warmer. In Symfony, optional warmers are always executed by default (you can change this by using the ``--no-optional-warmers`` option when executing the command). -To register your warmer with Symfony, give it the ``kernel.cache_warmer`` tag: +To register your warmer with Symfony, give it the ``kernel.cache_warmer`` +tag: .. configuration-block:: @@ -471,7 +478,9 @@ To register your warmer with Symfony, give it the ``kernel.cache_warmer`` tag: xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd"> - + @@ -486,8 +495,8 @@ To register your warmer with Symfony, give it the ``kernel.cache_warmer`` tag: .. note:: - The ``priority`` value is optional, and defaults to 0. - The higher the priority, the sooner it gets executed. + The ``priority`` value is optional and defaults to 0. The higher the + priority, the sooner it gets executed. Core Cache Warmers ~~~~~~~~~~~~~~~~~~ @@ -604,7 +613,7 @@ kernel.event_subscriber **Purpose**: To subscribe to a set of different events/hooks in Symfony To enable a custom subscriber, add it as a regular service in one of your -configuration, and tag it with ``kernel.event_subscriber``: +configuration and tag it with ``kernel.event_subscriber``: .. configuration-block:: @@ -636,7 +645,10 @@ configuration, and tag it with ``kernel.event_subscriber``: .. code-block:: php $container - ->register('kernel.subscriber.your_subscriber_name', 'Fully\Qualified\Subscriber\Class\Name') + ->register( + 'kernel.subscriber.your_subscriber_name', + 'Fully\Qualified\Subscriber\Class\Name' + ) ->addTag('kernel.event_subscriber') ; @@ -647,8 +659,8 @@ configuration, and tag it with ``kernel.event_subscriber``: .. note:: - If your service is created by a factory, you **MUST** correctly set the ``class`` - parameter for this tag to work correctly. + If your service is created by a factory, you **MUST** correctly set + the ``class`` parameter for this tag to work correctly. kernel.fragment_renderer ------------------------ @@ -699,7 +711,9 @@ channel when injecting the logger in a service. .. code-block:: php - $definition = new Definition('Fully\Qualified\Loader\Class\Name', array(new Reference('logger')); + $definition = new Definition('Fully\Qualified\Loader\Class\Name', array( + new Reference('logger'), + )); $definition->addTag('monolog.logger', array('channel' => 'acme')); $container->setDefinition('my_service', $definition); @@ -716,13 +730,13 @@ monolog.processor **Purpose**: Add a custom processor for logging -Monolog allows you to add processors in the logger or in the handlers to add -extra data in the records. A processor receives the record as an argument and -must return it after adding some extra data in the ``extra`` attribute of -the record. +Monolog allows you to add processors in the logger or in the handlers to +add extra data in the records. A processor receives the record as an argument +and must return it after adding some extra data in the ``extra`` attribute +of the record. -The built-in ``IntrospectionProcessor`` can be used to add the file, the line, -the class and the method where the logger was triggered. +The built-in ``IntrospectionProcessor`` can be used to add the file, the +line, the class and the method where the logger was triggered. You can add a processor globally: @@ -796,9 +810,9 @@ attribute: ->addTag('monolog.processor', array('handler' => 'firephp')) ; -You can also add a processor for a specific logging channel by using the ``channel`` -attribute. This will register the processor only for the ``security`` logging -channel used in the Security component: +You can also add a processor for a specific logging channel by using the +``channel`` attribute. This will register the processor only for the +``security`` logging channel used in the Security component: .. configuration-block:: @@ -842,7 +856,7 @@ routing.loader **Purpose**: Register a custom service that loads routes To enable a custom routing loader, add it as a regular service in one -of your configuration, and tag it with ``routing.loader``: +of your configuration and tag it with ``routing.loader``: .. configuration-block:: @@ -913,9 +927,9 @@ security.remember_me_aware **Purpose**: To allow remember me authentication -This tag is used internally to allow remember-me authentication to work. If -you have a custom authentication method where a user can be remember-me authenticated, -then you may need to use this tag. +This tag is used internally to allow remember-me authentication to work. +If you have a custom authentication method where a user can be remember-me +authenticated, then you may need to use this tag. If your custom authentication factory extends :class:`Symfony\\Bundle\\SecurityBundle\\DependencyInjection\\Security\\Factory\\AbstractFactory` @@ -964,15 +978,16 @@ swiftmailer.default.plugin **Purpose**: Register a custom SwiftMailer Plugin -If you're using a custom SwiftMailer plugin (or want to create one), you can -register it with SwiftMailer by creating a service for your plugin and tagging -it with ``swiftmailer.default.plugin`` (it has no options). +If you're using a custom SwiftMailer plugin (or want to create one), you +can register it with SwiftMailer by creating a service for your plugin and +tagging it with ``swiftmailer.default.plugin`` (it has no options). .. note:: ``default`` in this tag is the name of the mailer. If you have multiple - mailers configured or have changed the default mailer name for some reason, - you should change it to the name of your mailer in order to use this tag. + mailers configured or have changed the default mailer name for some + reason, you should change it to the name of your mailer in order to + use this tag. A SwiftMailer plugin must implement the ``Swift_Events_EventListener`` interface. For more information on plugins, see `SwiftMailer's Plugin Documentation`_. @@ -1031,8 +1046,8 @@ translation.loader **Purpose**: To register a custom service that loads translations -By default, translations are loaded from the filesystem in a variety of different -formats (YAML, XLIFF, PHP, etc). +By default, translations are loaded from the filesystem in a variety of +different formats (YAML, XLIFF, PHP, etc). .. seealso:: @@ -1071,19 +1086,23 @@ Now, register your loader as a service and tag it with ``translation.loader``: .. code-block:: php $container - ->register('main.translation.my_custom_loader', 'Acme\MainBundle\Translation\MyCustomLoader') + ->register( + 'main.translation.my_custom_loader', + 'Acme\MainBundle\Translation\MyCustomLoader' + ) ->addTag('translation.loader', array('alias' => 'bin')) ; The ``alias`` option is required and very important: it defines the file -"suffix" that will be used for the resource files that use this loader. For -example, suppose you have some custom ``bin`` format that you need to load. -If you have a ``bin`` file that contains French translations for the ``messages`` -domain, then you might have a file ``app/Resources/translations/messages.fr.bin``. +"suffix" that will be used for the resource files that use this loader. +For example, suppose you have some custom ``bin`` format that you need to +load. If you have a ``bin`` file that contains French translations for +the ``messages`` domain, then you might have a file +``app/Resources/translations/messages.fr.bin``. -When Symfony tries to load the ``bin`` file, it passes the path to your custom -loader as the ``$resource`` argument. You can then perform any logic you need -on that file in order to load your translations. +When Symfony tries to load the ``bin`` file, it passes the path to your +custom loader as the ``$resource`` argument. You can then perform any logic +you need on that file in order to load your translations. If you're loading translations from a database, you'll still need a resource file, but it might either be blank or contain a little bit of information @@ -1093,7 +1112,8 @@ the ``load`` method on your custom loader. translation.extractor --------------------- -**Purpose**: To register a custom service that extracts messages from a file +**Purpose**: To register a custom service that extracts messages from a +file When executing the ``translation:update`` command, it uses extractors to extract translation messages from a file. By default, the Symfony framework @@ -1102,9 +1122,9 @@ has a :class:`Symfony\\Bridge\\Twig\\Translation\\TwigExtractor` and a help to find and extract translation keys from Twig templates and PHP files. You can create your own extractor by creating a class that implements -:class:`Symfony\\Component\\Translation\\Extractor\\ExtractorInterface` and -tagging the service with ``translation.extractor``. The tag has one required -option: ``alias``, which defines the name of the extractor:: +:class:`Symfony\\Component\\Translation\\Extractor\\ExtractorInterface` +and tagging the service with ``translation.extractor``. The tag has one +required option: ``alias``, which defines the name of the extractor:: // src/Acme/DemoBundle/Translation/FooExtractor.php namespace Acme\DemoBundle\Translation; @@ -1173,9 +1193,9 @@ translation.dumper **Purpose**: To register a custom service that dumps messages to a file -After an `Extractor `_ has extracted all messages from -the templates, the dumpers are executed to dump the messages to a translation -file in a specific format. +After an `Extractor `_ has extracted all messages +from the templates, the dumpers are executed to dump the messages to a +translation file in a specific format. Symfony already comes with many dumpers: @@ -1242,7 +1262,7 @@ twig.extension **Purpose**: To register a custom Twig Extension To enable a Twig extension, add it as a regular service in one of your -configuration, and tag it with ``twig.extension``: +configuration and tag it with ``twig.extension``: .. configuration-block:: @@ -1274,7 +1294,10 @@ configuration, and tag it with ``twig.extension``: .. code-block:: php $container - ->register('twig.extension.your_extension_name', 'Fully\Qualified\Extension\Class\Name') + ->register( + 'twig.extension.your_extension_name', + 'Fully\Qualified\Extension\Class\Name' + ) ->addTag('twig.extension') ; @@ -1359,7 +1382,10 @@ the new loader and tag it with ``twig.loader``: .. code-block:: php $container - ->register('acme.demo_bundle.loader.some_twig_loader', 'Acme\DemoBundle\Loader\SomeTwigLoader') + ->register( + 'acme.demo_bundle.loader.some_twig_loader', + 'Acme\DemoBundle\Loader\SomeTwigLoader' + ) ->addTag('twig.loader', array('priority' => 0)) ; @@ -1385,14 +1411,15 @@ This tag provides a very uncommon piece of functionality that allows you to perform some sort of action on an object right before it's validated. For example, it's used by Doctrine to query for all of the lazily-loaded data on an object before it's validated. Without this, some data on a Doctrine -entity would appear to be "missing" when validated, even though this is not -really the case. +entity would appear to be "missing" when validated, even though this is +not really the case. If you do need to use this tag, just make a new class that implements the :class:`Symfony\\Component\\Validator\\ObjectInitializerInterface` interface. Then, tag it with the ``validator.initializer`` tag (it has no options). -For an example, see the ``EntityInitializer`` class inside the Doctrine Bridge. +For an example, see the ``EntityInitializer`` class inside the Doctrine +Bridge. .. _`Twig's documentation`: http://twig.sensiolabs.org/doc/advanced.html#creating-an-extension .. _`Twig official extension repository`: https://github.com/fabpot/Twig-extensions diff --git a/reference/requirements.rst b/reference/requirements.rst index b03fa95534c..a0f9e262846 100644 --- a/reference/requirements.rst +++ b/reference/requirements.rst @@ -6,11 +6,11 @@ Requirements for Running Symfony ================================ -To run Symfony, your system needs to adhere to a list of requirements. You can -easily see if your system passes all requirements by running the ``web/config.php`` -in your Symfony distribution. Since the CLI often uses a different ``php.ini`` -configuration file, it's also a good idea to check your requirements from -the command line via: +To run Symfony, your system needs to adhere to a list of requirements. You +can easily see if your system passes all requirements by running the +``web/config.php`` in your Symfony distribution. Since the CLI often uses +a different ``php.ini`` configuration file, it's also a good idea to check +your requirements from the command line via: .. code-block:: bash diff --git a/reference/twig_reference.rst b/reference/twig_reference.rst index 6519b1d9ba6..65b866e54a3 100644 --- a/reference/twig_reference.rst +++ b/reference/twig_reference.rst @@ -89,8 +89,8 @@ controller ``query`` **type**: ``array`` **default**: ``[]`` -Returns an instance of ``ControllerReference`` to be used with functions like -:ref:`render() ` and +Returns an instance of ``ControllerReference`` to be used with functions +like :ref:`render() ` and :ref:`render_esi() `. asset @@ -109,8 +109,8 @@ asset ``version`` **type**: ``string`` **default** ``null`` -Returns a public path to ``path``, which takes into account the base path set -for the package and the URL path. More information in +Returns a public path to ``path``, which takes into account the base path +set for the package and the URL path. More information in :ref:`book-templating-assets`. For asset versioning, see :ref:`ref-framework-assets-version`. assets_version @@ -168,8 +168,9 @@ form_end ``variables`` **type**: ``array`` **default**: ``[]`` -Renders the HTML end tag of a form together with all fields that have not been -rendered yet, more information in :ref:`the Twig Form reference `. +Renders the HTML end tag of a form together with all fields that have not +been rendered yet, more information in +:ref:`the Twig Form reference `. form_enctype ~~~~~~~~~~~~ @@ -181,8 +182,8 @@ form_enctype ``view`` **type**: ``FormView`` -Renders the required ``enctype="multipart/form-data"`` attribute if the form -contains at least one file upload field, more information in +Renders the required ``enctype="multipart/form-data"`` attribute if the +form contains at least one file upload field, more information in :ref:`the Twig Form reference `. form_widget @@ -242,8 +243,8 @@ form_row ``variables`` **type**: ``array`` **default**: ``[]`` -Renders the row (the field's label, errors and widget) of the given field, more -information in :ref:`the Twig Form reference `. +Renders the row (the field's label, errors and widget) of the given field, +more information in :ref:`the Twig Form reference `. form_rest ~~~~~~~~~ @@ -287,15 +288,14 @@ is_granted ``field`` **type**: ``string`` -Returns ``true`` if the current user has the required role. Optionally, an -object can be pasted to be used by the voter. More information can be found in -:ref:`book-security-template`. +Returns ``true`` if the current user has the required role. Optionally, +an object can be pasted to be used by the voter. More information can be +found in :ref:`book-security-template`. .. note:: - You can also pass in the field to use ACE for a specific field. Read more - about this in :ref:`cookbook-security-acl-field_scope`. - + You can also pass in the field to use ACE for a specific field. Read + more about this in :ref:`cookbook-security-acl-field_scope`. logout_path ~~~~~~~~~~~ @@ -336,9 +336,9 @@ path ``relative`` **type**: ``boolean`` **default**: ``false`` -Returns the relative URL (without the scheme and host) for the given route. If -``relative`` is enabled, it'll create a path relative to the current path. More -information in :ref:`book-templating-pages`. +Returns the relative URL (without the scheme and host) for the given route. +If ``relative`` is enabled, it'll create a path relative to the current +path. More information in :ref:`book-templating-pages`. url ~~~ @@ -417,8 +417,8 @@ humanize ``text`` **type**: ``string`` -Makes a technical name human readable (i.e. replaces underscores by spaces and -capitalizes the string). +Makes a technical name human readable (i.e. replaces underscores by spaces +and capitalizes the string). trans ~~~~~ @@ -474,8 +474,8 @@ yaml_encode ``dumpObjects`` **type**: ``boolean`` **default**: ``false`` -Transforms the input into YAML syntax. See :ref:`components-yaml-dump` for more -information. +Transforms the input into YAML syntax. See :ref:`components-yaml-dump` for +more information. yaml_dump ~~~~~~~~~ @@ -491,7 +491,8 @@ yaml_dump ``dumpObjects`` **type**: ``boolean`` **default**: ``false`` -Does the same as `yaml_encode() `_, but includes the type in the output. +Does the same as `yaml_encode() `_, but includes the type in +the output. abbr_class ~~~~~~~~~~ @@ -503,8 +504,8 @@ abbr_class ``class`` **type**: ``string`` -Generates an ```` element with the short name of a PHP class (the FQCN -will be shown in a tooltip when a user hovers over the element). +Generates an ```` element with the short name of a PHP class (the +FQCN will be shown in a tooltip when a user hovers over the element). abbr_method ~~~~~~~~~~~ @@ -516,9 +517,9 @@ abbr_method ``method`` **type**: ``string`` -Generates an ```` element using the ``FQCN::method()`` syntax. If ``method`` -is ``Closure``, ``Closure`` will be used instead and if ``method`` doesn't have a -class name, it's shown as a function (``method()``). +Generates an ```` element using the ``FQCN::method()`` syntax. If +``method`` is ``Closure``, ``Closure`` will be used instead and if ``method`` +doesn't have a class name, it's shown as a function (``method()``). format_args ~~~~~~~~~~~ @@ -572,8 +573,8 @@ format_file ``text`` **type**: ``string`` **default**: ``null`` -Generates the file path inside an ```` element. If the path is inside the -kernel root directory, the kernel root directory path is replaced by +Generates the file path inside an ```` element. If the path is inside +the kernel root directory, the kernel root directory path is replaced by ``kernel.root_dir`` (showing the full path in a tooltip on hover). format_file_from_text @@ -598,8 +599,8 @@ file_link ``line`` **type**: ``integer`` -Generates a link to the provided file (and optionally line number) using a -preconfigured scheme. +Generates a link to the provided file (and optionally line number) using +a preconfigured scheme. .. _reference-twig-tags: @@ -730,8 +731,9 @@ Symfony Standard Edition Extensions The Symfony Standard Edition adds some bundles to the Symfony Core Framework. Those bundles can have other Twig extensions: -* **Twig Extensions** includes some interesting extensions that do not belong to the - Twig core. You can read more in `the official Twig Extensions documentation`_; +* **Twig Extensions** includes some interesting extensions that do not belong + to the Twig core. You can read more in `the official Twig Extensions + documentation`_; * **Assetic** adds the ``{% stylesheets %}``, ``{% javascripts %}`` and ``{% image %}`` tags. You can read more about them in :doc:`the Assetic Documentation `.