PHPackages                             xchimx/laravel-unsplash - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [API Development](/categories/api)
4. /
5. xchimx/laravel-unsplash

ActiveLibrary[API Development](/categories/api)

xchimx/laravel-unsplash
=======================

Laravel package for easy integration with the Unsplash API. It allows you to use the Unsplash API in your Laravel applications to fetch photos, collections, and user data.

1.0.2(1w ago)247.6k↓17.3%3MITPHPPHP ^8.0

Since Oct 1Pushed 1w ago1 watchersCompare

[ Source](https://github.com/xchimx/laravel-unsplash)[ Packagist](https://packagist.org/packages/xchimx/laravel-unsplash)[ Docs](https://www.schottstaedt.net)[ RSS](/packages/xchimx-laravel-unsplash/feed)WikiDiscussions main Synced 2d ago

READMEChangelog (3)Dependencies (4)Versions (4)Used By (0)

About Laravel-Unsplash
======================

[](#about-laravel-unsplash)

A Laravel package for easy integration with the Unsplash API. It allows you to use the Unsplash API in your Laravel applications to fetch photos, collections, and user data. Current supported Laravel versions 9/10/11/12/13

- [Laravel](https://laravel.com/)
- [Urlscan](https://unsplash.com/)
- [Schottstaedt](https://www.schottstaedt.net/)

\---

- [About Laravel-Unsplash](#about-laravel-unsplash)
    - [Installation](#installation)
    - [Usage](#usage)
        - [Basic Usage](#basic-usage)
        - [Using the Facade](#using-the-facade)
    - [UnsplashService Methods](#unsplashservice-methods)
    - [Controller Examples](#controller-examples)
        - [1. searchPhotos](#1-searchphotos)
        - [2. searchPhotosAdvanced](#2-searchphotosadvanced)
        - [3. getPhoto](#3-getphoto)
        - [4. getRandomPhoto](#4-getrandomphoto)
        - [5. getPhotoDownloadLink](#5-getphotodownloadlink)
        - [6. listCollections](#6-listcollections)
        - [7. getCollection](#7-getcollection)
        - [8. getUser](#8-getuser)
        - [9. getUserPhotos](#9-getuserphotos)
        - [10. searchCollections](#10-searchcollections)
        - [11. withOptions](#11-withoptions)
    - [Rate Limiting Middleware](#rate-limiting-middleware)
        - [Configuration](#configuration)
        - [Usage](#usage-1)
    - [Error Handling](#error-handling)
    - [Notes on the Unsplash API](#notes-on-the-unsplash-api)
    - [License](#license)

Installation
------------

[](#installation)

You can install the package via composer:

```
composer require xchimx/laravel-unsplash
```

Publish the config file using the artisan CLI tool:

```
php artisan vendor:publish --provider="Xchimx\UnsplashApi\UnsplashServiceProvider" --tag="config"
```

finally set the [API Key](https://urlscan.io/docs/api/) in your ENV file:

```
UNSPLASH_ACCESS_KEY=your_unsplash_access_key
```

Optional Rate Limiting settings in ENV file:

```
UNSPLASH_RATE_LIMITING_ENABLED=true
UNSPLASH_RATE_LIMITING_THRESHOLD=10
```

Usage
-----

[](#usage)

### Basic Usage

[](#basic-usage)

You can use the UnsplashService in your controllers by injecting it via Dependency Injection:

```
use Xchimx\UnsplashApi\UnsplashService;

class UnsplashController extends Controller
{
    protected $unsplashService;

    public function __construct(UnsplashService $unsplashService)
    {
        $this->unsplashService = $unsplashService;
    }

    public function search()
    {
        $photos = $this->unsplashService->searchPhotos('Nature');

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

### Using the Facade

[](#using-the-facade)

Alternatively, you can use the provided Unsplash facade:

```
use Xchimx\UnsplashApi\Facades\Unsplash;

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

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

UnsplashService Methods
-----------------------

[](#unsplashservice-methods)

The UnsplashService provides the following methods:

1. searchPhotos($query, $perPage = 10, $page = 1)
2. searchPhotosAdvanced(array $params)
3. getPhoto($id)
4. getRandomPhoto(array $params = \[\])
5. getPhotoDownloadLink($id)
6. listCollections($perPage = 10, $page = 1)
7. getCollection($id)
8. getUser($username)
9. getUserPhotos($username, $perPage = 10, $page = 1)
10. searchCollections($query, $perPage = 10, $page = 1)
11. withOptions(array $options)

Controller Examples
-------------------

[](#controller-examples)

Here are comprehensive controller examples showing how to use the various methods of the UnsplashService in your Laravel controllers.

### 1. searchPhotos

[](#1-searchphotos)

```
namespace App\Http\Controllers;

use Illuminate\Http\Request;
use Xchimx\UnsplashApi\Facades\Unsplash;

class UnsplashController extends Controller
{
    public function search(Request $request)
    {
        $query = $request->input('query', 'Nature');
        $photos = Unsplash::searchPhotos($query);

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

Blade View:

```
@extends('layouts.app')

@section('content')
Photo by {{ $photo['user']['name'] }}

{{ $photo['description'] ?? 'No description available.' }}
@endsection

```

### 2. searchPhotosAdvanced

[](#2-searchphotosadvanced)

```
namespace App\Http\Controllers;

use Illuminate\Http\Request;
use Xchimx\UnsplashApi\Facades\Unsplash;

class UnsplashController extends Controller
{
    public function advancedSearch(Request $request)
    {
        $params = [
            'query' => $request->input('query', 'Nature'),
            'color' => $request->input('color'),
            'orientation' => $request->input('orientation'),
            'per_page' => $request->input('per_page', 15),
            'page' => $request->input('page', 1),
        ];

        $params = array_filter($params);

        $response = Unsplash::searchPhotosAdvanced($params);

        $photos = $response['results'];

        return view('unsplash.advanced_search', compact('photos', 'params'));
    }
}
```

### 3. getPhoto

[](#3-getphoto)

```
namespace App\Http\Controllers;

use Xchimx\UnsplashApi\Facades\Unsplash;

class UnsplashController extends Controller
{
    public function show($id)
    {
        $photo = Unsplash::getPhoto($id);

        return view('unsplash.show', compact('photo'));
    }
}
```

Blade View:

```
@extends('layouts.app')

@section('content')
Photo by {{ $photo['user']['name'] }}

{{ $photo['description'] ?? 'No description available.' }}
@endsection

```

### 4. getRandomPhoto

[](#4-getrandomphoto)

```
namespace App\Http\Controllers;

use Xchimx\UnsplashApi\Facades\Unsplash;

class RandomPhotoController extends Controller
{
    public function show()
    {
        $photo = Unsplash::getRandomPhoto();

        return view('photos.random', compact('photo'));
    }
}
```

Blade View:

```
@extends('layouts.app')

@section('content')
Random Photo

Photo by {{ $photo['user']['name'] }}
@endsection

```

### 5. getPhotoDownloadLink

[](#5-getphotodownloadlink)

```
namespace App\Http\Controllers;

use Xchimx\UnsplashApi\Facades\Unsplash;

class UnsplashController extends Controller
{
    public function download($id)
    {
        $downloadUrl = Unsplash::getPhotoDownloadLink($id);

        return redirect($downloadUrl);
    }
}
```

### 6. listCollections

[](#6-listcollections)

```
namespace App\Http\Controllers;

use Illuminate\Http\Request;
use Xchimx\UnsplashApi\Facades\Unsplash;

class CollectionController extends Controller
{
    public function index(Request $request)
    {
        $page = $request->input('page', 1);
        $collections = Unsplash::listCollections(15, $page);

        return view('collections.index', compact('collections'));
    }
}
```

Blade View:

```
@extends('layouts.app')

@section('content')
Collections
@foreach ($collections as $collection)

    {{ $collection['title'] }}
    {{ $collection['description'] ?? 'No description' }}
    View Details

@endforeach
@endsection

```

### 7. getCollection

[](#7-getcollection)

```
namespace App\Http\Controllers;

use Xchimx\UnsplashApi\Facades\Unsplash;

class CollectionController extends Controller
{
    public function show($id)
    {
        $collection = Unsplash::getCollection($id);

        return view('collections.show', compact('collection'));
    }
}
```

Blade View:

```
@extends('layouts.app')

@section('content')
{{ $collection['title'] }}
{{ $collection['description'] ?? 'No description available.' }}

@endsection

```

### 8. getUser

[](#8-getuser)

```
namespace App\Http\Controllers;

use Illuminate\Http\Request;
use Xchimx\UnsplashApi\Facades\Unsplash;

class UserController extends Controller
{
    public function user($username, Request $request)
    {
        $user  = Unsplash::getUser($name);

        return view('user', compact('user'));
    }
}
```

### 9. getUserPhotos

[](#9-getuserphotos)

```
namespace App\Http\Controllers;

use Illuminate\Http\Request;
use Xchimx\UnsplashApi\Facades\Unsplash;

class UserController extends Controller
{
    public function photos($username, Request $request)
    {
        $page = $request->input('page', 1);
        $photos = Unsplash::getUserPhotos($username, 15, $page);

        return view('users.photos', compact('photos', 'username'));
    }
}
```

Blade View:

```
@extends('layouts.app')

@section('content')
Photos by {{ $username }}
@foreach ($photos as $photo)

    {{ $photo['description'] ?? 'No description' }}

@endforeach
@endsection

```

### 10. searchCollections

[](#10-searchcollections)

```
namespace App\Http\Controllers;

use Illuminate\Http\Request;
use Xchimx\UnsplashApi\Facades\Unsplash;

class CollectionController extends Controller
{
    public function search(Request $request)
    {
        $query = $request->input('query', 'Nature');
        $page = $request->input('page', 1);

        $collections = Unsplash::searchCollections($query, 15, $page);

        return view('collections.search', compact('collections', 'query'));
    }
}
```

Blade View:

```
@extends('layouts.app')

@section('content')
Search Results for Collections: "{{ $query }}"
@foreach ($collections['results'] as $collection)

    {{ $collection['title'] }}
    {{ $collection['description'] ?? 'No description' }}
    View Photos
    @endforeach
@endsection

```

### 11. withOptions

[](#11-withoptions)

```
namespace App\Http\Controllers;

use Illuminate\Http\Request;
use Xchimx\UnsplashApi\Facades\Unsplash;

class CollectionController extends Controller
{
    public function searchWithTimeout(Request $request)
    {
        // Use withOptions to set custom Guzzle options, e.g., timeout
        $photos = Unsplash::withOptions(['timeout' => 2])->searchPhotos('Nature');

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

Blade View:

```
@extends('layouts.app')

@section('content')
Search Results for Collections: "{{ $query }}"
@foreach ($collections['results'] as $collection)

    {{ $collection['title'] }}
    {{ $collection['description'] ?? 'No description' }}
    View Photos
    @endforeach
@endsection

```

Rate Limiting Middleware
------------------------

[](#rate-limiting-middleware)

This package includes middleware to monitor and handle the Unsplash API rate limits. The middleware is enabled by default and can be customized in the configuration options.

### Configuration

[](#configuration)

The rate limiting settings are located in config/unsplash.php:

```
'rate_limiting' => [
    'enabled' => env('UNSPLASH_RATE_LIMITING_ENABLED', true),
    'threshold' => env('UNSPLASH_RATE_LIMITING_THRESHOLD', 10),
],
```

- enabled: Enables or disables the rate limiting middleware.
- threshold: The threshold for remaining requests at which the middleware intervenes.

### Usage

[](#usage-1)

To use the middleware in your routes, add it as follows:

```
Route::middleware(['unsplash.rate_limit'])->group(function () {
    Route::get('/unsplash/search', [UnsplashController::class, 'search'])->name('unsplash.search');
    // Other routes...
});
```

Error Handling
--------------

[](#error-handling)

It's important to handle errors during API calls, especially when communicating with external services.

```
public function search(Request $request)
{
    try {
        $photos = Unsplash::searchPhotos('Nature');
    } catch (\Exception $e) {
        // Log the error or display a user-friendly message
        return back()->withErrors('There was a problem communicating with the Unsplash API.');
    }

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

Notes on the Unsplash API
-------------------------

[](#notes-on-the-unsplash-api)

- Rate Limits: The Unsplash API has rate limits. Be sure to monitor the number of requests and use the provided middleware.
- Attribution: When using photos, you must credit the photographers according to Unsplash's guidelines.
- API Documentation: For more details, refer to the Unsplash API Documentation.

License
-------

[](#license)

This package is released under the MIT License.

###  Health Score

50

—

FairBetter than 95% of packages

Maintenance98

Actively maintained with recent releases

Popularity34

Limited adoption so far

Community11

Small or concentrated contributor base

Maturity47

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 80% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~315 days

Total

3

Last Release

10d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/e2d73ea67bfaa26a0421424b9baac10286c4f68dfae5d6d3a124be91abc565a0?d=identicon)[xchimx](/maintainers/xchimx)

---

Top Contributors

[![xchimx](https://avatars.githubusercontent.com/u/3500927?v=4)](https://github.com/xchimx "xchimx (4 commits)")[![angeloo](https://avatars.githubusercontent.com/u/1065919?v=4)](https://github.com/angeloo "angeloo (1 commits)")

---

Tags

laravellaravel-unsplashunsplashapilaravelimagesphotosUnsplashlaravel-unsplashschottstaedt.netTobias Schottstädt

### Embed Badge

![Health badge](/badges/xchimx-laravel-unsplash/health.svg)

```
[![Health](https://phpackages.com/badges/xchimx-laravel-unsplash/health.svg)](https://phpackages.com/packages/xchimx-laravel-unsplash)
```

###  Alternatives

[statamic/cms

The Statamic CMS Core Package

4.8k3.6M985](/packages/statamic-cms)[openai-php/laravel

OpenAI PHP for Laravel is a supercharged PHP API client that allows you to interact with the Open AI API

3.7k9.5M89](/packages/openai-php-laravel)[darkaonline/l5-swagger

OpenApi or Swagger integration to Laravel

3.0k37.6M134](/packages/darkaonline-l5-swagger)[backpack/crud

Quickly build admin interfaces using Laravel, Bootstrap and JavaScript.

3.4k3.7M223](/packages/backpack-crud)[unopim/unopim

UnoPim Laravel PIM

10.5k2.4k](/packages/unopim-unopim)[knuckleswtf/scribe

Generate API documentation for humans from your Laravel codebase.✍

2.3k14.2M62](/packages/knuckleswtf-scribe)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)