Merge branch '4.4'

wouterj · wouterj · commit 7d5a546335c6 · 2019-11-09T15:52:21.000+01:00
* 4.4: [#12600] Added versionadded for invokable listeners Revert "bug #12600 [Doctrine] Don't mention invokable listeners in 4.3 (javiereguiluz)" [#12584] Small tweaks Add WeekType Documentation [Doctrine] Don't mention invokable listeners in 4.3 [Messenger] update events for 4.4 Use normalizer context constants everywhere
diff --git a/components/serializer.rst b/components/serializer.rst
@@ -168,7 +168,7 @@ needs three parameters:
 
 By default, additional attributes that are not mapped to the denormalized object
 will be ignored by the Serializer component. If you prefer to throw an exception
-when this happens, set the ``allow_extra_attributes`` context option to
+when this happens, set the ``AbstractNormalizer::ALLOW_EXTRA_ATTRIBUTES`` context option to
 ``false`` and provide an object that implements ``ClassMetadataFactoryInterface``
 when constructing the normalizer::
 
@@ -188,7 +188,7 @@ when constructing the normalizer::
     // this will throw a Symfony\Component\Serializer\Exception\ExtraAttributesException
     // because "city" is not an attribute of the Person class
     $person = $serializer->deserialize($data, 'App\Model\Person', 'xml', [
-        'allow_extra_attributes' => false,
+        AbstractNormalizer::ALLOW_EXTRA_ATTRIBUTES => false,
     ]);
 
 Deserializing in an Existing Object
@@ -209,12 +209,12 @@ The serializer can also be used to update an existing object::
     </person>
     EOF;
 
-    $serializer->deserialize($data, Person::class, 'xml', ['object_to_populate' => $person]);
+    $serializer->deserialize($data, Person::class, 'xml', [AbstractNormalizer::OBJECT_TO_POPULATE => $person]);
     // $person = App\Model\Person(name: 'foo', age: '69', sportsperson: true)
 
 This is a common need when working with an ORM.
 
-The ``OBJECT_TO_POPULATE`` is only used for the top level object. If that object
+The ``AbstractNormalizer::OBJECT_TO_POPULATE`` is only used for the top level object. If that object
 is the root of a tree structure, all child elements that exist in the
 normalized data will be re-created with new instances.
 
@@ -372,6 +372,7 @@ Selecting Specific Attributes
 
 It is also possible to serialize only a set of specific attributes::
 
+    use Symfony\Component\Serializer\Normalizer\AbstractNormalizer;
     use Symfony\Component\Serializer\Normalizer\ObjectNormalizer;
     use Symfony\Component\Serializer\Serializer;
 
@@ -399,7 +400,7 @@ It is also possible to serialize only a set of specific attributes::
 
     $serializer = new Serializer([new ObjectNormalizer()]);
 
-    $data = $serializer->normalize($user, null, ['attributes' => ['familyName', 'company' => ['name']]]);
+    $data = $serializer->normalize($user, null, [AbstractNormalizer::ATTRIBUTES => ['familyName', 'company' => ['name']]]);
     // $data = ['familyName' => 'Dunglas', 'company' => ['name' => 'Les-Tilleuls.coop']];
 
 Only attributes that are not ignored (see below) are available.
@@ -411,11 +412,12 @@ Ignoring Attributes
 -------------------
 
 As an option, there's a way to ignore attributes from the origin object.
-To remove those attributes provide an array via the ``ignored_attributes``
+To remove those attributes provide an array via the ``AbstractNormalizer::IGNORED_ATTRIBUTES``
 key in the ``context`` parameter of the desired serializer method::
 
     use Acme\Person;
     use Symfony\Component\Serializer\Encoder\JsonEncoder;
+    use Symfony\Component\Serializer\Normalizer\AbstractNormalizer;
     use Symfony\Component\Serializer\Normalizer\ObjectNormalizer;
     use Symfony\Component\Serializer\Serializer;
 
@@ -427,7 +429,7 @@ key in the ``context`` parameter of the desired serializer method::
     $encoder = new JsonEncoder();
 
     $serializer = new Serializer([$normalizer], [$encoder]);
-    $serializer->serialize($person, 'json', ['ignored_attributes' => ['age']]); // Output: {"name":"foo"}
+    $serializer->serialize($person, 'json', [AbstractNormalizer::IGNORED_ATTRIBUTES => ['age']]); // Output: {"name":"foo"}
 
 .. _component-serializer-converting-property-names-when-serializing-and-deserializing:
 
@@ -843,7 +845,7 @@ Skipping ``null`` Values
 ------------------------
 
 By default, the Serializer will preserve properties containing a ``null`` value.
-You can change this behavior by setting the ``skip_null_values`` context option
+You can change this behavior by setting the ``AbstractObjectNormalizer::SKIP_NULL_VALUES`` context option
 to ``true``::
 
     $dummy = new class {
@@ -852,7 +854,7 @@ to ``true``::
     };
 
     $normalizer = new ObjectNormalizer();
-    $result = $normalizer->normalize($dummy, 'json', ['skip_null_values' => true]);
+    $result = $normalizer->normalize($dummy, 'json', [AbstractObjectNormalizer::SKIP_NULL_VALUES => true]);
     // ['bar' => 'notNull']
 
 .. _component-serializer-handling-circular-references:
@@ -1027,11 +1029,11 @@ in a Symfony application. When using the standalone component, refer to
 :ref:`the groups documentation <component-serializer-attributes-groups>` to
 learn how to do that.
 
-The check is only done if the ``enable_max_depth`` key of the serializer context
+The check is only done if the ``AbstractObjectNormalizer::ENABLE_MAX_DEPTH`` key of the serializer context
 is set to ``true``. In the following example, the third level is not serialized
 because it is deeper than the configured maximum depth of 2::
 
-    $result = $serializer->normalize($level1, null, ['enable_max_depth' => true]);
+    $result = $serializer->normalize($level1, null, [AbstractObjectNormalizer::ENABLE_MAX_DEPTH => true]);
     /*
     $result = [
         'foo' => 'level1',
@@ -1052,6 +1054,7 @@ having unique identifiers::
     use Symfony\Component\Serializer\Annotation\MaxDepth;
     use Symfony\Component\Serializer\Mapping\Factory\ClassMetadataFactory;
     use Symfony\Component\Serializer\Mapping\Loader\AnnotationLoader;
+    use Symfony\Component\Serializer\Normalizer\AbstractObjectNormalizer;
     use Symfony\Component\Serializer\Normalizer\ObjectNormalizer;
     use Symfony\Component\Serializer\Serializer;
 
@@ -1090,7 +1093,7 @@ having unique identifiers::
 
     $serializer = new Serializer([$normalizer]);
 
-    $result = $serializer->normalize($level1, null, [ObjectNormalizer::ENABLE_MAX_DEPTH => true]);
+    $result = $serializer->normalize($level1, null, [AbstractObjectNormalizer::ENABLE_MAX_DEPTH => true]);
     /*
     $result = [
         'id' => 1,
@@ -1220,6 +1223,7 @@ If the class constructor defines arguments, as usually happens with
 arguments are missing. In those cases, use the ``default_constructor_arguments``
 context option::
 
+    use Symfony\Component\Serializer\Normalizer\AbstractNormalizer;
     use Symfony\Component\Serializer\Normalizer\ObjectNormalizer;
     use Symfony\Component\Serializer\Serializer;
 
@@ -1241,7 +1245,7 @@ context option::
     $data = $serializer->denormalize(
         ['foo' => 'Hello'],
         'MyObj',
-        ['default_constructor_arguments' => [
+        [AbstractNormalizer::DEFAULT_CONSTRUCTOR_ARGUMENTS => [
             'MyObj' => ['foo' => '', 'bar' => ''],
         ]]
     );
diff --git a/doctrine/events.rst b/doctrine/events.rst
@@ -330,6 +330,10 @@ with the ``doctrine.orm.entity_listener`` tag:
             ])
         ;
 
+.. versionadded:: 4.4
+
+    Support for invokable listeners (using the ``__invoke()`` method) was introduced in Symfony 4.4.
+
 Doctrine Lifecycle Subscribers
 ------------------------------
 
diff --git a/messenger.rst b/messenger.rst
@@ -1448,10 +1448,12 @@ In addition to middleware, Messenger also dispatches several events. You can
 :doc:`create an event listener </event_dispatcher>` to hook into various parts
 of the process. For each, the event class is the event name:
 
+* :class:`Symfony\\Component\\Messenger\\Event\\WorkerStartedEvent`
+* :class:`Symfony\\Component\\Messenger\\Event\\WorkerMessageReceivedEvent`
 * :class:`Symfony\\Component\\Messenger\\Event\\SendMessageToTransportsEvent`
 * :class:`Symfony\\Component\\Messenger\\Event\\WorkerMessageFailedEvent`
 * :class:`Symfony\\Component\\Messenger\\Event\\WorkerMessageHandledEvent`
-* :class:`Symfony\\Component\\Messenger\\Event\\WorkerMessageReceivedEvent`
+* :class:`Symfony\\Component\\Messenger\\Event\\WorkerRunningEvent`
 * :class:`Symfony\\Component\\Messenger\\Event\\WorkerStoppedEvent`
 
 Multiple Buses, Command & Event Buses
diff --git a/reference/forms/types.rst b/reference/forms/types.rst
@@ -35,6 +35,7 @@ Form Types Reference
    types/datetime
    types/time
    types/birthday
+   types/week
 
    types/checkbox
    types/file
diff --git a/reference/forms/types/map.rst.inc b/reference/forms/types/map.rst.inc
@@ -34,6 +34,7 @@ Date and Time Fields
 * :doc:`DateTimeType </reference/forms/types/datetime>`
 * :doc:`TimeType </reference/forms/types/time>`
 * :doc:`BirthdayType </reference/forms/types/birthday>`
+* :doc:`WeekType </reference/forms/types/week>`
 
 Other Fields
 ~~~~~~~~~~~~
diff --git a/reference/forms/types/options/weeks.rst.inc b/reference/forms/types/options/weeks.rst.inc
@@ -0,0 +1,7 @@
+weeks
+~~~~~
+
+**type**: ``array`` **default**: 1 to 53
+
+List of weeks available to the week field type. This option is only relevant
+when the ``widget`` option is set to ``choice``.
diff --git a/reference/forms/types/week.rst b/reference/forms/types/week.rst
@@ -0,0 +1,184 @@
+.. index::
+   single: Forms; Fields; WeekType
+
+WeekType Field
+==============
+
+.. versionadded:: 4.4
+
+    The ``WeekType`` type was introduced in Symfony 4.4.
+
+This field type allows the user to modify data that represents a specific
+`ISO 8601`_ week number (e.g. ``1984-W05``).
+
+Can be rendered as a text input or select tags. The underlying format of
+the data can be a string or an array.
+
++----------------------+-----------------------------------------------------------------------------+
+| Underlying Data Type | can be a string, or array (see the ``input`` option)                        |
++----------------------+-----------------------------------------------------------------------------+
+| Rendered as          | single text box, two text boxes or two select fields                        |
++----------------------+-----------------------------------------------------------------------------+
+| Options              | - `choice_translation_domain`_                                              |
+|                      | - `placeholder`_                                                            |
+|                      | - `html5`_                                                                  |
+|                      | - `input`_                                                                  |
+|                      | - `widget`_                                                                 |
+|                      | - `weeks`_                                                                  |
+|                      | - `years`_                                                                  |
++----------------------+-----------------------------------------------------------------------------+
+| Overridden options   | - `compound`_                                                               |
+|                      | - `empty_data`_                                                             |
+|                      | - `error_bubbling`_                                                         |
++----------------------+-----------------------------------------------------------------------------+
+| Inherited            | - `attr`_                                                                   |
+| options              | - `data`_                                                                   |
+|                      | - `disabled`_                                                               |
+|                      | - `help`_                                                                   |
+|                      | - `help_attr`_                                                              |
+|                      | - `help_html`_                                                              |
+|                      | - `inherit_data`_                                                           |
+|                      | - `invalid_message`_                                                        |
+|                      | - `invalid_message_parameters`_                                             |
+|                      | - `mapped`_                                                                 |
+|                      | - `row_attr`_                                                               |
++----------------------+-----------------------------------------------------------------------------+
+| Parent type          | :doc:`FormType </reference/forms/types/form>`                               |
++----------------------+-----------------------------------------------------------------------------+
+| Class                | :class:`Symfony\\Component\\Form\\Extension\\Core\\Type\\WeekType`          |
++----------------------+-----------------------------------------------------------------------------+
+
+.. include:: /reference/forms/types/options/_debug_form.rst.inc
+
+Field Options
+-------------
+
+.. include:: /reference/forms/types/options/choice_translation_domain.rst.inc
+
+placeholder
+~~~~~~~~~~~
+
+**type**: ``string`` | ``array``
+
+If your widget option is set to ``choice``, then this field will be represented
+as a series of ``select`` boxes. When the placeholder value is a string,
+it will be used as the **blank value** of all select boxes::
+
+    use Symfony\Component\Form\Extension\Core\Type\WeekType;
+
+    $builder->add('startWeek', WeekType::class, [
+        'placeholder' => 'Select a value',
+    ]);
+
+Alternatively, you can use an array that configures different placeholder
+values for the year and week fields::
+
+    use Symfony\Component\Form\Extension\Core\Type\WeekType;
+
+    $builder->add('startDateTime', WeekType::class, [
+        'placeholder' => [
+            'year' => 'Year',
+            'week' => 'Week',
+        ]
+    ]);
+
+.. include:: /reference/forms/types/options/html5.rst.inc
+
+input
+~~~~~
+
+**type**: ``string`` **default**: ``array``
+
+The format of the *input* data - i.e. the format that the date is stored
+on your underlying object. Valid values are:
+
+* ``string`` (e.g. ``"2011-W17"``)
+* ``array`` (e.g. ``[2011, 17]``)
+
+The value that comes back from the form will also be normalized back into
+this format.
+
+widget
+~~~~~~
+
+**type**: ``string`` **default**: ``choice``
+
+The basic way in which this field should be rendered. Can be one of the
+following:
+
+* ``choice``: renders two select inputs;
+* ``text``: renders a two field input of type ``text`` (year and week);
+* ``single_text``: renders a single input of type ``week``.
+
+years
+~~~~~
+
+**type**: ``array`` **default**: ten years before to ten years after the
+current year
+
+List of years available to the year field type. This option is only relevant
+when the ``widget`` option is set to ``choice``.
+
+.. include:: /reference/forms/types/options/weeks.rst.inc
+
+Overridden Options
+------------------
+
+.. include:: /reference/forms/types/options/compound_type.rst.inc
+
+.. include:: /reference/forms/types/options/empty_data.rst.inc
+    :end-before: DEFAULT_PLACEHOLDER
+
+The actual default value of this option depends on other field options:
+
+* If ``widget`` is ``single_text``, then ``''`` (empty string);
+* Otherwise ``[]`` (empty array).
+
+.. include:: /reference/forms/types/options/empty_data.rst.inc
+    :start-after: DEFAULT_PLACEHOLDER
+
+error_bubbling
+~~~~~~~~~~~~~~
+
+**default**: ``false``
+
+Inherited Options
+-----------------
+
+These options inherit from the :doc:`FormType </reference/forms/types/form>`:
+
+.. include:: /reference/forms/types/options/attr.rst.inc
+
+.. include:: /reference/forms/types/options/data.rst.inc
+
+.. include:: /reference/forms/types/options/disabled.rst.inc
+
+.. include:: /reference/forms/types/options/help.rst.inc
+
+.. include:: /reference/forms/types/options/help_attr.rst.inc
+
+.. include:: /reference/forms/types/options/help_html.rst.inc
+
+.. include:: /reference/forms/types/options/inherit_data.rst.inc
+
+.. include:: /reference/forms/types/options/invalid_message.rst.inc
+
+.. include:: /reference/forms/types/options/invalid_message_parameters.rst.inc
+
+.. include:: /reference/forms/types/options/mapped.rst.inc
+
+.. include:: /reference/forms/types/options/row_attr.rst.inc
+
+Field Variables
+---------------
+
++----------+------------+----------------------------------------------------------------------+
+| Variable | Type       | Usage                                                                |
++==========+============+======================================================================+
+| widget   | ``mixed``  | The value of the `widget`_ option.                                   |
++----------+------------+----------------------------------------------------------------------+
+| type     | ``string`` | Only present when widget is ``single_text`` and HTML5 is activated,  |
+|          |            | contains the input type to use (``datetime``, ``date`` or ``time``). |
++----------+------------+----------------------------------------------------------------------+
+
+.. _`ISO 8601`: https://en.wikipedia.org/wiki/ISO_8601

Original file line number	Diff line number	Diff line change
@@ -330,6 +330,10 @@ with the ``doctrine.orm.entity_listener`` tag:
`330`	`330`	`])`
`331`	`331`	`;`
`332`	`332`
	`333`	`+.. versionadded:: 4.4`
	`334`	`+`
	`335`	+ Support for invokable listeners (using the ``__invoke()`` method) was introduced in Symfony 4.4.
	`336`	`+`
`333`	`337`	`Doctrine Lifecycle Subscribers`
`334`	`338`	`------------------------------`
`335`	`339`