CreateLumina / tickets by PadowYT2
forked from coderflexx/laravel-ticket

⚠️ All credits go to Coderflex ⚠️

This is a custom version for Lumina products. All credits goes to coderflexx/laravel-ticket

• ⚠️ All credits go to Coderflex ⚠️
• Introduction
• Installation
• Configuration
• Preparing your model
• Usage
  • Ticket Table Structure
  • Message Table Structure
  • Category Table Structure
• API Methods
  • Ticket API Methods
  • Ticket Relationship API Methods
  • Ticket Scopes
• Handling File Upload
• Testing
• Changelog
• Contributing
• Security Vulnerabilities
• Credits
• License

Introduction

Laravel Ticket package, is a Backend API to handle your ticket system, with an easy way.

Installation

You can install the package via composer:

composer require lumina/tickets

Configuration

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 Lumina\Tickets\Concerns\HasTickets;
use Lumina\Tickets\Contracts\CanUseTickets;
...
class User extends Model implements CanUseTickets
{
    ...
    use HasTickets;
    ...
}

Usage

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

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

Here is an example

use Lumina\Tickets\Models\Ticket;
use Lumina\Tickets\Models\Category;

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

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

    $category = Category::first();
    $ticket->attachCategories($category);
    
    // or you can create the categories & the tickets directly by:
    // $ticket->categories()->create(...);

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

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

| Column Name | Type | Default | | ----------- | ----------- | ---------- | | ID | integer | NOT NULL | | UUID | string | NOT NULL | | user_id | integer | NOT NULL | | title | string | NOT NULL | | message | string | NOT NULL | | status | string | open | | created_at | timestamp | NULL | | updated_at | timestamp | NULL |

Message Table Structure

| Column Name | Type | Default | | ----------- | ----------- | ---------- | | ID | integer | NOT NULL | | user_id | integer | NOT NULL | | ticket_id | integer | NOT NULL | | message | string | NOT NULL | | created_at | timestamp | NULL | | updated_at | timestamp | NULL |

Category Table Structure

| Column Name | Type | Default | | ----------- | ----------- | ---------- | | ID | integer | NOT NULL | | name | string | NULL | | created_at | timestamp | NULL | | updated_at | timestamp | NULL |

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:

| Method | Arguments | Description | Example | | ---------- | --------- | -------------------------- | --------------------- | | close | void | close the ticket | $ticket->close() | | open | void | open a closed ticket | $ticket->open() | | lock | void | lock the ticket | $ticket->lock() | | isOpen | void | check if the ticket open | $ticket->isOpen() | | isClosed | void | check if the ticket closed | $ticket->isClosed() | | isLocked | void | check if the ticket locked | $ticket->isLocked() |

Ticket Relationship API Methods

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

| Method | Arguments | Description | Example | | ------------------ | -------------------------------------------- | --------------------------------------------------------- | -------------------------------------------------------- | | attachCategories | mixed ID, array attributes, bool touch | associate categories into an existing ticket | $ticket->attachCategories([1,2,3,4]) | | syncCategories | Model/array IDs, bool detouching | associate categories into an existing ticket | $ticket->syncCategories([1,2,3,4]) | | message | string message | add new message on an existing ticket | $ticket->message('A message in a ticket') | | messageAsUser | Model/null user, string message | add new message on an existing ticket as a different user | $ticket->messageAsUser($user, 'A message in a ticket') |

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.

| Method | Arguments | Description | Example | | -------- | --------- | ---------------------- | ------------------------- | | opened | void | get the opened tickets | Ticket::opened()->get() | | closed | void | get the closed tickets | Ticket::closed()->get() | | locked | void | get the locked tickets | Ticket::locked()->get() |

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 \Lumina\Tickets\Models\Ticket implements HasMedia
{
    use InteractsWithMedia;
}

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

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

• ousid
• All Contributors

License

The MIT License (MIT). Please see License File for more information.