README

A helpdesk and ticket management package for Laravel. Provides a complete REST API for managing tickets, priorities, statuses, departments, and ticket types.

Beta Status

This package is in active development. While core API functionality is working and tested, please note:

• APIs are subject to change
• Not recommended for production use without thorough testing
• Breaking changes may occur between releases
• Some features (custom fields, topics) are not yet implemented

Features

• REST API with full CRUD for all resources
• Content negotiation -- responds with JSON or XML based on Accept header
• Config-driven models -- swap any model class via config
• Soft deletes on all resources
• Policy support -- optional, per-resource authorization via Laravel policies
• Auto-calculated foreground colors from background hex via the HasColors trait

Requirements

• PHP 8.0+
• Laravel 9.0, 10.0, 11.0, or 12.0

Installation

composer require crumbls/helpdesk

The service provider is auto-discovered. Run migrations:

php artisan migrate

To publish the config file:

php artisan vendor:publish --provider="Crumbls\HelpDesk\HelpDeskServiceProvider"

Configuration

After publishing, configure your helpdesk in config/helpdesk.php:

return [
    'api' => [
        'enabled' => true,
        'route-prefix' => 'api/helpdesk',
        'middleware' => ['web'],

        'department'  => ['usePolicy' => false],
        'priority'    => ['usePolicy' => false],
        'status'      => ['usePolicy' => false],
        'ticket'      => ['usePolicy' => false],
        'ticket_type' => ['usePolicy' => false],
    ],
];

Options

Swappable Models

Override any model class via config/helpdesk.php:

'models' => [
    'department'   => \App\Models\CustomDepartment::class,
    'priority'     => \App\Models\CustomPriority::class,
    'status'       => \App\Models\CustomTicketStatus::class,
    'ticket'       => \App\Models\CustomTicket::class,
    'type'         => \App\Models\CustomTicketType::class,
],

API Endpoints

All endpoints are prefixed with your configured route-prefix (default: /api/helpdesk).

A GET / endpoint lists all available API routes.

Quick Example

curl -X POST http://localhost/api/helpdesk/priorities \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"title": "Critical", "color_background": "#EF4444", "level": 5}'

XML Responses

Set the Accept header to receive XML instead of JSON:

curl -X GET http://localhost/api/helpdesk/priorities/1 \
  -H "Accept: application/xml"

API Documentation

Detailed API documentation with curl examples for each endpoint:

• Departments
• Priorities
• Statuses
• Tickets
• Types

Testing

composer test:unit

Or run just the Pest tests directly:

./vendor/bin/pest

Roadmap

• REST API for tickets, priorities, statuses, departments, types
• JSON and XML content negotiation
• Config-driven model swapping
• Soft deletes
• Custom fields
• Topics
• Email integration
• Frontend client portal
• Automated ticket routing
• SLA management
• Knowledge base
• Webhook support

License

This package is open-sourced software licensed under the MIT license.

Credits

• Created by Chase C. Miller
• Built with Laravel

Support

1. Check the API documentation
2. Search existing issues
3. Open a new issue if needed

As this is beta software, support is limited and response times may vary.