Integrating Unsplash photos in Laravel: the laravel-unsplash package

With my open-source package laravel-unsplash you integrate the Unsplash API into your Laravel application in a few minutes: photo search, random images, collections and user data – via a service class or a facade. The package supports Laravel 9 to 13, ships with an optional rate-limiting middleware and, with more than 20 stars, is my most popular package on GitHub.

What the package does

• Photo search: simple search with searchPhotos() or fine-tuned with searchPhotosAdvanced() – for example by colour, orientation and sorting

• Single photos: getPhoto(), getRandomPhoto() and getPhotoDownloadLink() for Unsplash-compliant download tracking

• Collections and users: listCollections(), getCollection(), searchCollections(), getUser() and getUserPhotos()

• Rate limiting: an optional middleware that protects your application from hitting the Unsplash API limit

Installation

The package is installed via Composer, the configuration is published with Artisan:

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

After that, all that is missing is the API key from your Unsplash developer account in the .env file:

UNSPLASH_ACCESS_KEY=your_unsplash_access_key

Usage: service or facade

You can use the UnsplashService via classic dependency injection – or the included facade if you want to move fast:

use Xchimx\UnsplashApi\Facades\Unsplash;

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

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

For advanced search, the Unsplash API parameters are available:

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

Rate limiting against the API limit

Unsplash limits API access depending on your access tier. To keep your application from silently hitting the limit, enable the included middleware via two environment variables:

UNSPLASH_RATE_LIMITING_ENABLED=true
UNSPLASH_RATE_LIMITING_THRESHOLD=10

Practical tip: follow the Unsplash guidelines

For production applications, Unsplash requires downloads to be reported via the official download endpoint – that is exactly what getPhotoDownloadLink() is for. If you only embed images by URL without triggering the tracking, you risk being rejected for production access.

Conclusion

laravel-unsplash takes the entire API integration off your hands – from authentication to rate limiting. You can find the source code on GitHub, installation runs via Packagist. And if you need support with your project: here are my services around Laravel development in Kassel.