diff --git a/CHANGELOG.md b/CHANGELOG.md index f2a7670..84a9481 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,10 +2,15 @@ All notable changes to `laravel-eloquent-state-machines` will be documented in this file +## v4.0.0 - 2021-02-12 + +- Added `changed_attributes` field in `state_histories` to record model old/new + values during transition (**Breaking change**) + ## v3.0.0 - 2021-02-10 - Added `beforeTransitionHooks` -- **Breaking Change**: Renamed `transitionHooks` to `afterTransitionHooks` and changed arguments for callbacks +- Renamed `transitionHooks` to `afterTransitionHooks` and changed arguments for callbacks (**Breaking Change**) - Refactored tests ## v2.3.0 - 2020-01-26 diff --git a/README.md b/README.md index 8b89b01..706c7fe 100644 --- a/README.md +++ b/README.md @@ -346,6 +346,29 @@ $salesOrder->status()->snapshotWhen('approved')->responsible; ## Advanced Usage +### Tracking Attribute Changes + +When `recordHistory()` is active, model state transitions are recorded in the `state_histories` table. Each transition +record contains information about the attributes that changed during the state transition. You can get information +about what has changed via the `changedAttributesNames()` method. This method will return an array of the attributes +names that changed. With these attributes names, you can then use the methods `changedAttributeOldValue($attributeName)` +and `changedAttributeNewValue($attributeName)` to get the old and new values respectively. + +```php +$salesOrder = SalesOrder::create([ + 'total' => 100, +]); + +$salesOrder->total = 200; + +$salesOrder->status()->transitionTo('approved'); + +$salesOrder->changedAttributesNames(); // ['total'] + +$salesOrder->changedAttributeOldValue('total'); // 100 +$salesOrder->changedAttributeNewValue('total'); // 200 +``` + ### Adding Validations Before transitioning to a new state, we can add validations that will allow/disallow the transition. To