diff --git a/book/doctrine.rst b/book/doctrine.rst index 026a3b4f977..8fc6e72dc6e 100644 --- a/book/doctrine.rst +++ b/book/doctrine.rst @@ -728,65 +728,18 @@ a controller, do the following:: $products = $query->getResult(); +The ``getResult()`` method returns an array of results. + If you're comfortable with SQL, then DQL should feel very natural. The biggest difference is that you need to think in terms of "objects" instead of rows -in a database. For this reason, you select *from* ``AcmeStoreBundle:Product`` -and then alias it as ``p``. - -The ``getResult()`` method returns an array of results. If you're querying -for just one object, you can use the ``getSingleResult()`` method instead:: - - $product = $query->getSingleResult(); - -.. caution:: - - The ``getSingleResult()`` method throws a ``Doctrine\ORM\NoResultException`` - exception if no results are returned and a ``Doctrine\ORM\NonUniqueResultException`` - if *more* than one result is returned. If you use this method, you may - need to wrap it in a try-catch block and ensure that only one result is - returned (if you're querying on something that could feasibly return - more than one result):: - - $query = $em->createQuery('SELECT ...') - ->setMaxResults(1); - - try { - $product = $query->getSingleResult(); - } catch (\Doctrine\Orm\NoResultException $e) { - $product = null; - } - // ... +in a database. For this reason, you select *from* the ``AcmeStoreBundle:Product`` +*object* and then alias it as ``p``. The DQL syntax is incredibly powerful, allowing you to easily join between entities (the topic of :ref:`relations ` will be covered later), group, etc. For more information, see the official Doctrine `Doctrine Query Language`_ documentation. -.. sidebar:: Setting Parameters - - Take note of the ``setParameter()`` method. When working with Doctrine, - it's always a good idea to set any external values as "placeholders", - which was done in the above query: - - .. code-block:: text - - ... WHERE p.price > :price ... - - You can then set the value of the ``price`` placeholder by calling the - ``setParameter()`` method:: - - ->setParameter('price', '19.99') - - Using parameters instead of placing values directly in the query string - is done to prevent SQL injection attacks and should *always* be done. - If you're using multiple parameters, you can set their values at once - using the ``setParameters()`` method:: - - ->setParameters(array( - 'price' => '19.99', - 'name' => 'Foo', - )) - Using Doctrine's Query Builder ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -819,10 +772,10 @@ Custom Repository Classes In the previous sections, you began constructing and using more complex queries from inside a controller. In order to isolate, test and reuse these queries, -it's a good idea to create a custom repository class for your entity and +it's a good practise to create a custom repository class for your entity and add methods with your query logic there. -To do this, add the name of the repository class to your mapping definition. +To do this, add the name of the repository class to your mapping definition: .. configuration-block:: @@ -1300,7 +1253,7 @@ Configuration Doctrine is highly configurable, though you probably won't ever need to worry about most of its options. To find out more about configuring Doctrine, see -the Doctrine section of the :doc:`reference manual `. +the Doctrine section of the :doc:`config reference `. Lifecycle Callbacks ------------------- @@ -1312,7 +1265,7 @@ stages of the lifecycle of an entity (e.g. the entity is inserted, updated, deleted, etc). If you're using annotations for your metadata, start by enabling the lifecycle -callbacks. This is not necessary if you're using YAML or XML for your mapping: +callbacks. This is not necessary if you're using YAML or XML for your mapping. .. code-block:: php-annotations @@ -1375,20 +1328,8 @@ the current date, only when the entity is first persisted (i.e. inserted): Now, right before the entity is first persisted, Doctrine will automatically call this method and the ``createdAt`` field will be set to the current date. - -This can be repeated for any of the other lifecycle events, which include: - -* ``preRemove`` -* ``postRemove`` -* ``prePersist`` -* ``postPersist`` -* ``preUpdate`` -* ``postUpdate`` -* ``postLoad`` -* ``loadClassMetadata`` - -For more information on what these lifecycle events mean and lifecycle callbacks -in general, see Doctrine's `Lifecycle Events documentation`_ +For more information on other lifecycle events and lifecycle callbacks in +general, see Doctrine's `Lifecycle Events documentation`_. .. sidebar:: Lifecycle Callbacks and Event Listeners @@ -1403,17 +1344,6 @@ in general, see Doctrine's `Lifecycle Events documentation`_ or subscriber and give it access to whatever resources you need. For more information, see :doc:`/cookbook/doctrine/event_listeners_subscribers`. -Doctrine Extensions: Timestampable, Sluggable, etc. ---------------------------------------------------- - -Doctrine is quite flexible, and a number of third-party extensions are available -that allow you to easily perform repeated and common tasks on your entities. -These include thing such as *Sluggable*, *Timestampable*, *Loggable*, *Translatable*, -and *Tree*. - -For more information on how to find and use these extensions, see the cookbook -article about :doc:`using common Doctrine extensions `. - .. _book-doctrine-field-types: Doctrine Field Types Reference @@ -1421,167 +1351,8 @@ Doctrine Field Types Reference Doctrine comes with a large number of field types available. Each of these maps a PHP data type to a specific column type in whatever database you're -using. The following types are supported in Doctrine: - -* **Strings** - - * ``string`` (used for shorter strings) - * ``text`` (used for larger strings) - -* **Numbers** - - * ``integer`` - * ``smallint`` - * ``bigint`` - * ``decimal`` - * ``float`` - -* **Dates and Times** (use a `DateTime`_ object for these fields in PHP) - - * ``date`` - * ``time`` - * ``datetime`` - * ``datetimetz`` - -* **Other Types** - - * ``boolean`` - * ``object`` (serialized and stored in a ``CLOB`` field) - * ``array`` (serialized and stored in a ``CLOB`` field) - * ``blob`` (mapped to a resource stream) - * ``simple_array`` (serialized using :phpfunction:`implode()` and :phpfunction:`explode()`, - with a comma as delimiter, and stored in a ``CLOB`` field) - * ``json_array`` (serialized using :phpfunction:`json_encode()` and :phpfunction:`json_decode()`, - and stored in a ``CLOB`` field) - * ``guid`` - -For more information, see Doctrine's `Mapping Types documentation`_. - -Field Options -~~~~~~~~~~~~~ - -Each field can have a set of options applied to it. The available options -include ``type`` (defaults to ``string``), ``name``, ``length``, ``unique`` -and ``nullable``. Take a few examples: - -.. configuration-block:: - - .. code-block:: php-annotations - - /** - * A string field with length 255 that cannot be null - * (reflecting the default values for the "type", "length" - * and *nullable* options) - * - * @ORM\Column() - */ - protected $name; - - /** - * A string field of length 150 that persists to an "email_address" column - * and has a unique index. - * - * @ORM\Column(name="email_address", unique=true, length=150) - */ - protected $email; - - .. code-block:: yaml - - fields: - # A string field length 255 that cannot be null - # (reflecting the default values for the "length" and *nullable* options) - # type attribute is necessary in YAML definitions - name: - type: string - - # A string field of length 150 that persists to an "email_address" column - # and has a unique index. - email: - type: string - column: email_address - length: 150 - unique: true - - .. code-block:: xml - - - - - -.. note:: - - There are a few more options not listed here. For more details, see - Doctrine's `Property Mapping documentation`_ - -.. index:: - single: Doctrine; ORM console commands - single: CLI; Doctrine ORM - -Console Commands ----------------- - -The Doctrine2 ORM integration offers several console commands under the -``doctrine`` namespace. To view the command list you can run the console -without any arguments: - -.. code-block:: bash - - $ php app/console - -A list of available commands will print out, many of which start with the -``doctrine:`` prefix. You can find out more information about any of these -commands (or any Symfony command) by running the ``help`` command. For example, -to get details about the ``doctrine:database:create`` task, run: - -.. code-block:: bash - - $ php app/console help doctrine:database:create - -Some notable or interesting tasks include: - -* ``doctrine:ensure-production-settings`` - checks to see if the current - environment is configured efficiently for production. This should always - be run in the ``prod`` environment: - - .. code-block:: bash - - $ php app/console doctrine:ensure-production-settings --env=prod - -* ``doctrine:mapping:import`` - allows Doctrine to introspect an existing - database and create mapping information. For more information, see - :doc:`/cookbook/doctrine/reverse_engineering`. - -* ``doctrine:mapping:info`` - tells you all of the entities that Doctrine - is aware of and whether or not there are any basic errors with the mapping. - -* ``doctrine:query:dql`` and ``doctrine:query:sql`` - allow you to execute - DQL or SQL queries directly from the command line. - -.. note:: - - To be able to load data fixtures to your database, you will need to have - the DoctrineFixturesBundle bundle installed. To learn how to do it, - read the ":doc:`/bundles/DoctrineFixturesBundle/index`" entry of the - documentation. - -.. tip:: - - This page shows working with Doctrine within a controller. You may also - want to work with Doctrine elsewhere in your application. The - :method:`Symfony\\Bundle\\FrameworkBundle\\Controller\\Controller::getDoctrine` - method of the controller returns the ``doctrine`` service, you can work with - this in the same way elsewhere by injecting this into your own - services. See :doc:`/book/service_container` for more on creating - your own services. +using. To see a list of all available types and more information, see +Doctrine's `Mapping Types documentation`_. Summary ------- @@ -1598,10 +1369,12 @@ that allow you to take different actions as objects go through their persistence lifecycle. For more information about Doctrine, see the *Doctrine* section of the -:doc:`cookbook `, which includes the following articles: +:doc:`cookbook `. Some usefull articles might be: -* :doc:`/bundles/DoctrineFixturesBundle/index` * :doc:`/cookbook/doctrine/common_extensions` +* :doc:`/cookbook/doctrine/console` +* :doc:`/bundles/DoctrineFixturesBundle/index` +* :doc:`/bundles/DoctrineMongoDBBundle/index` .. _`Doctrine`: http://www.doctrine-project.org/ .. _`MongoDB`: http://www.mongodb.org/ @@ -1609,10 +1382,8 @@ For more information about Doctrine, see the *Doctrine* section of the .. _`Query Builder`: http://docs.doctrine-project.org/projects/doctrine-orm/en/latest/reference/query-builder.html .. _`Doctrine Query Language`: http://docs.doctrine-project.org/projects/doctrine-orm/en/latest/reference/dql-doctrine-query-language.html .. _`Association Mapping Documentation`: http://docs.doctrine-project.org/projects/doctrine-orm/en/latest/reference/association-mapping.html -.. _`DateTime`: http://php.net/manual/en/class.datetime.php .. _`Mapping Types Documentation`: http://docs.doctrine-project.org/projects/doctrine-orm/en/latest/reference/basic-mapping.html#doctrine-mapping-types -.. _`Property Mapping documentation`: http://docs.doctrine-project.org/projects/doctrine-orm/en/latest/reference/basic-mapping.html#property-mapping +.. _`Property Mapping`: http://docs.doctrine-project.org/projects/doctrine-orm/en/latest/reference/basic-mapping.html#property-mapping .. _`Lifecycle Events documentation`: http://docs.doctrine-project.org/projects/doctrine-orm/en/latest/reference/events.html#lifecycle-events .. _`Reserved SQL keywords documentation`: http://docs.doctrine-project.org/projects/doctrine-orm/en/latest/reference/basic-mapping.html#quoting-reserved-words .. _`Persistent classes`: http://docs.doctrine-project.org/projects/doctrine-orm/en/latest/reference/basic-mapping.html#persistent-classes -.. _`Property Mapping`: http://docs.doctrine-project.org/projects/doctrine-orm/en/latest/reference/basic-mapping.html#property-mapping diff --git a/components/console/introduction.rst b/components/console/introduction.rst index 961b83d33be..0bd13d47098 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 ` 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/doctrine/console.rst b/cookbook/doctrine/console.rst new file mode 100644 index 00000000000..b48cd3e3f3c --- /dev/null +++ b/cookbook/doctrine/console.rst @@ -0,0 +1,60 @@ +.. index:: + single: Doctrine; ORM console commands + single: CLI; Doctrine ORM + +Console Commands +---------------- + +The Doctrine2 ORM integration offers several console commands under the +``doctrine`` namespace. To view the command list you can run the console +without any arguments: + +.. code-block:: bash + + $ php app/console + +A list of available commands will print out, many of which start with the +``doctrine:`` prefix. You can find out more information about any of these +commands (or any Symfony command) by running the ``help`` command. For example, +to get details about the ``doctrine:database:create`` task, run: + +.. code-block:: bash + + $ php app/console help doctrine:database:create + +Some notable or interesting tasks include: + +* ``doctrine:ensure-production-settings`` - checks to see if the current + environment is configured efficiently for production. This should always + be run in the ``prod`` environment: + + .. code-block:: bash + + $ php app/console doctrine:ensure-production-settings --env=prod + +* ``doctrine:mapping:import`` - allows Doctrine to introspect an existing + database and create mapping information. For more information, see + :doc:`/cookbook/doctrine/reverse_engineering`. + +* ``doctrine:mapping:info`` - tells you all of the entities that Doctrine + is aware of and whether or not there are any basic errors with the mapping. + +* ``doctrine:query:dql`` and ``doctrine:query:sql`` - allow you to execute + DQL or SQL queries directly from the command line. + +.. note:: + + To be able to load data fixtures to your database, you will need to have + the DoctrineFixturesBundle bundle installed. To learn how to do it, + read the ":doc:`/bundles/DoctrineFixturesBundle/index`" entry of the + documentation. + +.. tip:: + + This page shows working with Doctrine within a controller. You may also + want to work with Doctrine elsewhere in your application. The + :method:`Symfony\\Bundle\\FrameworkBundle\\Controller\\Controller::getDoctrine` + method of the controller returns the ``doctrine`` service, you can work with + this in the same way elsewhere by injecting this into your own + services. See :doc:`/book/service_container` for more on creating + your own services. diff --git a/cookbook/doctrine/index.rst b/cookbook/doctrine/index.rst index 7f19ef7d4fe..a62c736db11 100644 --- a/cookbook/doctrine/index.rst +++ b/cookbook/doctrine/index.rst @@ -14,3 +14,4 @@ Doctrine resolve_target_entity mapping_model_classes registration_form + console 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/map.rst.inc b/cookbook/map.rst.inc index b2777f42f5e..60ec9546e85 100644 --- a/cookbook/map.rst.inc +++ b/cookbook/map.rst.inc @@ -62,6 +62,7 @@ * :doc:`/cookbook/doctrine/resolve_target_entity` * :doc:`/cookbook/doctrine/mapping_model_classes` * :doc:`/cookbook/doctrine/registration_form` + * :doc:`/cookbook/doctrine/console` * :doc:`/cookbook/email/index` diff --git a/cookbook/security/custom_authentication_provider.rst b/cookbook/security/custom_authentication_provider.rst index 7bdf7f5e213..ba3a6638215 100644 --- a/cookbook/security/custom_authentication_provider.rst +++ b/cookbook/security/custom_authentication_provider.rst @@ -182,6 +182,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/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 b6c014784b5..9c72ed2fe98 100644 --- a/reference/forms/types/collection.rst +++ b/reference/forms/types/collection.rst @@ -21,8 +21,8 @@ forms, which is useful when creating forms that expose one-to-many relationships | | - `prototype_name`_ | +-------------+-----------------------------------------------------------------------------+ | 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 19abd57d0ae..863ef0bb609 100644 --- a/reference/forms/types/file.rst +++ b/reference/forms/types/file.rst @@ -9,8 +9,9 @@ The ``file`` type represents a file input in your form. +-------------+---------------------------------------------------------------------+ | Rendered as | ``input`` ``file`` field | +-------------+---------------------------------------------------------------------+ -| Inherited | - `required`_ | -| options | - `label`_ | +| Inherited | - `empty_data`_ | +| options | - `required`_ | +| | - `label`_ | | | - `label_attr`_ | | | - `read_only`_ | | | - `disabled`_ | @@ -82,6 +83,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 cda5cb276ca..a92ae6697df 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`_ | @@ -69,6 +70,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 1becc320c7f..8152a65c913 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`_ | @@ -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/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