README

# Laravel Logger v1.0

Laravel Logger was made to keep track of Model history! When you have an application with multiple user roles, it is important to know who made changes to the application Database. Laravel Logger can help you do that with an easy setup!

With Laravel Logger you can:

Keep track of of model change history
Have a clean front-end to view model changes
Sync model with previous states
Export model history (CSV, PDF) from a Date Range or its full history
View everything from a clean and responsive front-end

# Compatibility Chart

Laravel Logger	Laravel	PHP
^1.0	5.5	>=7.0

# Installation

Require our package:

composer require hvlucas/laravel-logger 1.0

Publish required files and select the number corresponding to this package:

php artisan vendor:publish

Which provider or tag's files would you like to publish?:
  [0 ] Publish files from all providers and tags listed below
  [X ] Provider:  HVLucas\Laravel Logger\Laravel LoggerServiceProvider

Setup your config/laravel_logger.php and then run migrations:

php artisan migrate

# Configuration

There are a few configurations that can be set from the get-go. They are all optional, but will improve flexibility. Since Laravel Logger is configured at compiler-time (when your application's Service Providers are being booted), it is important to setup your config file before running php artisan migrate (first time installation). Otherwise, it will try to auto-discover models in your app/ directory, and create a copy of each database row available.
Each model row will have a startpoint. Meaning from the moment Laravel Logger's service provider boots up, it will try to find a model instance which has not started its tracking yet. Which is why it would be benefitial for you to fully understand the configuration!

Config	Type	Default	What it does
route_prefix	string	"events"	Route prefix which the list of events is going to be. `https://{server_domain}/{your_custom_prefix}/list/`
log_connection	string	`null`	If you wish to store model instances in a different database you create a connection in `config/database.php`.
table_name	string	"logged_events"	Name of Event table that is going to be created.
user_model	string	"App\User"	Authenticated user class name in which an Event will be associated with. Make sure to include namespacing.
user_column	string	`null`	Column for the associated user of an Event to be displayed in the front-end. Omitting this option will display their Primary Key by default.
loggable_models	string\|array	`null`	Ommitting this option will cause Laravel Logger to go through your `app` folder to automatically search for models to track.
discover_path	string	"app/"	If `loggable_models` is `null`, this config can set the path in which Laravel Logger will automatically search for models to track.
discover_namespace	string	"App"	If `loggable_models` option is left blank, this option can be set to define the namespace of your `discover_path`.
auth_middleware	string	"auth"	Middleware name for only allowing authenticated users to access this package.

# Configuration - Initialization by Config

This is a list of available sub-options for the loggable_models option:

Option	Type	Required	Default	Description
model	string	yes	`null`	Model which is going to be tracked.
trackable_attributes	string\|array	no	`null`	Which attributes which will be stored when an event happens. If this is not set, it will pull all non-hidden attributes.
sync_attributes	string\|array	no	`null`	Which attributes will update when syncing model. When this is not set, it will default to `trackable_attributes`. Columns must exist in model table.
only_when_authenticated	bool	no	`false`	Events will only be logged if there is an authenticated user present. This will default to `false` if `tracks_user` is also `false`.
tracks_data	bool	no	`true`	Are attributes going to be tracked? Setting `tracks_data` to `false` will overwrite `trackable_attributes` and `sync_attributes` to `[]`.
tracks_user	bool	no	`true`	Is the authenticated user being tracked?
is_favorite	bool	no	`false`	Show this model in the beginning of the event's tabs container. Models are sorted by favoritism then alphabetically.

An advantage of Laravel Logger is that it incorporates Laravel's accessors.

class MyClass extends Model 
{
    public function getPrettyWeightAttribute()
    {
        return (int) $this->weight / 1.5;
    }
    //...
}

Then add the attribute to your config/laravel_logger.php options.

'loggable_models' => [
    [
        'model' => 'App\Model',
        'trackable_attributes' => [...,'pretty_weight',...]
    ],
    //...
],

To read more about accessors, check Laravel's documentation

# Configuration - Initialization by Model

You can set up loggable_models in many different ways. Just passing a string will only track one model and its attributes.
For example:

'loggable_models' => 'App\MyClass'
//or
'loggable_models' => ['App\MyClass', 'App\SpecialModelNamespace\Team']

There are ways you can configure what will be tracked through the model itself. In each file, you can set protected properties which will do the trick for Laravel Logger:

class MyClass extends Model 
{
    protected $trackable_attributes = ['name', 'title', 'role_id', 'salary', 'gender'];
    protected $sync_attributes = ['name', 'title', 'gender'];
    protected $tracks_user = false;
    protected $tracks_data = true;
    protected $is_favorite = true;
    //...
}

# Configuration - Sensitive Data

In case you don't want to store/display sensitive data, you can use Laravel's hidden attributes (or set trackable_attributes config). Laravel Logger will automatically ignore id, created_at, updated_at, deleted_at, unless specified.

class MyClass extends Model 
{
    protected $hidden = ['password'];
}

# Events

# Events- Middleware

If there are routes in your application where the instace doesn't get updated/deleted/restored, then you have the flexibility to add log_event middleware to your routes or controller __construct():

routes/web.php

Route::get('/fecthing-model/{model_id}/', 'FetchingController@fetch')->middleware('log_event');

app\Http\Controllers\FecthingController.php

public function __construct(...)
{
    $this->middleware('log_event')->only('fetch');
}

Laravel Logger will parse through the parameters in the request and look for your model instance! The default event name will be retrieved. Of course, you can pass a different name like so:

    $this->middleware('log_event:jumped');

Just be careful passing log_event middleware to methods that update/delete/restore your model instace, since it will be logged multiple times! To read more about middlewares check out Laravel's documentation

# Events - Filtering

Laravel Logger takes advantages of Server-Side Processing DataTables has to offer. By clicking on individual tags, we can start filtering by them.

Here are some other keywords you can use in the search bar. You can also use regular keywords, which will filter through every record on the table server-sided.

Keyword	Tags
tag/tags	All available tags
users/user	Authenticated user Primary Key/Column tags
event/events	All events
activity/activities	Alias for event
method/methods	Method type associated with event
request/requests	Alias for method

# Events - Syncing

Laravel Logger can keep track of your model well, but it can also sync your model to a point in time when necessary! You can click on the ID of the model you wish to inspect with more detail.

When you click on the ID of the Model, you are able to see the all time history of the selected ID. If the highlighted history is too far apart to read or there are too many events, then you can slide the top right slider for a more appropriate timeline. You can also hover highlighted sections, which represent an event that took place in the model's timeline.

By clicking on the sync icon, a modal will popup defining which columns will be updated. Check the attribute checkboxes you wish to update and click sync. When syncing, Laravel Logger will create a SYNC event instance. It is important to note that sync_attributes option need to have valid model's table columns.

# Events - Model Actions

Laravel Logger gives you a few options out of the box. You can select individual/all rows for archiving/deletion. When an archived row gets deleted it will be deleted permanently, so you have been warned! Event deletions are not kept on the record list. Selecting 'all' rows will only select the current page you are in, but you can select a bigger scope (50, 150, 300, 500, All) from the Show dropdown above.

Exporting, in the other hand, will export the whole table. The filters you applied will also be taken into the query.

TODO

Add middleware section

# Testing

None as of yet, sorry guys :(

# Incoming features

I like to keep it fresh. There are a few ideas I have in mind for this package that I would like to start working on as soon as I have time:

Coloring of custom middleware tags
More options when exporting
- Ommiting columns
- Flexibility to change the date format of 'When' column
More filtering options
- Date range/picker
- Filter by Model ID
Language & Translations Support
- Add support for different languages on the front-end
Tooltips
- Maybe you have a business manager that wants to use this tool, having help tooltips can be nice
Compact mode
- Ommit certain columns so the table is a little more compact
Cleanup front-end a little more. I know can do better. But hey I'm a developer not a designer, so Bootstrap 4 is what you get for right now
Bootstrap version control

# Development

If you have any ideas to contribute or bug fixes in mind:

Fork the repo
Create a PR for me to take a look

hvlucas / laravel-logger

Maintainers

Details