library userstamps

wildside/userstamps

Eloquent trait to automatically maintain created_by and updated_by (and deleted_by when using SoftDeletes) on your models

, _(*1)

About Laravel Userstamps

Laravel Userstamps provides an Eloquent trait which automatically maintains created_by and updated_by columns on your model, populated by the currently authenticated user in your application., _(*2)

When using the Laravel SoftDeletes trait, a deleted_by column is also handled by this package., _(*3)

Installing

This package requires Laravel 9 or later running on PHP 8.2 or higher., _(*4)

This package can be installed using composer:, _(*5)

composer require wildside/userstamps

Usage

Your model will need to include a created_by and updated_by column, defaulting to null., _(*6)

If using the Laravel SoftDeletes trait, it will also need a deleted_by column., _(*7)

The column type should match the type of the ID column in your user's table., _(*8)

Userstamp columns can be created using:, _(*9)

$table->userstamps();
$table->userstampSoftDeletes();

You can now load the trait within your model, and userstamps will automatically be maintained:, _(*10)

use Mattiverse\Userstamps\Traits\Userstamps;

class Foo extends Model {

    use Userstamps;
}

Optionally, should you wish to override the names of the created_by, updated_by or deleted_by columns, you can do so by setting the appropriate class constants on your model. Ensure you match these column names in your migration., _(*11)

use Mattiverse\Userstamps\Traits\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';
}

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., _(*12)

$model->creator; // the user who created the model
$model->editor; // the user who last updated the model
$model->destroyer; // the user who deleted the model

Methods are also available to temporarily stop the automatic maintaining of userstamps on your models:, _(*13)

$model->stopUserstamping(); // stops userstamps being maintained on the model
$model->startUserstamping(); // resumes userstamps being maintained on the model

Resolving Users

By default users will be resolved using the Laravel Auth::id() method, to return the ID of the currently authenticated user., _(*14)

More advanced use-cases are supported with a custom resolution strategy., _(*15)

In this example, a custom resolution method is called to retrieve the ID., _(*16)

use Mattiverse\Userstamps\Userstamps;

Userstamps::resolveUsing(
    fn () => auth()->user()->customUserIdResolutionMethod()
);

The Userstamps::resolveUsing method is likely best suited to the boot method of AppServiceProvider., _(*17)

Workarounds

This package works by hooking into Eloquent's model event listeners, and is subject to the same limitations of all such listeners., _(*18)

When you make changes to models that bypass Eloquent, the event listeners won't be fired and userstamps will not be updated., _(*19)

Commonly this will happen if bulk updating or deleting models, or their relations., _(*20)

In this example, model relations are updated via Eloquent and userstamps will be maintained:, _(*21)

$model->foos->each(function ($item) {
    $item->bar = 'x';
    $item->save();
});

However in this example, model relations are bulk updated and bypass Eloquent. Userstamps will not be maintained:, _(*22)

$model->foos()->update([
    'bar' => 'x',
]);

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., _(*23)

You generally won't have to use these methods, unless making bulk updates that bypass Eloquent events., _(*24)

In this example, models are bulk updated and userstamps will not be maintained:, _(*25)

$model->where('name', 'foo')->update([
    'name' => 'bar',
]);

However in this example, models are bulk updated using the helper method and userstamps will be maintained:, _(*26)

$model->where('name', 'foo')->updateWithUserstamps([
    'name' => 'bar',
]);

License

This open-source software is licensed under the MIT license., _(*27)