diff --git a/content/collections/extending-docs/data.md b/content/collections/extending-docs/data.md index ec3ee428b..4a7bba64d 100644 --- a/content/collections/extending-docs/data.md +++ b/content/collections/extending-docs/data.md @@ -268,3 +268,44 @@ $entry->toAugmentedCollection(['title', 'collection']); ``` The `toAugmentedArray` method does the same as `toAugmentedCollection`, except that it returns an array. + + +### Checking for data changes + +Statamic provides the `isDirty`, `isClean`, and `getOriginal` methods so you can determine what data has changed from when the item was originally retrieved. + +The `isDirty` method checks if any of the item's data has been changed since it was last saved. You may pass a specific attribute name or an array of attributes to the `isDirty` method to determine if any of the attributes are "dirty". The `isClean` method will determine if an attribute has remained unchanged since the item was retrieved. This method also accepts an optional attribute argument: + +```php +$entry->title; // "Post title" +$entry->image; // "/path/to/image.jpg" + +$entry->title = 'New Title'; + +$entry->isDirty(); // true +$entry->isDirty('title'); // true +$entry->isDirty('image'); // false +$entry->isDirty(['image', 'title']); // true + +$entry->isClean(); // false +$entry->isClean('title'); // false +$entry->isClean('image'); // true +$entry->isClean(['image', 'title']); // false + +$entry->save(); + +$entry->isDirty(); // false +$entry->isClean(); // true +``` + +The `getOriginal` method returns an array containing the original attributes of the item regardless of any changes to the item since it was retrieved. This method also accepts an optional attribute argument: + +```php +$entry->title; // "Post title" +$entry->image; // "/path/to/image.jpg" + +$entry->title = 'New Title'; + +$entry->getOriginal('title'); // "Post title" +$entry->getOriginal(); // ["Post title", "/path/to/image.jpg"] +```