Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/tappnetwork/filament-auditing
A Filament plugin for Laravel Auditing package.
https://github.com/tappnetwork/filament-auditing
audit auditing filament hacktoberfest hacktoberfest2022 laravel php plugin
Last synced: 6 days ago
JSON representation
A Filament plugin for Laravel Auditing package.
- Host: GitHub
- URL: https://github.com/tappnetwork/filament-auditing
- Owner: TappNetwork
- Created: 2022-08-14T23:20:31.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2024-12-12T18:48:08.000Z (about 2 months ago)
- Last Synced: 2025-01-17T16:13:41.543Z (13 days ago)
- Topics: audit, auditing, filament, hacktoberfest, hacktoberfest2022, laravel, php, plugin
- Language: PHP
- Homepage:
- Size: 85 KB
- Stars: 85
- Watchers: 4
- Forks: 22
- Open Issues: 8
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
Awesome Lists containing this project
README
# Filament Laravel Auditing
[](https://packagist.org/packages/tapp/filament-auditing)
[](https://packagist.org/packages/tapp/filament-auditing)
A Filament plugin for [Laravel Auditing](https://laravel-auditing.com/) package.
This plugin contains a relation manager for audits that you can add to your Filament resources.
This package provides a Filament resource manager that shows a table with all audits on view and edit pages and allows
restore audits.
## Installation
> **Note**
> This plugin uses the [Laravel Auditing](https://laravel-auditing.com/) package. First install and configure this
> package.
You can install the plugin via composer:
```bash
composer require tapp/filament-auditing:"^3.0"
```
> **Note**
> For **Filament 2.x** check the **[2.x](https://github.com//TappNetwork/filament-auditing/tree/2.x)** branch
You can publish the view files with:
```bash
php artisan vendor:publish --tag="filament-auditing-views"
```
You can publish the translation files with:
```bash
php artisan vendor:publish --tag="filament-auditing-translations"
```
You can publish the config file with:
```bash
php artisan vendor:publish --tag="filament-auditing-config"
```
This is the content of the published config file:
```php
[
'column' => 'created_at',
'direction' => 'desc',
],
'is_lazy' => true,
'audits_extend' => [
// 'url' => [
// 'class' => \Filament\Tables\Columns\TextColumn::class,
// 'methods' => [
// 'sortable',
// 'searchable' => true,
// 'default' => 'N/A'
// ]
// ],
]
'custom_audits_view' => false,
'custom_view_parameters' => [
],
'mapping' => [
],
];
```
The `audits_sort` can be used to change the default sort on the audits table.
## Usage
To show the audits table in your Filament resource, just add `AuditsRelationManager::class` on your
resource's `getRelations` method:
```php
use Tapp\FilamentAuditing\RelationManagers\AuditsRelationManager;
public static function getRelations(): array
{
return [
// ...
AuditsRelationManager::class,
];
}
```
That's it, you're all set!
If you access your resource, and edit some data, you will now see the audits table on edit and view pages.
### Extending Columns
In case you need to add a column to the AuditsRelationManager that does
not already exist in the table, you can add it in the config using the format denoted in the example below, and it will be
prepended to the table builder. The name of the column to be added is the key of an associative array that contains other information about the class, as shown in the example below. The class instance of the column must be added, but the methods can be left out if not required, or added wherever necessary.
```php
[
'url' => [
'class' => \Filament\Tables\Columns\TextColumn::class, // required
'methods' => [
'sortable',
'default' => 'NIL',
],
],
]
];
```
After adding this information in the config, please run this command for changes to take place.
```bash
php artisan optimize
```
Methods with two or more parameters can be specified with an array like so:
```php
[
'created_at' => [
'class' => \Filament\Tables\Columns\TextColumn::class, // required
'methods' => [
'sortable',
'date' => ['Y-m-d H:i:s', 'America/New_York'],
],
],
]
];
```
### Custom View Data Formatting
If you want to modify the content of the audit to display the old and new values in a specific way, such as showing the value of a specific column instead of the ID for relationships, or even customize the entire view to display data in a different way than the default table, you can use one of these methods described below (first, make sure the plugin views are published):
#### Show a related column instead of foreign id
To use another field to be displayed for relationships instead of the foreign id, in old and new values, you can add on the `mapping` array, in `filament-auditing.php` config file, the label and field that should be displayed, as well as the related model, using the foreign key as the array key. For example, on an `user` relationship with the `user_id` foreing key, this config will display the user `name` along with the `User` label:
```bash
'mapping' => [
'user_id' => [
'model' => App\Models\User::class,
'field' => 'name',
'label' => 'User',
],
],
```
And you'd like to customize the view, you can do it in the published view `views/vendor/filament-auditing/tables/columns/key-value.blade.php` file.
#### Customizing the Old and New Values
If you need to customize the presentation for other old and new values, besides the related fields, you can add a `formatAuditFieldsForPresentation($field, $record)` method on the model that is auditable, with two parameters:
- the first parameter contains the name of the field (`old_values` or `new_values`).
- the second parameter contains de current audit record
This method must return the formatted audit fields.
For example, let's say you have an `Article` model that is auditable and contains a related user, and you added a `formatAuditFieldsForPresentation($field, $record)` method that returns the related user name instead of the id, and the data formatted with some HTML code:
```php
{$field});
$formattedResult = '
- ';
- ';
$formattedResult .= match ($key) {
'user_id' => 'User: '.User::find($record->{$field}['user_id'])?->name.'
',
'title' => 'Title: '.(string) str($record->{$field}['title'])->title().'
',
'order' => 'Order: '.$record->{$field}['order'].'
',
'content' => 'Content: '.$record->{$field}['content'].'
',
default => ' - ',
};
$formattedResult .= ' ';
foreach ($fields as $key => $value) {
$formattedResult .= '
}
$formattedResult .= '
return new HtmlString($formattedResult);
}
public function user(): BelongsTo
{
return $this->belongsTo(User::class);
}
}
```
#### Customizing the Entire View Content
If you'd like to customize the entire view content, you may set the `custom_audits_view` config value to `true` on `config/filament-auditing.php` file:
```php
'custom_audits_view' => true,
```
This modification will allow you to take full control of the display and tailor it to your specific requirements. You can now add your custom content on `resources/views/vendor/filament-auditing/tables/custom-audit-content.blade.php` file.
For example:
```php
@php
$type = (string) str(class_basename($owner))->lower();
@endphp
@if(isset($records))
@foreach($headers as $header)
{{$header}}
@endforeach
@foreach($records as $audit)
@foreach ($audit->getModified() as $attribute => $modified)
@lang($type.'.metadata', $audit->getMetadata())
@php
$current = $type.'.'.$audit->event.'.modified.'.$attribute;
$modified['new'] = $owner->formatFieldForPresentation($attribute, $modified['new']);
if (isset($modified['old'])) {
$modified['old'] = $owner->formatFieldForPresentation($attribute, $modified['old']);
}
@endphp
@lang($current, $modified)
@endforeach
@endforeach
@else
@lang($type.'.unavailable_audits')
@endif
```
The owner record is available to this view via `$owner` variable. To pass some additional parameters to the view, you may use the `custom_view_parameters` config:
```php
'custom_view_parameters' => [
'headers' => [
'Audit',
],
],
```
To format a field, you may also add a `formatFieldForPresentation` method on the owner model, with the field name and value as parameters, like in the example above. This method must return a formatted field.
For example, in an `Article` model, to return the name of the related user:
```php
public function formatFieldForPresentation($field, $value)
{
return match($field) {
'user_id' => $value ? optional(User::find($value))->name : $value,
default => $value,
};
}
```
An example of the `article.php` lang file content used in the `custom-audit-content.blade.php` view code above:
```php
'No article audits available',
'metadata' => 'On :audit_created_at, :user_name [:audit_ip_address] :audit_event this record via :audit_url',
'updated' => [
'modified' => [
'order' => 'The Order has been modified from :old to :new',
'title' => 'The Title has been modified from :old to :new',
'content' => 'The Content has been modified from :old to :new',
'user_id' => 'The User has been modified from :old to :new',
],
],
];
```
### Permissions
Two permissions are registered by default, allowing access to:
- `audit`: view audits
- `restoreAudit`: restore audits
You can override these permissions by adding a policy with `audit` and `restoreAudit`.
### Event emitted
The `auditRestored` event is emitted when an audit is restored, so you could register a listener using the $listeners property to execute some extra code after the audit is restored.
E.g.: on Edit page of your resource:
```php
protected $listeners = [
'auditRestored',
];
public function auditRestored()
{
// your code
}
```
### Event listener
The audits relation manager listen to the `updateAuditsRelationManager` event to refresh the audits table.
So you can dispatch this event in the Edit page of your resource (e.g.: in a edit page of a `PostResource` -> `app/Filament/Resources/PostResource/Pages/EditPost.php`) when the form is updated:
```php
protected function afterSave(): void
{
$this->dispatch('updateAuditsRelationManager');
}
```
> [!WARNING]
> When dispaching this event, set the [is_lazy](https://filamentphp.com/docs/3.x/panels/resources/relation-managers#disabling-lazy-loading) configuration to `false`, on `filament-auditing.php`
> config file, to avoid this exception: "Typed property Filament\Resources\RelationManagers\RelationManager::$table
> must not be accessed before initialization"