README

This package provides a trait that tracks the user responsible for creating, modifying, or deleting an Eloquent model.

Accountable will observe any activity on your models and it sets the created_by_user_id, updated_by_user_id, and deleted_by_user_id accordingly using the currently authenticated user.

It also provides you with some useful scope query functions, allowing you to fetch models that were either created, modified, or deleted by a specific user.

Table of Contents

• Installation
• Usage
  • Using the Migration helper
  • Using the Trait
• Examples
• Tests
• Changelog
• Contributing
• Credits
• License

Installation

This package can be installed through Composer:

$ composer require testmonitor/laravel-accountable

The package will automatically register itself.

Optionally, publish the configuration file:

$ php artisan vendor:publish --provider="TestMonitor\Accountable\AccountableServiceProvider" --tag="config"

The configuration file allows you to set the preferred authentication driver, the database column names, and anonymous user. The latter can be used to deal with records created/updated by unauthenticated users.

When left untouched, Accountable will use the default authentication driver and the default column names (created_by_user_id, updated_by_user_id, and deleted_by_user_id).

Usage

In order to add Accountable to your Laravel application, you'll need to:

1. Add the required columns to your migration file(s).
2. Use the trait TestMonitor\Accountable\Traits\Accountable on your model(s).

Please note that due to the nature of Laravel event system, mass updates will not be handled by Accountable.

Using the Migration helper

The migration helper simplifies the process of adding columns to your migration:

use TestMonitor\Accountable\Accountable;

class CreateProjectsTable extends Migration
{
    public function up()
    {
        Schema::create('projects', function (Blueprint $table) {
            $table->increments('id');
            $table->string('name');

            $table->timestamps();
            $table->softDeletes();

            // This will add the required columns
            Accountable::columns($table);
        });
    }
}

Tip: if you do not use soft-deletes on your model, use Accountable::columns($table, false) to prevent the helper from adding a deleted_by_user_id column.

Using the Trait

Add the Accountable trait on the models you want to track:

use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\SoftDeletes;
use TestMonitor\Accountable\Traits\Accountable;

class Project extends Model
{
    use Accountable, SoftDeletes;

    protected $table = 'projects';
}

Examples

Set up your model and make sure you are authenticated.

Basics

Create a project and show the name of the user that created it:

$project = new Project(['name' => 'Awesome project']);
$project->save();

// Show the name of user that created the project
echo $project->creator->name;

Get all projects created by a specific user:

$user = User::findOrFail(42);

// Get all projects created by user with id 42
Project::onlyCreatedBy($user)->get();

Properties

You can use the following properties and methods to reveal the user responsible for creating, updating or deleting the record.

// Get the user that created the model
$model->created_by_user_id;
$model->creator->name;

// Get the user that last updated the model
$model->updated_by_user_id;
$model->editor->name;

// Get the user that last deleted the model
$model->deleted_by_user_id;
$model->deleter->name;

Scope Queries

The following scope queries are at your disposal:

// Retrieve the models either created, updated,
// or deleted by $user.
Model::onlyCreatedBy($user)->get();
Model::onlyUpdatedBy($user)->get();
Model::onlyDeletedBy($user)->get();

// And one extra: get all models that were created
// by the currently authenticated user.
Model::mine()->get();

Disable Logging

In some cases, you don't want to automatically save the user along with the model (for example: when seeding test data). You can disable accountable by using the disableUserLogging method.

$project = new Project(['name' => 'Do not track me']);
$project->disableUserLogging()->save();

If you want to re-enable accountable, simply use the enableUserLogging method afterwards.

Impersonation

When authentication is not available - for example, when running jobs in a queue - you might want to "impersonate" a user. Simply override user identification with the actingAs method:

accountable()->actingAs($event->causer);

You can end the impersonation by calling the reset method.

Tests

The package contains integration tests. You can run them using PHPUnit.

$ vendor/bin/phpunit

Changelog

Refer to CHANGELOG for more information.

Contributing

Refer to CONTRIBUTING for contributing details.

Credits

• Thijs Kok - Lead developer - ThijsKok
• Stephan Grootveld - Developer - Stefanius
• Frank Keulen - Developer - FrankIsGek
• Muriel Nooder - Developer - ThaNoodle

• All Contributors

License

The MIT License (MIT). Refer to the License for more information.