Getting Started

Minimal Setup

Installation

composer require plaidfoxsg/ticketit7

Add the service provider to config/app.php:

'providers' => [
    // ...
    Plaidfoxsg\Ticketit7\TicketitServiceProvider::class,
],

Publish Config

php artisan vendor:publish --provider="Plaidfoxsg\Ticketit7\TicketitServiceProvider" --tag="config"

Configure config/ticketit.php with your API credentials and desired settings.

First Use Case: Creating a Ticket

use Plaidfoxsg\Ticketit7\Facades\Ticketit;

$ticket = Ticketit::create([
    'title' => 'Bug Fix: Login Redirect',
    'description' => 'Users are redirected to homepage instead of dashboard.',
    'priority' => 'high',
    'project_id' => 123,
]);

Key Files to Review

Config: config/ticketit.php (API endpoints, default settings)
Facade: app/Facades/Ticketit.php (if extended)
Service Provider: src/TicketitServiceProvider.php (bootstrapping logic)

Implementation Patterns

Core Workflows

1. Ticket Management

Create/Update:

$ticket = Ticketit::update($ticketId, ['status' => 'in_progress']);

Fetching:

$tickets = Ticketit::getTickets(['project_id' => 123, 'limit' => 10]);
$ticket = Ticketit::find($ticketId);

Bulk Actions:

Ticketit::bulkUpdate([1, 2, 3], ['status' => 'resolved']);

2. Project Integration

Link tickets to projects dynamically:

$projectTickets = Ticketit::getTickets(['project_id' => $project->id]);

Use in a Laravel resource controller:

public function show(Project $project) {
    $tickets = Ticketit::getTickets(['project_id' => $project->id]);
    return view('projects.show', compact('project', 'tickets'));
}

3. Event-Driven Patterns

Listen for ticket updates via webhooks (if supported):

// In EventServiceProvider
protected $listen = [
    'Plaidfoxsg\Ticketit7\Events\TicketUpdated' => [
        'App\Listeners\NotifyTeamSlack',
    ],
];

4. API Wrapper Abstraction

Extend the facade for custom logic:

// app/Facades/ExtendedTicketit.php
class ExtendedTicketit extends \Plaidfoxsg\Ticketit7\Facades\Ticketit {
    public function createFromForm(Request $request) {
        return $this->create($request->validate([
            'title' => 'required',
            'description' => 'required',
        ]));
    }
}

Integration Tips

Laravel Ecosystem Synergy

Eloquent Models: Attach tickets to Eloquent models:

class Project extends Model {
    public function tickets() {
        return $this->hasMany(Ticket::class)->where('project_id', $this->id);
    }
}

Sync with Ticketit API periodically via a job.

Nova/Panel: Display tickets in admin panels:

// Nova Resource
public static $displayInNavigation = false;
public static $title = 'Ticket #';
public function fields(Request $request) {
    return [
        Text::make('Title')->onlyOnDetail(),
        Textarea::make('Description')->onlyOnDetail(),
        Select::make('Status')->options(Ticketit::getStatuses()),
    ];
}

Performance

Cache frequent queries:

$tickets = Cache::remember("project_{$projectId}_tickets", now()->addHours(1), function() use ($projectId) {
    return Ticketit::getTickets(['project_id' => $projectId]);
});

Gotchas and Tips

Pitfalls

API Rate Limits

The package may not handle rate limiting by default. Monitor responses for 429 Too Many Requests and implement retries:

use Plaidfoxsg\Ticketit7\Exceptions\RateLimitExceeded;

try {
    $ticket = Ticketit::create([...]);
} catch (RateLimitExceeded $e) {
    retry()->times(3)->later(5)->try(fn() => Ticketit::create([...]));
}

Project ID Mismatches
- Ensure project_id in the API matches your Laravel Project model IDs. Use a mapper if needed:
```
$apiProjectId = ProjectMapper::toApi($project->id);
```

Webhook Delays

If using webhooks, assume eventual consistency. Design your system to handle duplicate events:

public function handle(TicketUpdated $event) {
    if (!Ticket::where('api_id', $event->ticket->id)->exists()) {
        // Process update
    }
}

Debugging

Enable Debug Mode Set debug to true in config/ticketit.php to log API requests/responses:
```
'debug' => env('APP_DEBUG', false),
```

Mock API Calls Use a mock HTTP client for testing:

$this->app->bind(\Plaidfoxsg\Ticketit7\Contracts\HttpClient::class, function() {
    return new MockHttpClient();
});

Extension Points

Custom HTTP Client Override the default Guzzle client:

// In ServiceProvider
$this->app->bind(
    \Plaidfoxsg\Ticketit7\Contracts\HttpClient::class,
    \App\Services\CustomTicketitClient::class
);

Event Customization Publish and extend events:

php artisan vendor:publish --provider="Plaidfoxsg\Ticketit7\TicketitServiceProvider" --tag="events"

Then modify app/Events/TicketitEvents.php.

API Response Transformation Override the response handler:

// In a service provider
$this->app->bind(
    \Plaidfoxsg\Ticketit7\Contracts\ResponseTransformer::class,
    \App\Services\CustomTransformer::class
);

Configuration Quirks

Base URL Overrides The package assumes a default API URL. Override it in config:

'api' => [
    'base_url' => env('TICKETIT_API_URL', 'https://api.ticketit.example.com/v1'),
],

Authentication Supports multiple auth methods (API key, OAuth). Configure in config/ticketit.php:
```
'auth' => [
    'method' => 'api_key',
    'api_key' => env('TICKETIT_API_KEY'),
],
```

Pro Tips

Soft Deletes If the API supports soft deletes, sync with Laravel’s SoftDeletes:

class Ticket extends Model {
    use SoftDeletes;
    protected $dates = ['deleted_at'];
}

Search Functionality Leverage the API’s search if available:

$results = Ticketit::search('login redirect', ['project_id' => 123]);

Webhook Verification Validate webhook signatures if security is critical:

public function handleIncomingWebhook(Request $request) {
    if (!Ticketit::verifyWebhook($request->header('X-Signature'), $request->getContent())) {
        abort(403);
    }
    // Process webhook
}

Ticketit7 Laravel Package