From b881bea6515c6e880849d0e7ebb9ec7668c96428 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Mon, 8 Jun 2015 17:41:36 +0200 Subject: [PATCH 01/17] Remove the Propel book chapter and explain why we do that --- book/propel.rst | 539 ++---------------------------------------------- 1 file changed, 13 insertions(+), 526 deletions(-) diff --git a/book/propel.rst b/book/propel.rst index 53b953dd75d..c8d1e196955 100644 --- a/book/propel.rst +++ b/book/propel.rst @@ -4,529 +4,16 @@ Databases and Propel ==================== -One of the most common and challenging tasks for any application -involves persisting and reading information to and from a database. Symfony -does not come integrated with any ORMs but the Propel integration is easy. -To install Propel, read `Working With Symfony2`_ on the Propel documentation. - -A Simple Example: A Product ---------------------------- - -In this section, you'll configure your database, create a ``Product`` object, -persist it to the database and fetch it back out. - -Configuring the Database -~~~~~~~~~~~~~~~~~~~~~~~~ - -Before you can start, you'll need to configure your database connection -information. By convention, this information is usually configured in an -``app/config/parameters.yml`` file: - -.. code-block:: yaml - - # app/config/parameters.yml - parameters: - database_driver: mysql - database_host: localhost - database_name: test_project - database_user: root - database_password: password - database_charset: UTF8 - -These parameters defined in ``parameters.yml`` can now be included in the -configuration file (``config.yml``): - -.. code-block:: yaml - - propel: - dbal: - driver: "%database_driver%" - user: "%database_user%" - password: "%database_password%" - dsn: "%database_driver%:host=%database_host%;dbname=%database_name%;charset=%database_charset%" - -.. note:: - - Defining the configuration via ``parameters.yml`` is a - :ref:`Symfony Framework Best Practice `, - feel free to do it differently if that suits your application better. - -Now that Propel knows about your database, it can create the database for -you: - -.. code-block:: bash - - $ php app/console propel:database:create - -.. note:: - - In this example, you have one configured connection, named ``default``. If - you want to configure more than one connection, read the - `PropelBundle configuration section`_. - -Creating a Model Class -~~~~~~~~~~~~~~~~~~~~~~ - -In the Propel world, ActiveRecord classes are known as **models** because classes -generated by Propel contain some business logic. - -.. note:: - - For people who use Symfony with Doctrine2, **models** are equivalent to - **entities**. - -Suppose you're building an application where products need to be displayed. -First, create a ``schema.xml`` file inside the ``Resources/config`` directory -of your AppBundle: - -.. code-block:: xml - - - - - - - - - - - - -
- - -Building the Model -~~~~~~~~~~~~~~~~~~ - -After creating your ``schema.xml``, generate your model from it by running: - -.. code-block:: bash - - $ php app/console propel:model:build - -This generates each model class to quickly develop your application in the -``Model/`` directory of the AppBundle bundle. - -Creating the Database Tables/Schema -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Now you have a usable ``Product`` class and all you need to persist it. Of -course, you don't yet have the corresponding ``product`` table in your -database. Fortunately, Propel can automatically create all the database tables -needed for every known model in your application. To do this, run: - -.. code-block:: bash - - $ php app/console propel:sql:build - $ php app/console propel:sql:insert --force - -Your database now has a fully-functional ``product`` table with columns that -match the schema you've specified. - -.. tip:: - - You can run the last three commands combined by using the following - command: - - .. code-block:: bash - - $ php app/console propel:build --insert-sql - -Persisting Objects to the Database -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Now that you have a ``Product`` object and corresponding ``product`` table, -you're ready to persist data to the database. From inside a controller, this -is pretty easy. Add the following method to the ``ProductController`` of the -bundle:: - - // src/AppBundle/Controller/ProductController.php - - // ... - use AppBundle\Model\Product; - use Symfony\Component\HttpFoundation\Response; - - class ProductController extends Controller - { - public function createAction() - { - $product = new Product(); - $product->setName('A Foo Bar'); - $product->setPrice(19.99); - $product->setDescription('Lorem ipsum dolor'); - - $product->save(); - - return new Response('Created product id '.$product->getId()); - } - } - -In this piece of code, you instantiate and work with the ``$product`` object. -When you call the ``save()`` method on it, you persist it to the database. No -need to use other services, the object knows how to persist itself. - -.. note:: - - If you're following along with this example, you'll need to create a - :doc:`route ` that points to this action to see it in action. - -Fetching Objects from the Database -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Fetching an object back from the database is even easier. For example, suppose -you've configured a route to display a specific ``Product`` based on its ``id`` -value:: - - // src/AppBundle/Controller/ProductController.php - - // ... - use AppBundle\Model\ProductQuery; - - class ProductController extends Controller - { - // ... - - public function showAction($id) - { - $product = ProductQuery::create()->findPk($id); - - if (!$product) { - throw $this->createNotFoundException( - 'No product found for id '.$id - ); - } - - // ... do something, like pass the $product object into a template - } - } - -Updating an Object -~~~~~~~~~~~~~~~~~~ - -Once you've fetched an object from Propel, updating it is easy. Suppose you -have a route that maps a product id to an update action in a controller:: - - // src/AppBundle/Controller/ProductController.php - - // ... - use AppBundle\Model\ProductQuery; - - class ProductController extends Controller - { - // ... - - public function updateAction($id) - { - $product = ProductQuery::create()->findPk($id); - - if (!$product) { - throw $this->createNotFoundException( - 'No product found for id '.$id - ); - } - - $product->setName('New product name!'); - $product->save(); - - return $this->redirect($this->generateUrl('homepage')); - } - } - -Updating an object involves just three steps: - -#. fetching the object from Propel (line 12 - 18); -#. modifying the object (line 20); -#. saving it (line 21). - -Deleting an Object -~~~~~~~~~~~~~~~~~~ - -Deleting an object is very similar to updating, but requires a call to the -``delete()`` method on the object:: - - $product->delete(); - -Querying for Objects --------------------- - -Propel provides generated ``Query`` classes to run both basic and complex queries -without any work:: - - use AppBundle\Model\ProductQuery; - // ... - - ProductQuery::create()->findPk($id); - - ProductQuery::create() - ->filterByName('Foo') - ->findOne(); - -Imagine that you want to query for products which cost more than 19.99, ordered -from cheapest to most expensive. From inside a controller, do the following:: - - use AppBundle\Model\ProductQuery; - // ... - - $products = ProductQuery::create() - ->filterByPrice(array('min' => 19.99)) - ->orderByPrice() - ->find(); - -In one line, you get your products in a powerful object-oriented way. No need -to waste your time with SQL or whatever, Symfony offers fully object-oriented -programming and Propel respects the same philosophy by providing an awesome -abstraction layer. - -If you want to reuse some queries, you can add your own methods to the -``ProductQuery`` class:: - - // src/AppBundle/Model/ProductQuery.php - - // ... - class ProductQuery extends BaseProductQuery - { - public function filterByExpensivePrice() - { - return $this->filterByPrice(array( - 'min' => 1000, - )); - } - } - -However, note that Propel generates a lot of methods for you and a simple -``findAllOrderedByName()`` can be written without any effort:: - - use AppBundle\Model\ProductQuery; - // ... - - ProductQuery::create() - ->orderByName() - ->find(); - -Relationships/Associations --------------------------- - -Suppose that the products in your application all belong to exactly one -"category". In this case, you'll need a ``Category`` object and a way to relate -a ``Product`` object to a ``Category`` object. - -Start by adding the ``category`` definition in your ``schema.xml``: - -.. code-block:: xml - - - - - - - - - - - - - - - - - - -
- - - - - -
- - -Create the classes: - -.. code-block:: bash - - $ php app/console propel:model:build - -Assuming you have products in your database, you don't want to lose them. Thanks to -migrations, Propel will be able to update your database without losing existing -data. - -.. code-block:: bash - - $ php app/console propel:migration:generate-diff - $ php app/console propel:migration:migrate - -Your database has been updated, you can continue writing your application. - -Saving Related Objects -~~~~~~~~~~~~~~~~~~~~~~ - -Now, try the code in action. Imagine you're inside a controller:: - - // src/AppBundle/Controller/ProductController.php - - // ... - use AppBundle\Model\Category; - use AppBundle\Model\Product; - use Symfony\Component\HttpFoundation\Response; - - class ProductController extends Controller - { - public function createProductAction() - { - $category = new Category(); - $category->setName('Main Products'); - - $product = new Product(); - $product->setName('Foo'); - $product->setPrice(19.99); - // relate this product to the category - $product->setCategory($category); - - // save the whole - $product->save(); - - return new Response( - 'Created product id: '.$product->getId().' and category id: '.$category->getId() - ); - } - } - -Now, a single row is added to both the ``category`` and ``product`` tables. The -``product.category_id`` column for the new product is set to whatever the id is -of the new category. Propel manages the persistence of this relationship for -you. - -Fetching Related Objects -~~~~~~~~~~~~~~~~~~~~~~~~ - -When you need to fetch associated objects, your workflow looks just like it did -before: Fetch a ``$product`` object and then access its related ``Category``:: - - // src/AppBundle/Controller/ProductController.php - - // ... - use AppBundle\Model\ProductQuery; - - class ProductController extends Controller - { - public function showAction($id) - { - $product = ProductQuery::create() - ->joinWithCategory() - ->findPk($id); - - $categoryName = $product->getCategory()->getName(); - - // ... - } - } - -Note, in the above example, only one query was made. - -More Information on Associations -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -You will find more information on relations by reading the dedicated chapter on -`Relationships`_. - -Lifecycle Callbacks -------------------- - -Sometimes, you need to perform an action right before or after an object is -inserted, updated, or deleted. These types of actions are known as "lifecycle" -callbacks or "hooks", as they're callback methods that you need to execute -during different stages of the lifecycle of an object (e.g. the object is -inserted, updated, deleted, etc). - -To add a hook, just add a new method to the object class:: - - // src/AppBundle/Model/Product.php - - // ... - class Product extends BaseProduct - { - public function preInsert(\PropelPDO $con = null) - { - // ... do something before the object is inserted - } - } - -Propel provides the following hooks: - -``preInsert()`` - Code executed before insertion of a new object. -``postInsert()`` - Code executed after insertion of a new object. -``preUpdate()`` - Code executed before update of an existing object. -``postUpdate()`` - Code executed after update of an existing object. -``preSave()`` - Code executed before saving an object (new or existing). -``postSave()`` - Code executed after saving an object (new or existing). -``preDelete()`` - Code executed before deleting an object. -``postDelete()`` - Code executed after deleting an object. - -Behaviors ---------- - -All bundled behaviors in Propel are working with Symfony. To get more -information about how to use Propel behaviors, look at the -`Behaviors reference section`_. - -Commands --------- - -You should read the dedicated section for `Propel commands in Symfony2`_. - -.. _`Working With Symfony2`: http://propelorm.org/Propel/cookbook/symfony2/working-with-symfony2.html#installation -.. _`PropelBundle configuration section`: http://propelorm.org/Propel/cookbook/symfony2/working-with-symfony2.html#configuration -.. _`Relationships`: http://propelorm.org/Propel/documentation/04-relationships.html -.. _`Behaviors reference section`: http://propelorm.org/Propel/documentation/#behaviors-reference -.. _`Propel commands in Symfony2`: http://propelorm.org/Propel/cookbook/symfony2/working-with-symfony2#the-commands +Propel is an open-source Object-Relational Mapping (ORM) for PHP5 which +implements the `ActiveRecord pattern`_. It allows you to access your database +using a set of objects, providing a simple API for storing and retrieving data. +Propel uses PDO as an abstraction layer, and code generation to remove the +burden of runtime introspection. + +A few years ago, Propel was a very popular alternative to Doctrine. However, its +popularity has rapidly declined and that's why the Symfony book no longer includes +the Propel documentation. Read the `official PropelBundle documentation`_ to learn +how to integrate Propel into your Symfony projects. + +.. _`ActiveRecord pattern`: https://en.wikipedia.org/wiki/Active_record_pattern +.. _`official PropelBundle documentation`: https://github.com/propelorm/PropelBundle/blob/1.4/Resources/doc/index.markdown From 3487157078e921ca69ae5fa233d496512c0ecdd5 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Wed, 10 Jun 2015 08:27:08 +0200 Subject: [PATCH 02/17] Fixed issues reported by @xabbuh --- book/propel.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/book/propel.rst b/book/propel.rst index c8d1e196955..410656289cf 100644 --- a/book/propel.rst +++ b/book/propel.rst @@ -4,10 +4,10 @@ Databases and Propel ==================== -Propel is an open-source Object-Relational Mapping (ORM) for PHP5 which +Propel is an open-source Object-Relational Mapping (ORM) for PHP which implements the `ActiveRecord pattern`_. It allows you to access your database using a set of objects, providing a simple API for storing and retrieving data. -Propel uses PDO as an abstraction layer, and code generation to remove the +Propel uses PDO as an abstraction layer and code generation to remove the burden of runtime introspection. A few years ago, Propel was a very popular alternative to Doctrine. However, its From d452137e9c880c7fc06effca47730e4ba9932cb0 Mon Sep 17 00:00:00 2001 From: Tony Cosentino Date: Wed, 24 Sep 2014 21:44:45 +0200 Subject: [PATCH 03/17] Added support for standard Forwarded header Refs https://github.com/symfony/symfony/pull/11379 --- .../request/load_balancer_reverse_proxy.rst | 24 ++++++++++++------- 1 file changed, 16 insertions(+), 8 deletions(-) diff --git a/cookbook/request/load_balancer_reverse_proxy.rst b/cookbook/request/load_balancer_reverse_proxy.rst index e23e0ac01c2..88979f87477 100644 --- a/cookbook/request/load_balancer_reverse_proxy.rst +++ b/cookbook/request/load_balancer_reverse_proxy.rst @@ -7,9 +7,14 @@ an AWS Elastic Load Balancer) or a reverse proxy (e.g. Varnish for For the most part, this doesn't cause any problems with Symfony. But, when a request passes through a proxy, certain request information is sent using -special ``X-Forwarded-*`` headers. For example, instead of reading the ``REMOTE_ADDR`` -header (which will now be the IP address of your reverse proxy), the user's -true IP will be stored in an ``X-Forwarded-For`` header. +either the standard ``Forwarded`` header or non standard special ``X-Forwarded-*`` +headers. For example, instead of reading the ``REMOTE_ADDR`` header (which +will now be the IP address of your reverse proxy), the user's true IP will be +stored in a standard ``Forwarded: for="..."`` header or a non standard +``X-Forwarded-For`` header. + +.. versionadded:: 2.7 + ``Forwarded`` header support was introduced in Symfony 2.7 If you don't configure Symfony to look for these headers, you'll get incorrect information about the client's IP address, whether or not the client is connecting @@ -57,9 +62,9 @@ the IP address ``192.0.0.1`` or matches the range of IP addresses that use the CIDR notation ``10.0.0.0/8``. For more details, see the :ref:`framework.trusted_proxies ` option. -That's it! Symfony will now look for the correct ``X-Forwarded-*`` headers -to get information like the client's IP address, host, port and whether or -not the request is using HTTPS. +That's it! Symfony will now look for the correct headers to get information +like the client's IP address, host, port and whether the request is +using HTTPS. But what if the IP of my Reverse Proxy Changes Constantly! ---------------------------------------------------------- @@ -90,9 +95,12 @@ other information. My Reverse Proxy Uses Non-Standard (not X-Forwarded) Headers ------------------------------------------------------------ -Most reverse proxies store information on specific ``X-Forwarded-*`` headers. -But if your reverse proxy uses non-standard header names, you can configure +Although `rfc7239`_ recently defined a standard ``Forwarded`` header to disclose +all proxy information, most reverse proxies store information on non standard +``X-Forwarded-*`` headers. +But if your reverse proxy uses other non-standard header names, you can configure these (see ":doc:`/components/http_foundation/trusting_proxies`"). The code for doing this will need to live in your front controller (e.g. ``web/app.php``). .. _`security groups`: http://docs.aws.amazon.com/ElasticLoadBalancing/latest/DeveloperGuide/using-elb-security-groups.html +.. _`rfc7239`: http://tools.ietf.org/html/rfc7239 From ac3689b0ecd7f120bdf1cd0f0904a67ddfcf0461 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Thu, 11 Jun 2015 13:02:01 +0200 Subject: [PATCH 04/17] Added support for standard Forwarded header --- cookbook/request/load_balancer_reverse_proxy.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/cookbook/request/load_balancer_reverse_proxy.rst b/cookbook/request/load_balancer_reverse_proxy.rst index 88979f87477..0ade3346af9 100644 --- a/cookbook/request/load_balancer_reverse_proxy.rst +++ b/cookbook/request/load_balancer_reverse_proxy.rst @@ -7,7 +7,7 @@ an AWS Elastic Load Balancer) or a reverse proxy (e.g. Varnish for For the most part, this doesn't cause any problems with Symfony. But, when a request passes through a proxy, certain request information is sent using -either the standard ``Forwarded`` header or non standard special ``X-Forwarded-*`` +either the standard ``Forwarded`` header or non-standard special ``X-Forwarded-*`` headers. For example, instead of reading the ``REMOTE_ADDR`` header (which will now be the IP address of your reverse proxy), the user's true IP will be stored in a standard ``Forwarded: for="..."`` header or a non standard @@ -95,12 +95,12 @@ other information. My Reverse Proxy Uses Non-Standard (not X-Forwarded) Headers ------------------------------------------------------------ -Although `rfc7239`_ recently defined a standard ``Forwarded`` header to disclose -all proxy information, most reverse proxies store information on non standard +Although `RFC 7239`_ recently defined a standard ``Forwarded`` header to disclose +all proxy information, most reverse proxies store information on non-standard ``X-Forwarded-*`` headers. But if your reverse proxy uses other non-standard header names, you can configure these (see ":doc:`/components/http_foundation/trusting_proxies`"). The code for doing this will need to live in your front controller (e.g. ``web/app.php``). .. _`security groups`: http://docs.aws.amazon.com/ElasticLoadBalancing/latest/DeveloperGuide/using-elb-security-groups.html -.. _`rfc7239`: http://tools.ietf.org/html/rfc7239 +.. _`RFC 7239`: http://tools.ietf.org/html/rfc7239 From 319c081974198c055c1e352117484a8d78e0a50b Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Tue, 16 Jun 2015 15:58:08 +0200 Subject: [PATCH 05/17] Fixed a minor grammar issue --- cookbook/request/load_balancer_reverse_proxy.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/cookbook/request/load_balancer_reverse_proxy.rst b/cookbook/request/load_balancer_reverse_proxy.rst index 0ade3346af9..aa1104a7644 100644 --- a/cookbook/request/load_balancer_reverse_proxy.rst +++ b/cookbook/request/load_balancer_reverse_proxy.rst @@ -96,10 +96,12 @@ My Reverse Proxy Uses Non-Standard (not X-Forwarded) Headers ------------------------------------------------------------ Although `RFC 7239`_ recently defined a standard ``Forwarded`` header to disclose -all proxy information, most reverse proxies store information on non-standard +all proxy information, most reverse proxies store information in non-standard ``X-Forwarded-*`` headers. + But if your reverse proxy uses other non-standard header names, you can configure these (see ":doc:`/components/http_foundation/trusting_proxies`"). + The code for doing this will need to live in your front controller (e.g. ``web/app.php``). .. _`security groups`: http://docs.aws.amazon.com/ElasticLoadBalancing/latest/DeveloperGuide/using-elb-security-groups.html From 8928049d4d23e7ef68fa9bdc02706cb67efeeb84 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Tue, 16 Jun 2015 22:24:24 +0200 Subject: [PATCH 06/17] Fixed a minor grammar issue --- cookbook/request/load_balancer_reverse_proxy.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/cookbook/request/load_balancer_reverse_proxy.rst b/cookbook/request/load_balancer_reverse_proxy.rst index aa1104a7644..f0c864d2a59 100644 --- a/cookbook/request/load_balancer_reverse_proxy.rst +++ b/cookbook/request/load_balancer_reverse_proxy.rst @@ -14,7 +14,7 @@ stored in a standard ``Forwarded: for="..."`` header or a non standard ``X-Forwarded-For`` header. .. versionadded:: 2.7 - ``Forwarded`` header support was introduced in Symfony 2.7 + ``Forwarded`` header support was introduced in Symfony 2.7. If you don't configure Symfony to look for these headers, you'll get incorrect information about the client's IP address, whether or not the client is connecting From ce6b808ef4d33740fe8f38cf571569f93d5113d8 Mon Sep 17 00:00:00 2001 From: WouterJ Date: Mon, 15 Jun 2015 09:03:01 +0200 Subject: [PATCH 07/17] Added some more docs about the remember me feature --- cookbook/security/remember_me.rst | 42 ++++++++++++++++++++++++------- 1 file changed, 33 insertions(+), 9 deletions(-) diff --git a/cookbook/security/remember_me.rst b/cookbook/security/remember_me.rst index 8fde1e9083b..1855a58e737 100644 --- a/cookbook/security/remember_me.rst +++ b/cookbook/security/remember_me.rst @@ -16,17 +16,27 @@ the session lasts using a cookie with the ``remember_me`` firewall option: # app/config/security.yml firewalls: - main: + default: + # ... remember_me: key: "%secret%" lifetime: 604800 # 1 week in seconds path: / + # by default, the feature is enabled by checking a + # checkbox in the login form (see below), uncomment the + # below lines to always enable it. + #always_remember_me: true .. code-block:: xml - + + + + @@ -40,11 +50,16 @@ the session lasts using a cookie with the ``remember_me`` firewall option: // app/config/security.php $container->loadFromExtension('security', array( 'firewalls' => array( - 'main' => array( + 'default' => array( + // ... 'remember_me' => array( 'key' => '%secret%', 'lifetime' => 604800, // 1 week in seconds 'path' => '/', + // by default, the feature is enabled by checking a + // checkbox in the login form (see below), uncomment + // the below lines to always enable it. + //'always_remember_me' => true, ), ), ), @@ -94,21 +109,30 @@ The ``remember_me`` firewall defines the following configuration options: "Remember Me" feature is always enabled, regardless of the desire of the end user. +``token_provider`` (default value: ``null``) + Defines the service id of a token provider to use. By default, tokens are + stored in a cookie. For example, you might want to store the token in a + database, to not have a (hashed) version of the password in a cookie. The + DoctrineBridge comes with a + ``Symfony\Bridge\Doctrine\Security\RememberMe\DoctrineTokenProvider`` that + you can use. + Forcing the User to Opt-Out of the Remember Me Feature ------------------------------------------------------ It's a good idea to provide the user with the option to use or not use the remember me functionality, as it will not always be appropriate. The usual way of doing this is to add a checkbox to the login form. By giving the checkbox -the name ``_remember_me``, the cookie will automatically be set when the checkbox -is checked and the user successfully logs in. So, your specific login form -might ultimately look like this: +the name ``_remember_me`` (or the name you configured using ``remember_me_parameter``), +the cookie will automatically be set when the checkbox is checked and the user +successfully logs in. So, your specific login form might ultimately look like +this: .. configuration-block:: .. code-block:: html+jinja - {# src/Acme/SecurityBundle/Resources/views/Security/login.html.twig #} + {# app/Resources/views/security/login.html.twig #} {% if error %}
{{ error.message }}
{% endif %} @@ -128,7 +152,7 @@ might ultimately look like this: .. code-block:: html+php - +
getMessage() ?>
@@ -150,7 +174,7 @@ might ultimately look like this: The user will then automatically be logged in on subsequent visits while the cookie remains valid. -Forcing the User to Re-authenticate before Accessing certain Resources +Forcing the User to Re-Authenticate before Accessing certain Resources ---------------------------------------------------------------------- When the user returns to your site, they are authenticated automatically based From 2f81cddbe19a216bd995c60f8283d73608b631ac Mon Sep 17 00:00:00 2001 From: Richard van Laak Date: Fri, 5 Jun 2015 14:07:50 +0200 Subject: [PATCH 08/17] Document security.switch_user event ... in the cookbook article about How to Impersonate a User. Added code sample about how to change the locale in case of a sticky locale: http://symfony.com/doc/current/cookbook/session/locale_sticky_session.html --- cookbook/security/impersonating_user.rst | 60 ++++++++++++++++++++++++ 1 file changed, 60 insertions(+) diff --git a/cookbook/security/impersonating_user.rst b/cookbook/security/impersonating_user.rst index 48a1adf498b..dc254f42900 100644 --- a/cookbook/security/impersonating_user.rst +++ b/cookbook/security/impersonating_user.rst @@ -151,3 +151,63 @@ setting: ), ), )); + +Events +------ + +The firewall dispatches the ``security.switch_user`` event right after the impersonation +is completed. The :class:`Symfony\\Component\\Security\\Http\\Event\\SwitchUserEvent` is +passed to the listener, and you can use this to get the user that you are now impersonating. + +The cookbook article about +:doc:`Making the Locale "Sticky" during a User's Session ` +does not update the locale when you impersonate a user. The following code sample will show +how to change the sticky locale: + +.. configuration-block:: + + .. code-block:: yaml + + # app/config/services.yml + services: + app.switch_user_listener: + class: AppBundle\EventListener\SwitchUserListener + tags: + - { name: kernel.event_listener, event: security.switch_user, method: onSwitchUser } + + .. code-block:: xml + + + + + + + .. code-block:: php + + // app/config/services.php + $container + ->register('app.switch_user_listener', 'AppBundle\EventListener\SwitchUserListener') + ->addTag('kernel.event_listener', array('event' => 'security.switch_user', 'method' => 'onSwitchUser')) + ; + +.. caution:: + + The listener implementation assumes your ``User`` entity has a ``getLocale()`` method. + +.. code-block:: php + + // src/AppBundle/EventListener/SwitchUserListener.pnp + namespace AppBundle\EventListener; + + use Symfony\Component\Security\Http\Event\SwitchUserEvent; + + class SwitchUserListener + { + public function onSwitchUser(SwitchUserEvent $event) + { + $event->getRequest()->getSession()->set( + '_locale', + $event->getTargetUser()->getLocale() + ); + } + } From 1fa69fe10df17351160a59c80c73854babad781a Mon Sep 17 00:00:00 2001 From: Bernhard Schussek Date: Mon, 18 Aug 2014 13:40:46 +0200 Subject: [PATCH 09/17] Added information about the new date handling in the comparison constraints and Range Conflicts: reference/constraints/GreaterThan.rst reference/constraints/GreaterThanOrEqual.rst reference/constraints/LessThan.rst reference/constraints/LessThanOrEqual.rst --- reference/constraints/GreaterThan.rst | 217 ++++++++++++++++--- reference/constraints/GreaterThanOrEqual.rst | 217 ++++++++++++++++--- reference/constraints/LessThan.rst | 202 +++++++++++++++-- reference/constraints/LessThanOrEqual.rst | 210 +++++++++++++++--- reference/constraints/Range.rst | 198 +++++++++++++++++ 5 files changed, 934 insertions(+), 110 deletions(-) diff --git a/reference/constraints/GreaterThan.rst b/reference/constraints/GreaterThan.rst index b1066c6b1f4..a8638acf025 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`. @@ -14,7 +14,6 @@ than another value, see :doc:`/reference/constraints/LessThan`. +----------------+---------------------------------------------------------------------------+ | Options | - `value`_ | | | - `message`_ | -| | - `payload`_ | +----------------+---------------------------------------------------------------------------+ | Class | :class:`Symfony\\Component\\Validator\\Constraints\\GreaterThan` | +----------------+---------------------------------------------------------------------------+ @@ -24,11 +23,20 @@ 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:: + .. code-block:: yaml + + # src/SocialBundle/Resources/config/validation.yml + Acme\SocialBundle\Entity\Person: + properties: + age: + - GreaterThan: + value: 18 + .. code-block:: php-annotations // src/Acme/SocialBundle/Entity/Person.php @@ -46,31 +54,16 @@ than ``18``, you could do the following: protected $age; } - .. code-block:: yaml - - # src/Acme/SocialBundle/Resources/config/validation.yml - Acme\SocialBundle\Entity\Person: - properties: - age: - - GreaterThan: - value: 18 - .. code-block:: xml - - - - - - - - - - - + + + + + + + .. code-block:: php @@ -90,6 +83,170 @@ than ``18``, you could do the following: } } +Comparing Dates +--------------- + +This constraint can be used to compare ``DateTime`` objects against any date +string `accepted by the DateTime constructor`_. For example, you could check +that a date must at least be the next day: + +.. configuration-block:: + + .. code-block:: yaml + + # src/OrderBundle/Resources/config/validation.yml + Acme\OrderBundle\Entity\Order: + properties: + deliveryDate: + - GreaterThan: today + + .. code-block:: php-annotations + + // src/Acme/SocialBundle/Entity/Order.php + namespace Acme\OrderBundle\Entity; + + use Symfony\Component\Validator\Constraints as Assert; + + class Order + { + /** + * @Assert\GreaterThan("today") + */ + protected $deliveryDate; + } + + .. code-block:: xml + + + + + today + + + + .. code-block:: php + + // src/Acme/OrderBundle/Entity/Order.php + namespace Acme\OrderBundle\Entity; + + use Symfony\Component\Validator\Mapping\ClassMetadata; + use Symfony\Component\Validator\Constraints as Assert; + + class Order + { + public static function loadValidatorMetadata(ClassMetadata $metadata) + { + $metadata->addPropertyConstraint('deliveryDate', new Assert\GreaterThan('today')); + } + } + +Be aware that PHP will use the server's configured timezone to interpret these +dates. If you want to fix the timezone, append it to the date string: + +.. configuration-block:: + + .. code-block:: yaml + + # src/OrderBundle/Resources/config/validation.yml + Acme\OrderBundle\Entity\Order: + properties: + deliveryDate: + - GreaterThan: today UTC + + .. code-block:: php-annotations + + // src/Acme/SocialBundle/Entity/Order.php + namespace Acme\OrderBundle\Entity; + + use Symfony\Component\Validator\Constraints as Assert; + + class Order + { + /** + * @Assert\GreaterThan("today UTC") + */ + protected $deliveryDate; + } + + .. code-block:: xml + + + + + today UTC + + + + .. code-block:: php + + // src/Acme/OrderBundle/Entity/Order.php + namespace Acme\OrderBundle\Entity; + + use Symfony\Component\Validator\Mapping\ClassMetadata; + use Symfony\Component\Validator\Constraints as Assert; + + class Order + { + public static function loadValidatorMetadata(ClassMetadata $metadata) + { + $metadata->addPropertyConstraint('deliveryDate', new Assert\GreaterThan('today UTC')); + } + } + +The ``DateTime`` class also accepts relative dates or times. For example, you +can check that the above delivery date starts at least five hours after the +current time: + +.. configuration-block:: + + .. code-block:: yaml + + # src/OrderBundle/Resources/config/validation.yml + Acme\OrderBundle\Entity\Order: + properties: + deliveryDate: + - GreaterThan: +5 hours + + .. code-block:: php-annotations + + // src/Acme/SocialBundle/Entity/Order.php + namespace Acme\OrderBundle\Entity; + + use Symfony\Component\Validator\Constraints as Assert; + + class Order + { + /** + * @Assert\GreaterThan("+5 hours") + */ + protected $deliveryDate; + } + + .. code-block:: xml + + + + + +5 hours + + + + .. code-block:: php + + // src/Acme/OrderBundle/Entity/Order.php + namespace Acme\OrderBundle\Entity; + + use Symfony\Component\Validator\Mapping\ClassMetadata; + use Symfony\Component\Validator\Constraints as Assert; + + class Order + { + public static function loadValidatorMetadata(ClassMetadata $metadata) + { + $metadata->addPropertyConstraint('deliveryDate', new Assert\GreaterThan('+5 hours')); + } + } + Options ------- @@ -100,7 +257,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 +.. _`accepted by the DateTime constructor`: http://www.php.net/manual/en/datetime.formats.php diff --git a/reference/constraints/GreaterThanOrEqual.rst b/reference/constraints/GreaterThanOrEqual.rst index cc868390490..bdc6f9e36cf 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`. +----------------+----------------------------------------------------------------------------------+ @@ -13,7 +13,6 @@ in the options. To force that a value is greater than another value, see +----------------+----------------------------------------------------------------------------------+ | Options | - `value`_ | | | - `message`_ | -| | - `payload`_ | +----------------+----------------------------------------------------------------------------------+ | Class | :class:`Symfony\\Component\\Validator\\Constraints\\GreaterThanOrEqual` | +----------------+----------------------------------------------------------------------------------+ @@ -23,11 +22,20 @@ in 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:: + .. code-block:: yaml + + # src/SocialBundle/Resources/config/validation.yml + Acme\SocialBundle\Entity\Person: + properties: + age: + - GreaterThanOrEqual: + value: 18 + .. code-block:: php-annotations // src/Acme/SocialBundle/Entity/Person.php @@ -45,31 +53,16 @@ than or equal to ``18``, you could do the following: protected $age; } - .. code-block:: yaml - - # src/Acme/SocialBundle/Resources/config/validation.yml - Acme\SocialBundle\Entity\Person: - properties: - age: - - GreaterThanOrEqual: - value: 18 - .. code-block:: xml - - - - - - - - - - - + + + + + + + .. code-block:: php @@ -89,6 +82,170 @@ than or equal to ``18``, you could do the following: } } +Comparing Dates +--------------- + +This constraint can be used to compare ``DateTime`` objects against any date +string `accepted by the DateTime constructor`_. For example, you could check +that a date must at least be the current day: + +.. configuration-block:: + + .. code-block:: yaml + + # src/OrderBundle/Resources/config/validation.yml + Acme\OrderBundle\Entity\Order: + properties: + deliveryDate: + - GreaterThanOrEqual: today + + .. code-block:: php-annotations + + // src/Acme/SocialBundle/Entity/Order.php + namespace Acme\OrderBundle\Entity; + + use Symfony\Component\Validator\Constraints as Assert; + + class Order + { + /** + * @Assert\GreaterThanOrEqual("today") + */ + protected $deliveryDate; + } + + .. code-block:: xml + + + + + today + + + + .. code-block:: php + + // src/Acme/OrderBundle/Entity/Order.php + namespace Acme\OrderBundle\Entity; + + use Symfony\Component\Validator\Mapping\ClassMetadata; + use Symfony\Component\Validator\Constraints as Assert; + + class Order + { + public static function loadValidatorMetadata(ClassMetadata $metadata) + { + $metadata->addPropertyConstraint('deliveryDate', new Assert\GreaterThanOrEqual('today')); + } + } + +Be aware that PHP will use the server's configured timezone to interpret these +dates. If you want to fix the timezone, append it to the date string: + +.. configuration-block:: + + .. code-block:: yaml + + # src/OrderBundle/Resources/config/validation.yml + Acme\OrderBundle\Entity\Order: + properties: + deliveryDate: + - GreaterThanOrEqual: today UTC + + .. code-block:: php-annotations + + // src/Acme/SocialBundle/Entity/Order.php + namespace Acme\OrderBundle\Entity; + + use Symfony\Component\Validator\Constraints as Assert; + + class Order + { + /** + * @Assert\GreaterThanOrEqual("today UTC") + */ + protected $deliveryDate; + } + + .. code-block:: xml + + + + + today UTC + + + + .. code-block:: php + + // src/Acme/OrderBundle/Entity/Order.php + namespace Acme\OrderBundle\Entity; + + use Symfony\Component\Validator\Mapping\ClassMetadata; + use Symfony\Component\Validator\Constraints as Assert; + + class Order + { + public static function loadValidatorMetadata(ClassMetadata $metadata) + { + $metadata->addPropertyConstraint('deliveryDate', new Assert\GreaterThanOrEqual('today UTC')); + } + } + +The ``DateTime`` class also accepts relative dates or times. For example, you +can check that the above delivery date starts at least five hours after the +current time: + +.. configuration-block:: + + .. code-block:: yaml + + # src/OrderBundle/Resources/config/validation.yml + Acme\OrderBundle\Entity\Order: + properties: + deliveryDate: + - GreaterThanOrEqual: +5 hours + + .. code-block:: php-annotations + + // src/Acme/SocialBundle/Entity/Order.php + namespace Acme\OrderBundle\Entity; + + use Symfony\Component\Validator\Constraints as Assert; + + class Order + { + /** + * @Assert\GreaterThanOrEqual("+5 hours") + */ + protected $deliveryDate; + } + + .. code-block:: xml + + + + + +5 hours + + + + .. code-block:: php + + // src/Acme/OrderBundle/Entity/Order.php + namespace Acme\OrderBundle\Entity; + + use Symfony\Component\Validator\Mapping\ClassMetadata; + use Symfony\Component\Validator\Constraints as Assert; + + class Order + { + public static function loadValidatorMetadata(ClassMetadata $metadata) + { + $metadata->addPropertyConstraint('deliveryDate', new Assert\GreaterThanOrEqual('+5 hours')); + } + } + Options ------- @@ -99,7 +256,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 +.. _`accepted by the DateTime constructor`: http://www.php.net/manual/en/datetime.formats.php diff --git a/reference/constraints/LessThan.rst b/reference/constraints/LessThan.rst index d14e289fd0c..09c5f93ef40 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`. @@ -14,7 +14,6 @@ than another value, see :doc:`/reference/constraints/GreaterThan`. +----------------+------------------------------------------------------------------------+ | Options | - `value`_ | | | - `message`_ | -| | - `payload`_ | +----------------+------------------------------------------------------------------------+ | Class | :class:`Symfony\\Component\\Validator\\Constraints\\LessThan` | +----------------+------------------------------------------------------------------------+ @@ -29,6 +28,15 @@ If you want to ensure that the ``age`` of a ``Person`` class is less than .. configuration-block:: + .. code-block:: yaml + + # src/SocialBundle/Resources/config/validation.yml + Acme\SocialBundle\Entity\Person: + properties: + age: + - LessThan: + value: 80 + .. code-block:: php-annotations // src/Acme/SocialBundle/Entity/Person.php @@ -46,31 +54,75 @@ If you want to ensure that the ``age`` of a ``Person`` class is less than protected $age; } + .. code-block:: xml + + + + + + + + + + + .. code-block:: php + + // src/Acme/SocialBundle/Entity/Person.php + namespace Acme\SocialBundle\Entity; + + use Symfony\Component\Validator\Mapping\ClassMetadata; + use Symfony\Component\Validator\Constraints as Assert; + + class Person + { + public static function loadValidatorMetadata(ClassMetadata $metadata) + { + $metadata->addPropertyConstraint('age', new Assert\LessThan(array( + 'value' => 80, + ))); + } + } + +Comparing Dates +--------------- + +This constraint can be used to compare ``DateTime`` objects against any date +string `accepted by the DateTime constructor`_. For example, you could check +that a date must be in the past like this: + +.. configuration-block:: + .. code-block:: yaml - # src/Acme/SocialBundle/Resources/config/validation.yml + # src/SocialBundle/Resources/config/validation.yml Acme\SocialBundle\Entity\Person: properties: age: - - LessThan: - value: 80 + - LessThan: today + + .. code-block:: php-annotations + + // src/Acme/SocialBundle/Entity/Person.php + namespace Acme\SocialBundle\Entity; + + use Symfony\Component\Validator\Constraints as Assert; + + class Person + { + /** + * @Assert\LessThan("today") + */ + protected $age; + } .. code-block:: xml - - - - - - - - - - - + + + today + + .. code-block:: php @@ -84,9 +136,113 @@ If you want to ensure that the ``age`` of a ``Person`` class is less than { public static function loadValidatorMetadata(ClassMetadata $metadata) { - $metadata->addPropertyConstraint('age', new Assert\LessThan(array( - 'value' => 80, - ))); + $metadata->addPropertyConstraint('age', new Assert\LessThan('today')); + } + } + +Be aware that PHP will use the server's configured timezone to interpret these +dates. If you want to fix the timezone, append it to the date string: + +.. configuration-block:: + + .. code-block:: yaml + + # src/SocialBundle/Resources/config/validation.yml + Acme\SocialBundle\Entity\Person: + properties: + age: + - LessThan: today UTC + + .. code-block:: php-annotations + + // src/Acme/SocialBundle/Entity/Person.php + namespace Acme\SocialBundle\Entity; + + use Symfony\Component\Validator\Constraints as Assert; + + class Person + { + /** + * @Assert\LessThan("today UTC") + */ + protected $age; + } + + .. code-block:: xml + + + + + today UTC + + + + .. code-block:: php + + // src/Acme/SocialBundle/Entity/Person.php + namespace Acme\SocialBundle\Entity; + + use Symfony\Component\Validator\Mapping\ClassMetadata; + use Symfony\Component\Validator\Constraints as Assert; + + class Person + { + public static function loadValidatorMetadata(ClassMetadata $metadata) + { + $metadata->addPropertyConstraint('age', new Assert\LessThan('today UTC')); + } + } + +The ``DateTime`` class also accepts relative dates or times. For example, you +can check that a person must be at least 18 years old like this: + +.. configuration-block:: + + .. code-block:: yaml + + # src/SocialBundle/Resources/config/validation.yml + Acme\SocialBundle\Entity\Person: + properties: + age: + - LessThan: -18 years + + .. code-block:: php-annotations + + // src/Acme/SocialBundle/Entity/Person.php + namespace Acme\SocialBundle\Entity; + + use Symfony\Component\Validator\Constraints as Assert; + + class Person + { + /** + * @Assert\LessThan("-18 years") + */ + protected $age; + } + + .. code-block:: xml + + + + + -18 years + + + + .. code-block:: php + + // src/Acme/SocialBundle/Entity/Person.php + namespace Acme\SocialBundle\Entity; + + use Symfony\Component\Validator\Mapping\ClassMetadata; + use Symfony\Component\Validator\Constraints as Assert; + + class Person + { + public static function loadValidatorMetadata(ClassMetadata $metadata) + { + $metadata->addPropertyConstraint('age', new Assert\LessThan('-18 years')); } } @@ -103,4 +259,4 @@ message This is the message that will be shown if the value is not less than the comparison value. -.. include:: /reference/constraints/_payload-option.rst.inc +.. _`accepted by the DateTime constructor`: http://www.php.net/manual/en/datetime.formats.php diff --git a/reference/constraints/LessThanOrEqual.rst b/reference/constraints/LessThanOrEqual.rst index c75266bbc52..61261fbe571 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`. +----------------+-------------------------------------------------------------------------------+ @@ -13,7 +13,6 @@ the options. To force that a value is less than another value, see +----------------+-------------------------------------------------------------------------------+ | Options | - `value`_ | | | - `message`_ | -| | - `payload`_ | +----------------+-------------------------------------------------------------------------------+ | Class | :class:`Symfony\\Component\\Validator\\Constraints\\LessThanOrEqual` | +----------------+-------------------------------------------------------------------------------+ @@ -23,11 +22,20 @@ the 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:: + .. code-block:: yaml + + # src/SocialBundle/Resources/config/validation.yml + Acme\SocialBundle\Entity\Person: + properties: + age: + - LessThanOrEqual: + value: 80 + .. code-block:: php-annotations // src/Acme/SocialBundle/Entity/Person.php @@ -45,31 +53,75 @@ or equal to ``80``, you could do the following: protected $age; } + .. code-block:: xml + + + + + + + + + + + .. code-block:: php + + // src/Acme/SocialBundle/Entity/Person.php + namespace Acme\SocialBundle\Entity; + + use Symfony\Component\Validator\Mapping\ClassMetadata; + use Symfony\Component\Validator\Constraints as Assert; + + class Person + { + public static function loadValidatorMetadata(ClassMetadata $metadata) + { + $metadata->addPropertyConstraint('age', new Assert\LessThanOrEqual(array( + 'value' => 80, + ))); + } + } + +Comparing Dates +--------------- + +This constraint can be used to compare ``DateTime`` objects against any date +string `accepted by the DateTime constructor`_. For example, you could check +that a date must be today or in the past like this: + +.. configuration-block:: + .. code-block:: yaml - # src/Acme/SocialBundle/Resources/config/validation.yml + # src/SocialBundle/Resources/config/validation.yml Acme\SocialBundle\Entity\Person: properties: age: - - LessThanOrEqual: - value: 80 + - LessThanOrEqual: today + + .. code-block:: php-annotations + + // src/Acme/SocialBundle/Entity/Person.php + namespace Acme\SocialBundle\Entity; + + use Symfony\Component\Validator\Constraints as Assert; + + class Person + { + /** + * @Assert\LessThanOrEqual("today") + */ + protected $age; + } .. code-block:: xml - - - - - - - - - - - + + + today + + .. code-block:: php @@ -83,9 +135,113 @@ or equal to ``80``, you could do the following: { public static function loadValidatorMetadata(ClassMetadata $metadata) { - $metadata->addPropertyConstraint('age', new Assert\LessThanOrEqual(array( - 'value' => 80, - ))); + $metadata->addPropertyConstraint('age', new Assert\LessThanOrEqual('today')); + } + } + +Be aware that PHP will use the server's configured timezone to interpret these +dates. If you want to fix the timezone, append it to the date string: + +.. configuration-block:: + + .. code-block:: yaml + + # src/SocialBundle/Resources/config/validation.yml + Acme\SocialBundle\Entity\Person: + properties: + age: + - LessThanOrEqual: today UTC + + .. code-block:: php-annotations + + // src/Acme/SocialBundle/Entity/Person.php + namespace Acme\SocialBundle\Entity; + + use Symfony\Component\Validator\Constraints as Assert; + + class Person + { + /** + * @Assert\LessThanOrEqual("today UTC") + */ + protected $age; + } + + .. code-block:: xml + + + + + today UTC + + + + .. code-block:: php + + // src/Acme/SocialBundle/Entity/Person.php + namespace Acme\SocialBundle\Entity; + + use Symfony\Component\Validator\Mapping\ClassMetadata; + use Symfony\Component\Validator\Constraints as Assert; + + class Person + { + public static function loadValidatorMetadata(ClassMetadata $metadata) + { + $metadata->addPropertyConstraint('age', new Assert\LessThanOrEqual('today UTC')); + } + } + +The ``DateTime`` class also accepts relative dates or times. For example, you +can check that a person must be at least 18 years old like this: + +.. configuration-block:: + + .. code-block:: yaml + + # src/SocialBundle/Resources/config/validation.yml + Acme\SocialBundle\Entity\Person: + properties: + age: + - LessThanOrEqual: -18 years + + .. code-block:: php-annotations + + // src/Acme/SocialBundle/Entity/Person.php + namespace Acme\SocialBundle\Entity; + + use Symfony\Component\Validator\Constraints as Assert; + + class Person + { + /** + * @Assert\LessThanOrEqual("-18 years") + */ + protected $age; + } + + .. code-block:: xml + + + + + -18 years + + + + .. code-block:: php + + // src/Acme/SocialBundle/Entity/Person.php + namespace Acme\SocialBundle\Entity; + + use Symfony\Component\Validator\Mapping\ClassMetadata; + use Symfony\Component\Validator\Constraints as Assert; + + class Person + { + public static function loadValidatorMetadata(ClassMetadata $metadata) + { + $metadata->addPropertyConstraint('age', new Assert\LessThanOrEqual('-18 years')); } } @@ -99,7 +255,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 +.. _`accepted by the DateTime constructor`: http://www.php.net/manual/en/datetime.formats.php diff --git a/reference/constraints/Range.rst b/reference/constraints/Range.rst index b588cc31cca..6009adf7a55 100644 --- a/reference/constraints/Range.rst +++ b/reference/constraints/Range.rst @@ -99,6 +99,203 @@ you might add the following: } } +Date Ranges +----------- + +This constraint can be used to compare ``DateTime`` objects against date ranges. +The minimum and maximum date of the range should be given as any date string +`accepted by the DateTime constructor`_. For example, you could check that a +date must lie within the current year like this: + +.. configuration-block:: + + .. code-block:: yaml + + # src/EventBundle/Resources/config/validation.yml + Acme\EventBundle\Entity\Event: + properties: + startDate: + - Range: + min: first day of January + max: first day of January next year + + .. code-block:: php-annotations + + // src/Acme/SocialBundle/Entity/Event.php + namespace Acme\EventBundle\Entity; + + use Symfony\Component\Validator\Constraints as Assert; + + class Event + { + /** + * @Assert\Range( + * min = "first day of January", + * max = "first day of January next year" + * ) + */ + protected $startDate; + } + + .. code-block:: xml + + + + + + + + + + + + .. code-block:: php + + // src/Acme/EventBundle/Entity/Person.php + namespace Acme\EventBundle\Entity; + + use Symfony\Component\Validator\Mapping\ClassMetadata; + use Symfony\Component\Validator\Constraints as Assert; + + class Event + { + public static function loadValidatorMetadata(ClassMetadata $metadata) + { + $metadata->addPropertyConstraint('startDate', new Assert\Range(array( + 'min' => 'first day of January', + 'max' => 'first day of January next year', + ))); + } + } + +Be aware that PHP will use the server's configured timezone to interpret these +dates. If you want to fix the timezone, append it to the date string: + +.. configuration-block:: + + .. code-block:: yaml + + # src/EventBundle/Resources/config/validation.yml + Acme\EventBundle\Entity\Event: + properties: + startDate: + - Range: + min: first day of January UTC + max: first day of January next year UTC + + .. code-block:: php-annotations + + // src/Acme/SocialBundle/Entity/Event.php + namespace Acme\EventBundle\Entity; + + use Symfony\Component\Validator\Constraints as Assert; + + class Event + { + /** + * @Assert\Range( + * min = "first day of January UTC", + * max = "first day of January next year UTC" + * ) + */ + protected $startDate; + } + + .. code-block:: xml + + + + + + + + + + + + .. code-block:: php + + // src/Acme/EventBundle/Entity/Person.php + namespace Acme\EventBundle\Entity; + + use Symfony\Component\Validator\Mapping\ClassMetadata; + use Symfony\Component\Validator\Constraints as Assert; + + class Event + { + public static function loadValidatorMetadata(ClassMetadata $metadata) + { + $metadata->addPropertyConstraint('startDate', new Assert\Range(array( + 'min' => 'first day of January UTC', + 'max' => 'first day of January next year UTC', + ))); + } + } + +The ``DateTime`` class also accepts relative dates or times. For example, you +can check that a delivery date starts within the next five hours like this: + +.. configuration-block:: + + .. code-block:: yaml + + # src/OrderBundle/Resources/config/validation.yml + Acme\OrderBundle\Entity\Order: + properties: + deliveryDate: + - Range: + min: now + max: +5 hours + + .. code-block:: php-annotations + + // src/Acme/SocialBundle/Entity/Order.php + namespace Acme\OrderBundle\Entity; + + use Symfony\Component\Validator\Constraints as Assert; + + class Order + { + /** + * @Assert\Range( + * min = "now", + * max = "+5 hours" + * ) + */ + protected $deliveryDate; + } + + .. code-block:: xml + + + + + + + + + + + + .. code-block:: php + + // src/Acme/OrderBundle/Entity/Order.php + namespace Acme\OrderBundle\Entity; + + use Symfony\Component\Validator\Mapping\ClassMetadata; + use Symfony\Component\Validator\Constraints as Assert; + + class Order + { + public static function loadValidatorMetadata(ClassMetadata $metadata) + { + $metadata->addPropertyConstraint('deliveryDate', new Assert\Range(array( + 'min' => 'now', + 'max' => '+5 hours', + ))); + } + } + Options ------- @@ -145,3 +342,4 @@ the `is_numeric`_ PHP function). .. include:: /reference/constraints/_payload-option.rst.inc .. _`is_numeric`: http://www.php.net/manual/en/function.is-numeric.php +.. _`accepted by the DateTime constructor`: http://www.php.net/manual/en/datetime.formats.php From 70034452d978b25deb1bf4b0422dff1216d33968 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Thu, 11 Jun 2015 14:56:52 +0200 Subject: [PATCH 10/17] Finished the documentation of the new data comparison validators --- reference/constraints/GreaterThan.rst | 83 ++++++++++++------- reference/constraints/GreaterThanOrEqual.rst | 71 +++++++++++----- reference/constraints/LessThan.rst | 87 +++++++++++++------- reference/constraints/LessThanOrEqual.rst | 71 +++++++++++----- reference/constraints/Range.rst | 68 +++++++++------ 5 files changed, 253 insertions(+), 127 deletions(-) diff --git a/reference/constraints/GreaterThan.rst b/reference/constraints/GreaterThan.rst index a8638acf025..8f7783b1937 100644 --- a/reference/constraints/GreaterThan.rst +++ b/reference/constraints/GreaterThan.rst @@ -57,13 +57,19 @@ If you want to ensure that the ``age`` of a ``Person`` class is greater than .. code-block:: xml - - - - - - - + + + + + + + + + + + .. code-block:: php @@ -86,6 +92,9 @@ If you want to ensure that the ``age`` of a ``Person`` class is greater than Comparing Dates --------------- +.. versionadded:: 2.6 + The feature to compare dates was added in Symfony 2.6. + This constraint can be used to compare ``DateTime`` objects against any date string `accepted by the DateTime constructor`_. For example, you could check that a date must at least be the next day: @@ -94,7 +103,7 @@ that a date must at least be the next day: .. code-block:: yaml - # src/OrderBundle/Resources/config/validation.yml + # src/Acme/OrderBundle/Resources/config/validation.yml Acme\OrderBundle\Entity\Order: properties: deliveryDate: @@ -102,7 +111,7 @@ that a date must at least be the next day: .. code-block:: php-annotations - // src/Acme/SocialBundle/Entity/Order.php + // src/Acme/OrderBundle/Entity/Order.php namespace Acme\OrderBundle\Entity; use Symfony\Component\Validator\Constraints as Assert; @@ -118,11 +127,17 @@ that a date must at least be the next day: .. code-block:: xml - - - today - - + + + + + + today + + + .. code-block:: php @@ -147,7 +162,7 @@ dates. If you want to fix the timezone, append it to the date string: .. code-block:: yaml - # src/OrderBundle/Resources/config/validation.yml + # src/Acme/OrderBundle/Resources/config/validation.yml Acme\OrderBundle\Entity\Order: properties: deliveryDate: @@ -155,7 +170,7 @@ dates. If you want to fix the timezone, append it to the date string: .. code-block:: php-annotations - // src/Acme/SocialBundle/Entity/Order.php + // src/Acme/OrderBundle/Entity/Order.php namespace Acme\OrderBundle\Entity; use Symfony\Component\Validator\Constraints as Assert; @@ -171,11 +186,17 @@ dates. If you want to fix the timezone, append it to the date string: .. code-block:: xml - - - today UTC - - + + + + + + today UTC + + + .. code-block:: php @@ -201,7 +222,7 @@ current time: .. code-block:: yaml - # src/OrderBundle/Resources/config/validation.yml + # src/Acme/OrderBundle/Resources/config/validation.yml Acme\OrderBundle\Entity\Order: properties: deliveryDate: @@ -209,7 +230,7 @@ current time: .. code-block:: php-annotations - // src/Acme/SocialBundle/Entity/Order.php + // src/Acme/OrderBundle/Entity/Order.php namespace Acme\OrderBundle\Entity; use Symfony\Component\Validator\Constraints as Assert; @@ -225,11 +246,17 @@ current time: .. code-block:: xml - - - +5 hours - - + + + + + + +5 hours + + + .. code-block:: php diff --git a/reference/constraints/GreaterThanOrEqual.rst b/reference/constraints/GreaterThanOrEqual.rst index bdc6f9e36cf..e5abbfb239f 100644 --- a/reference/constraints/GreaterThanOrEqual.rst +++ b/reference/constraints/GreaterThanOrEqual.rst @@ -56,13 +56,19 @@ or equal to ``18``, you could do the following: .. code-block:: xml - - - - - - - + + + + + + + + + + + .. code-block:: php @@ -85,6 +91,9 @@ or equal to ``18``, you could do the following: Comparing Dates --------------- +.. versionadded:: 2.6 + The feature to compare dates was added in Symfony 2.6. + This constraint can be used to compare ``DateTime`` objects against any date string `accepted by the DateTime constructor`_. For example, you could check that a date must at least be the current day: @@ -117,11 +126,17 @@ that a date must at least be the current day: .. code-block:: xml - - - today - - + + + + + + today + + + .. code-block:: php @@ -170,11 +185,17 @@ dates. If you want to fix the timezone, append it to the date string: .. code-block:: xml - - - today UTC - - + + + + + + today UTC + + + .. code-block:: php @@ -224,11 +245,17 @@ current time: .. code-block:: xml - - - +5 hours - - + + + + + + +5 hours + + + .. code-block:: php diff --git a/reference/constraints/LessThan.rst b/reference/constraints/LessThan.rst index 09c5f93ef40..f4a2f32af40 100644 --- a/reference/constraints/LessThan.rst +++ b/reference/constraints/LessThan.rst @@ -57,13 +57,19 @@ If you want to ensure that the ``age`` of a ``Person`` class is less than .. code-block:: xml - - - - - - - + + + + + + + + + + + .. code-block:: php @@ -86,6 +92,9 @@ If you want to ensure that the ``age`` of a ``Person`` class is less than Comparing Dates --------------- +.. versionadded:: 2.6 + The feature to compare dates was added in Symfony 2.6. + This constraint can be used to compare ``DateTime`` objects against any date string `accepted by the DateTime constructor`_. For example, you could check that a date must be in the past like this: @@ -97,7 +106,7 @@ that a date must be in the past like this: # src/SocialBundle/Resources/config/validation.yml Acme\SocialBundle\Entity\Person: properties: - age: + dateOfBirth: - LessThan: today .. code-block:: php-annotations @@ -112,17 +121,23 @@ that a date must be in the past like this: /** * @Assert\LessThan("today") */ - protected $age; + protected $dateOfBirth; } .. code-block:: xml - - - today - - + + + + + + today + + + .. code-block:: php @@ -136,7 +151,7 @@ that a date must be in the past like this: { public static function loadValidatorMetadata(ClassMetadata $metadata) { - $metadata->addPropertyConstraint('age', new Assert\LessThan('today')); + $metadata->addPropertyConstraint('dateOfBirth', new Assert\LessThan('today')); } } @@ -150,7 +165,7 @@ dates. If you want to fix the timezone, append it to the date string: # src/SocialBundle/Resources/config/validation.yml Acme\SocialBundle\Entity\Person: properties: - age: + dateOfBirth: - LessThan: today UTC .. code-block:: php-annotations @@ -165,17 +180,23 @@ dates. If you want to fix the timezone, append it to the date string: /** * @Assert\LessThan("today UTC") */ - protected $age; + protected $dateOfBirth; } .. code-block:: xml - - - today UTC - - + + + + + + today UTC + + + .. code-block:: php @@ -203,7 +224,7 @@ can check that a person must be at least 18 years old like this: # src/SocialBundle/Resources/config/validation.yml Acme\SocialBundle\Entity\Person: properties: - age: + dateOfBirth: - LessThan: -18 years .. code-block:: php-annotations @@ -218,17 +239,23 @@ can check that a person must be at least 18 years old like this: /** * @Assert\LessThan("-18 years") */ - protected $age; + protected $dateOfBirth; } .. code-block:: xml - - - -18 years - - + + + + + + -18 years + + + .. code-block:: php @@ -242,7 +269,7 @@ can check that a person must be at least 18 years old like this: { public static function loadValidatorMetadata(ClassMetadata $metadata) { - $metadata->addPropertyConstraint('age', new Assert\LessThan('-18 years')); + $metadata->addPropertyConstraint('dateOfBirth', new Assert\LessThan('-18 years')); } } diff --git a/reference/constraints/LessThanOrEqual.rst b/reference/constraints/LessThanOrEqual.rst index 61261fbe571..89d67ff41b4 100644 --- a/reference/constraints/LessThanOrEqual.rst +++ b/reference/constraints/LessThanOrEqual.rst @@ -56,13 +56,19 @@ equal to ``80``, you could do the following: .. code-block:: xml - - - - - - - + + + + + + + + + + + .. code-block:: php @@ -85,6 +91,9 @@ equal to ``80``, you could do the following: Comparing Dates --------------- +.. versionadded:: 2.6 + The feature to compare dates was added in Symfony 2.6. + This constraint can be used to compare ``DateTime`` objects against any date string `accepted by the DateTime constructor`_. For example, you could check that a date must be today or in the past like this: @@ -117,11 +126,17 @@ that a date must be today or in the past like this: .. code-block:: xml - - - today - - + + + + + + today + + + .. code-block:: php @@ -170,11 +185,17 @@ dates. If you want to fix the timezone, append it to the date string: .. code-block:: xml - - - today UTC - - + + + + + + today UTC + + + .. code-block:: php @@ -223,11 +244,17 @@ can check that a person must be at least 18 years old like this: .. code-block:: xml - - - -18 years - - + + + + + + -18 years + + + .. code-block:: php diff --git a/reference/constraints/Range.rst b/reference/constraints/Range.rst index 6009adf7a55..1dce92d6a59 100644 --- a/reference/constraints/Range.rst +++ b/reference/constraints/Range.rst @@ -140,18 +140,24 @@ date must lie within the current year like this: .. code-block:: xml - - - - - - - - + + + + + + + + + + + + .. code-block:: php - // src/Acme/EventBundle/Entity/Person.php + // src/Acme/EventBundle/Entity/Event.php namespace Acme\EventBundle\Entity; use Symfony\Component\Validator\Mapping\ClassMetadata; @@ -204,14 +210,20 @@ dates. If you want to fix the timezone, append it to the date string: .. code-block:: xml - - - - - - - - + + + + + + + + + + + + .. code-block:: php @@ -268,14 +280,20 @@ can check that a delivery date starts within the next five hours like this: .. code-block:: xml - - - - - - - - + + + + + + + + + + + + .. code-block:: php From 39f46e1902abc51f0c3ffc448e68015a5aa07d08 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Tue, 16 Jun 2015 16:22:01 +0200 Subject: [PATCH 11/17] Fixed the issues reported by @xabbuh --- reference/constraints/GreaterThan.rst | 7 +++++-- reference/constraints/GreaterThanOrEqual.rst | 4 ++-- reference/constraints/LessThan.rst | 4 ++-- reference/constraints/LessThanOrEqual.rst | 4 ++-- 4 files changed, 11 insertions(+), 8 deletions(-) diff --git a/reference/constraints/GreaterThan.rst b/reference/constraints/GreaterThan.rst index 8f7783b1937..ccc89c9e92f 100644 --- a/reference/constraints/GreaterThan.rst +++ b/reference/constraints/GreaterThan.rst @@ -14,6 +14,7 @@ than another value, see :doc:`/reference/constraints/LessThan`. +----------------+---------------------------------------------------------------------------+ | Options | - `value`_ | | | - `message`_ | +| | - `payload`_ | +----------------+---------------------------------------------------------------------------+ | Class | :class:`Symfony\\Component\\Validator\\Constraints\\GreaterThan` | +----------------+---------------------------------------------------------------------------+ @@ -30,7 +31,7 @@ If you want to ensure that the ``age`` of a ``Person`` class is greater than .. code-block:: yaml - # src/SocialBundle/Resources/config/validation.yml + # src/Acme/SocialBundle/Resources/config/validation.yml Acme\SocialBundle\Entity\Person: properties: age: @@ -93,7 +94,7 @@ Comparing Dates --------------- .. versionadded:: 2.6 - The feature to compare dates was added in Symfony 2.6. + The feature to compare dates was introduced in Symfony 2.6. This constraint can be used to compare ``DateTime`` objects against any date string `accepted by the DateTime constructor`_. For example, you could check @@ -287,4 +288,6 @@ message 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 + .. _`accepted by the DateTime constructor`: http://www.php.net/manual/en/datetime.formats.php diff --git a/reference/constraints/GreaterThanOrEqual.rst b/reference/constraints/GreaterThanOrEqual.rst index e5abbfb239f..b591f38d0b4 100644 --- a/reference/constraints/GreaterThanOrEqual.rst +++ b/reference/constraints/GreaterThanOrEqual.rst @@ -29,7 +29,7 @@ or equal to ``18``, you could do the following: .. code-block:: yaml - # src/SocialBundle/Resources/config/validation.yml + # src/Acme/SocialBundle/Resources/config/validation.yml Acme\SocialBundle\Entity\Person: properties: age: @@ -92,7 +92,7 @@ Comparing Dates --------------- .. versionadded:: 2.6 - The feature to compare dates was added in Symfony 2.6. + The feature to compare dates was introduced in Symfony 2.6. This constraint can be used to compare ``DateTime`` objects against any date string `accepted by the DateTime constructor`_. For example, you could check diff --git a/reference/constraints/LessThan.rst b/reference/constraints/LessThan.rst index f4a2f32af40..d07c163abfb 100644 --- a/reference/constraints/LessThan.rst +++ b/reference/constraints/LessThan.rst @@ -30,7 +30,7 @@ If you want to ensure that the ``age`` of a ``Person`` class is less than .. code-block:: yaml - # src/SocialBundle/Resources/config/validation.yml + # src/Acme/SocialBundle/Resources/config/validation.yml Acme\SocialBundle\Entity\Person: properties: age: @@ -93,7 +93,7 @@ Comparing Dates --------------- .. versionadded:: 2.6 - The feature to compare dates was added in Symfony 2.6. + The feature to compare dates was introduced in Symfony 2.6. This constraint can be used to compare ``DateTime`` objects against any date string `accepted by the DateTime constructor`_. For example, you could check diff --git a/reference/constraints/LessThanOrEqual.rst b/reference/constraints/LessThanOrEqual.rst index 89d67ff41b4..78c40bb9c95 100644 --- a/reference/constraints/LessThanOrEqual.rst +++ b/reference/constraints/LessThanOrEqual.rst @@ -29,7 +29,7 @@ equal to ``80``, you could do the following: .. code-block:: yaml - # src/SocialBundle/Resources/config/validation.yml + # src/Acme/SocialBundle/Resources/config/validation.yml Acme\SocialBundle\Entity\Person: properties: age: @@ -92,7 +92,7 @@ Comparing Dates --------------- .. versionadded:: 2.6 - The feature to compare dates was added in Symfony 2.6. + The feature to compare dates was introduced in Symfony 2.6. This constraint can be used to compare ``DateTime`` objects against any date string `accepted by the DateTime constructor`_. For example, you could check From e3efbbf81f2785ad36bf2f72e3ee174bf5c57d9b Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Tue, 16 Jun 2015 16:26:57 +0200 Subject: [PATCH 12/17] Reordered the code blocks to show Annotations, YAML, XML and PHP --- reference/constraints/GreaterThan.rst | 66 ++++++++++---------- reference/constraints/GreaterThanOrEqual.rst | 66 ++++++++++---------- reference/constraints/LessThan.rst | 66 ++++++++++---------- reference/constraints/LessThanOrEqual.rst | 66 ++++++++++---------- 4 files changed, 132 insertions(+), 132 deletions(-) diff --git a/reference/constraints/GreaterThan.rst b/reference/constraints/GreaterThan.rst index ccc89c9e92f..bf47027494d 100644 --- a/reference/constraints/GreaterThan.rst +++ b/reference/constraints/GreaterThan.rst @@ -29,15 +29,6 @@ If you want to ensure that the ``age`` of a ``Person`` class is greater than .. configuration-block:: - .. code-block:: yaml - - # src/Acme/SocialBundle/Resources/config/validation.yml - Acme\SocialBundle\Entity\Person: - properties: - age: - - GreaterThan: - value: 18 - .. code-block:: php-annotations // src/Acme/SocialBundle/Entity/Person.php @@ -55,6 +46,15 @@ If you want to ensure that the ``age`` of a ``Person`` class is greater than protected $age; } + .. code-block:: yaml + + # src/Acme/SocialBundle/Resources/config/validation.yml + Acme\SocialBundle\Entity\Person: + properties: + age: + - GreaterThan: + value: 18 + .. code-block:: xml @@ -102,14 +102,6 @@ that a date must at least be the next day: .. configuration-block:: - .. code-block:: yaml - - # src/Acme/OrderBundle/Resources/config/validation.yml - Acme\OrderBundle\Entity\Order: - properties: - deliveryDate: - - GreaterThan: today - .. code-block:: php-annotations // src/Acme/OrderBundle/Entity/Order.php @@ -125,6 +117,14 @@ that a date must at least be the next day: protected $deliveryDate; } + .. code-block:: yaml + + # src/Acme/OrderBundle/Resources/config/validation.yml + Acme\OrderBundle\Entity\Order: + properties: + deliveryDate: + - GreaterThan: today + .. code-block:: xml @@ -161,14 +161,6 @@ dates. If you want to fix the timezone, append it to the date string: .. configuration-block:: - .. code-block:: yaml - - # src/Acme/OrderBundle/Resources/config/validation.yml - Acme\OrderBundle\Entity\Order: - properties: - deliveryDate: - - GreaterThan: today UTC - .. code-block:: php-annotations // src/Acme/OrderBundle/Entity/Order.php @@ -184,6 +176,14 @@ dates. If you want to fix the timezone, append it to the date string: protected $deliveryDate; } + .. code-block:: yaml + + # src/Acme/OrderBundle/Resources/config/validation.yml + Acme\OrderBundle\Entity\Order: + properties: + deliveryDate: + - GreaterThan: today UTC + .. code-block:: xml @@ -221,14 +221,6 @@ current time: .. configuration-block:: - .. code-block:: yaml - - # src/Acme/OrderBundle/Resources/config/validation.yml - Acme\OrderBundle\Entity\Order: - properties: - deliveryDate: - - GreaterThan: +5 hours - .. code-block:: php-annotations // src/Acme/OrderBundle/Entity/Order.php @@ -244,6 +236,14 @@ current time: protected $deliveryDate; } + .. code-block:: yaml + + # src/Acme/OrderBundle/Resources/config/validation.yml + Acme\OrderBundle\Entity\Order: + properties: + deliveryDate: + - GreaterThan: +5 hours + .. code-block:: xml diff --git a/reference/constraints/GreaterThanOrEqual.rst b/reference/constraints/GreaterThanOrEqual.rst index b591f38d0b4..eb5754c2eaa 100644 --- a/reference/constraints/GreaterThanOrEqual.rst +++ b/reference/constraints/GreaterThanOrEqual.rst @@ -27,15 +27,6 @@ or equal to ``18``, you could do the following: .. configuration-block:: - .. code-block:: yaml - - # src/Acme/SocialBundle/Resources/config/validation.yml - Acme\SocialBundle\Entity\Person: - properties: - age: - - GreaterThanOrEqual: - value: 18 - .. code-block:: php-annotations // src/Acme/SocialBundle/Entity/Person.php @@ -53,6 +44,15 @@ or equal to ``18``, you could do the following: protected $age; } + .. code-block:: yaml + + # src/Acme/SocialBundle/Resources/config/validation.yml + Acme\SocialBundle\Entity\Person: + properties: + age: + - GreaterThanOrEqual: + value: 18 + .. code-block:: xml @@ -100,14 +100,6 @@ that a date must at least be the current day: .. configuration-block:: - .. code-block:: yaml - - # src/OrderBundle/Resources/config/validation.yml - Acme\OrderBundle\Entity\Order: - properties: - deliveryDate: - - GreaterThanOrEqual: today - .. code-block:: php-annotations // src/Acme/SocialBundle/Entity/Order.php @@ -123,6 +115,14 @@ that a date must at least be the current day: protected $deliveryDate; } + .. code-block:: yaml + + # src/OrderBundle/Resources/config/validation.yml + Acme\OrderBundle\Entity\Order: + properties: + deliveryDate: + - GreaterThanOrEqual: today + .. code-block:: xml @@ -159,14 +159,6 @@ dates. If you want to fix the timezone, append it to the date string: .. configuration-block:: - .. code-block:: yaml - - # src/OrderBundle/Resources/config/validation.yml - Acme\OrderBundle\Entity\Order: - properties: - deliveryDate: - - GreaterThanOrEqual: today UTC - .. code-block:: php-annotations // src/Acme/SocialBundle/Entity/Order.php @@ -182,6 +174,14 @@ dates. If you want to fix the timezone, append it to the date string: protected $deliveryDate; } + .. code-block:: yaml + + # src/OrderBundle/Resources/config/validation.yml + Acme\OrderBundle\Entity\Order: + properties: + deliveryDate: + - GreaterThanOrEqual: today UTC + .. code-block:: xml @@ -219,14 +219,6 @@ current time: .. configuration-block:: - .. code-block:: yaml - - # src/OrderBundle/Resources/config/validation.yml - Acme\OrderBundle\Entity\Order: - properties: - deliveryDate: - - GreaterThanOrEqual: +5 hours - .. code-block:: php-annotations // src/Acme/SocialBundle/Entity/Order.php @@ -242,6 +234,14 @@ current time: protected $deliveryDate; } + .. code-block:: yaml + + # src/OrderBundle/Resources/config/validation.yml + Acme\OrderBundle\Entity\Order: + properties: + deliveryDate: + - GreaterThanOrEqual: +5 hours + .. code-block:: xml diff --git a/reference/constraints/LessThan.rst b/reference/constraints/LessThan.rst index d07c163abfb..3afcd1be4f1 100644 --- a/reference/constraints/LessThan.rst +++ b/reference/constraints/LessThan.rst @@ -28,15 +28,6 @@ If you want to ensure that the ``age`` of a ``Person`` class is less than .. configuration-block:: - .. code-block:: yaml - - # src/Acme/SocialBundle/Resources/config/validation.yml - Acme\SocialBundle\Entity\Person: - properties: - age: - - LessThan: - value: 80 - .. code-block:: php-annotations // src/Acme/SocialBundle/Entity/Person.php @@ -54,6 +45,15 @@ If you want to ensure that the ``age`` of a ``Person`` class is less than protected $age; } + .. code-block:: yaml + + # src/Acme/SocialBundle/Resources/config/validation.yml + Acme\SocialBundle\Entity\Person: + properties: + age: + - LessThan: + value: 80 + .. code-block:: xml @@ -101,14 +101,6 @@ that a date must be in the past like this: .. configuration-block:: - .. code-block:: yaml - - # src/SocialBundle/Resources/config/validation.yml - Acme\SocialBundle\Entity\Person: - properties: - dateOfBirth: - - LessThan: today - .. code-block:: php-annotations // src/Acme/SocialBundle/Entity/Person.php @@ -124,6 +116,14 @@ that a date must be in the past like this: protected $dateOfBirth; } + .. code-block:: yaml + + # src/SocialBundle/Resources/config/validation.yml + Acme\SocialBundle\Entity\Person: + properties: + dateOfBirth: + - LessThan: today + .. code-block:: xml @@ -160,14 +160,6 @@ dates. If you want to fix the timezone, append it to the date string: .. configuration-block:: - .. code-block:: yaml - - # src/SocialBundle/Resources/config/validation.yml - Acme\SocialBundle\Entity\Person: - properties: - dateOfBirth: - - LessThan: today UTC - .. code-block:: php-annotations // src/Acme/SocialBundle/Entity/Person.php @@ -183,6 +175,14 @@ dates. If you want to fix the timezone, append it to the date string: protected $dateOfBirth; } + .. code-block:: yaml + + # src/SocialBundle/Resources/config/validation.yml + Acme\SocialBundle\Entity\Person: + properties: + dateOfBirth: + - LessThan: today UTC + .. code-block:: xml @@ -219,14 +219,6 @@ can check that a person must be at least 18 years old like this: .. configuration-block:: - .. code-block:: yaml - - # src/SocialBundle/Resources/config/validation.yml - Acme\SocialBundle\Entity\Person: - properties: - dateOfBirth: - - LessThan: -18 years - .. code-block:: php-annotations // src/Acme/SocialBundle/Entity/Person.php @@ -242,6 +234,14 @@ can check that a person must be at least 18 years old like this: protected $dateOfBirth; } + .. code-block:: yaml + + # src/SocialBundle/Resources/config/validation.yml + Acme\SocialBundle\Entity\Person: + properties: + dateOfBirth: + - LessThan: -18 years + .. code-block:: xml diff --git a/reference/constraints/LessThanOrEqual.rst b/reference/constraints/LessThanOrEqual.rst index 78c40bb9c95..889ffe9d46a 100644 --- a/reference/constraints/LessThanOrEqual.rst +++ b/reference/constraints/LessThanOrEqual.rst @@ -27,15 +27,6 @@ equal to ``80``, you could do the following: .. configuration-block:: - .. code-block:: yaml - - # src/Acme/SocialBundle/Resources/config/validation.yml - Acme\SocialBundle\Entity\Person: - properties: - age: - - LessThanOrEqual: - value: 80 - .. code-block:: php-annotations // src/Acme/SocialBundle/Entity/Person.php @@ -53,6 +44,15 @@ equal to ``80``, you could do the following: protected $age; } + .. code-block:: yaml + + # src/Acme/SocialBundle/Resources/config/validation.yml + Acme\SocialBundle\Entity\Person: + properties: + age: + - LessThanOrEqual: + value: 80 + .. code-block:: xml @@ -100,14 +100,6 @@ that a date must be today or in the past like this: .. configuration-block:: - .. code-block:: yaml - - # src/SocialBundle/Resources/config/validation.yml - Acme\SocialBundle\Entity\Person: - properties: - age: - - LessThanOrEqual: today - .. code-block:: php-annotations // src/Acme/SocialBundle/Entity/Person.php @@ -123,6 +115,14 @@ that a date must be today or in the past like this: protected $age; } + .. code-block:: yaml + + # src/SocialBundle/Resources/config/validation.yml + Acme\SocialBundle\Entity\Person: + properties: + age: + - LessThanOrEqual: today + .. code-block:: xml @@ -159,14 +159,6 @@ dates. If you want to fix the timezone, append it to the date string: .. configuration-block:: - .. code-block:: yaml - - # src/SocialBundle/Resources/config/validation.yml - Acme\SocialBundle\Entity\Person: - properties: - age: - - LessThanOrEqual: today UTC - .. code-block:: php-annotations // src/Acme/SocialBundle/Entity/Person.php @@ -182,6 +174,14 @@ dates. If you want to fix the timezone, append it to the date string: protected $age; } + .. code-block:: yaml + + # src/SocialBundle/Resources/config/validation.yml + Acme\SocialBundle\Entity\Person: + properties: + age: + - LessThanOrEqual: today UTC + .. code-block:: xml @@ -218,14 +218,6 @@ can check that a person must be at least 18 years old like this: .. configuration-block:: - .. code-block:: yaml - - # src/SocialBundle/Resources/config/validation.yml - Acme\SocialBundle\Entity\Person: - properties: - age: - - LessThanOrEqual: -18 years - .. code-block:: php-annotations // src/Acme/SocialBundle/Entity/Person.php @@ -241,6 +233,14 @@ can check that a person must be at least 18 years old like this: protected $age; } + .. code-block:: yaml + + # src/SocialBundle/Resources/config/validation.yml + Acme\SocialBundle\Entity\Person: + properties: + age: + - LessThanOrEqual: -18 years + .. code-block:: xml From 7ef2e6a09294bb4662f6842ee15735cd45551675 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Tue, 16 Jun 2015 22:26:30 +0200 Subject: [PATCH 13/17] Show annotations first --- reference/constraints/Range.rst | 60 ++++++++++++++++----------------- 1 file changed, 30 insertions(+), 30 deletions(-) diff --git a/reference/constraints/Range.rst b/reference/constraints/Range.rst index 1dce92d6a59..6f4dea3339d 100644 --- a/reference/constraints/Range.rst +++ b/reference/constraints/Range.rst @@ -109,16 +109,6 @@ date must lie within the current year like this: .. configuration-block:: - .. code-block:: yaml - - # src/EventBundle/Resources/config/validation.yml - Acme\EventBundle\Entity\Event: - properties: - startDate: - - Range: - min: first day of January - max: first day of January next year - .. code-block:: php-annotations // src/Acme/SocialBundle/Entity/Event.php @@ -137,6 +127,16 @@ date must lie within the current year like this: protected $startDate; } + .. code-block:: yaml + + # src/EventBundle/Resources/config/validation.yml + Acme\EventBundle\Entity\Event: + properties: + startDate: + - Range: + min: first day of January + max: first day of January next year + .. code-block:: xml @@ -179,16 +179,6 @@ dates. If you want to fix the timezone, append it to the date string: .. configuration-block:: - .. code-block:: yaml - - # src/EventBundle/Resources/config/validation.yml - Acme\EventBundle\Entity\Event: - properties: - startDate: - - Range: - min: first day of January UTC - max: first day of January next year UTC - .. code-block:: php-annotations // src/Acme/SocialBundle/Entity/Event.php @@ -207,6 +197,16 @@ dates. If you want to fix the timezone, append it to the date string: protected $startDate; } + .. code-block:: yaml + + # src/EventBundle/Resources/config/validation.yml + Acme\EventBundle\Entity\Event: + properties: + startDate: + - Range: + min: first day of January UTC + max: first day of January next year UTC + .. code-block:: xml @@ -249,16 +249,6 @@ can check that a delivery date starts within the next five hours like this: .. configuration-block:: - .. code-block:: yaml - - # src/OrderBundle/Resources/config/validation.yml - Acme\OrderBundle\Entity\Order: - properties: - deliveryDate: - - Range: - min: now - max: +5 hours - .. code-block:: php-annotations // src/Acme/SocialBundle/Entity/Order.php @@ -277,6 +267,16 @@ can check that a delivery date starts within the next five hours like this: protected $deliveryDate; } + .. code-block:: yaml + + # src/OrderBundle/Resources/config/validation.yml + Acme\OrderBundle\Entity\Order: + properties: + deliveryDate: + - Range: + min: now + max: +5 hours + .. code-block:: xml From b6c1a93e7e9a11ff99b9ae46c81ebce3ef9d60e6 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Tue, 16 Jun 2015 22:27:45 +0200 Subject: [PATCH 14/17] Added the "payload" option back --- reference/constraints/GreaterThanOrEqual.rst | 3 +++ reference/constraints/LessThan.rst | 3 +++ reference/constraints/LessThanOrEqual.rst | 3 +++ 3 files changed, 9 insertions(+) diff --git a/reference/constraints/GreaterThanOrEqual.rst b/reference/constraints/GreaterThanOrEqual.rst index eb5754c2eaa..4d61dd5b077 100644 --- a/reference/constraints/GreaterThanOrEqual.rst +++ b/reference/constraints/GreaterThanOrEqual.rst @@ -13,6 +13,7 @@ the options. To force that a value is greater than another value, see +----------------+----------------------------------------------------------------------------------+ | Options | - `value`_ | | | - `message`_ | +| | - `payload`_ | +----------------+----------------------------------------------------------------------------------+ | Class | :class:`Symfony\\Component\\Validator\\Constraints\\GreaterThanOrEqual` | +----------------+----------------------------------------------------------------------------------+ @@ -286,4 +287,6 @@ message 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 + .. _`accepted by the DateTime constructor`: http://www.php.net/manual/en/datetime.formats.php diff --git a/reference/constraints/LessThan.rst b/reference/constraints/LessThan.rst index 3afcd1be4f1..772f6e629ee 100644 --- a/reference/constraints/LessThan.rst +++ b/reference/constraints/LessThan.rst @@ -14,6 +14,7 @@ than another value, see :doc:`/reference/constraints/GreaterThan`. +----------------+------------------------------------------------------------------------+ | Options | - `value`_ | | | - `message`_ | +| | - `payload`_ | +----------------+------------------------------------------------------------------------+ | Class | :class:`Symfony\\Component\\Validator\\Constraints\\LessThan` | +----------------+------------------------------------------------------------------------+ @@ -286,4 +287,6 @@ message This is the message that will be shown if the value is not less than the comparison value. +.. include:: /reference/constraints/_payload-option.rst.inc + .. _`accepted by the DateTime constructor`: http://www.php.net/manual/en/datetime.formats.php diff --git a/reference/constraints/LessThanOrEqual.rst b/reference/constraints/LessThanOrEqual.rst index 889ffe9d46a..22d0201a429 100644 --- a/reference/constraints/LessThanOrEqual.rst +++ b/reference/constraints/LessThanOrEqual.rst @@ -13,6 +13,7 @@ options. To force that a value is less than another value, see +----------------+-------------------------------------------------------------------------------+ | Options | - `value`_ | | | - `message`_ | +| | - `payload`_ | +----------------+-------------------------------------------------------------------------------+ | Class | :class:`Symfony\\Component\\Validator\\Constraints\\LessThanOrEqual` | +----------------+-------------------------------------------------------------------------------+ @@ -285,4 +286,6 @@ message 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 + .. _`accepted by the DateTime constructor`: http://www.php.net/manual/en/datetime.formats.php From 023a96fe15b3fe31cec933d4e6da8cf37251e312 Mon Sep 17 00:00:00 2001 From: Javier Spagnoletti Date: Mon, 15 Jun 2015 12:16:30 -0300 Subject: [PATCH 15/17] [Contributing] [Conventions] Added entry for Yoda conditions | Q | A | ------------- | --- | Doc fix? | yes | New docs? | no | Applies to | 2.8+ | Fixed tickets | --- contributing/code/standards.rst | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/contributing/code/standards.rst b/contributing/code/standards.rst index 48864f6992b..025a3376dde 100644 --- a/contributing/code/standards.rst +++ b/contributing/code/standards.rst @@ -102,6 +102,9 @@ Structure * Always use `identical comparison`_ unless you need type juggling; +* Use `Yoda conditions`_ when checking a variable against an expression to avoid + an accidental assignment inside the condition statement; + * Add a comma after each array item in a multi-line array, even after the last one; @@ -189,3 +192,4 @@ License .. _`PSR-2`: http://www.php-fig.org/psr/psr-2/ .. _`PSR-4`: http://www.php-fig.org/psr/psr-4/ .. _`identical comparison`: https://php.net/manual/en/language.operators.comparison.php +.. _`Yoda conditions`: https://en.wikipedia.org/wiki/Yoda_conditions From d606f3e0ccf43dddb00a7b0323ad7dc7acdb9888 Mon Sep 17 00:00:00 2001 From: Ryan Weaver Date: Sun, 28 Jun 2015 13:55:09 -0400 Subject: [PATCH 16/17] [#5402] Being explicit what this applies to (it should not apply to things like >=) --- contributing/code/standards.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/contributing/code/standards.rst b/contributing/code/standards.rst index 025a3376dde..2168129d7fa 100644 --- a/contributing/code/standards.rst +++ b/contributing/code/standards.rst @@ -103,7 +103,8 @@ Structure * Always use `identical comparison`_ unless you need type juggling; * Use `Yoda conditions`_ when checking a variable against an expression to avoid - an accidental assignment inside the condition statement; + an accidental assignment inside the condition statement (this applies to ``==``, + ``!=``, ``===``, and ``!==``); * Add a comma after each array item in a multi-line array, even after the last one; From c9a40019d6b159f00a3a00ac2843302cf43d1ace Mon Sep 17 00:00:00 2001 From: Thomas Schulz Date: Tue, 16 Jun 2015 09:51:09 +0200 Subject: [PATCH 17/17] Changed PhpStormOpener to PhpStormProtocol PhpStormOpener only supports Mac OS. PhpStormProtocol supports Windows, so the sentence here now makes sense. --- reference/configuration/framework.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/reference/configuration/framework.rst b/reference/configuration/framework.rst index 9de35e6bc0b..d2fdb146b5a 100644 --- a/reference/configuration/framework.rst +++ b/reference/configuration/framework.rst @@ -256,7 +256,7 @@ you use PHPstorm on the Mac OS platform, you will do something like: .. tip:: - If you're on a Windows PC, you can install the `PhpStormOpener`_ to + If you're on a Windows PC, you can install the `PhpStormProtocol`_ to be able to use this. Of course, since every developer uses a different IDE, it's better to set @@ -1529,4 +1529,4 @@ Full Default Configuration .. _`HTTP Host header attacks`: http://www.skeletonscribe.net/2013/05/practical-http-host-header-attacks.html .. _`Security Advisory Blog post`: http://symfony.com/blog/security-releases-symfony-2-0-24-2-1-12-2-2-5-and-2-3-3-released#cve-2013-4752-request-gethost-poisoning .. _`Doctrine Cache`: http://docs.doctrine-project.org/projects/doctrine-common/en/latest/reference/caching.html -.. _`PhpStormOpener`: https://github.com/pinepain/PhpStormOpener +.. _`PhpStormProtocol`: https://github.com/aik099/PhpStormProtocol