README

# FAL Laravel Integration Library

This Laravel package provides integration with [FAL AI](https://fal.ai) via queue-based endpoint execution, webhook handling, error tracking, and request management.

---

## 🚀 Installation

```bash
composer require aifnet-com/fal-laravel

⚙️ Environment Setup

Add the following environment variables to your .env file:

FAL_KEY=your-fal-api-key
FAL_NGROK_URL_FOR_LOCALHOST=https://your-ngrok-url.io

FAL_KEY: Your API key from https://fal.ai
FAL_NGROK_URL_FOR_LOCALHOST: Used in local environment to map the webhook route via ngrok

🔄 Queue Configuration

Important: This package requires a working queue system to function properly.

Webhook processing is handled asynchronously via Laravel's queue system. Make sure you have:

Configured a queue driver in your .env (e.g., redis, database, sqs):
```
QUEUE_CONNECTION=redis
```
A queue worker running:
```
php artisan queue:work
```

Without an active queue worker, webhook events will not be processed.

🧱 Migrations

This package auto-loads its migrations.

Run:

php artisan migrate

Or publish them into your project:

php artisan vendor:publish --tag=fal-migrations

This will create the following tables:

fal_requests
fal_endpoints
fal_data
fal_errors

📡 Webhook Handling

The package registers this route automatically:

POST /fal/webhook

You don't need to manually define this. The controller handles incoming FAL webhook updates, finds the matching request, updates its status, and logs errors if applicable.

🧠 Submitting Requests

To submit a request to a FAL endpoint:

use Aifnet\Fal\Models\FalRequest;

FalRequest::submit('your-endpoint-name', [
    'input_key' => 'value',
], [
    'user_id' => auth()->id(),
], FalRequest::TYPE_AUDIO);

🕒 Scheduled Command

This package includes a command to fail stale requests:

php artisan fal:check-for-stuck-requests

It will:

Fail requests older than 10 minutes
Mark them as STATUS_FAILED
Trigger a FalWebhookArrived event

Add it to your schedule:

In App\Console\Kernel.php:

protected function schedule(Schedule $schedule)
{
    $schedule->command('fal:check-for-stuck-requests')->everyFiveMinutes();
}

🛠 Laravel Compatibility

Laravel 8, 9, 10, 11
PHP >= 8.0
Auto-discovered Service Provider

📄 License

MIT

aifnet-com / fal-laravel

Maintainers

Details