README

A unified bridge for multiple media sources — search photos and videos from Unsplash, Pexels, Pixabay, Bing, Wikimedia Commons, and NASA through a single consistent interface.

This package was renamed from chuoke/unify-gallery to chuoke/media-bridge in v2.

Supported Sources

Installation

composer require chuoke/media-bridge

For Laravel integration, also install:

composer require illuminate/support

Usage

Standalone

use Chuoke\MediaBridge\MediaManager;

$manager = new MediaManager([
    'default' => 'unsplash',
    'drivers' => [
        'unsplash' => ['api_key' => 'your-unsplash-key'],
        'pexels'   => ['api_key' => 'your-pexels-key'],
        'pixabay'  => ['api_key' => 'your-pixabay-key'],
    ],
]);

// Search photos
$result = $manager->driver('pexels')->search('mountain', page: 1, perPage: 20);

// Browse without query (Bing, Wikimedia; NASA falls back to a generic feed)
$result = $manager->driver('bing')->search();

// Use default driver
$result = $manager->search('ocean');

foreach ($result->items as $item) {
    echo $item->source;       // 'pexels'
    echo $item->url;          // full image URL
    echo $item->thumb_url;    // thumbnail URL
    print_r($item->variants); // available size / asset variants
    echo $item->author_name;  // photographer name
    echo $item->license;      // 'pexels', 'cc0', etc.
}

Extra Parameters

$result = $manager->driver('pixabay')->search('forest', extras: [
    'orientation' => 'landscape',   // 'landscape' | 'portrait' | 'squarish'
    'color'       => 'green',
    'media_type'  => 'video',       // 'photo' | 'video'
    'locale'      => 'zh-CN',
]);

Media Variants

foreach ($item->variants as $variant) {
    echo $variant->type;   // 'thumb', 'small', 'large', 'original', etc.
    echo $variant->url;
    echo $variant->width;
    echo $variant->height;
}

Pagination

$result = $manager->driver('wikimedia')->search('', perPage: 20);

if ($result->hasMore) {
    $next = $manager->driver('wikimedia')->search('', perPage: 20, extras: [
        'cursor' => $result->nextPage,
    ]);
}

Most drivers return the next numeric page in nextPage. Cursor-based sources such as Wikimedia may return an opaque token array; pass it back as extras['cursor'].

Bing only exposes a shallow daily archive feed. The driver fetches the available archive batches internally, deduplicates repeated items by source_id, and then paginates the merged result locally.

MediaResult fields:

Check Driver Capabilities

$driver = $manager->driver('bing');

$driver->source();        // 'bing'
$driver->searchable();    // false — Bing does not support keyword search
$driver->requiresApiKey(); // false

Laravel

If you are using a full Laravel application, the required Illuminate packages are already present.

Publish the config file:

php artisan vendor:publish --tag="media-bridge-config"

Configure your API keys in config/media-bridge.php or via environment variables:

UNSPLASH_API_KEY=your-key
PEXELS_API_KEY=your-key
PIXABAY_API_KEY=your-key

Use the facade:

use Chuoke\MediaBridge\Laravel\Media;

$result = Media::driver('unsplash')->search('sunset');
$result = Media::search('cat'); // uses default driver

When the package runs inside a Laravel application, outgoing requests use Laravel's Http client automatically. That allows Laravel-side tooling such as Telescope to observe these requests. Outside Laravel, the package continues to use Guzzle directly.

MediaItem Fields

Testing

composer test

The default test suite uses mocked HTTP responses and does not require API keys or network access.

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Credits

• chuoke
• All Contributors

License

The MIT License (MIT). Please see License File for more information.