Unsplash-Fotos in Laravel einbinden: das Paket laravel-unsplash

Mit meinem Open-Source-Paket laravel-unsplash binden Sie die Unsplash-API in wenigen Minuten in Ihre Laravel-Anwendung ein: Fotosuche, Zufallsbilder, Kollektionen und Nutzerdaten – wahlweise per Service-Klasse oder Facade. Das Paket unterstützt Laravel 9 bis 13, bringt eine optionale Rate-Limiting-Middleware mit und ist mit über 20 Sternen mein populärstes Paket auf GitHub.

Was das Paket kann

• Fotosuche: einfache Suche mit searchPhotos() oder feinjustiert mit searchPhotosAdvanced() – etwa nach Farbe, Ausrichtung und Sortierung

• Einzelne Fotos: getPhoto(), getRandomPhoto() und getPhotoDownloadLink() für das Unsplash-konforme Download-Tracking

• Kollektionen und Nutzer: listCollections(), getCollection(), searchCollections(), getUser() und getUserPhotos()

• Rate Limiting: eine optionale Middleware, die Ihre Anwendung vor dem API-Limit von Unsplash schützt

Installation

Das Paket kommt über Composer, die Konfiguration wird per Artisan veröffentlicht:

composer require xchimx/laravel-unsplash
php artisan vendor:publish --provider="Xchimx\UnsplashApi\UnsplashServiceProvider" --tag="config"

Danach fehlt nur noch der API-Key aus Ihrem Unsplash-Developer-Konto in der .env-Datei:

UNSPLASH_ACCESS_KEY=your_unsplash_access_key

Nutzung: Service oder Facade

Sie können den UnsplashService klassisch per Dependency Injection nutzen – oder die mitgelieferte Facade, wenn es schnell gehen soll:

use Xchimx\UnsplashApi\Facades\Unsplash;

class UnsplashController extends Controller
{
    public function search()
    {
        $photos = Unsplash::searchPhotos('Nature');

        return view('unsplash.search', compact('photos'));
    }
}

Für die erweiterte Suche stehen Ihnen die Parameter der Unsplash-API offen:

$photos = Unsplash::searchPhotosAdvanced([
    'query' => 'Kassel',
    'orientation' => 'landscape',
    'per_page' => 24,
]);

Rate Limiting gegen das API-Limit

Unsplash begrenzt die API-Zugriffe je nach Zugangsstufe. Damit Ihre Anwendung nicht unbemerkt ins Limit läuft, aktivieren Sie die mitgelieferte Middleware über zwei Umgebungsvariablen:

UNSPLASH_RATE_LIMITING_ENABLED=true
UNSPLASH_RATE_LIMITING_THRESHOLD=10

Praxis-Tipp: Unsplash-Richtlinien einhalten

Unsplash verlangt für produktive Anwendungen, dass Downloads über den offiziellen Download-Endpoint gemeldet werden – genau dafür gibt es getPhotoDownloadLink(). Wer Bilder nur per URL einbettet, ohne das Tracking auszulösen, riskiert die Ablehnung des Production-Zugangs.

Fazit

laravel-unsplash nimmt Ihnen die komplette API-Anbindung ab – von der Authentifizierung bis zum Rate Limiting. Den Quellcode finden Sie auf GitHub, die Installation läuft über Packagist. Und wenn Sie Unterstützung bei Ihrem Projekt brauchen: Hier finden Sie meine Leistungen rund um Laravel Entwicklung in Kassel.