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.1(1y ago)246.6k↓17.9%3MITPHPPHP ^8.0

Since Oct 1Pushed 1y 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 1mo ago

READMEChangelog (2)Dependencies (2)Versions (3)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

- [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

37

—

LowBetter than 83% of packages

Maintenance46

Moderate activity, may be stable

Popularity34

Limited adoption so far

Community11

Small or concentrated contributor base

Maturity45

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 ~179 days

Total

2

Last Release

415d 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

apilaravelimagesphotosUnsplashlaravel-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

[openai-php/laravel

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

3.7k7.6M74](/packages/openai-php-laravel)[darkaonline/l5-swagger

OpenApi or Swagger integration to Laravel

2.9k34.0M112](/packages/darkaonline-l5-swagger)[knuckleswtf/scribe

Generate API documentation for humans from your Laravel codebase.✍

2.3k12.2M45](/packages/knuckleswtf-scribe)[nickurt/laravel-postcodeapi

Universal PostcodeApi for Laravel 11.x/12.x/13.x

97221.2k](/packages/nickurt-laravel-postcodeapi)[mozex/anthropic-laravel

Anthropic PHP for Laravel is a supercharged PHP API client that allows you to interact with the Anthropic API

71226.4k1](/packages/mozex-anthropic-laravel)[scriptdevelop/whatsapp-manager

Paquete para manejo de WhatsApp Business API en Laravel

762.6k](/packages/scriptdevelop-whatsapp-manager)

PHPackages © 2026

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