Description
I have a few workflows where I need to keep a log of the workflow places the entity has been through also including a timestamp and optional 'memo' - a short text detailing the state change. This is for three reasons;

• to be able to display a timeline of states in the admin for that entity,
• to be able to use the workflow to alert the admin to states that have not changed after a pre-determined amount of times (e.g. a cart has items in it but has not been checked out, items that need to be urgently dispatched as they've been sitting in the to_dispatch place for a while and are now overdue the three-day dispatch time window etc).
• above all, to be machine readable and parsable easily via code.

config

I have come upon this solution for the workflow definition by allowing an additional config inside the workflow.yaml file:

       # the workflow config
        payflow:
            ....
            ....
            marking_history_store:
                # the column name of where to store the history
                history_property: state_history
                # an optional field which will be stored with the history and then cleared, ready for next change 
                memo_property: current_state_note

This additional configuration inside the workflow will essentially help set up a listener that stores a history of states for that entity inside the trail_property field which listens for the workflow's entered event. An optional memo_property allows the user to store a brief description of the state change if required (e.g. payment verified by daniel, state automatically changed, admin changed state etc)

entity

The entity will be set up like this (with getters / setters omitted):

    /**
     * a note for the current state
     * @var string
     * @ORM\Column(type="string", length=255, nullable=true)
     */
    private $currentStateNote;

    /**
     * an archive of the states been through along with note and timestamps
     * @var array
     */
    private $stateHistory;

output

Upon a state change, the state history is populated with an assoc array that contains the state the entity is changed to, including a timestamp, the froms and tos, the name of the transition used, and the value of the optional memo field if not null. This array is appended to the existing array value, and is keyed by workflow name allowing histories of multiple workflow states to be stored if necessary.

A dd of the state history field after a few state changes:

array:1 [▼
  "payflow" => array:3 [▼ // the name of the workflow
    0 => array:4 [▼  // an assoc array detailing a state change 
           "timestamp" => "2018-08-25 15:16:23"
      "marking" => array:1 [▼
       0 => "not_shipped"
      ]
      "transition" => "awaiting_shipment"
      "memo" => "updating test"
    ]
    1 => array:4 [▼
      "timestamp" => "2018-08-25 15:16:23"
      "marking=> array:1 [▼
        0 => "shipped"
      ]
      "transition" => "item_shipped"
      "memo" => ""
    ]
    2 => array:4 [▼
      "timestamp" => "2018-08-25 15:16:23"
      "marking" => array:1 [▼
        0 => "received"
      ]
      "transition" => "received_delivery_needs_checking"
      "memo" => ""
    ]
  ]
]

I'd like to ask for comments on:

• does the config seem sensible? property names are good etc
• does the output seem reasonable?