README

Backend API to handle your ticket system.

Introduction
Installation
Configuration
Preparing your model
Model customization
Usage
API Methods
Handling File Upload
Event System
Testing
Changelog
Contributing
Security Vulnerabilities
Credits
License

Introduction

Laravel Ticket package, is a Backend API to handle your ticket system, with an easy way. It was forked from CoderFlex Laravel-ticket and refactored to allow model updates and be more flexible to match your app requirements.

Main differences:

All models can be copied and altered to meet your requirements; all you need to do is change the paths in config/laravel-ticket.php.
Tickets can be assigned to a user model, groups, or teams via a polymorphic many-to-many relationship.
Messages model was renamed to Comments model for semantic purposes.
Event support is provided for changes of state in both the Ticket and Comment models.

Installation

You can install the package via composer:

composer require Renatoxm/laravel-ticket

Configuration

You can publish the config file with:

php artisan vendor:publish --tag="ticket-config"

You can publish and run the migrations with:

php artisan vendor:publish --tag="ticket-migrations"

Before Running the migration, you may publish the config file, and make sure the current tables does not make a conflict with your existing application, and once you are happy with the migration table, you can run

php artisan migrate

Preparing your model

Add HasTickets trait into your User model, along with CanUseTickets interface

...
use Renatoxm\LaravelTicket\Concerns\HasTickets;
use Renatoxm\LaravelTicket\Contracts\CanUseTickets;
...
class User extends Model implements CanUseTickets
{
    ...
    use HasTickets;
    ...
}

Model customization

You can copy one or more of the package models to your App/Models folder to customize them to suit your needs. All you need to do is change the class paths in your config/laravel-ticket.php and you are good to go.

    'model' => [
        'category' => Renatoxm\LaravelTicket\Models\Category::class,
        'label' => Renatoxm\LaravelTicket\Models\Label::class,
        'comment' => Renatoxm\LaravelTicket\Models\Comment::class,
        'ticket' => Renatoxm\LaravelTicket\Models\Ticket::class,
    ],

Usage

The Basic Usage of this package, is to create a ticket, then associate the labels and the categories to it.

You can associate as many as categories/labels into a single ticket.

Here is an example

use Renatoxm\LaravelTicket\Models\Ticket;
use Renatoxm\LaravelTicket\Models\Category;
use Renatoxm\LaravelTicket\Models\Label;

...
public function store(Request $request)
{
    /** @var User */
    $user = Auth::user();

    $ticket = $user->tickets()
                    ->create($request->validated());

    $category = Category::first();
    $label = Label::first();

    $ticket->attachCategories($category);
    $ticket->attachLabels($label);

    // or you can create the categories & the tickets directly by:
    // $ticket->categories()->create(...);
    // $ticket->labels()->create(...);

    return redirect(route('tickets.show', $ticket->uuid))
            ->with('success', __('Your Ticket Was created successfully.'));
}

public function createLabel()
{
    // If you create a label seperated from the ticket and wants to
    // associate it to a ticket, you may do the following.
    $label = Label::create(...);

    $label->tickets()->attach($ticket);

    // or maybe
    $label->tickets()->detach($ticket);
}

public function createCategory()
{
    // If you create a category/categories seperated from the ticket and wants to
    // associate it to a ticket, you may do the following.
    $category = Category::create(...);

    $category->tickets()->attach($ticket);

    // or maybe
    $category->tickets()->detach($ticket);
}
...

Ticket Table Structure

Comment Table Structure

Label Table Structure

Category Table Structure

API Methods

Ticket API Methods

The ticket model came with handy methods to use, to make your building process easy and fast, and here is the list of the available API:

The Chainable column, is showing the state for the method, that if it can be chained or not, something like

    $ticket->archive()
            ->close()
            ->markAsResolved();

Ticket Relationship API Methods

The ticket model has also a list of methods for interacting with another related models

The attachCategories and syncCategories methods, is an alternative for attach and sync laravel methods, and if you want to learn more, please take a look at this link

The commentAsUser accepts a user as a first argument, if it's null, the authenticated user will be user as default.

Ticket Scopes

The ticket model has also a list of scopes to begin filter with.

Category & Label Scopes

Handling File Upload

This package doesn't come with file upload feature (yet) Instead you can use laravel-medialibrary by Spatie, to handle file functionality.

The steps are pretty straight forward, all what you need to do is the following.

Extends the Ticket model, by creating a new model file in your application by

php artisan make:model Ticket

Then extend the base Ticket Model, then use InteractWithMedia trait by spatie package, and the interface HasMedia:

namespace App\Models\Ticket;
use Spatie\MediaLibrary\HasMedia;
use Spatie\MediaLibrary\InteractsWithMedia;

class Ticket extends \Renatoxm\LaravelTicket\Models\Ticket implements HasMedia
{
    use InteractsWithMedia;
}

The rest of the implementation, head to the docs of spatie package to know more.

Event system

All events are located in the Renatoxm\laravel-ticket\Events namespace.

Ticket events

The following events are dispatched as a result of Eloquent events being fired.

TicketCreating
TicketCreated
TicketSaving
TicketSaved
TicketUpdating
TicketUpdated
TicketDeleting
TicketDeleted

Comment events

The following events are dispatched as a result of Eloquent events being fired.

CommentCreating
CommentCreated
CommentSaving
CommentSaved
CommentUpdating
CommentUpdated
CommentDeleting
CommentDeleted

Consuming events

use Renatoxm\LaravelTicket\Events\TicketCreated;

Event::listen(function (TicketCreated $event) {
    dump($event->ticket->title);
});

// or
Event::listen(TicketCreated::class, [SomeListener::class, 'handle']);

Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

License

MIT. Please see the license file for more information.

renatoxm / laravel-ticket

Maintainers

Details