README

A driver-based, extensible Laravel package for generating high-quality website banners using AI image models (Gemini, OpenAI, or custom providers).

This package abstracts AI image generation, prompt building, image handling, and storage, while allowing developers to plug in their own AI drivers without touching core logic.

✨ Features

• 🔌 Driver-based architecture (Gemini, OpenAI, Null, Custom)
• 🧠 Centralized AI model management
• 🖼️ Supports image-to-image generation
• 🧩 Fully extensible with custom drivers
• 🧼 Automatic temporary file cleanup
• 📦 Clean separation of concerns (Service, Drivers, Helpers)
• 🛡️ Safe base64 image validation before storage

📦 Installation

1️⃣ Install via Composer

composer require vedanshi/ai-banner-generator

2️⃣ Publish Configuration

php artisan vendor:publish --tag=ai-banner-generator

This will create:

config/ai-banner-generator.php

3️⃣ Configure Storage

Ensure your output disk is publicly accessible.

php artisan storage:link

🔑 Environment variables

AI_BANNER_DRIVER = 'driver_name'

# Storage
GEMINI_INPUT_DISK=local
GEMINI_OUTPUT_DISK=public

🧠 Storage Design (Important)

This package follows industry best practices:

Type	Disk	Visibility
Input images	local	🔒 Private
Generated banners	public	🌍 Public

storage/
├── app/
│   ├── private/
│   │   └── banner/input/
│   └── public/
│       └── banner/output/

⚙️ Configuration (config/ai-banner-generator.php)

return [

    /*
    |--------------------------------------------------------------------------
    | Driver Configuration
    |--------------------------------------------------------------------------
    */

    'driver' => env('AI_BANNER_DRIVER', 'gemini'),

    'drivers' => [

        'gemini' => [
            'model'   => env('GEMINI_MODEL', 'gemini-2.5-flash-image'),
            'api_key' => env('GEMINI_API_KEY'),
        ],

        'openai' => [
            'model'   => env('OPENAI_MODEL', 'gpt-4o-mini'),
            'api_key' => env('OPENAI_API_KEY'),
        ],

    ],

    /*
    |--------------------------------------------------------------------------
    | Storage Configuration
    |--------------------------------------------------------------------------
    */

    'disks' => [
        'input'  => env('BANNER_INPUT_IMAGE_DISK', 'local'),   // private
        'output' => env('BANNER_OUTPUT_IMAGE_DISK', 'public'), // public
    ],

    'paths' => [

        // Input uploads
        'front' => 'banner/front',
        'back' => 'banner/back',
        'reference' => 'banner/ref',

        // Output (generated banners)
        'output' => 'banner/output',
    ],

    'cleanup' => [
        'enabled' => true,
    ],

    /*
    |--------------------------------------------------------------------------
    | Output Configuration
    |--------------------------------------------------------------------------
    */
    'output' => [
        'format' => 'png',
        'allowed_mime_types' => ['image/png', 'image/jpeg'],
    ],

];

📌 Important

• Users switch models only via config
• No runtime config injection
• Drivers stay clean and predictable

🧠 Architecture Overview

Controller / App
     ↓
BannerService
     ↓
BannerDriverFactory
     ↓
Driver (Gemini / OpenAI / Custom)
     ↓
AI Model

Key Components

Layer	Responsibility
Service	Business flow
Factory	Driver resolution
Driver	AI interaction
Helpers	Image / prompt handling
Storage	File persistence

🧩 Banner Generation Flow

1. Input images are uploaded
2. Images are loaded & converted to Base64
3. Prompt is generated
4. Driver is resolved
5. AI generates banner
6. Image is validated & stored
7. Temporary files are cleaned
8. Public URL is returned

🚀 Usage

1️⃣ Sync Generation (Facade)

use Vedanshi\Banner\Facades\Banner;
use Vedanshi\Banner\Http\Requests\BannerGenerationRequest;

function (BannerGenerationRequest $request) {
    $result = Banner::generate($request->payload());
}

Returns a public URL of the generated banner.

2️⃣ Async Generation (Queue)

use Vedanshi\Banner\Jobs\BannerGenerationJob;
use Vedanshi\Banner\Http\Requests\BannerGenerationRequest;

function (BannerGenerationRequest $request) {
    BannerGenerationJob::dispatch($request->payload());
}

✅ Ideal for:

• Heavy image processing
• High-traffic systems
• Background workflows

🧾 Expected Payload Structure

[
    'front_image' => string,        // path on input disk
    'back_image' => string,         // path on input disk
    'transparent_image' => string,  // path on input disk
    'product_name' => string,
]

⚠️ Do NOT pass temp paths (php/tmp). Files must be stored first using Laravel storage.

🧹 Automatic Cleanup

• Input images are deleted immediately after successful generation
• Cleanup is retry-safe
• Cleanup can be disabled via config

'cleanup' => [
    'enabled' => false,
],

🖼️ Image Handling & Safety

Before storing the generated image:

• data:image/*;base64,... is handled
• Strict Base64 decoding
• Image validity is verified
• MIME type is validated

ImageStorage::store($base64);

This prevents:

• Invalid data storage
• Corrupt images
• Security risks

🔌 Built-in Drivers

Gemini Driver

new GeminiDriver($config);

Uses Prism internally for image generation.

OpenAI Driver

new OpenAIDriver($config);

Abstracted behind the same interface.

Null Driver

new NullDriver($config);

Useful for:

• Testing
• CI pipelines
• Fallback mode

🧩 Creating a Custom Driver (User Extensible)

1️⃣ Implement the Contract

use Vedanshi\Banner\Contracts\BannerDriver;

class MyDriver implements BannerDriver
{
    public function __construct(protected array $config) {}

    public function generate(string $prompt, array $images): string
    {
        // Custom AI logic
        return $base64;
    }
}

2️⃣ Register the Driver

use Vedanshi\Banner\Factory\BannerDriverFactory;

BannerDriverFactory::extend('my-driver', function ($config) {
    return new MyDriver($config);
});

3️⃣ Add Key in .env

AI_BANNER_DRIVER = 'my-driver'

🎉 Done — no core code touched.

🧠 Why This Design Works

• ✔ Manager-controlled configuration
• ✔ No runtime config injection
• ✔ Clean SOLID design
• ✔ Laravel-style driver extension
• ✔ Production-ready

This is the same architecture Laravel uses for Cache, Queue, Mail, and Filesystems.

🧪 Testing

Use the null driver:

AI_BANNER_DRIVER = 'null'

This avoids API calls and allows fast testing.

📌 Summary

• AI-agnostic banner generation
• Driver-based extensibility
• Safe image handling
• Clean separation of concerns
• Enterprise-grade Laravel architecture

📄 License

MIT License

🙌 Credits

Developed by Vedanshi Shethia

🤝 Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss improvements.