README

Laravel Stock Image is a pluggable image search API tool that allows you to query stock images from various providers like Unsplash, Pexels, Pixabay, and also generate placeholder images dynamically.

🚀 Features

• Supports multiple providers: Unsplash, Pexels, Pixabay, Placeholder
• Custom API keys per request or config
• Smart keyword fallback mechanism
• Random image selection and provider rotation
• Easy Laravel integration with route and controller
• Fully testable and extendable architecture

📦 Installation

composer require apsonex/laravel-stock-image

If you're using Laravel 10+, package auto-discovery will register everything automatically.

⚙️ Configuration

Publish the configuration file if needed:

php artisan vendor:publish --tag=laravel-stock-image-config

This will create config/stock-image.php:

return [
    'route' => [
        'enable'     => true,
        'path'       => 'api/ai/tools/stock-images/search',
        'middleware' => [
            // middlewares
        ],
    ],
];

🔌 Routing

The package automatically registers this route when enabled in the config:

POST /stock-image-search

Payload Parameters

✅ Example Request (JSON)

POST to /api/ai/tools/stock-images/search

// result
{
  "keywords": "mountain, beach",
  "random_result": true,
  "random_provider": false,
  "page": 1,
  "cache": false,
  "result_limit": 10,
  "provider_api_keys": {
    "pexels": "<PEXELS_API_KEY>",
    "unsplash": "<UNSPLASH_API_KEY>",
    "pixabay": "<PIXABAY_API_KEY>"
  },
  "placeholder_text": "Placeholder Image",
  "placeholder_size": "600x400",
  "placeholder_bg_color": "cccccc",
  "placeholder_text_color": "333333"
}

🔄 Sample JSON Response

{
  "items": [
    {
      "image_url": "https://example.com/image.jpg",
      "image_description": "A stunning mountain landscape",
      "source": "unsplash"
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 30,
    "count": 1
  },
  "status": "success"
}

🧪 Testing

You can run tests using Pest:

./vendor/bin/pest

Make sure to mock external APIs to avoid hitting rate limits.

🧠 License

MIT © Apsonex