Merge branch '3.4' into 4.3

* 3.4:
  [Workflow] Rework a bit the doc

Author: javiereguiluz

_build/redirection_map

@@ -414,7 +414,8 @@
 /frontend/encore/legacy-apps /frontend/encore/legacy-applications
 /configuration/external_parameters /configuration/environment_variables
 /contributing/code/patches /contributing/code/pull_requests
-/workflow/state-machines /workflow/introduction
+/workflow/state-machines /workflow/workflow-and-state-machine
+/workflow/introduction /workflow/workflow-and-state-machine
 /workflow/usage /workflow
 /introduction/from_flat_php_to_symfony2 /introduction/from_flat_php_to_symfony
 /configuration/environment_variables /configuration/env_var_processors

reference/configuration/framework.rst

@@ -2879,7 +2879,7 @@ type
 **type**: ``string`` **possible values**: ``'workflow'`` or ``'state_machine'``
 
 Defines the kind of workflow that is going to be created, which can be either
-a normal workflow or a state machine. Read :doc:`this article </workflow/introduction>`
+a normal workflow or a state machine. Read :doc:`this article </workflow/workflow-and-state-machine>`
 to know their differences.
 
 .. _`HTTP Host header attacks`: http://www.skeletonscribe.net/2013/05/practical-http-host-header-attacks.html

workflow.rst

@@ -3,7 +3,7 @@ Workflow
 
 Using the Workflow component inside a Symfony application requires to know first
 some basic theory and concepts about workflows and state machines.
-:doc:`Read this article </workflow/introduction>` for a quick overview.
+:doc:`Read this article </workflow/workflow-and-state-machine>` for a quick overview.
 
 Installation
 ------------
@@ -170,6 +170,25 @@ As configured, the following property is used by the marking store::
         public $content;
     }
 
+.. note::
+
+    The marking store type could be "multiple_state" or "single_state". A single
+    state marking store does not support a model being on multiple places at the
+    same time. This means a "workflow" must use a "multiple_state" marking store
+    and a "state_machine" must use a "single_state" marking store. Symfony
+    configures the marking store according to the "type" by default, so it's
+    preferable to not configure it.
+
+    A single state marking store uses a string to store the data. A multiple
+    state marking store uses an array to store the data.
+
+.. tip::
+
+    The ``marking_store.type`` (the default value depends on the ``type`` value)
+    and ``arguments`` (default value ``['marking']``) attributes of the
+    ``marking_store`` option are optional. If omitted, their default values will
+    be used. It's highly recommenced to use the default value.
+
 .. tip::
 
     Setting the ``audit_trail.enabled`` option to ``true`` makes the application
@@ -744,5 +763,5 @@ Learn more
 .. toctree::
    :maxdepth: 1
 
-   workflow/introduction
-   workflow/dumping-workflows
+   /workflow/workflow-and-state-machine
+   /workflow/dumping-workflows

workflow/introduction.rst renamed to workflow/workflow-and-state-machine.rst

@@ -49,8 +49,6 @@ your model. The most important differences between them are:
 
 * Workflows can be in more than one place at the same time, whereas state
   machines can't;
-* Workflows usually don't have cyclic paths in the definition graph, but it's
-  common for state machines;
 * In order to apply a transition, workflows require that the object is in all
   the previous places of the transition, whereas state machines only require
   that the object is at least in one of those places.