zairakai / laravel-activity
History of the pivot tables of Eloquent many-to-many relations, built on Spatie Laravel Activity Log
Package info
gitlab.com/zairakai/php-packages/laravel-activity
pkg:composer/zairakai/laravel-activity
Requires
- php: ^8.4
- illuminate/contracts: ^12.0 || ^13.0
- illuminate/database: ^12.0 || ^13.0
- illuminate/support: ^12.0 || ^13.0
- spatie/laravel-activitylog: ^5.1.3
Requires (Dev)
- ergebnis/composer-normalize: ^2.58
- orchestra/testbench: ^10.0 || ^11.3
- phpunit/phpunit: ^12.5.45
- zairakai/laravel-dev-tools: ^5.5
Suggests
- ergebnis/composer-normalize: Automated composer.json normalization
Provides
None
Conflicts
None
Replaces
None
README
zairakai/laravel-activity
Activity logs for the changes of Eloquent many-to-many relationships, built on Spatie Laravel Activity Log.
Documentation: laravel-activity-a54436.gitlab.io
Features
- History of the pivot table: a pivot table has no model, so each entry keeps its rows before and after the change.
- Fluent API:
->activity()on aBelongsToManyorMorphToManyrelation, thenattach,detach,sync,syncWithoutDetaching,toggleorupdateExistingPivot. - Built on Spatie: same causer, log name and enable switch, with the data in
attribute_changes. - Safe: sensitive columns (
password,token…) are never logged, and nothing is logged when nothing changes. TraceActivitiestrait: the entries a model caused, the ones on it, and the ones where it is on the other side of a relation.
Requirements
PHP 8.4 or higher, Laravel 12 or 13, and spatie/laravel-activitylog 5 (installed with the package, with its activity_log table migrated: Spatie ships no migration for a table of an older version, see its upgrade guide).
Install
composer require zairakai/laravel-activity
php artisan vendor:publish --tag=laravel-activity-config # optional
Configuration
The package has one optional config file, config/laravel-activity.php.
| Key | Role |
|---|---|
log_name | log of the entries (pivot by default, ACTIVITY_PIVOT_LOG_NAME), null for the default log of Spatie |
hidden_columns | columns of the pivot tables never written in the log (password, remember_token, token, api_token, secret by default) |
use_pivot_hidden | true by default (ACTIVITY_PIVOT_USE_HIDDEN): also leave out the $hidden of the pivot model (->using(RoleUser::class)) |
Usage
$user->roles()
->activity()
->by(auth()->user())
->withMessage('Assigned roles')
->sync([1, 2, 3]);
$user->tags()->activity()->attach(5);
$user->tags()->activity()->detach(5);
What an entry contains
One entry per operation. The subject is the parent model, the `event` is the operation (`attached`, `detached`, `synced`, `synced_without_detaching`, `toggled`, `updated_pivot`), the `properties` hold the relation, the pivot table and the type of the related model, and `attribute_changes` hold the pivot rows before (`old`) and after (`attributes`), by ID of the related model, only for the rows that changed. Detaching the role 3 from the user 1: ```json { "event": "detached", "log_name": "pivot", "description": "Detached 1 role", "properties": { "relation": "roles", "table": "role_user", "related_type": "App\\Models\\Role" }, "attribute_changes": { "old": { "3": { "user_id": 1, "role_id": 3, "granted_by": "System" } }, "attributes": [] } } ``` An attached row is only in `attributes`, a detached one only in `old` (with all its columns, so it can be restored), a modified one in both.Causer, message, log and columns
- `->by($model)`, `->by($id)` and `->byAnonymous()` work as in Spatie (`causedBy()` and `causedByAnonymous()` too). Without a causer, Spatie decides. - `->withMessage('…')` is for the next operation only. - `->inLog('audit')` writes the entries of the instance in another log. - `->withoutColumns(['granted_by'])` leaves more columns out of the rows. - When Spatie is disabled, the operation runs and nothing is written.Query the entries of a model
```php use Zairakai\LaravelActivity\Traits\TraceActivities; $user->activities()->on()->get(); // its relations changed $user->activities()->by()->get(); // caused by the user $user->activities()->all(); // both $role->activities()->related()->get(); // where the role was attached or detached, on any user ``` `related()` filters on the `log_name` (indexed) before it reads the JSON, so it does not find the entries written with `->inLog()` in another log. On a big table, an index on the JSON paths of your database helps.Development
See CONTRIBUTING.md for the workflow and the quality standards. composer install and make install-hooks set the package up.
make quality # Pint, PHPStan and Markdownlint (with the rest of the gate)
make quality-fast # Pint, PHPStan and Markdownlint
make quality-fix # every automatic fix
make test # PHPUnit
make bats # the structure tests of the repository
make ci # the whole gate: quality, tests and Bats
The configuration of each tool is in config/dev-tools/, one file per setting. These files come from laravel-dev-tools: make setup-check tells which ones are late on the package (make setup-update publishes them again).
Statistics
Contributing
Contributions are welcome. Please read CONTRIBUTING.md for the project-specific workflow and quality standards.
Getting Help
Made with ❤️ by Zairakai