Laravel Unsplash

https://github.com/xchimx/laravel-unsplash
Admin
A Laravel package that provides easy integration with the Unsplash API to fetch photos, collections,...
Tokens:10,220
Snippets:53
Trust Score:6.8
Update:8 months ago
Show doc for...
Tokens:
Raw
### Install Laravel-Unsplash Package

Source: https://github.com/xchimx/laravel-unsplash/blob/main/readme.md

Installs the Laravel-Unsplash package using Composer. This is the first step to integrate Unsplash API functionalities into your Laravel application.

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

--------------------------------

### Search Photos with Laravel-Unsplash

Source: https://github.com/xchimx/laravel-unsplash/blob/main/readme.md

An example controller method that searches for photos based on a user-provided query, defaulting to 'Nature'. It utilizes the Unsplash facade for searching.

```php
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'));
    }
}
```

--------------------------------

### GET /collections

Source: https://context7.com/xchimx/laravel-unsplash/llms.txt

List all public collections with pagination.

```APIDOC
## GET /collections

### Description
List all public collections with pagination.

### Method
GET

### Endpoint
`/collections`

### Parameters
#### Query Parameters
- **page** (integer) - Optional - The page number of results to retrieve.
- **per_page** (integer) - Optional - The number of results per page (defaults to 15).

### Response
#### Success Response (200)
- **id** (integer) - The collection's unique identifier.
- **title** (string) - The title of the collection.
- **description** (string) - A description of the collection.
- **total_photos** (integer) - The total number of photos in the collection.
- **cover_photo** (object) - Information about the cover photo of the collection.
- **user** (object) - Information about the user who created the collection.
  - **name** (string) - The user's name.

#### Response Example
```json
[
    {
        "id": 296,
        "title": "I like a man with a beard.",
        "description": "Beards, bears, and men.",
        "total_photos": 12,
        "cover_photo": { ... },
        "user": {
            "name": "Jane Doe"
        }
    }
    // ... more collections
]
```
```

--------------------------------

### Handle Unsplash API Errors Gracefully (PHP)

Source: https://github.com/xchimx/laravel-unsplash/blob/main/readme.md

Provides an example of how to implement error handling for Unsplash API calls using a try-catch block. This allows for logging errors or displaying user-friendly messages when communication with the API fails.

```php
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'));
}
```

--------------------------------

### GET /photos/{id}/download

Source: https://context7.com/xchimx/laravel-unsplash/llms.txt

Get the download URL for a photo (triggers Unsplash download tracking).

```APIDOC
## GET /photos/{id}/download

### Description
Get the download URL for a photo. This endpoint triggers Unsplash's download tracking mechanism. It's recommended to use this before initiating a download to comply with API guidelines.

### Method
GET

### Endpoint
`/photos/{id}/download`

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the photo to download.

### Response
#### Success Response (200)
- **photo_id** (string) - The unique identifier of the photo.
- **download_url** (string) - The URL from which the photo can be downloaded.

#### Response Example
```json
{
    "photo_id": "Dwu85P9SOIk",
    "download_url": "https://unsplash.com/photos/Dwu85P9SOIk/download?force=true"
}
```
```

--------------------------------

### Get Photo Download Link

Source: https://github.com/xchimx/laravel-unsplash/blob/main/readme.md

Generates a direct download link for a specific photo using its ID. This controller fetches the download URL via the Unsplash facade and then redirects the user to that URL. It requires a photo ID as input.

```php
namespace App\Http\Controllers;

use Xchimx\UnsplashApi\Facades\Unsplash;

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

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

--------------------------------

### GET /photos/{id}

Source: https://context7.com/xchimx/laravel-unsplash/llms.txt

Retrieve a single photo by its unique ID with full metadata.

```APIDOC
## GET /photos/{id}

### Description
Retrieve a single photo by its unique ID with full metadata.

### Method
GET

### Endpoint
`/photos/{id}`

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the photo.

### Response
#### Success Response (200)
- **id** (string) - The photo's unique identifier.
- **width** (integer) - The photo's width in pixels.
- **height** (integer) - The photo's height in pixels.
- **color** (string) - The dominant color of the photo.
- **description** (string) - The photo's description.
- **alt_description** (string) - Alternative description for accessibility.
- **urls** (object) - Object containing different URL formats for the photo.
  - **raw** (string) - URL for the original image.
  - **full** (string) - URL for the full-size image.
  - **regular** (string) - URL for a regular-size image.
  - **small** (string) - URL for a small-size image.
  - **thumb** (string) - URL for a thumbnail image.
- **user** (object) - Information about the photo's uploader.
  - **name** (string) - The user's name.
  - **username** (string) - The user's username.
  - **portfolio_url** (string) - The user's portfolio URL.
- **exif** (object) - Exchangeable image file format data.
  - **make** (string) - Camera manufacturer.
  - **model** (string) - Camera model.
- **location** (object) - The location where the photo was taken.
  - **city** (string) - The city.
  - **country** (string) - The country.

#### Response Example
```json
{
    "id": "Dwu85P9SOIk",
    "width": 2448,
    "height": 3264,
    "color": "#6E633A",
    "description": "A scenic view...",
    "alt_description": "Mountain landscape",
    "urls": {
        "raw": "https://images.unsplash.com/photo-1506744038136-46273834b3fb?ixlib=rb-1.2.1&q=80&fm=jpg&crop=entropy&cs=tinysrgb&w=1080&fit=max",
        "full": "https://images.unsplash.com/photo-1506744038136-46273834b3fb?ixlib=rb-1.2.1&q=80&fm=jpg&crop=entropy&cs=tinysrgb&w=1080&fit=max",
        "regular": "https://images.unsplash.com/photo-1506744038136-46273834b3fb?ixlib=rb-1.2.1&q=80&fm=jpg&crop=entropy&cs=tinysrgb&w=1080&fit=max",
        "small": "https://images.unsplash.com/photo-1506744038136-46273834b3fb?ixlib=rb-1.2.1&q=80&fm=jpg&crop=entropy&cs=tinysrgb&w=400&fit=max",
        "thumb": "https://images.unsplash.com/photo-1506744038136-46273834b3fb?ixlib=rb-1.2.1&q=80&fm=jpg&crop=entropy&cs=tinysrgb&w=200&fit=max"
    },
    "user": {
        "name": "John Doe",
        "username": "johndoe",
        "portfolio_url": "https://example.com/johndoe"
    },
    "exif": {
        "make": "Canon",
        "model": "EOS 5D"
    },
    "location": {
        "city": "Denver",
        "country": "USA"
    }
}
```
```

--------------------------------

### GET /photos/random

Source: https://context7.com/xchimx/laravel-unsplash/llms.txt

Fetch a random photo, optionally filtered by query, collections, or topics.

```APIDOC
## GET /photos/random

### Description
Fetch a random photo, optionally filtered by query, collections, or topics.

### Method
GET

### Endpoint
`/photos/random`

### Parameters
#### Query Parameters
- **query** (string) - Optional - Search term to filter random photos.
- **collections** (string) - Optional - Comma-separated list of collection IDs to filter by.
- **content_filter** (string) - Optional - Filter for 'low' or 'high' quality adult content.
- **orientation** (string) - Optional - Orientation of the photo (e.g., 'landscape', 'portrait', 'squarish').

### Response
#### Success Response (200)
- **id** (string) - The photo's unique identifier.
- **urls** (object) - Object containing different URL formats for the photo.
  - **regular** (string) - URL for a regular-size image.
- **user** (object) - Information about the photo's uploader.
  - **name** (string) - The user's name.
- **links** (object) - Links related to the photo.
  - **download_location** (string) - URL to get the download location.

#### Response Example (Filtered)
```json
{
    "id": "some_random_photo_id",
    "urls": {
        "regular": "https://images.unsplash.com/photo-1506744038136-46273834b3fb?ixlib=rb-1.2.1&q=80&fm=jpg&crop=entropy&cs=tinysrgb&w=1080&fit=max"
    },
    "user": {
        "name": "Random Photographer"
    },
    "links": {
        "download_location": "https://api.unsplash.com/photos/some_random_photo_id/download"
    }
}
```
```

--------------------------------

### Get User Information

Source: https://github.com/xchimx/laravel-unsplash/blob/main/readme.md

Fetches information about a specific Unsplash user based on their username. This controller utilizes the Unsplash facade and passes the user data to a 'user' Blade view. It requires the username as a parameter.

```php
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); // Note: 'name' should likely be '$username'

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

--------------------------------

### Get User Photos

Source: https://github.com/xchimx/laravel-unsplash/blob/main/readme.md

Retrieves a list of photos uploaded by a specific Unsplash user, with pagination support. It takes the username, a limit per page (hardcoded to 15), and the page number as input. The photos and username are passed to a Blade view. Requires the Request and Unsplash facades.

```php
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'));
    }
}
```

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

@section('content')
<h1>Photos by {{ $username }}</h1>
@foreach ($photos as $photo)
<div>
    <img src="{{ $photo['urls']['small'] }}" alt="{{ $photo['alt_description'] }}">
    <p>{{ $photo['description'] ?? 'No description' }}</p>
</div>
@endforeach
@endsection
```

--------------------------------

### Get User Photos with Pagination (PHP)

Source: https://context7.com/xchimx/laravel-unsplash/llms.txt

Fetches all public photos uploaded by a specific Unsplash user, supporting pagination to manage large result sets. It first retrieves the user's profile and then their photos, returning a view with both. Error handling for non-existent users is included. Requires the Unsplash facade and the Request object.

```php
<?php

namespace App\Http\Controllers;

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

class UserController extends Controller
{
    public function photos(string $username, Request $request)
    {
        $perPage = 20;
        $page = $request->input('page', 1);

        try {
            $user = Unsplash::getUser($username);
            $photos = Unsplash::getUserPhotos($username, $perPage, $page);

            // $photos is an array of photo objects

            return view('users.photos', [
                'user' => $user,
                'photos' => $photos,
                'page' => $page
            ]);
        } catch (\Exception $e) {
            abort(404, 'User not found');
        }
    }
}

```

--------------------------------

### Get a Specific Photo by ID

Source: https://github.com/xchimx/laravel-unsplash/blob/main/readme.md

Fetches a single photo from Unsplash using its unique ID. It utilizes the Unsplash facade and returns a view with the photo details. Dependencies include the Unsplash API service and a Blade view for rendering.

```php
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'));
    }
}
```

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

@section('content')
<h1>Photo by {{ $photo['user']['name'] }}</h1>
<img src="{{ $photo['urls']['regular'] }}" alt="{{ $photo['alt_description'] }}">
<p>{{ $photo['description'] ?? 'No description available.' }}</p>
@endsection
```

--------------------------------

### Get a Random Photo

Source: https://github.com/xchimx/laravel-unsplash/blob/main/readme.md

Retrieves a random photo from Unsplash. This function uses the Unsplash facade to fetch the photo and then renders it using a dedicated Blade view. No specific input is required, and the output is a single photo object.

```php
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'));
    }

}
```

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

@section('content')
<h1>Random Photo</h1>
<img src="{{ $photo['urls']['regular'] }}" alt="{{ $photo['alt_description'] }}">
<p>Photo by {{ $photo['user']['name'] }}</p>
@endsection
```

--------------------------------

### Get a Specific Collection by ID

Source: https://github.com/xchimx/laravel-unsplash/blob/main/readme.md

Retrieves details for a specific Unsplash collection using its ID. This controller uses the Unsplash facade to fetch the collection data and then renders it in a dedicated Blade view. It requires the collection ID as a parameter.

```php
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'));
    }
}
```

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

@section('content')
<h1>{{ $collection['title'] }}</h1>
<p>{{ $collection['description'] ?? 'No description available.' }}</p>
<!-- Display additional details -->
@endsection
```

--------------------------------

### Get Photo Download Link (PHP)

Source: https://context7.com/xchimx/laravel-unsplash/llms.txt

Provides the download URL for a specific photo, which is essential for triggering Unsplash's download tracking mechanism. This method must be used before initiating a download to comply with Unsplash API guidelines. It includes error handling for cases where the download URL cannot be retrieved.

```php
<?php

namespace App\Http\Controllers;

use Xchimx\UnsplashApi\Facades\Unsplash;

class DownloadController extends Controller
{
    public function download(string $id)
    {
        try {
            // This triggers the download endpoint which Unsplash uses for tracking
            // Always use this before downloading to comply with API guidelines
            $downloadUrl = Unsplash::getPhotoDownloadLink($id);

            if ($downloadUrl) {
                return redirect($downloadUrl);
            }

            return back()->withErrors('Download URL not available.');
        } catch (\Exception $e) {
            return back()->withErrors('Failed to get download link.');
        }
    }

    public function getDownloadInfo(string $id)
    {
        $downloadUrl = Unsplash::getPhotoDownloadLink($id);

        return response()->json([
            'photo_id' => $id,
            'download_url' => $downloadUrl
        ]);
    }
}

```

--------------------------------

### Get Collection Details by ID (PHP)

Source: https://context7.com/xchimx/laravel-unsplash/llms.txt

Fetches detailed information about a specific Unsplash collection using its unique ID. It handles potential exceptions and returns a view with the collection data or a 404 error if not found. Dependencies include the Unsplash facade.

```php
<?php

namespace App\Http\Controllers;

use Xchimx\UnsplashApi\Facades\Unsplash;

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

            // Response includes:
            // [
            //     'id' => 296,
            //     'title' => 'I like a man with a beard.',
            //     'description' => 'Beards, bears, and men.',
            //     'published_at' => '2016-01-12T18:16:09-05:00',
            //     'total_photos' => 12,
            //     'private' => false,
            //     'cover_photo' => [...],
            //     'user' => ['name' => 'Jane Doe', 'username' => 'janedoe', ...],
            //     'links' => ['self' => '...', 'html' => '...', 'photos' => '...']
            // ]

            return view('collections.show', compact('collection'));
        } catch (\Exception $e) {
            abort(404, 'Collection not found');
        }
    }
}

```

--------------------------------

### Get User Profile by Username (PHP)

Source: https://context7.com/xchimx/laravel-unsplash/llms.txt

Retrieves the public profile information for a given Unsplash user identified by their username. This function includes error handling for cases where the user is not found, returning a 404 error. It depends on the Unsplash facade for API interaction.

```php
<?php

namespace App\Http\Controllers;

use Xchimx\UnsplashApi\Facades\Unsplash;

class UserController extends Controller
{
    public function show(string $username)
    {
        try {
            $user = Unsplash::getUser($username);

            // Response includes:
            // [
            //     'id' => 'pXhwzz1JtQU',
            //     'username' => 'johndoe',
            //     'name' => 'John Doe',
            //     'bio' => 'Photographer based in NYC',
            //     'location' => 'New York',
            //     'total_photos' => 45,
            //     'total_collections' => 3,
            //     'profile_image' => ['small' => '...', 'medium' => '...', 'large' => '...'],
            //     'links' => ['self' => '...', 'html' => '...', 'photos' => '...']
            // ]

            return view('users.show', compact('user'));
        } catch (\Exception $e) {
            abort(404, 'User not found');
        }
    }
}

```

--------------------------------

### Basic Unsplash Service Usage in Laravel Controller

Source: https://github.com/xchimx/laravel-unsplash/blob/main/readme.md

Demonstrates how to use the UnsplashService in a Laravel controller by injecting it via Dependency Injection. It fetches nature photos and passes them to a view.

```php
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'));
    }
}
```

--------------------------------

### Unsplash Facade Usage in Laravel Controller

Source: https://github.com/xchimx/laravel-unsplash/blob/main/readme.md

Shows an alternative way to use the Unsplash API in a Laravel controller using the provided Unsplash facade. This method simplifies direct access to Unsplash functionalities.

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

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

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

--------------------------------

### Configure Unsplash API Key and Rate Limiting

Source: https://github.com/xchimx/laravel-unsplash/blob/main/readme.md

Sets the Unsplash API Access Key and optional rate limiting settings in the .env file. Ensure you replace 'your_unsplash_access_key' with your actual key.

```php
UNSPLASH_ACCESS_KEY=your_unsplash_access_key
UNSPLASH_RATE_LIMITING_ENABLED=true
UNSPLASH_RATE_LIMITING_THRESHOLD=10
```

--------------------------------

### Apply Rate Limiting Middleware to Routes (PHP)

Source: https://github.com/xchimx/laravel-unsplash/blob/main/readme.md

Illustrates how to apply the 'unsplash.rate_limit' middleware to specific routes within a Laravel application. This ensures that routes protected by this middleware will adhere to the configured Unsplash API rate limits.

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

--------------------------------

### Configure Unsplash API Rate Limiting (PHP)

Source: https://github.com/xchimx/laravel-unsplash/blob/main/readme.md

Shows how to configure the rate limiting middleware for the Unsplash API package. This includes enabling/disabling the middleware and setting a threshold for remaining requests before intervention.

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

--------------------------------

### Search Photos with Custom Timeout (PHP)

Source: https://github.com/xchimx/laravel-unsplash/blob/main/readme.md

Demonstrates how to search for photos using the Unsplash API facade and set a custom timeout option for the HTTP request. This is useful for controlling the maximum time spent waiting for a response from the API.

```php
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'));
    }
}
```

--------------------------------

### Publish Laravel-Unsplash Configuration

Source: https://github.com/xchimx/laravel-unsplash/blob/main/readme.md

Publishes the configuration file for the Laravel-Unsplash package using the Artisan CLI. This allows you to customize package settings.

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

--------------------------------

### List Collections

Source: https://github.com/xchimx/laravel-unsplash/blob/main/readme.md

Fetches a list of Unsplash collections, allowing for pagination. It takes an optional page number and a limit per page (hardcoded to 15). The results are passed to a Blade view for display. Requires the Request facade and Unsplash facade.

```php
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'));
    }
}
```

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

@section('content')
<h1>Collections</h1>
@foreach ($collections as $collection)
<div>
    <h2>{{ $collection['title'] }}</h2>
    <p>{{ $collection['description'] ?? 'No description' }}</p>
    <a href="{{ route('collections.show', $collection['id']) }}">View Details</a>
</div>
@endforeach
@endsection
```

--------------------------------

### Displaying a Single Photo in Blade View

Source: https://github.com/xchimx/laravel-unsplash/blob/main/readme.md

A Blade template snippet to display a single photo fetched from Unsplash. It shows the photographer's name, the image itself, and its description.

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

@section('content')
<h1>Photo by {{ $photo['user']['name'] }}</h1>
<img src="{{ $photo['urls']['regular'] }}" alt="{{ $photo['alt_description'] }}">
<p>{{ $photo['description'] ?? 'No description available.' }}</p>
@endsection
```

--------------------------------

### Use Unsplash Service via Dependency Injection in Laravel Controller

Source: https://context7.com/xchimx/laravel-unsplash/llms.txt

Demonstrates how to inject the UnsplashService into a Laravel controller for accessing Unsplash API functionalities. This approach promotes cleaner code and better testability compared to using facades.

```php
<?php

namespace App\Http\Controllers;

use Illuminate\Http\Request;
use Xchimx\UnsplashApi\UnsplashService;

class PhotoController extends Controller
{
    protected UnsplashService $unsplash;

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

    public function search(Request $request)
    {
        $query = $request->input('query', 'nature');
        $photos = $this->unsplash->searchPhotos($query, 15, 1);

        return view('photos.search', ['photos' => $photos['results']]);
    }

    public function featured()
    {
        // Access rate limit headers from the last request
        $photos = $this->unsplash->searchPhotos('featured', 10);
        $headers = $this->unsplash->getLastResponseHeaders();

        $rateLimit = $headers['X-Ratelimit-Limit'][0] ?? 'unknown';
        $remaining = $headers['X-Ratelimit-Remaining'][0] ?? 'unknown';

        return response()->json([
            'photos' => $photos['results'],
            'rate_limit' => $rateLimit,
            'remaining' => $remaining
        ]);
    }
}

```

--------------------------------

### Display Search Results for Collections (Blade)

Source: https://github.com/xchimx/laravel-unsplash/blob/main/readme.md

A Blade template snippet for displaying search results of Unsplash collections. It iterates through the 'results' array, showing the collection title, description, and a link to view associated photos.

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

@section('content')
<h1>Search Results for Collections: "{{ $query }}"</h1>
@foreach ($collections['results'] as $collection)
<div>
    <h2>{{ $collection['title'] }}</h2>
    <p>{{ $collection['description'] ?? 'No description' }}</p>
    <a href="{{ route('collections.photos', $collection['id']) }}">View Photos</a>
    @endforeach
@endsection
</div>
```

--------------------------------

### Search Collections

Source: https://github.com/xchimx/laravel-unsplash/blob/main/readme.md

Searches for Unsplash collections based on a query string, with support for pagination. It takes a search query and page number as input, defaulting to 'Nature' and page 1 respectively. The search results and query are passed to a Blade view. Requires the Request and Unsplash facades.

```php
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'));
    }
}
```

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

@section('content')
<h1>Search Results for Collections: "{{ $query }}"</h1>
@foreach ($collections['results'] as $collection)
<div>
    <h2>{{ $collection['title'] }}</h2>
    <p>{{ $collection['description'] ?? 'No description' }}</p>
    <a href="{{ route('collections.photos', $collection['id']) }}">View Photos</a>
    @endforeach
@endsection
</div>
```

--------------------------------

### Configure Unsplash API Rate Limiting in Laravel

Source: https://context7.com/xchimx/laravel-unsplash/llms.txt

This configuration file sets up access keys, base URIs, and rate limiting parameters for the Unsplash API integration. It allows enabling rate limiting and setting a threshold to prevent excessive requests.

```php
<?php

// In config/unsplash.php
return [
    'unsplash_access_key' => env('UNSPLASH_ACCESS_KEY', ''),
    'base_uri' => 'https://api.unsplash.com/',
    'rate_limiting' => [
        'enabled' => env('UNSPLASH_RATE_LIMITING_ENABLED', true),
        'threshold' => env('UNSPLASH_RATE_LIMITING_THRESHOLD', 10), // Stop requests when remaining < 10
    ],
];

// In routes/web.php
use App\Http\Controllers\PhotoController;

Route::middleware(['unsplash.rate_limit'])->group(function () {
    Route::get('/photos/search', [PhotoController::class, 'search'])->name('photos.search');
    Route::get('/photos/random', [PhotoController::class, 'random'])->name('photos.random');
    Route::get('/photos/{id}', [PhotoController::class, 'show'])->name('photos.show');
    Route::get('/photos/{id}/download', [PhotoController::class, 'download'])->name('photos.download');
});

// When rate limit is reached, middleware returns:
// HTTP 429: {"error": "Unsplash API rate limit reached. Please try again later."}

```

--------------------------------

### List Collections (PHP)

Source: https://context7.com/xchimx/laravel-unsplash/llms.txt

Lists all public Unsplash collections with support for pagination. It allows specifying the number of items per page and the current page number. The response is an array of collection objects, each containing details like ID, title, description, total photos, and cover photo information.

```php
<?php

namespace App\Http\Controllers;

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

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

        $collections = Unsplash::listCollections($perPage, $page);

        // Response is an array of collections:
        // [
        //     [
        //         'id' => 296,
        //         'title' => 'I like a man with a beard.',
        //         'description' => 'Beards, bears, and men.',
        //         'total_photos' => 12,
        //         'cover_photo' => [...],
        //         'user' => ['name' => 'Jane Doe', ...]
        //     ],
        //     // ... more collections
        // ]

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

```

--------------------------------

### Search Collections by Keyword (PHP)

Source: https://context7.com/xchimx/laravel-unsplash/llms.txt

Searches for Unsplash collections based on a provided keyword. It allows for pagination and specifies the number of results per page. The function returns a view displaying the search results, total count, and the query used. It utilizes the Request object for input and the Unsplash facade.

```php
<?php

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', 'travel');
        $perPage = 15;
        $page = $request->input('page', 1);

        $response = Unsplash::searchCollections($query, $perPage, $page);

        // Response structure:
        // [
        //     'total' => 237,
        //     'total_pages' => 16,
        //     'results' => [
        //         ['id' => 193, 'title' => 'Travel Adventures', ...],
        //         // ... more results
        //     ]
        // ]

        return view('collections.search', [
            'collections' => $response['results'],
            'total' => $response['total'],
            'query' => $query
        ]);
    }
}

```

--------------------------------

### Retrieve Single Photo by ID (PHP)

Source: https://context7.com/xchimx/laravel-unsplash/llms.txt

Fetches a single photo's full metadata using its unique ID. It utilizes the Unsplash facade and handles potential 'not found' errors by aborting with a 404 status. The response includes detailed information about the photo, its URLs, user, EXIF data, and location.

```php
<?php

namespace App\Http\Controllers;

use Xchimx\UnsplashApi\Facades\Unsplash;

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

            // Response includes:
            // [
            //     'id' => 'Dwu85P9SOIk',
            //     'width' => 2448,
            //     'height' => 3264,
            //     'color' => '#6E633A',
            //     'description' => 'A scenic view...',
            //     'alt_description' => 'Mountain landscape',
            //     'urls' => [
            //         'raw' => 'https://images.unsplash.com/...',
            //         'full' => 'https://images.unsplash.com/...',
            //         'regular' => 'https://images.unsplash.com/...&w=1080',
            //         'small' => 'https://images.unsplash.com/...&w=400',
            //         'thumb' => 'https://images.unsplash.com/...&w=200'
            //     ],
            //     'user' => ['name' => 'John Doe', 'username' => 'johndoe', 'portfolio_url' => '...'],
            //     'exif' => ['make' => 'Canon', 'model' => 'EOS 5D', ...],
            //     'location' => ['city' => 'Denver', 'country' => 'USA', ...]
            // ]

            return view('photos.show', compact('photo'));
        } catch (\Exception $e) {
            abort(404, 'Photo not found');
        }
    }
}

```

--------------------------------

### Advanced Photo Search with Laravel-Unsplash

Source: https://github.com/xchimx/laravel-unsplash/blob/main/readme.md

This controller method performs an advanced search for photos, allowing parameters like color, orientation, and pagination. It filters out empty parameters before sending the request.

```php
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'));
    }
}
```

--------------------------------

### Set Custom HTTP Options for Requests (PHP)

Source: https://context7.com/xchimx/laravel-unsplash/llms.txt

Allows setting custom Guzzle HTTP client options, such as timeout and proxy, for individual Unsplash API requests. This provides flexibility for managing request behavior, like setting a specific timeout for a photo search or routing requests through a proxy. It uses the Unsplash facade and returns JSON or a view.

```php
<?php

namespace App\Http\Controllers;

use Xchimx\UnsplashApi\Facades\Unsplash;

class PhotoController extends Controller
{
    public function searchWithTimeout()
    {
        // Set a custom timeout of 2 seconds for this request only
        $photos = Unsplash::withOptions(['timeout' => 2])
            ->searchPhotos('nature');

        return response()->json($photos);
    }

    public function searchWithProxy()
    {
        // Use a proxy for this request
        $photos = Unsplash::withOptions([
            'proxy' => 'http://proxy.example.com:8080',
            'timeout' => 10,
            'connect_timeout' => 5
        ])->searchPhotos('architecture');

        return view('photos.search', ['photos' => $photos['results']]);
    }
}

```

--------------------------------

### Search Photos with Laravel Unsplash

Source: https://context7.com/xchimx/laravel-unsplash/llms.txt

Searches for photos on Unsplash using keywords and pagination. It utilizes the Unsplash facade to interact with the API and returns results to a Blade view. Handles potential API errors.

```php
<?php

namespace App\Http\Controllers;

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

class PhotoController extends Controller
{
    public function search(Request $request)
    {
        $query = $request->input('query', 'mountains');
        $perPage = 15;
        $page = $request->input('page', 1);

        try {
            $response = Unsplash::searchPhotos($query, $perPage, $page);

            // Response structure:
            // [
            //     'total' => 10000,
            //     'total_pages' => 667,
            //     'results' => [
            //         [
            //             'id' => 'abc123',
            //             'urls' => ['raw' => '...', 'full' => '...', 'regular' => '...', 'small' => '...', 'thumb' => '...'],
            //             'user' => ['name' => 'John Doe', 'username' => 'johndoe'],
            //             'alt_description' => 'A mountain landscape',
            //             'description' => 'Beautiful mountain scenery'
            //         ],
            //         // ... more results
            //     ]
            // ]

            return view('photos.search', [
                'photos' => $response['results'],
                'total' => $response['total'],
                'query' => $query
            ]);
        } catch (\Exception $e) {
            return back()->withErrors('Failed to fetch photos from Unsplash.');
        }
    }
}
```

--------------------------------

### Advanced Photo Search with Laravel Unsplash

Source: https://context7.com/xchimx/laravel-unsplash/llms.txt

Performs an advanced search for photos on Unsplash, allowing filtering by query, color, orientation, and other parameters. It uses the Unsplash facade and handles potential API exceptions.

```php
<?php

namespace App\Http\Controllers;

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

class PhotoController extends Controller
{
    public function advancedSearch(Request $request)
    {
        $params = [
            'query' => $request->input('query', 'landscape'),
            'color' => $request->input('color'),         // black_and_white, black, white, yellow, orange, red, purple, magenta, green, teal, blue
            'orientation' => $request->input('orientation'), // landscape, portrait, squarish
            'per_page' => $request->input('per_page', 20),
            'page' => $request->input('page', 1),
            'order_by' => 'relevant', // relevant, latest
        ];

        // Remove null values
        $params = array_filter($params);

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

            return view('photos.advanced', [
                'photos' => $response['results'],
                'totalPages' => $response['total_pages'],
                'params' => $params
            ]);
        } catch (\Exception $e) {
            return back()->withErrors('Search failed: ' . $e->getMessage());
        }
    }
}
```

--------------------------------

### Fetch Random Photo (PHP)

Source: https://context7.com/xchimx/laravel-unsplash/llms.txt

Retrieves a random photo from Unsplash. This function can optionally accept parameters to filter the random photo selection by query, orientation, and content filter. The output can be a full photo object or a JSON response with specific details like ID, URL, photographer, and download location.

```php
<?php

namespace App\Http\Controllers;

use Xchimx\UnsplashApi\Facades\Unsplash;

class PhotoController extends Controller
{
    public function random()
    {
        // Get a completely random photo
        $photo = Unsplash::getRandomPhoto();

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

    public function randomFiltered()
    {
        // Get random photo with filters
        $photo = Unsplash::getRandomPhoto([
            'query' => 'nature',
            'orientation' => 'landscape',
            'content_filter' => 'high', // low or high (filter adult content)
        ]);

        return response()->json([
            'id' => $photo['id'],
            'url' => $photo['urls']['regular'],
            'photographer' => $photo['user']['name'],
            'download_location' => $photo['links']['download_location']
        ]);
    }
}

```
Tokens:
Raw