diff --git a/book/validation.rst b/book/validation.rst index ea5315afaae..f7f7e8205df 100644 --- a/book/validation.rst +++ b/book/validation.rst @@ -1072,7 +1072,7 @@ Now, change the ``User`` class to implement add the :method:`Symfony\\Component\\Validator\\GroupSequenceProviderInterface::getGroupSequence`, which should return an array of groups to use. Also, add the -``@Assert\GroupSequenceProvider`` annotation to the class. If you imagine +``@Assert\GroupSequenceProvider`` annotation to the class (or ``group_sequence_provider: true`` to the YAML). If you imagine that a method called ``isPremium`` returns true if the user is a premium member, then your code might look like this:: diff --git a/components/console/introduction.rst b/components/console/introduction.rst index 86274c029ca..af99f3322c4 100644 --- a/components/console/introduction.rst +++ b/components/console/introduction.rst @@ -35,7 +35,7 @@ Creating a basic Command To make a console command that greets you from the command line, create ``GreetCommand.php`` and add the following to it:: - namespace Acme\DemoBundle\Command; + namespace Acme\Command; use Symfony\Component\Console\Command\Command; use Symfony\Component\Console\Input\InputArgument; @@ -86,9 +86,9 @@ an ``Application`` and adds commands to it:: #!/usr/bin/env php `). diff --git a/contributing/code/patches.rst b/contributing/code/patches.rst index d2dae74d2fd..7f0667ea960 100644 --- a/contributing/code/patches.rst +++ b/contributing/code/patches.rst @@ -72,7 +72,7 @@ Get the Symfony2 source code: * Fork the `Symfony2 repository`_ (click on the "Fork" button); * After the "forking action" has completed, clone your fork locally - (this will create a `symfony` directory): + (this will create a ``symfony`` directory): .. code-block:: bash @@ -105,16 +105,16 @@ Choose the right Branch ~~~~~~~~~~~~~~~~~~~~~~~ Before working on a patch, you must determine on which branch you need to -work. The branch should be based on the `master` branch if you want to add a +work. The branch should be based on the ``master`` branch if you want to add a new feature. But if you want to fix a bug, use the oldest but still maintained -version of Symfony where the bug happens (like `2.2`). +version of Symfony where the bug happens (like ``2.3``). .. note:: All bug fixes merged into maintenance branches are also merged into more recent branches on a regular basis. For instance, if you submit a patch - for the `2.2` branch, the patch will also be applied by the core team on - the `master` branch. + for the ``2.3`` branch, the patch will also be applied by the core team on + the ``master`` branch. Create a Topic Branch ~~~~~~~~~~~~~~~~~~~~~ @@ -126,26 +126,26 @@ topic branch: $ git checkout -b BRANCH_NAME master -Or, if you want to provide a bugfix for the 2.2 branch, first track the remote -`2.2` branch locally: +Or, if you want to provide a bugfix for the ``2.3`` branch, first track the remote +``2.3`` branch locally: .. code-block:: bash - $ git checkout -t origin/2.2 + $ git checkout -t origin/2.3 -Then create a new branch off the 2.2 branch to work on the bugfix: +Then create a new branch off the ``2.3`` branch to work on the bugfix: .. code-block:: bash - $ git checkout -b BRANCH_NAME 2.2 + $ git checkout -b BRANCH_NAME 2.3 .. tip:: - Use a descriptive name for your branch (`ticket_XXX` where `XXX` is the + Use a descriptive name for your branch (``ticket_XXX`` where ``XXX`` is the ticket number is a good convention for bug fixes). The above checkout commands automatically switch the code to the newly created -branch (check the branch you are working on with `git branch`). +branch (check the branch you are working on with ``git branch``). Work on your Patch ~~~~~~~~~~~~~~~~~~ @@ -154,7 +154,7 @@ Work on the code as much as you want and commit as much as you want; but keep in mind the following: * Read about the Symfony :doc:`conventions ` and follow the - coding :doc:`standards ` (use `git diff --check` to check for + coding :doc:`standards ` (use ``git diff --check`` to check for trailing spaces -- also read the tip below); * Add unit tests to prove that the bug is fixed or that the new feature @@ -164,7 +164,7 @@ in mind the following: provide a compatibility layer to support the old way) -- patches that break backward compatibility have less chance to be merged; -* Do atomic and logically separate commits (use the power of `git rebase` to +* Do atomic and logically separate commits (use the power of ``git rebase`` to have a clean and logical history); * Squash irrelevant commits that are just about fixing coding standards or @@ -179,7 +179,7 @@ in mind the following: When submitting pull requests, `fabbot`_ checks your code for common typos and verifies that you are using the PHP coding standards - as defined in PSR-1 and PSR-2. + as defined in `PSR-1`_ and `PSR-2`_. A status is posted below the pull request description with a summary of any problems it detects or any Travis CI build failures. @@ -199,11 +199,11 @@ Prepare your Patch for Submission When your patch is not about a bug fix (when you add a new feature or change an existing one for instance), it must also include the following: -* An explanation of the changes in the relevant CHANGELOG file(s) (the ``[BC - BREAK]`` or the ``[DEPRECATION]`` prefix must be used when relevant); +* An explanation of the changes in the relevant ``CHANGELOG`` file(s) (the + ``[BC BREAK]`` or the ``[DEPRECATION]`` prefix must be used when relevant); * An explanation on how to upgrade an existing application in the relevant - UPGRADE file(s) if the changes break backward compatibility or if you + ``UPGRADE`` file(s) if the changes break backward compatibility or if you deprecate something that will ultimately break backward compatibility. Step 3: Submit your Patch @@ -228,7 +228,8 @@ while to finish your changes): .. tip:: - Replace `master` with `2.2` if you are working on a bugfix + Replace ``master`` with the branch you selected previously (e.g. ``2.3``) + if you are working on a bugfix When doing the ``rebase`` command, you might have to fix merge conflicts. ``git status`` will show you the *unmerged* files. Resolve all the conflicts, @@ -243,7 +244,7 @@ Check that all tests still pass and push your branch remotely: .. code-block:: bash - $ git push origin BRANCH_NAME + $ git push -f origin BRANCH_NAME Make a Pull Request ~~~~~~~~~~~~~~~~~~~ @@ -252,8 +253,8 @@ You can now make a pull request on the ``symfony/symfony`` Github repository. .. tip:: - Take care to point your pull request towards ``symfony:2.2`` if you want - the core team to pull a bugfix based on the 2.2 branch. + Take care to point your pull request towards ``symfony:2.3`` if you want + the core team to pull a bugfix based on the ``2.3`` branch. To ease the core team work, always include the modified components in your pull request message, like in: @@ -316,10 +317,10 @@ Some answers to the questions trigger some more requirements: documentation and reference it under the "Doc PR" section; * If you answer yes to "BC breaks?", the patch must contain updates to the - relevant CHANGELOG and UPGRADE files; + relevant ``CHANGELOG`` and ``UPGRADE`` files; * If you answer yes to "Deprecations?", the patch must contain updates to the - relevant CHANGELOG and UPGRADE files; + relevant ``CHANGELOG`` and ``UPGRADE`` files; * If you answer no to "Tests pass", you must add an item to a todo-list with the actions that must be done to fix the tests; @@ -381,7 +382,7 @@ convert many commits to one commit. To do this, use the rebase command: .. code-block:: bash - $ git rebase -i HEAD~3 + $ git rebase -i upstream/master $ git push -f origin BRANCH_NAME The number 3 here must equal the amount of commits in your branch. After you @@ -393,11 +394,11 @@ type this command, an editor will popup showing a list of commits: pick 7fc64b4 second commit pick 7d33018 third commit -To squash all commits into the first one, remove the word "pick" before the -second and the last commits, and replace it by the word "squash" or just "s". -When you save, Git will start rebasing, and if successful, will ask you to -edit the commit message, which by default is a listing of the commit messages -of all the commits. When you finish, execute the push command. +To squash all commits into the first one, remove the word ``pick`` before the +second and the last commits, and replace it by the word ``squash`` or just + ``s``. When you save, Git will start rebasing, and if successful, will ask + you to edit the commit message, which by default is a listing of the commit + messages of all the commits. When you are finished, execute the push command. .. _ProGit: http://git-scm.com/book .. _GitHub: https://github.com/signup/free @@ -409,3 +410,5 @@ of all the commits. When you finish, execute the push command. .. _`travis-ci.org Getting Started Guide`: http://about.travis-ci.org/docs/user/getting-started/ .. _`documentation repository`: https://github.com/symfony/symfony-docs .. _`fabbot`: http://fabbot.io +.. _`PSR-1`: http://www.php-fig.org/psr/psr-1/ +.. _`PSR-2`: http://www.php-fig.org/psr/psr-2/ diff --git a/cookbook/bundles/remove.rst b/cookbook/bundles/remove.rst index 69ba500f2b6..af1dfd774b8 100644 --- a/cookbook/bundles/remove.rst +++ b/cookbook/bundles/remove.rst @@ -18,8 +18,8 @@ starting a project, but you'll probably want to eventually remove it. To disconnect the bundle from the framework, you should remove the bundle from the ``AppKernel::registerBundles()`` method. The bundle is normally found in -the ``$bundles`` array but the AcmeDemoBundle is only registered in a -development environment and you can find him in the if statement after:: +the ``$bundles`` array but the AcmeDemoBundle is only registered in the +development environment and you can find it inside the if statement below:: // app/AppKernel.php @@ -96,8 +96,8 @@ rely on the bundle you are about to remove. .. tip:: If one bundle relies on another, in most it means that it uses some services - from the bundle. Searching for a ``acme_demo`` string may help you spot - them. + from the bundle. Searching for the bundle alias string may help you spot + them (e.g. ``acme_demo`` for bundles depending on AcmeDemoBundle). .. tip:: diff --git a/cookbook/form/form_collections.rst b/cookbook/form/form_collections.rst index 8a09dee95af..654524b84b8 100644 --- a/cookbook/form/form_collections.rst +++ b/cookbook/form/form_collections.rst @@ -20,7 +20,7 @@ that Task, right inside the same form. including the ``ManyToMany`` association mapping definition on the Task's ``tags`` property. -Let's start there: suppose that each ``Task`` belongs to multiple ``Tags`` +Let's start there: suppose that each ``Task`` belongs to multiple ``Tag`` objects. Start by creating a simple ``Task`` class:: // src/Acme/TaskBundle/Entity/Task.php diff --git a/cookbook/security/custom_authentication_provider.rst b/cookbook/security/custom_authentication_provider.rst index 468bcffcba0..89cf591aff1 100644 --- a/cookbook/security/custom_authentication_provider.rst +++ b/cookbook/security/custom_authentication_provider.rst @@ -194,6 +194,13 @@ a 403 Response is returned. does not require maintaining authentication sessions or login forms, it won't be used for this example. +.. note:: + + Returning prematurely from the listener is relevant only if you want to chain + authentication providers (for example to allow anonymous users). If you want + to forbid access to anonymous users and have a nice 403 error, you should set + the status code of the response before returning. + The Authentication Provider --------------------------- diff --git a/cookbook/security/custom_password_authenticator.rst b/cookbook/security/custom_password_authenticator.rst index 2f4b86c4647..751beef449c 100644 --- a/cookbook/security/custom_password_authenticator.rst +++ b/cookbook/security/custom_password_authenticator.rst @@ -25,7 +25,7 @@ the user:: use Symfony\Component\HttpFoundation\Request; use Symfony\Component\Security\Core\Authentication\SimpleFormAuthenticatorInterface; - use Symfony\Component\Security\Core\Authentication\TokenInterface; + use Symfony\Component\Security\Core\Authentication\Token\TokenInterface; use Symfony\Component\Security\Core\Authentication\Token\UsernamePasswordToken; use Symfony\Component\Security\Core\Encoder\EncoderFactoryInterface; use Symfony\Component\Security\Core\Exception\AuthenticationException; diff --git a/reference/forms/types/button.rst b/reference/forms/types/button.rst index 44bf65a90b7..18cbbd3103f 100644 --- a/reference/forms/types/button.rst +++ b/reference/forms/types/button.rst @@ -38,4 +38,7 @@ Options .. include:: /reference/forms/types/options/button_translation_domain.rst.inc +Overridden Options +------------------ + .. include:: /reference/forms/types/options/button_auto_initialize.rst.inc diff --git a/reference/forms/types/checkbox.rst b/reference/forms/types/checkbox.rst index adb6f8d1b24..fc529e3a7d9 100644 --- a/reference/forms/types/checkbox.rst +++ b/reference/forms/types/checkbox.rst @@ -14,7 +14,8 @@ if the box is unchecked, the value will be set to false. | Options | - `value`_ | +-------------+------------------------------------------------------------------------+ | Inherited | - `data`_ | -| options | - `required`_ | +| options | - `empty_data`_ | +| | - `required`_ | | | - `label`_ | | | - `label_attr`_ | | | - `read_only`_ | @@ -60,6 +61,8 @@ These options inherit from the :doc:`form ` type: .. include:: /reference/forms/types/options/data.rst.inc +.. include:: /reference/forms/types/options/empty_data.rst.inc + .. include:: /reference/forms/types/options/required.rst.inc .. include:: /reference/forms/types/options/label.rst.inc diff --git a/reference/forms/types/collection.rst b/reference/forms/types/collection.rst index fe1e6ee8cb5..dca2d76660f 100644 --- a/reference/forms/types/collection.rst +++ b/reference/forms/types/collection.rst @@ -22,8 +22,8 @@ forms, which is useful when creating forms that expose one-to-many relationships | | - `delete_empty`_ | +-------------+-----------------------------------------------------------------------------+ | Inherited | - `label`_ | -| | - `label_attr`_ | -| options | - `error_bubbling`_ | +| options | - `label_attr`_ | +| | - `error_bubbling`_ | | | - `error_mapping`_ | | | - `by_reference`_ | | | - `empty_data`_ | diff --git a/reference/forms/types/country.rst b/reference/forms/types/country.rst index ceb1f8385d8..e8bb61ae572 100644 --- a/reference/forms/types/country.rst +++ b/reference/forms/types/country.rst @@ -31,6 +31,7 @@ you should just use the ``choice`` type directly. | | - `empty_value`_ | | | - `error_bubbling`_ | | | - `error_mapping`_ | +| | - `empty_data`_ | | | - `required`_ | | | - `label`_ | | | - `label_attr`_ | @@ -74,6 +75,8 @@ These options inherit from the :doc:`choice ` typ These options inherit from the :doc:`form ` type: +.. include:: /reference/forms/types/options/empty_data.rst.inc + .. include:: /reference/forms/types/options/required.rst.inc .. include:: /reference/forms/types/options/label.rst.inc diff --git a/reference/forms/types/currency.rst b/reference/forms/types/currency.rst index b92d1a3e4d5..b91b55f5a48 100644 --- a/reference/forms/types/currency.rst +++ b/reference/forms/types/currency.rst @@ -24,6 +24,7 @@ should just use the ``choice`` type directly. | | - `preferred_choices`_ | | | - `empty_value`_ | | | - `error_bubbling`_ | +| | - `empty_data`_ | | | - `required`_ | | | - `label`_ | | | - `label_attr`_ | @@ -64,6 +65,8 @@ These options inherit from the :doc:`choice` type These options inherit from the :doc:`form` type: +.. include:: /reference/forms/types/options/empty_data.rst.inc + .. include:: /reference/forms/types/options/required.rst.inc .. include:: /reference/forms/types/options/label.rst.inc diff --git a/reference/forms/types/datetime.rst b/reference/forms/types/datetime.rst index e607655f03e..5db418b44f3 100644 --- a/reference/forms/types/datetime.rst +++ b/reference/forms/types/datetime.rst @@ -26,6 +26,7 @@ data can be a ``DateTime`` object, a string, a timestamp or an array. | | - `years`_ | | | - `months`_ | | | - `days`_ | +| | - `with_minutes`_ | | | - `with_seconds`_ | | | - `model_timezone`_ | | | - `view_timezone`_ | @@ -109,6 +110,8 @@ for more details. .. include:: /reference/forms/types/options/days.rst.inc +.. include:: /reference/forms/types/options/with_minutes.rst.inc + .. include:: /reference/forms/types/options/with_seconds.rst.inc .. include:: /reference/forms/types/options/model_timezone.rst.inc diff --git a/reference/forms/types/email.rst b/reference/forms/types/email.rst index 1ba1ec68d95..33908563a9a 100644 --- a/reference/forms/types/email.rst +++ b/reference/forms/types/email.rst @@ -11,7 +11,8 @@ The ``email`` field is a text field that is rendered using the HTML5 | Rendered as | ``input`` ``email`` field (a text box) | +-------------+---------------------------------------------------------------------+ | Inherited | - `max_length`_ | -| options | - `required`_ | +| options | - `empty_data`_ | +| | - `required`_ | | | - `label`_ | | | - `label_attr`_ | | | - `data`_ | @@ -34,6 +35,8 @@ These options inherit from the :doc:`form ` type: .. include:: /reference/forms/types/options/max_length.rst.inc +.. include:: /reference/forms/types/options/empty_data.rst.inc + .. include:: /reference/forms/types/options/required.rst.inc .. include:: /reference/forms/types/options/label.rst.inc diff --git a/reference/forms/types/entity.rst b/reference/forms/types/entity.rst index bcedc2775c0..15255213749 100644 --- a/reference/forms/types/entity.rst +++ b/reference/forms/types/entity.rst @@ -26,6 +26,7 @@ objects from the database. | options | - `expanded`_ | | | - `preferred_choices`_ | | | - `empty_value`_ | +| | - `empty_data`_ | | | - `required`_ | | | - `label`_ | | | - `label_attr`_ | @@ -196,6 +197,8 @@ These options inherit from the :doc:`choice ` typ These options inherit from the :doc:`form ` type: +.. include:: /reference/forms/types/options/empty_data.rst.inc + .. include:: /reference/forms/types/options/required.rst.inc .. include:: /reference/forms/types/options/label.rst.inc diff --git a/reference/forms/types/file.rst b/reference/forms/types/file.rst index e941b7abfbb..fa79a02e18e 100644 --- a/reference/forms/types/file.rst +++ b/reference/forms/types/file.rst @@ -11,8 +11,9 @@ The ``file`` type represents a file input in your form. +-------------+---------------------------------------------------------------------+ | Options | - `multiple`_ | +-------------+---------------------------------------------------------------------+ -| Inherited | - `required`_ | -| options | - `label`_ | +| Inherited | - `empty_data`_ | +| options | - `required`_ | +| | - `label`_ | | | - `label_attr`_ | | | - `read_only`_ | | | - `disabled`_ | @@ -94,6 +95,8 @@ Inherited options These options inherit from the :doc:`form ` type: +.. include:: /reference/forms/types/options/empty_data.rst.inc + .. include:: /reference/forms/types/options/required.rst.inc .. include:: /reference/forms/types/options/label.rst.inc diff --git a/reference/forms/types/form.rst b/reference/forms/types/form.rst index 4a99b6e55d8..fc630baa1b1 100644 --- a/reference/forms/types/form.rst +++ b/reference/forms/types/form.rst @@ -15,6 +15,8 @@ on all fields. .. include:: /reference/forms/types/options/data_class.rst.inc +.. include:: /reference/forms/types/options/empty_data.rst.inc + .. include:: /reference/forms/types/options/required.rst.inc .. include:: /reference/forms/types/options/label.rst.inc @@ -41,6 +43,8 @@ on all fields. .. include:: /reference/forms/types/options/block_name.rst.inc +.. include:: /reference/forms/types/options/max_length.rst.inc + inherit_data ------------ diff --git a/reference/forms/types/integer.rst b/reference/forms/types/integer.rst index ba4a0760b25..1b376ca1266 100644 --- a/reference/forms/types/integer.rst +++ b/reference/forms/types/integer.rst @@ -19,8 +19,9 @@ integers. By default, all non-integer values (e.g. 6.78) will round down (e.g. 6 | | - `precision`_ | | | - `grouping`_ | +-------------+-----------------------------------------------------------------------+ -| Inherited | - `required`_ | -| options | - `label`_ | +| Inherited | - `empty_data`_ | +| options | - `required`_ | +| | - `label`_ | | | - `label_attr`_ | | | - `data`_ | | | - `read_only`_ | @@ -77,6 +78,8 @@ Inherited options These options inherit from the :doc:`form ` type: +.. include:: /reference/forms/types/options/empty_data.rst.inc + .. include:: /reference/forms/types/options/required.rst.inc .. include:: /reference/forms/types/options/label.rst.inc diff --git a/reference/forms/types/language.rst b/reference/forms/types/language.rst index 8205045e6e4..1b8e78b2db4 100644 --- a/reference/forms/types/language.rst +++ b/reference/forms/types/language.rst @@ -32,6 +32,7 @@ you should just use the ``choice`` type directly. | | - `empty_value`_ | | | - `error_bubbling`_ | | | - `error_mapping`_ | +| | - `empty_data`_ | | | - `required`_ | | | - `label`_ | | | - `label_attr`_ | @@ -75,6 +76,8 @@ These options inherit from the :doc:`choice ` typ These options inherit from the :doc:`form ` type: +.. include:: /reference/forms/types/options/empty_data.rst.inc + .. include:: /reference/forms/types/options/required.rst.inc .. include:: /reference/forms/types/options/label.rst.inc diff --git a/reference/forms/types/locale.rst b/reference/forms/types/locale.rst index 4d5dd32d621..c5626f71b95 100644 --- a/reference/forms/types/locale.rst +++ b/reference/forms/types/locale.rst @@ -34,6 +34,7 @@ you should just use the ``choice`` type directly. | | - `empty_value`_ | | | - `error_bubbling`_ | | | - `error_mapping`_ | +| | - `empty_data`_ | | | - `required`_ | | | - `label`_ | | | - `label_attr`_ | @@ -77,6 +78,8 @@ These options inherit from the :doc:`choice ` typ These options inherit from the :doc:`form ` type: +.. include:: /reference/forms/types/options/empty_data.rst.inc + .. include:: /reference/forms/types/options/required.rst.inc .. include:: /reference/forms/types/options/label.rst.inc diff --git a/reference/forms/types/money.rst b/reference/forms/types/money.rst index 5e143c93570..3a136b1ca22 100644 --- a/reference/forms/types/money.rst +++ b/reference/forms/types/money.rst @@ -19,8 +19,9 @@ how the input and output of the data is handled. | | - `precision`_ | | | - `grouping`_ | +-------------+---------------------------------------------------------------------+ -| Inherited | - `required`_ | -| options | - `label`_ | +| Inherited | - `empty_data`_ | +| options | - `required`_ | +| | - `label`_ | | | - `label_attr`_ | | | - `data`_ | | | - `read_only`_ | @@ -87,6 +88,8 @@ Inherited Options These options inherit from the :doc:`form ` type: +.. include:: /reference/forms/types/options/empty_data.rst.inc + .. include:: /reference/forms/types/options/required.rst.inc .. include:: /reference/forms/types/options/label.rst.inc diff --git a/reference/forms/types/number.rst b/reference/forms/types/number.rst index 74d35a4f61a..4858a5de097 100644 --- a/reference/forms/types/number.rst +++ b/reference/forms/types/number.rst @@ -15,8 +15,9 @@ you want to use for your number. | | - `precision`_ | | | - `grouping`_ | +-------------+----------------------------------------------------------------------+ -| Inherited | - `required`_ | -| options | - `label`_ | +| Inherited | - `empty_data`_ | +| options | - `required`_ | +| | - `label`_ | | | - `label_attr`_ | | | - `data`_ | | | - `read_only`_ | @@ -73,6 +74,8 @@ Inherited Options These options inherit from the :doc:`form ` type: +.. include:: /reference/forms/types/options/empty_data.rst.inc + .. include:: /reference/forms/types/options/required.rst.inc .. include:: /reference/forms/types/options/label.rst.inc diff --git a/reference/forms/types/options/data_class.rst.inc b/reference/forms/types/options/data_class.rst.inc index 3636dbf13d6..85024141f81 100644 --- a/reference/forms/types/options/data_class.rst.inc +++ b/reference/forms/types/options/data_class.rst.inc @@ -1,6 +1,3 @@ -.. versionadded:: 2.4 - The ``data_class`` option was introduced in Symfony 2.4. - data_class ~~~~~~~~~~ @@ -9,6 +6,8 @@ data_class This option is used to set the appropriate data mapper to be used by the form, so you can use it for any form field type which requires an object. +.. code-block:: php + $builder->add('media', 'sonata_media_type', array( 'data_class' => 'Acme\DemoBundle\Entity\Media', )); diff --git a/reference/forms/types/options/max_length.rst.inc b/reference/forms/types/options/max_length.rst.inc index ef0a487e473..d20d44e1199 100644 --- a/reference/forms/types/options/max_length.rst.inc +++ b/reference/forms/types/options/max_length.rst.inc @@ -1,7 +1,10 @@ max_length ~~~~~~~~~~ -**type**: ``integer`` +**type**: ``integer`` **default**: ``null`` -This option is used to add a ``maxlength`` attribute, which is used by -some browsers to limit the amount of text in a field. +If this option is not null, an attribute ``maxlength`` is added, which +is used by some browsers to limit the amount of text in a field. + +This is just a browser validation, so data must still be validated +server-side. diff --git a/reference/forms/types/options/with_minutes.rst.inc b/reference/forms/types/options/with_minutes.rst.inc new file mode 100644 index 00000000000..274509e0b83 --- /dev/null +++ b/reference/forms/types/options/with_minutes.rst.inc @@ -0,0 +1,10 @@ +.. versionadded:: 2.2 + The ``with_minutes`` option was introduced in Symfony 2.2. + +with_minutes +~~~~~~~~~~~~ + +**type**: ``Boolean`` **default**: ``true`` + +Whether or not to include minutes in the input. This will result in an additional +input to capture minutes. diff --git a/reference/forms/types/password.rst b/reference/forms/types/password.rst index 7cdbf2f3970..12ed8b17d77 100644 --- a/reference/forms/types/password.rst +++ b/reference/forms/types/password.rst @@ -12,7 +12,8 @@ The ``password`` field renders an input password text box. | Options | - `always_empty`_ | +-------------+------------------------------------------------------------------------+ | Inherited | - `max_length`_ | -| options | - `required`_ | +| options | - `empty_data`_ | +| | - `required`_ | | | - `label`_ | | | - `label_attr`_ | | | - `trim`_ | @@ -51,6 +52,8 @@ These options inherit from the :doc:`form ` type: .. include:: /reference/forms/types/options/max_length.rst.inc +.. include:: /reference/forms/types/options/empty_data.rst.inc + .. include:: /reference/forms/types/options/required.rst.inc .. include:: /reference/forms/types/options/label.rst.inc diff --git a/reference/forms/types/percent.rst b/reference/forms/types/percent.rst index 2abe9fba4e9..dbde292cc35 100644 --- a/reference/forms/types/percent.rst +++ b/reference/forms/types/percent.rst @@ -18,8 +18,9 @@ This field adds a percentage sign "``%``" after the input box. | Options | - `type`_ | | | - `precision`_ | +-------------+-----------------------------------------------------------------------+ -| Inherited | - `required`_ | -| options | - `label`_ | +| Inherited | - `empty_data`_ | +| options | - `required`_ | +| | - `label`_ | | | - `label_attr`_ | | | - `data`_ | | | - `read_only`_ | @@ -71,6 +72,8 @@ Inherited Options These options inherit from the :doc:`form ` type: +.. include:: /reference/forms/types/options/empty_data.rst.inc + .. include:: /reference/forms/types/options/required.rst.inc .. include:: /reference/forms/types/options/label.rst.inc diff --git a/reference/forms/types/radio.rst b/reference/forms/types/radio.rst index 9478a8816ee..6d29555f3fa 100644 --- a/reference/forms/types/radio.rst +++ b/reference/forms/types/radio.rst @@ -18,7 +18,8 @@ If you want to have a Boolean field, use :doc:`checkbox ` type: .. include:: /reference/forms/types/options/data.rst.inc +.. include:: /reference/forms/types/options/empty_data.rst.inc + .. include:: /reference/forms/types/options/required.rst.inc .. include:: /reference/forms/types/options/label.rst.inc diff --git a/reference/forms/types/search.rst b/reference/forms/types/search.rst index d06b072d7a2..9ff7b9d8393 100644 --- a/reference/forms/types/search.rst +++ b/reference/forms/types/search.rst @@ -13,7 +13,8 @@ Read about the input search field at `DiveIntoHTML5.info`_ | Rendered as | ``input search`` field | +-------------+----------------------------------------------------------------------+ | Inherited | - `max_length`_ | -| options | - `required`_ | +| options | - `empty_data`_ | +| | - `required`_ | | | - `label`_ | | | - `label_attr`_ | | | - `trim`_ | @@ -35,6 +36,8 @@ These options inherit from the :doc:`form ` type: .. include:: /reference/forms/types/options/max_length.rst.inc +.. include:: /reference/forms/types/options/empty_data.rst.inc + .. include:: /reference/forms/types/options/required.rst.inc .. include:: /reference/forms/types/options/label.rst.inc diff --git a/reference/forms/types/text.rst b/reference/forms/types/text.rst index d63d403f53e..675b1f800ae 100644 --- a/reference/forms/types/text.rst +++ b/reference/forms/types/text.rst @@ -10,7 +10,8 @@ The text field represents the most basic input text field. | Rendered as | ``input`` ``text`` field | +-------------+--------------------------------------------------------------------+ | Inherited | - `max_length`_ | -| options | - `required`_ | +| options | - `empty_data`_ | +| | - `required`_ | | | - `label`_ | | | - `label_attr`_ | | | - `data`_ | @@ -34,6 +35,8 @@ These options inherit from the :doc:`form ` type: .. include:: /reference/forms/types/options/max_length.rst.inc +.. include:: /reference/forms/types/options/empty_data.rst.inc + .. include:: /reference/forms/types/options/required.rst.inc .. include:: /reference/forms/types/options/label.rst.inc diff --git a/reference/forms/types/textarea.rst b/reference/forms/types/textarea.rst index 0602dd2b6ec..de0787c920e 100644 --- a/reference/forms/types/textarea.rst +++ b/reference/forms/types/textarea.rst @@ -10,6 +10,7 @@ Renders a ``textarea`` HTML element. | Rendered as | ``textarea`` tag | +-------------+------------------------------------------------------------------------+ | Inherited | - `max_length`_ | +| options | - `empty_data`_ | | options | - `required`_ | | | - `label`_ | | | - `label_attr`_ | @@ -33,6 +34,8 @@ These options inherit from the :doc:`form ` type: .. include:: /reference/forms/types/options/max_length.rst.inc +.. include:: /reference/forms/types/options/empty_data.rst.inc + .. include:: /reference/forms/types/options/required.rst.inc .. include:: /reference/forms/types/options/label.rst.inc diff --git a/reference/forms/types/time.rst b/reference/forms/types/time.rst index 4a203498615..49a40782ae5 100644 --- a/reference/forms/types/time.rst +++ b/reference/forms/types/time.rst @@ -17,6 +17,7 @@ as a ``DateTime`` object, a string, a timestamp or an array. +----------------------+-----------------------------------------------------------------------------+ | Options | - `widget`_ | | | - `input`_ | +| | - `with_minutes`_ | | | - `with_seconds`_ | | | - `hours`_ | | | - `minutes`_ | @@ -83,13 +84,21 @@ widget The basic way in which this field should be rendered. Can be one of the following: -* ``choice``: renders two (or three if `with_seconds`_ is true) select inputs. +* ``choice``: renders one, two (default) or three select inputs (hour, minute, + second), depending on the `with_minutes`_ and `with_seconds`_ options. -* ``text``: renders a two or three text inputs (hour, minute, second). +* ``text``: renders one, two (default) or three text inputs (hour, minute, + second), depending on the `with_minutes`_ and `with_seconds`_ options. -* ``single_text``: renders a single input of type text. User's input will +* ``single_text``: renders a single input of type ``time``. User's input will be validated against the form ``hh:mm`` (or ``hh:mm:ss`` if using seconds). +.. caution:: + + Combining the widget type ``single_text`` and the `with_minutes`_ option + set to ``false`` can cause unexpected behavior in the client as the input + type ``time`` might not support selecting an hour only. + input ~~~~~ @@ -106,6 +115,8 @@ your underlying object. Valid values are: The value that comes back from the form will also be normalized back into this format. +.. include:: /reference/forms/types/options/with_minutes.rst.inc + .. include:: /reference/forms/types/options/with_seconds.rst.inc .. include:: /reference/forms/types/options/hours.rst.inc diff --git a/reference/forms/types/timezone.rst b/reference/forms/types/timezone.rst index 04f3006c5a9..ef4769e1cff 100644 --- a/reference/forms/types/timezone.rst +++ b/reference/forms/types/timezone.rst @@ -25,6 +25,7 @@ you should just use the ``choice`` type directly. | options | - `expanded`_ | | | - `preferred_choices`_ | | | - `empty_value`_ | +| | - `empty_data`_ | | | - `required`_ | | | - `label`_ | | | - `label_attr`_ | @@ -66,6 +67,8 @@ These options inherit from the :doc:`choice ` typ These options inherit from the :doc:`form ` type: +.. include:: /reference/forms/types/options/empty_data.rst.inc + .. include:: /reference/forms/types/options/required.rst.inc .. include:: /reference/forms/types/options/label.rst.inc diff --git a/reference/forms/types/url.rst b/reference/forms/types/url.rst index b915793057c..44a68d68218 100644 --- a/reference/forms/types/url.rst +++ b/reference/forms/types/url.rst @@ -14,7 +14,8 @@ have a protocol. | Options | - `default_protocol`_ | +-------------+-------------------------------------------------------------------+ | Inherited | - `max_length`_ | -| options | - `required`_ | +| options | - `empty_data`_ | +| | - `required`_ | | | - `label`_ | | | - `label_attr`_ | | | - `data`_ | @@ -49,6 +50,8 @@ These options inherit from the :doc:`form ` type: .. include:: /reference/forms/types/options/max_length.rst.inc +.. include:: /reference/forms/types/options/empty_data.rst.inc + .. include:: /reference/forms/types/options/required.rst.inc .. include:: /reference/forms/types/options/label.rst.inc