PHP Unsplash Wrapper

A PHP client for the Unsplash API.

• Official documentation
• Changelog

Quick links to methods you're likely to care about:

• Get a list of new photos 🎉
• Get a random photo 🎑
• Trigger a photo download 📡
• Search for a photo by keyword 🕵️‍♂️

Note: Every application must abide by the API Guidelines. Specifically, remember to hotlink images and trigger a download when appropriate.

Installation

unsplash-php uses Composer. To use it, require the library

composer require unsplash/unsplash

Usage

Configuration

Before using, configure the client with your access key and secret. If you don't have an access key and secret, follow the steps from the Unsplash API to register your application.

Note: if you're just using actions that require the public permission scope, only the access key is required. Access key is entered as applicationId due to legacy reasons.

Note: if utmSource is omitted from $credentials a notice will be raised.

Unsplash\HttpClient::init([
	'applicationId'	=> 'YOUR ACCESS KEY',
	'secret'	=> 'YOUR APPLICATION SECRET',
	'callbackUrl'	=> 'https://your-application.com/oauth/callback',
	'utmSource' => 'NAME OF YOUR APPLICATION'
]);

User Authorization workflow

If you need to access actions that are non-public on behalf of the user (i.e. uploading a photo to a specific account), you'll need to follow the user authentication workflow to access their data.

An example of this flow can be found in /examples/oauth-flow.php

Direct them to an authorization URL (configuring any scopes before generating the authorization URL):

$scopes = ['public', 'write_user'];
Unsplash\HttpClient::$connection->getConnectionUrl($scopes);

Upon authorization, Unsplash will return to you an authentication code via your OAuth callback handler. Use it to generate an access token:

Unsplash\HttpClient::$connection->generateToken($code);

With the token you can now access any additional non-public actions available for the authorized user.

Permission Scopes

The current permission scopes defined by the Unsplash API are:

• public (Access a user's public data)
• read_user (Access a user's private data)
• write_user (Edit and create user data)
• read_photos (Access private information from a user's photos)
• write_photos (Post and edit photos for a user)
• write_likes (Like a photo for a user)
• read_collections (View a user’s private collections)
• write_collections (Create and update a user’s collections)

API methods

For more information about the responses for each call, refer to the official documentation.

Some parameters are identical across all methods:

Note: The methods that return multiple objects return an ArrayObject, which acts like a normal stdClass.

Search

$search = 'forest';
$page = 3;
$per_page = 15;
$orientation = 'landscape';

Unsplash\Search::photos($search, $page, $per_page, $orientation);

Unsplash\Search::collections($search, $page, $per_page);

Unsplash\Search::users($search, $page, $per_page);

Unsplash\Collection::all($page, $per_page);

$collection = Unsplash\Collection::find(integer $id);
$photos = $collection->photos($page, $per_page);

$collection = Unsplash\Collection::find($id);
$collection->related();

$collection = Unsplash\Collection::create($title);

$collection = Unsplash\Collection::find(int $id);
$collection->update(['private' => true])

$collection = Unsplash\Collection::find(int $id);
$collection->destroy()

$collection = Unsplash\Collection::find(int $id);
$collection->add(int $photo_id)

$collection = Unsplash\Collection::find(int $id);
$collection->remove(int $photo_id)

Unsplash\Photo::all($page, $per_page, $order_by);

Unsplash\Photo::find($id);

$photo = Unsplash\Photo::find(string $id)
$photo->update(array $parameters);

$photo = Unsplash\Photo::find(string $id);
$photo->photographer();

// Or apply some optional filters by passing a key value array of filters
$filters = [
    'username' => 'andy_brunner',
    'query'    => 'coffee',
    'w'        => 100,
    'h'        => 100
];
Unsplash\Photo::random($filters);

$photo = Unsplash\Photo::find(string $id);
$photo->like();

$photo = Unsplash\Photo::find(string $id);
$photo->unlike();

$photo = Unsplash\Photo::find($id);
$photo->statistics('days', 7);

$photo = Unsplash\Photo::find();
$photo->download();

Unsplash\User::find($username)

Unsplash\User::portfolio($username)

$user = Unsplash\User::current();

$user = Unsplash\User::find($username);
$user->photos($page, $per_page);

$user = Unsplash\User::find($username);
$user->collections($page, $per_page);

$user = Unsplash\User::find($username);
$user->likes($page, $per_page, $order_by);

$user = Unsplash\User::current();
$user->update(['first_name' => 'Elliot', 'last_name' => 'Alderson']);

$user = Unsplash\User::find($id);
$user->statistics('days', 7);