From c2c7cbebac5b9efb968fe530c4d88d9da0b70f49 Mon Sep 17 00:00:00 2001
From: Matt McDonald <matt@wildside.uk>
Date: Fri, 20 Sep 2019 11:36:25 +0100
Subject: [PATCH] [ci skip] Updated README.md to document helper methods

---
 README.md | 32 ++++++++++++++++++++++++++------
 1 file changed, 26 insertions(+), 6 deletions(-)

diff --git a/README.md b/README.md
index 87c24da..122112f 100644
--- a/README.md
+++ b/README.md
@@ -17,7 +17,7 @@
 
 ## About Laravel Userstamps
 
-Laravel Userstamps provides an Eloquent trait which automatically handles `created_by` and `updated_by` columns on your model, populated by the currently authenticated user in your application. 
+Laravel Userstamps provides an Eloquent trait which automatically handles `created_by` and `updated_by` columns on your model, populated by the currently authenticated user in your application.
 
 When using the Laravel `SoftDeletes` trait, a `deleted_by` column is also handled by this package.
 
@@ -65,7 +65,7 @@ use Wildside\Userstamps\Userstamps;
 class Foo extends Model {
 
     use Userstamps;
-    
+
     const CREATED_BY = 'alt_created_by';
     const UPDATED_BY = 'alt_updated_by';
     const DELETED_BY = 'alt_deleted_by';
@@ -73,7 +73,7 @@ class Foo extends Model {
 ```
 
 When using this trait, helper relationships are available to let you retrieve the user who created, updated and deleted (when using the Laravel `SoftDeletes` trait) your model.
-    
+
 ```php
 $model -> creator; // the user who created the model
 $model -> editor; // the user who last updated the model
@@ -87,13 +87,13 @@ $model -> stopUserstamping(); // stops userstamps being maintained on the model
 $model -> startUserstamping(); // resumes userstamps being maintained on the model
 ```
 
-## Limitations
+## Workarounds
 
 This package works by by hooking into Eloquent's model event listeners, and is subject to the same limitations of all such listeners.
 
 When you make changes to models that bypass Eloquent, the event listeners won't be fired and userstamps will not be updated.
 
-Commonly this would happen if mass updating or deleting models, or their relations.
+Commonly this will happen if bulk updating or deleting models, or their relations.
 
 In this example, model relations are updated via Eloquent and userstamps **will** be maintained:
 
@@ -104,7 +104,7 @@ $model->foos->each(function ($item) {
 });
 ```
 
-However, in this example, model relations are mass updated and bypass Eloquent. Userstamps **will not** be maintained:
+However in this example, model relations are bulk updated and bypass Eloquent. Userstamps **will not** be maintained:
 
 ```php
 $model->foos()->update([
@@ -112,6 +112,26 @@ $model->foos()->update([
 ]);
 ```
 
+As a workaroud to this issue two helper methods are available - `updateWithUserstamps` and `deleteWithUserstamps`. Their behaviour is identical to `update` and `delete`, but they ensure the `updated_by` and `deleted_by` properties are maintained on the model.
+
+ You generally won't have to use these methods, unless making bulk updates that bypass Eloquent events.
+
+ In this example, models are bulk updated and userstamps **will not** be maintained:
+
+```php
+$model->where('name', 'foo')->update([
+    'name' => 'bar',
+]);
+```
+
+However in this example, models are bulk updated using the helper method and userstamps **will** be maintained:
+
+```php
+$model->where('name', 'foo')->updateWithUserstamps([
+    'name' => 'bar',
+]);
+```
+
 ## Sponsors
 
 <a href="https://wildside.uk">