> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/charlietyn/openapi-generator/llms.txt
> Use this file to discover all available pages before exploring further.

# Events

> Event system and lifecycle hooks for OpenAPI generation

## Overview

The Laravel OpenAPI Generator does not currently define custom event classes or listeners. The package focuses on direct generation without event-based workflows.

<Info>
  While the package doesn't dispatch Laravel events, it does provide logging hooks and cache integration points for observability.
</Info>

***

## Current State

The service provider includes a placeholder method for future event integration:

**Location:** `src/Providers/OpenApiGeneratorServiceProvider.php`

```php theme={null}
/**
 * Placeholder for cache clear listener.
 * No event bindings are registered by default.
 */
protected function registerCacheClearListener(): void
{
    // Reserved for future event hooks
}
```

***

## Logging as Event Alternative

The package uses Laravel's logging system extensively, which can serve as an observability mechanism.

### Logging Channel

All generation activities are logged to the `openapi` channel:

```php theme={null}
// config/logging.php
'channels' => [
    'openapi' => [
        'driver' => 'daily',
        'path' => storage_path('logs/openapi.log'),
        'level' => env('LOG_LEVEL', 'debug'),
        'days' => 14,
    ],
],
```

### Logged Activities

The generator logs various activities that could be considered "events":

**Route Processing:**

```php theme={null}
Log::channel('openapi')->info('Nwidart modular structure detected', [
    'uri' => $uri,
    'module' => $module,
    'entity' => $entity,
]);
```

**API Type Filtering:**

```php theme={null}
Log::channel('openapi')->info('API type filter set', [
    'types' => $this->apiTypeFilter,
    'available_types' => array_keys(config('openapi.api_types')),
]);
```

**Request Body Generation:**

```php theme={null}
Log::channel('openapi')->info('[buildRequestBody] Using FormRequest/Model data', [
    'source' => $documentation['form_request_class'] ?? 'Model fallback',
    'scenario' => $documentation['scenario'] ?? 'none',
    'fields' => $exampleFields,
]);
```

**Location:** `src/Services/OpenApiServices.php` (multiple occurrences)

***

## Monitoring Generation

You can monitor generation by tailing the log file:

```bash theme={null}
# Watch OpenAPI generation logs
tail -f storage/logs/openapi.log
```

**Example Log Output:**

```
[2026-03-07 10:15:32] local.INFO: API type filter set
{"types":["api","mobile"],"available_types":["api","site","mobile","admin"]}

[2026-03-07 10:15:33] local.INFO: Nwidart modular structure detected
{"uri":"api/security/users","module":"security","entity":"users"}

[2026-03-07 10:15:33] local.INFO: Request name generated
{"uri":"api/security/users","route_name":"security.users.index","module":"security","entity":"users","detected_action":"list","technical_name":"security.users.list","display_name":"[API] security.users.list"}
```

***

## Cache Hooks

While not events, the cache system provides integration points:

### Cache Store

When a specification is generated and cached:

**Location:** `src/Services/OpenApiServices.php:110-112`

```php theme={null}
if (config('openapi.cache.enabled')) {
    Cache::put($cacheKey, $result, config('openapi.cache.ttl'));
}
```

### Cache Retrieval

When a cached specification is retrieved:

**Location:** `src/Services/OpenApiServices.php:90-95`

```php theme={null}
if ($useCache && config('openapi.cache.enabled')) {
    $cached = Cache::get($cacheKey);
    if ($cached) {
        return $cached; // Cache hit
    }
}
```

### Cache Clearing

When cache is manually cleared:

**Location:** `src/Services/OpenApiServices.php:1479-1488`

```php theme={null}
public function clearCache(): void
{
    $patterns = [
        config('openapi.cache.key_prefix') . '*',
    ];

    foreach ($patterns as $pattern) {
        Cache::forget($pattern);
    }
}
```

***

## Future Event System

If you need event-based workflows, you can implement them in your application.

### Custom Event Example

**Define an Event:**

```php theme={null}
// app/Events/OpenApiGenerated.php
namespace App\Events;

use Illuminate\Foundation\Events\Dispatchable;

class OpenApiGenerated
{
    use Dispatchable;

    public function __construct(
        public array $spec,
        public array $apiTypes,
        public string $format,
        public float $generationTime
    ) {}
}
```

**Dispatch in Your Code:**

```php theme={null}
use App\Events\OpenApiGenerated;
use Ronu\OpenApiGenerator\Facades\OpenApiGenerator;

$start = microtime(true);
$spec = OpenApiGenerator::generateOpenApi(apiTypes: ['api']);
$time = microtime(true) - $start;

event(new OpenApiGenerated(
    spec: $spec,
    apiTypes: ['api'],
    format: 'openapi',
    generationTime: $time
));
```

**Create a Listener:**

```php theme={null}
// app/Listeners/NotifyTeamOfNewSpec.php
namespace App\Listeners;

use App\Events\OpenApiGenerated;
use Illuminate\Support\Facades\Notification;

class NotifyTeamOfNewSpec
{
    public function handle(OpenApiGenerated $event): void
    {
        // Send Slack notification
        Notification::route('slack', config('services.slack.webhook'))
            ->notify(new SpecGeneratedNotification(
                apiTypes: $event->apiTypes,
                format: $event->format,
                generationTime: $event->generationTime
            ));
    }
}
```

**Register the Listener:**

```php theme={null}
// app/Providers/EventServiceProvider.php
protected $listen = [
    OpenApiGenerated::class => [
        NotifyTeamOfNewSpec::class,
        LogSpecGeneration::class,
    ],
];
```

***

## Potential Event Points

If the package were to implement events, these would be logical dispatch points:

### Before Generation

```php theme={null}
GenerationStarting::class
```

**Use Cases:**

* Validate configuration
* Log generation request
* Clear stale cache

***

### After Generation

```php theme={null}
GenerationCompleted::class
```

**Use Cases:**

* Store spec to database
* Upload to CDN or S3
* Send notifications
* Update documentation site

***

### Cache Events

```php theme={null}
CacheHit::class
CacheMiss::class
CacheCleared::class
```

**Use Cases:**

* Monitor cache performance
* Trigger cache warming
* Alert on cache misses

***

### Route Discovery

```php theme={null}
RouteDiscovered::class
```

**Use Cases:**

* Log discovered routes
* Track API growth
* Detect new endpoints

***

### Export Events

```php theme={null}
PostmanExported::class
InsomniaExported::class
```

**Use Cases:**

* Auto-import to collection management
* Sync with team workspace
* Trigger CI/CD pipelines

***

## Laravel Event Integration

You can hook into Laravel's existing events:

### Model Events

If you store specs in a database:

```php theme={null}
use App\Models\ApiSpecification;

ApiSpecification::created(function ($spec) {
    // New spec version created
    event(new SpecVersionCreated($spec));
});
```

***

### Cache Events

Listen to Laravel's cache events:

```php theme={null}
use Illuminate\Support\Facades\Event;
use Illuminate\Cache\Events\CacheHit;
use Illuminate\Cache\Events\CacheMissed;

Event::listen(CacheHit::class, function ($event) {
    if (str_starts_with($event->key, 'openapi_spec_')) {
        // OpenAPI cache hit
        logger()->debug('OpenAPI cache hit', ['key' => $event->key]);
    }
});

Event::listen(CacheMissed::class, function ($event) {
    if (str_starts_with($event->key, 'openapi_spec_')) {
        // OpenAPI cache miss
        logger()->debug('OpenAPI cache miss', ['key' => $event->key]);
    }
});
```

***

## Observability Patterns

### Telescope Integration

If using Laravel Telescope, generation activities are automatically recorded:

* Cache hits/misses
* Log entries
* HTTP requests (if using routes)
* Command execution (Artisan)

**View in Telescope:**

```
http://localhost:8000/telescope/logs
http://localhost:8000/telescope/cache
http://localhost:8000/telescope/commands
```

***

### Custom Metrics

Track generation metrics:

```php theme={null}
use Illuminate\Support\Facades\Redis;

class MetricsListener
{
    public function handle(OpenApiGenerated $event): void
    {
        Redis::incr('openapi:generations:total');
        Redis::hincrby('openapi:generations:by_format', $event->format, 1);
        Redis::lpush('openapi:generation_times', $event->generationTime);
    }
}
```

***

## Webhook Integration

Trigger webhooks after generation:

```php theme={null}
use Illuminate\Support\Facades\Http;

class WebhookListener
{
    public function handle(OpenApiGenerated $event): void
    {
        Http::post('https://your-app.com/webhooks/openapi-generated', [
            'api_types' => $event->apiTypes,
            'format' => $event->format,
            'path_count' => count($event->spec['paths'] ?? []),
            'generated_at' => now()->toIso8601String(),
        ]);
    }
}
```

***

## Scheduled Generation

Use Laravel's scheduler as a time-based "event" system:

```php theme={null}
// app/Console/Kernel.php
protected function schedule(Schedule $schedule)
{
    $schedule->command('openapi:generate --all --no-cache')
        ->daily()
        ->onSuccess(function () {
            // Notify team
            event(new DailySpecGenerated());
        })
        ->onFailure(function () {
            // Alert on failure
            event(new SpecGenerationFailed());
        });
}
```

***

## Related Documentation

<CardGroup cols={2}>
  <Card title="Public API" icon="code" href="/api-reference/public-api">
    Programmatic generation API
  </Card>

  <Card title="Configuration" icon="gear" href="/configuration/reference">
    Configure logging and cache
  </Card>

  <Card title="Logging" icon="file-lines" href="/guides/logging">
    Advanced logging configuration
  </Card>

  <Card title="Testing" icon="flask" href="/guides/testing">
    Test generation workflows
  </Card>
</CardGroup>