PHPackages                             lanos/laravel-bfl - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Image & Media](/categories/media)
4. /
5. lanos/laravel-bfl

ActiveLibrary[Image & Media](/categories/media)

lanos/laravel-bfl
=================

Laravel wrapper for Black Forest Labs FLUX API - AI-powered image generation and fine-tuning services

v1.0.0(10mo ago)00MITPHPPHP ^8.1

Since Aug 25Pushed 10mo agoCompare

[ Source](https://github.com/l4nos/Laravel-Black-Forest-Labs)[ Packagist](https://packagist.org/packages/lanos/laravel-bfl)[ Docs](https://github.com/l4nos/Laravel-Black-Forest-Labs)[ RSS](/packages/lanos-laravel-bfl/feed)WikiDiscussions main Synced today

READMEChangelogDependencies (12)Versions (2)Used By (0)

Laravel Black Forest Labs (BFL) Package
=======================================

[](#laravel-black-forest-labs-bfl-package)

[![Latest Version on Packagist](https://camo.githubusercontent.com/d20c8ffc5c2c72a3d8f066703a945ca8daba400a94166cec7f8b283c9f3bfe65/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6c616e6f732f6c61726176656c2d62666c2e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/lanos/laravel-bfl)[![GitHub Tests Action Status](https://camo.githubusercontent.com/fc40be06089c7695b67c2b27fe94dfd88ebd3eb8a487dd53058eaf602402e8fa/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f6c346e6f732f4c61726176656c2d426c61636b2d466f726573742d4c6162732f74657374732e796d6c3f6272616e63683d6d61696e266c6162656c3d7465737473267374796c653d666c61742d737175617265)](https://github.com/l4nos/Laravel-Black-Forest-Labs/actions?query=workflow%3Atests+branch%3Amain)[![GitHub Code Style Action Status](https://camo.githubusercontent.com/a7abfc363790e3ea70aa5837c1ec3965b436591aaa192a6c702d03a580769ef9/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f6c346e6f732f4c61726176656c2d426c61636b2d466f726573742d4c6162732f6669782d7068702d636f64652d7374796c652d6973737565732e796d6c3f6272616e63683d6d61696e266c6162656c3d636f64652532307374796c65267374796c653d666c61742d737175617265)](https://github.com/l4nos/Laravel-Black-Forest-Labs/actions?query=workflow%3A%22Fix+PHP+code+style+issues%22+branch%3Amain)[![Total Downloads](https://camo.githubusercontent.com/e76230537231aca9213212acbb4091919ca1e15369cb17397cd0bcb2b42202d2/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6c616e6f732f6c61726176656c2d62666c2e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/lanos/laravel-bfl)

A professional Laravel wrapper for Black Forest Labs' FLUX API, providing seamless integration for AI-powered image generation and fine-tuning services.

Features
--------

[](#features)

- **Multiple Processing Modes**: Manual, synchronous, and queue-based job processing
- **Complete Model Support**: All FLUX models (Pro, Dev, Ultra, Fill, Expand, Canny, Depth, Kontext)
- **Fine-tuning Support**: Create and manage fine-tuned models with dedicated service
- **File Storage Integration**: Automatic file downloading and storage with configurable drivers
- **Job Tracking**: Complete job lifecycle management with database persistence
- **Queue Integration**: Built-in Laravel queue job for background processing
- **Facade Support**: Convenient facades for BFL and fine-tuning operations
- **Comprehensive Testing**: Full test coverage with PHPUnit
- **Type-Safe**: Full PHP 8.1+ type hints and strict types

Installation
------------

[](#installation)

Install the package via Composer:

```
composer require lanos/laravel-bfl
```

### Publish and Run Migrations

[](#publish-and-run-migrations)

Publish the migration and config files:

```
php artisan vendor:publish --provider="Lanos\LaravelBFL\BFLServiceProvider"
```

Or publish them separately:

```
# Publish only the config
php artisan vendor:publish --tag="bfl-config"

# Publish only migrations
php artisan vendor:publish --tag="bfl-migrations"
```

Run the migrations:

```
php artisan migrate
```

### Environment Configuration

[](#environment-configuration)

Add your BFL API key to your `.env` file:

```
BFL_API_KEY=your-black-forest-labs-api-key
BFL_STORE_FILES=true
BFL_STORAGE_DISK=local
BFL_STORAGE_PATH_PREFIX=generated-bfl-images
```

Configuration
-------------

[](#configuration)

The package publishes a configuration file to `config/bfl.php`. Key configuration options:

```
return [
    'api_key' => env('BFL_API_KEY'),

    'storage' => [
        'store_files' => env('BFL_STORE_FILES', true),
        'disk' => env('BFL_STORAGE_DISK', 'local'),
        'path_prefix' => env('BFL_STORAGE_PATH_PREFIX', 'generated-bfl-images'),
        'public' => env('BFL_STORAGE_PUBLIC', false),
    ],

    'jobs' => [
        'queue_connection' => env('BFL_QUEUE_CONNECTION', 'default'),
        'queue_name' => env('BFL_QUEUE_NAME', 'default'),
        'polling' => [
            'max_attempts' => env('BFL_POLLING_MAX_ATTEMPTS', 120),
            'delay_seconds' => env('BFL_POLLING_DELAY_SECONDS', 3),
        ],
        'cleanup_after_days' => env('BFL_CLEANUP_AFTER_DAYS', 30),
    ],
];
```

Basic Usage
-----------

[](#basic-usage)

The package provides three different processing modes:

### 1. Manual Mode

[](#1-manual-mode)

Create a job and manually check its status:

```
use Lanos\LaravelBFL\Facades\BFL;
use Lanos\LaravelBFL\Models\BFLJob;

// Create a manual job
$job = BFL::createManualJob(
    BFLJob::MODEL_FLUX_1_PRO,
    'A majestic dragon soaring through clouds at sunset',
    [
        'width' => 1024,
        'height' => 768,
        'steps' => 50,
        'guidance' => 3.5,
    ],
    ['user_request_id' => 'req_123'], // metadata
    auth()->user() // optional user association
);

// Later, check the job status
$updatedJob = BFL::checkJobStatus($job);

if ($updatedJob->isCompleted()) {
    echo "Job completed! Files stored at: ";
    foreach ($updatedJob->file_paths ?? [] as $path) {
        echo BFL::getFileUrl($path) . "\n";
    }
} elseif ($updatedJob->isFailed()) {
    echo "Job failed: " . $updatedJob->error_message;
}
```

### 2. Synchronous Mode

[](#2-synchronous-mode)

Create a job and wait for completion:

```
// This will block until completion or timeout
$job = BFL::createSyncJob(
    BFLJob::MODEL_FLUX_1_PRO,
    'A beautiful sunset over mountains',
    [
        'aspect_ratio' => '16:9',
        'steps' => 28,
        'safety_tolerance' => 2,
    ]
);

// Job is automatically completed when this returns
if ($job->isCompleted()) {
    echo "Generated image result: " . json_encode($job->result);
}
```

### 3. Queue Mode

[](#3-queue-mode)

Create a job that processes in the background:

```
// Dispatch to queue for background processing
$job = BFL::createQueueJob(
    BFLJob::MODEL_FLUX_11_PRO_ULTRA,
    'An abstract artistic composition with vibrant colors',
    [
        'aspect_ratio' => '1:1',
        'raw' => false,
    ],
    [], // metadata
    auth()->user(), // user
    'redis', // queue connection (optional)
    'images'  // queue name (optional)
);

echo "Job queued with ID: {$job->id}";

// Check status later
$job->refresh();
if ($job->isCompleted()) {
    // Handle completion
}
```

Available Models
----------------

[](#available-models)

```
// Generation models
BFLJob::MODEL_FLUX_1_PRO           // 'flux-1-pro'
BFLJob::MODEL_FLUX_1_DEV           // 'flux-1-dev'
BFLJob::MODEL_FLUX_11_PRO          // 'flux-1.1-pro'
BFLJob::MODEL_FLUX_11_PRO_ULTRA    // 'flux-1.1-pro-ultra'

// Editing models
BFLJob::MODEL_FLUX_1_FILL          // 'flux-1-fill'
BFLJob::MODEL_FLUX_1_EXPAND        // 'flux-1-expand'
BFLJob::MODEL_FLUX_1_CANNY         // 'flux-1-canny'
BFLJob::MODEL_FLUX_1_DEPTH         // 'flux-1-depth'

// Context models
BFLJob::MODEL_FLUX_KONTEXT_PRO     // 'flux-kontext-pro'
BFLJob::MODEL_FLUX_KONTEXT_MAX     // 'flux-kontext-max'
```

Common Parameters
-----------------

[](#common-parameters)

```
$parameters = [
    // Dimensions
    'width' => 1024,
    'height' => 768,
    'aspect_ratio' => '16:9', // Alternative to width/height

    // Generation settings
    'steps' => 50,           // Denoising steps
    'guidance' => 3.5,       // How closely to follow prompt
    'seed' => 42,           // For reproducible results
    'safety_tolerance' => 2, // Content filtering (0=strict, 6=lenient)
    'output_format' => 'png', // 'png' or 'jpeg'

    // Advanced options
    'image_prompt' => base64_encode(file_get_contents('reference.jpg')),
    'prompt_upsampling' => true,

    // Webhooks
    'webhook_url' => 'https://your-site.com/webhooks/bfl',
    'webhook_secret' => 'your-webhook-secret',
];
```

### Model-Specific Parameters

[](#model-specific-parameters)

**Fill/Inpainting models:**

```
$parameters = [
    'image' => base64_encode(file_get_contents('input.jpg')),
    'mask' => base64_encode(file_get_contents('mask.png')), // Optional
];
```

**Expand models:**

```
$parameters = [
    'image' => base64_encode(file_get_contents('input.jpg')),
    'top' => 100,      // Pixels to add
    'bottom' => 100,
    'left' => 50,
    'right' => 50,
];
```

**Control models (Canny/Depth):**

```
$parameters = [
    'control_image' => base64_encode(file_get_contents('control.jpg')),
    'canny_low_threshold' => 50,   // For Canny model
    'canny_high_threshold' => 200,
];
```

Fine-tuning
-----------

[](#fine-tuning)

The package provides comprehensive fine-tuning support through the `BFLFinetune` facade:

### Creating Fine-tunes

[](#creating-fine-tunes)

```
use Lanos\LaravelBFL\Facades\BFLFinetune;
use Lanos\LaravelBFL\Enums\FinetuneMode;

// Create from file paths (automatically zips and encodes)
$finetune = BFLFinetune::create([
    'files' => [
        '/path/to/image1.jpg',
        '/path/to/image2.jpg',
        '/path/to/image3.jpg',
    ],
    'finetune_comment' => 'My custom style training',
    'mode' => FinetuneMode::STYLE, // or 'style' as string
    'trigger_word' => 'MYSTYLE',
    'iterations' => 500,
]);

// Or create from pre-encoded ZIP
$finetune = BFLFinetune::create([
    'file_data' => base64_encode(file_get_contents('training_data.zip')),
    'finetune_comment' => 'Character fine-tune',
    'mode' => 'character',
    'trigger_word' => 'MYCHAR',
    'iterations' => 800,
]);
```

### Managing Fine-tunes

[](#managing-fine-tunes)

```
// Get finetune details
$details = BFLFinetune::getDetails('ft-123');

// List your finetunes
$finetunes = BFLFinetune::listMyFinetunes();

// Delete a finetune
$result = BFLFinetune::delete('ft-123');
```

### Generating with Fine-tuned Models

[](#generating-with-fine-tuned-models)

```
// Generate with fine-tuned Pro
$job = BFLFinetune::generateWithFinetunedPro(
    'ft-123',
    'A beautiful sunset in MYSTYLE',
    ['width' => 1024, 'height' => 768]
);

// Generate with fine-tuned Ultra
$job = BFLFinetune::generateWithFinetunedUltra(
    'ft-123',
    'Portrait in MYSTYLE',
    ['raw' => true]
);

// Generate with fine-tuned control models
$job = BFLFinetune::generateWithFinetunedCanny(
    'ft-123',
    'Landscape in MYSTYLE',
    base64_encode(file_get_contents('control.jpg'))
);
```

Job Status and Management
-------------------------

[](#job-status-and-management)

### Status Checking

[](#status-checking)

```
$job = BFLJob::find(1);

// Status checks
$job->isPending();     // Job created but not started
$job->isProcessing();  // Job is currently running
$job->isCompleted();   // Job finished successfully
$job->isFailed();      // Job failed
$job->isFinished();    // Job is in any terminal state

// Progress tracking
echo "Progress: {$job->progress}%";
echo "Started: {$job->started_at}";
echo "Completed: {$job->completed_at}";
```

### User Association

[](#user-association)

```
// Create job for specific user
$job = BFL::createManualJob(
    BFLJob::MODEL_FLUX_1_PRO,
    'User generated image',
    [],
    [],
    User::find(1)
);

// Get user's jobs
$userJobs = BFL::getUserJobs(auth()->user(), [
    'status' => BFLJob::STATUS_COMPLETED,
    'model_type' => BFLJob::MODEL_FLUX_1_PRO,
]);
```

Queue Configuration
-------------------

[](#queue-configuration)

### Queue Settings

[](#queue-settings)

Configure queue processing in `config/bfl.php`:

```
'jobs' => [
    'queue_connection' => 'redis',
    'queue_name' => 'bfl-jobs',
    'polling' => [
        'max_attempts' => 120,    // Maximum poll attempts
        'delay_seconds' => 3,     // Delay between polls
    ],
],
```

### Running Queue Workers

[](#running-queue-workers)

```
# Start worker for BFL jobs
php artisan queue:work --queue=bfl-jobs

# With specific connection
php artisan queue:work redis --queue=bfl-jobs
```

File Storage
------------

[](#file-storage)

Generated images are automatically downloaded and stored when `store_files` is enabled:

```
// Access stored files
$job = BFLJob::find(1);
$filePaths = $job->file_paths; // Array of stored file paths

// Get public URLs
foreach ($filePaths as $path) {
    echo BFL::getFileUrl($path);
}
```

### Custom Storage Configuration

[](#custom-storage-configuration)

```
// Use S3 or other disks
'storage' => [
    'disk' => 's3',
    'public' => true,
],
```

Utility Methods
---------------

[](#utility-methods)

### Cleanup

[](#cleanup)

```
// Clean up old jobs (respects cleanup_after_days config)
$deletedCount = BFL::cleanupOldJobs();
```

### Direct Client Access

[](#direct-client-access)

```
// Access underlying FLUX client for advanced usage
$client = BFL::getClient();
$config = BFL::getConfig();
```

Testing
-------

[](#testing)

Run the package test suite:

```
composer test
```

### Testing in Your Application

[](#testing-in-your-application)

```
use Lanos\LaravelBFL\Services\BFLService;
use Lanos\LaravelBFL\Models\BFLJob;

public function test_image_generation()
{
    $mockService = $this->mock(BFLService::class);
    $mockJob = new BFLJob([
        'bfl_task_id' => 'test-task',
        'status' => BFLJob::STATUS_COMPLETED,
    ]);

    $mockService->allows('createManualJob')
        ->andReturn($mockJob);

    // Test your application logic
}
```

API Reference
-------------

[](#api-reference)

### BFL Facade Methods

[](#bfl-facade-methods)

```
// Job creation
BFL::createManualJob(string $modelType, string $prompt, array $parameters = [], array $metadata = [], ?object $user = null): BFLJob
BFL::createSyncJob(string $modelType, string $prompt, array $parameters = [], array $metadata = [], ?object $user = null): BFLJob
BFL::createQueueJob(string $modelType, string $prompt, array $parameters = [], array $metadata = [], ?object $user = null, ?string $queueConnection = null, ?string $queueName = null): BFLJob

// Job management
BFL::checkJobStatus(BFLJob $job): BFLJob
BFL::completeJob(BFLJob $job, GetResultResponse $result): BFLJob

// Utility methods
BFL::getStorageDisk(): \Illuminate\Contracts\Filesystem\Filesystem
BFL::getFileUrl(string $filePath): string
BFL::cleanupOldJobs(): int
BFL::getUserJobs(object $user, array $filters = []): \Illuminate\Database\Eloquent\Collection
BFL::getClient(): \Lanos\PHPBFL\FluxClient
BFL::getConfig(): array
```

### BFLFinetune Facade Methods

[](#bflfinetune-facade-methods)

```
// Finetune management
BFLFinetune::create(array $params): array
BFLFinetune::getDetails(string $finetuneId): array
BFLFinetune::listMyFinetunes(): array
BFLFinetune::delete(string $finetuneId): array

// Generation with finetuned models
BFLFinetune::generateWithFinetunedPro(string $finetuneId, string $prompt, array $parameters = [], array $metadata = [], ?object $user = null): BFLJob
BFLFinetune::generateWithFinetunedUltra(string $finetuneId, string $prompt, array $parameters = [], array $metadata = [], ?object $user = null): BFLJob
BFLFinetune::generateWithFinetunedDepth(string $finetuneId, string $prompt, string $controlImage, array $parameters = [], array $metadata = [], ?object $user = null): BFLJob
BFLFinetune::generateWithFinetunedCanny(string $finetuneId, string $prompt, string $controlImage, array $parameters = [], array $metadata = [], ?object $user = null): BFLJob
BFLFinetune::generateWithFinetunedFill(string $finetuneId, string $image, array $parameters = [], array $metadata = [], ?object $user = null): BFLJob
```

### Job Model Methods

[](#job-model-methods)

```
// Status checks
$job->isPending(): bool
$job->isProcessing(): bool
$job->isCompleted(): bool
$job->isFailed(): bool
$job->isFinished(): bool

// Status updates
$job->markAsProcessing(): self
$job->markAsCompleted(?array $result = null, ?array $filePaths = null): self
$job->markAsFailed(?string $errorMessage = null): self
$job->updateProgress(float $progress): self
```

Contributing
------------

[](#contributing)

We welcome contributions! Please ensure all tests pass and follow PSR-12 coding standards.

Security Vulnerabilities
------------------------

[](#security-vulnerabilities)

Please review our security policy on how to report security vulnerabilities.

Credits
-------

[](#credits)

- [Lanos](https://github.com/l4nos)
- [All Contributors](../../contributors)

License
-------

[](#license)

The MIT License (MIT). Please see [License File](LICENSE.md) for more information.

Changelog
---------

[](#changelog)

Please see [CHANGELOG.md](CHANGELOG.md) for more information on what has changed recently.

###  Health Score

28

—

LowBetter than 52% of packages

Maintenance54

Moderate activity, may be stable

Popularity0

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity45

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Unknown

Total

1

Last Release

314d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/31861108?v=4)[Rob](/maintainers/l4nos)[@l4nos](https://github.com/l4nos)

---

Top Contributors

[![l4nos](https://avatars.githubusercontent.com/u/31861108?v=4)](https://github.com/l4nos "l4nos (2 commits)")

---

Tags

phplaravelsdkaifluximage-generationblack-forest-labs

###  Code Quality

TestsPest

Static AnalysisPHPStan

Code StylePHP CS Fixer

Type Coverage Yes

### Embed Badge

![Health badge](/badges/lanos-laravel-bfl/health.svg)

```
[![Health](https://phpackages.com/badges/lanos-laravel-bfl/health.svg)](https://phpackages.com/packages/lanos-laravel-bfl)
```

###  Alternatives

[laravel/ai

The official AI SDK for Laravel.

1.0k3.2M201](/packages/laravel-ai)[psalm/plugin-laravel

Psalm plugin for Laravel

3355.3M346](/packages/psalm-plugin-laravel)[roots/acorn

Framework for Roots WordPress projects built with Laravel components.

9762.4M131](/packages/roots-acorn)[laravel/scout

Laravel Scout provides a driver based solution to searching your Eloquent models.

1.7k55.0M619](/packages/laravel-scout)[illuminate/queue

The Illuminate Queue package.

21332.6M1.6k](/packages/illuminate-queue)[laravel/pulse

Laravel Pulse is a real-time application performance monitoring tool and dashboard for your Laravel application.

1.7k15.1M132](/packages/laravel-pulse)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)