Tracker
Eloquent CRUD records tracking for Laravel, (*1)
Installation
You can install this package via composer, (*2)
composer require panoscape/tracker
First, register service provider, (*3)
config/app.php, (*4)
'providers' => [
...
Panoscape\Tracker\TrackerServiceProvider::class,
];
Next, you may publish the config file with, (*5)
php artisan vendor:publish --provider="Panoscape\Tracker\TrackerServiceProvider" --tag=config
Migration, (*6)
php artisan vendor:publish --provider="Panoscape\Tracker\TrackerServiceProvider" --tag=migrations
php artisan migrate
Publish localization, (*7)
php artisan vendor:publish --provider="Panoscape\Tracker\TrackerServiceProvider" --tag=translations
Usage
Add Panoscape\Tracker\Context trait to any model(s) you'd like to track., (*8)
<?php
namespace App\Models;
use Illuminate\Database\Eloquent\Model;
use Panoscape\Tracker\Context;
class Project extends Model
{
use Context;
public function getContextLabel()
{
return $this->display_name;
}
...
}
Remember that you'll need to implement the abstract getContextLabel method from the trait.
This will add the specified name value to the records., (*9)
Created new Project project_001, (*10)
Context
A Context is a model which is tracked on CURD actions. Like in User 001 Deleted Project 001, Project 001 is the Context we're talking about here., (*11)
To get all records of a contexted model, (*12)
$project->records();
or via dynamic property, (*13)
$project->records;
You may change the name of records if you like(or to resolve method name conflicts), (*14)
use Context { records as logs; }
Agent
An Agent is a user who performs an action. Like in User 001 Deleted Project 001, User 001 is the Agent., (*15)
The agent in a record is always got from Auth, thus the authorized user when the action is being performed., (*16)
You might have multiple user types in your application, and this package take well care of it., (*17)
To be able to getting related records from an agent, all you need is to add Panoscape\Tracker\Agent trait to that model., (*18)
<?php
namespace App;
use Illuminate\Notifications\Notifiable;
use Illuminate\Foundation\Auth\User as Authenticatable;
use Illuminate\Database\Eloquent\SoftDeletes;
use Panoscape\Tracker\Agent;
class User extends Authenticatable
{
use SoftDeletes, Notifiable, Agent;
...
}
Get all records performed by an agent, (*19)
$user->records();
or via dynamic property, (*20)
$user->records;
You may change the name of records if you like(or to resolve method name conflicts), (*21)
use Agent { records as logs; }
A record's agent might be null if it's tracked while unauthenticated, (*22)
Record
The default strcuture of a record, (*23)
| Field |
Type |
Nullable |
| id |
big unsigned integer |
N |
| context_id |
unsigned integer |
N |
| context_type |
string |
N |
| agent_id |
unsigned integer |
Y |
| agent_type |
string |
Y |
| message |
string |
N |
| meta |
text |
Y |
| performed_at |
timestamp |
N |
The message filed is the action message in brief. examples, (*24)
Created new Project my_project, (*25)
Updating Project my_project, (*26)
Deleting Project my_project, (*27)
Restoring Project my_project, (*28)
The meta field is a json context of modified properties of a model. It's only available when the record is Updating ...., (*29)
The performed_at is a timestamp which indicates the moment the record is created, thus the moment the action being performed., (*30)
Get context of a record, (*31)
$record->context();
or via dynamic property, (*32)
$record->context;
Check agent of a record, (*33)
$record->hasAgent();
Get agent of a record, (*34)
$record->agent();
or via dynamic property, (*35)
$record->agent;
The meta property on Record is deserialized to an array, which hold the modification history, (*36)
$record->meta;
[
['key' => 'name', 'old' => 'myName', 'new' => 'myNewName'],
['key' => 'age', 'old' => 10, 'new' => 100],
...
]
Localization
You may lolcalize the record output, (*37)
This is the default localization, (*38)
<?php
return [
/*
|--------------------------------------------------------------------------
| Tracker Language Lines
|--------------------------------------------------------------------------
|
| The following language lines are used across application for various
| messages that we need to display to the user. You are free to modify
| these language lines according to your application's requirements.
|
*/
'created' => 'Created new :context :name',
'updating' => 'Updating :context :name',
'deleting' => 'Deleting :context :name',
'restored' => 'Restored :context :name',
];
Simplified Chinese, (*39)
<?php
return [
/*
|--------------------------------------------------------------------------
| Tracker Language Lines
|--------------------------------------------------------------------------
|
| The following language lines are used across application for various
| messages that we need to display to the user. You are free to modify
| these language lines according to your application's requirements.
|
*/
'created' => '创建新的:context :name',
'updating' => '更新:context :name',
'deleting' => '删除:context :name',
'restored' => '恢复:context :name',
];
The :context is by default the class's base name., (*40)
To localize it, you can append a new language line to the localization file with the key being the class base name in snake case, (*41)
<?php
return [
...
'project' => '项目',
'component_template' => '组件模板',
];
The :name is provided by getContextLabel which we have mentioned above., (*42)
Configuration
Here is the default Configuration, (*43)
<?php
return [
/*
|--------------------------------------------------------------
| Literally
|--------------------------------------------------------------
|
|
*/
'enabled' => true,
/*
|--------------------------------------------------------------
| Record table name
|--------------------------------------------------------------
|
|
*/
'records_table' => 'tracker_records',
/*
|--------------------------------------------------------------
| Operatiopn whitelist
|--------------------------------------------------------------
|
| Operations in this array will be recorded.
| Available operations are: created, updating, deleting, restored
|
*/
'operations' => [
'created', 'updating', 'deleting', 'restored',
],
/*
|--------------------------------------------------------------
| Agent blacklist
|--------------------------------------------------------------
|
| Operations performed by agents in this array will NOT be recorded.
| Please add the whole class names. Example: \App\User
| Use 'nobody' to bypass unauthenticated operations
|
*/
'agent_ignore' => [
],
/*
|--------------------------------------------------------------
| Enabled when application running in console
|--------------------------------------------------------------
|
| When application is running in console(include seeding)
|
*/
'console' => false,
/*
|--------------------------------------------------------------
| Enabled when application running in unit tests
|--------------------------------------------------------------
|
| When application is running unit tests
|
*/
'unit_test' => false,
/*
|--------------------------------------------------------------
| Enviroments blacklist
|--------------------------------------------------------------
|
| When application's environment is in the list, tracker will be disabled
|
*/
'env_ignore' => [
],
];
To change the table hodling the records, set records_table. Remember to update your migration after that., (*44)
To apply filters to operations, set operations. Only operations in the list will be tracked., (*45)
To apply filters to agents, set agent_ignore. Operations performed by agents in the list will NOT be tracked., (*46)
If you'd like to bypass an unauthenticated operation, add 'nobody' to agent_ignore., (*47)
If you need to bypass a specific agent type, add it's class name to agent_ignore., (*48)
Wallogit.com
