sacred96 / timeline
Easy way to create timeline with Laravel
Requires
- php: ^7.1
- laravel/framework: ~5.8.0
README
Create a timeline history featuring different models
Introduction
This package allows you to add a timeline service to your Laravel ^5.8 application
Installation
From the command line, run:
composer require sacred96/timeline
Publish the assets:
php artisan vendor:publish
Run the migrations:
php artisan migrate
Usage
You can specify different Models as participants. Optionally, you can specify the model as the timeline initiator by making it the owner of the timeline. For example, you can have Invoice
and Companies
models that are participants in the timeline
Main idea
You create a timeline history by specifying multiple models as story participants. When there is an initiating model among the participants, it must use the TimelineInitiator
trait. For example, for the history of article moderation, the article will be the initiator.
After creating the timeline, you add events to the history with an indication of its author. Additionally, you can specify a detailed comment for the event.
History may have actual state. For example, the initiator model expects user action. This can be indicated in the current state of the timeline. When the story ends, you mark the timeline as complete.
Adding the ability to participate in timeline
Add the Sacred96\Timeline\Traits\Eventable
trait to any Model you want to participate in Timeline history.
Indicate that the model is the initiator of the timeline
Add the trait Sacred96\Timeline\Traits\TimelineInitiator
to indicate that this model is the initiator of the timeline.
This can be useful if you want to highlight different sides of the timeline. Let's say you have an invoice that started the timeline. Here he is the initiator. The rest of the actors, such as the invoiced company, will simply be a participant in the timeline.
Creating the timeline history
You can start a timeline history with an array of models as participants. You can also set the current state.
$history = Timeline::create([$invoiceModel, $userModel, ..., $anotherModel], 'Initial state');
Get timeline history by id
$history = Timeline::history()->getById($id);
Add a new event to history
Timeline::event('Event text') ->from($eventableModel) ->to($history) ->withComment('Extended comment to event') ->push();
Get event by id
Timeline::events()->getByID($id);
Get event info
$event->author; // event author $eventSide = $event->side(); // event side: [initiator_side|second_side]
Timeline history actual state
$history->switchState('New state text'); // Set timeline actual state $history->getCurrentState(); // Get timeline actual state
Additional function of timeline history
Timeline::history($history)->getParticipants(); // get all participants of timeline history Timeline::history($history)->removeParticipants([$participant1, $participant2]); // delete multiple participants Timeline::history($history)->getEvents('desc'); // get all events of history with sort Timeline::history($history)->makeFinished(); // make history as finished Timeline::history($history)->isFinished(); // check if the story is complete
License
Timeline package is open-sourced software licensed under the MIT license