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:

param	Description
`$per_page`	Defines the number of objects per page. Default 10
`$page`	Defines the offset page. Default 1

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

Search

Photos

Retrieve a single page of photo results depending on search results.

Arguments

Argument	Type	Opt/Required
`$search`	string	Required
`$page`	int	Opt (Default: 1)
`$per_page`	int	Opt (Default: 10 / Maximum: 30)
`$orientation`	string	Opt (Default: null / Available: "landscape", "portrait", "squarish")
`$collections`	string	Opt (Default: null / If multiple, comma-separated)
`$order_by`	string	How to sort the photos. (Optional; default: relevant). Valid values are latest and relevant.

Example

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

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

Collections

Retrieve a single page of collection results depending on search results.

Arguments

Argument	Type	Opt/Required
`$search`	string	Required
`$per_page`	int	Opt (Default: 10 / Maximum: 30)
`$page`	int	Opt (Default: 1)

Example

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

Users

Retrieve a single page of user results depending on search results.

Arguments

Argument	Type	Opt/Required
`$search`	string	Required
`$per_page`	int	Opt (Default: 10 / Maximum: 30)
`$page`	int	Opt (Default: 1)

Example

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

Collections

Retrieve the list of collections.

Arguments

Argument	Type	Opt/Required
`$per_page`	int	Opt (Default: 10 / Maximum: 30)
`$page`	int	Opt (Default: 1)

Example

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

Unsplash\Collection::photos($page, $per_page)

Retrieve photos from a collection.

Note: You need to instantiate a collection object first.

Arguments

Argument	Type	Opt/Required
`$per_page`	int	Opt (Default: 10 / Maximum: 30)
`$page`	int	Opt (Default: 1)

Example

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

Unsplash\Collection::related($page, $per_page)

Retrieve list of featured collections.

Note You must instantiate a collection first

Arguments

Argument	Type	Opt/Required

Example

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

Unsplash\Collection::create($title, $description, $private)

Create a collection on the user's behalf.

Note: You need the write_collections permission scope

Arguments

Argument	Type	Opt/Required
`$title`	string	Required
`$description`	string	Opt (Default: '')
`$private`	boolean	Opt (Default: false)

Example

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

Unsplash\Collection::update($parameters)

Update a collection on the user's behalf.

Note: You need to instantiate a collection object first

Note: You need the write_collections permission scope

Arguments

Argument | Type | Opt/Required | Note ---------------|---------|---------------------- $parameters | array | Required | The following keys can be set in the array : title, description, private

Example

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

Unsplash\Collection::destroy()

Delete a collection on the user's behalf.

Note: You need to instantiate a collection object first

Note: You need the write_collections permission scope

Example

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

Unsplash\Collection::add($photo_id)

Add a photo in the collection on the user's behalf.

Note: You need to instantiate a collection object first

Note: You need the write_collections permission scope

Arguments

Argument	Type	Opt/Required
`$photo_id`	integer	Required

Example

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

Unsplash\Collection::remove($photo_id)

Remove a photo from the collection on the user's behalf.

Note: You need to instantiate a collection object first

Note: You need the write_collections permission scope

Arguments

Argument	Type	Opt/Required
`$photo_id`	integer	Required

Example

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

Photo

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

Retrieve a list of photos.

Arguments

Argument	Type	Opt/Required
`$per_page`	int	Opt (Default: 10 / Maximum: 30)
`$page`	int	Opt (Default: 1)
`$order_by`	string	Opt (Default: latest / Available: oldest, popular)

Example

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

Unsplash\Photo::find($id)

Retrieve a specific photo.

Arguments

Argument	Type	Opt/Required
`$id`	int	Required

Example

Unsplash\Photo::find($id);

Unsplash\Photo::update($parameters = [])

Post a photo on the user's behalf.

Note: You need the write_photos permission scope You need to instantiate the Photo object first

Arguments

Argument	Type	Opt/Required
`$parameters`	array	Required

Example

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

Unsplash\Photo::photographer()

Retrieve the photo's photographer.

Note: You need to instantiate a photo object first

Arguments

N/A

Example

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

Unsplash\Photo::random([featured => $value, username => $value, query => $value, w => $value, h => $value])

Retrieve a random photo from specified filters. For more information regarding filtering, refer to the Offical documentation.

Note: An array needs to be passed as a parameter.

Arguments

Argument	Type	Opt/Required
featured	boolean	Opt (Limit selection to featured photos)
username	string	Opt (Limit selection to a single user)
query	string	Opt (Limit selection to photos matching a search term)
w	int	Opt (Image width in pixels)
h	int	Opt (Image height in pixels)

Example

// 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);

Unsplash\Photo::like()

Like a photo on the user's behalf.

Note: You need to instantiate a photo object first

Note: You need the like_photos permission scope

Arguments

N/A

Example

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

Unsplash\Photo::unlike()

Unlike a photo on the user's behalf.

Note: You need to instantiate a photo object first

Note: You need the like_photos permission scope

Arguments

N/A

Example

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

Unsplash\Photo::statistics(string $resolution, int $quantity)

Retrieve total number of downloads, views and likes of a single photo, as well as the historical breakdown of these stats in a specific timeframe (default is 30 days).

Note: You must instantiate a Photo object first

Arguments

Argument	Type	Opt/Required
resolution	string	Opt (Accepts only days currently)
quantity	int	Opt (Defaults to 30, can be between 1 and 30)

Example

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

Unsplash\Photo::download()

Trigger a download for a photo. This is needed to follow the 'trigger a download' API Guideline.

Note: You must instantiate a Photo object first

Arguments

Argument	Type	Opt/Required

Example

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

User

Unsplash\User::find($username)

Retrieve a user's information.

Arguments

Argument	Type	Opt/Required
`$username`	string	Required

Example

Unsplash\User::find($username)

Unsplash\User::portfolio($username)

Retrieve a link to the user's portfolio page.

Arguments

Argument	Type	Opt/Required
`$username`	string	Required

Example

Unsplash\User::portfolio($username)

Unsplash\User::current()

Retrieve the user's private information.

Note: You need the read_user permission scope

Arguments

N/A

Example

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

Unsplash\User::photos($page, $per_page, $order_by)

Retrieve user's photos.

Note: You need to instantiate a user object first

Arguments

Argument	Type	Opt/Required
`$per_page`	int	Opt (Default: 10 / Maximum: 30)
`$page`	int	Opt (Default: 1)
`$order_by`	string	Opt (Default: latest / Available: oldest, popular)

Example

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

Unsplash\User::collections($page, $per_page)

Retrieve user's collections.

Note: You need to instantiate a user object first Note: You need the read_collections permission scope to retrieve user's private collections

Arguments

Argument	Type	Opt/Required
`$per_page`	int	Opt (Default: 10 / Maximum: 30)
`$page`	int	Opt (Default: 1)

Example

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

Unsplash\User::likes($page, $per_page, $order_by)

Retrieve user's collections.

Note: You need to instantiate a user object first

Arguments

Argument	Type	Opt/Required
`$per_page`	int	Opt (Default: 10 / Maximum: 30)
`$page`	int	Opt (Default: 1)
`$order_by`	string	Opt (Default: latest / Available: oldest, popular)

Example

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

Unsplash\User::update([$key => value])

Update current user's fields. Multiple fields can be passed in the array.

Note: You need to instantiate a user object first

Note: You need the write_user permission scope.

Arguments

Argument	Type	Opt/Required	Note
`$key`	string	Required	The following keys are accepted: `username`, `first_name`, `last_name`, `email`, `url`, `location`, `bio`, `instagram_username`
`$value`	mixed	required

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

Unsplash\User::statistics(string $resolution, int $quantity)

Retrieve total number of downloads, views and likes for a user, as well as the historical breakdown of these stats in a specific timeframe (default is 30 days).

Note: You must instantiate the User object first

Arguments

Argument	Type	Opt/Required
resolution	string	Opt (Accepts only days currently)
quantity	int	Opt (Defaults to 30, can be between 1 and 30)

Example

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

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/unsplash/unsplash-php. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.

OPEN ISSUES

See all

Collection Retrieve Photos by @apapazisis
Bad error message when photo ID is missing by @winternet-studio
How to find the information for the attribution by @RoqueCampos
Are there any plans to add a proxy option to this? by @nemuki
Cannot search only within collection by @b-tte
Auto update Packagist by @stayallive
When will a PHP 8.1 release be made? by @HughDuggan
Exception on downloading "plus" Photo by @KarolNet
Script works in the browser, but fails on CRONJOB, FETCH, or RUN SCRIPT by @aerialglasgow

RELEASES

See all

2.4.0 by @lukechesser
2.4.3 by @lukechesser
2.4.4 by @lukechesser
3.2.0 by @aaronklaassen
3.2.1 by @lukechesser

unsplash/unsplash-php

octicon-link" viewBox="0 0 16 16" version="1.1" width="16" height="16" aria-hidden="true">PHP Unsplash Wrapper

octicon-link" viewBox="0 0 16 16" version="1.1" width="16" height="16" aria-hidden="true">Installation

octicon-link" viewBox="0 0 16 16" version="1.1" width="16" height="16" aria-hidden="true">Usage

octicon-link" viewBox="0 0 16 16" version="1.1" width="16" height="16" aria-hidden="true">Configuration

octicon-link" viewBox="0 0 16 16" version="1.1" width="16" height="16" aria-hidden="true">User Authorization workflow

octicon-link" viewBox="0 0 16 16" version="1.1" width="16" height="16" aria-hidden="true">Permission Scopes

octicon-link" viewBox="0 0 16 16" version="1.1" width="16" height="16" aria-hidden="true">API methods

octicon-link" viewBox="0 0 16 16" version="1.1" width="16" height="16" aria-hidden="true">Search

octicon-link" viewBox="0 0 16 16" version="1.1" width="16" height="16" aria-hidden="true">Photos

octicon-link" viewBox="0 0 16 16" version="1.1" width="16" height="16" aria-hidden="true">Collections

octicon-link" viewBox="0 0 16 16" version="1.1" width="16" height="16" aria-hidden="true">Users

octicon-link" viewBox="0 0 16 16" version="1.1" width="16" height="16" aria-hidden="true">Collections

octicon-link" viewBox="0 0 16 16" version="1.1" width="16" height="16" aria-hidden="true">Unsplash\Collection::photos($page, $per_page)

octicon-link" viewBox="0 0 16 16" version="1.1" width="16" height="16" aria-hidden="true">Unsplash\Collection::related($page, $per_page)

octicon-link" viewBox="0 0 16 16" version="1.1" width="16" height="16" aria-hidden="true">Unsplash\Collection::create($title, $description, $private)

octicon-link" viewBox="0 0 16 16" version="1.1" width="16" height="16" aria-hidden="true">Unsplash\Collection::update($parameters)

octicon-link" viewBox="0 0 16 16" version="1.1" width="16" height="16" aria-hidden="true">Unsplash\Collection::destroy()

octicon-link" viewBox="0 0 16 16" version="1.1" width="16" height="16" aria-hidden="true">Unsplash\Collection::add($photo_id)

octicon-link" viewBox="0 0 16 16" version="1.1" width="16" height="16" aria-hidden="true">Unsplash\Collection::remove($photo_id)

octicon-link" viewBox="0 0 16 16" version="1.1" width="16" height="16" aria-hidden="true">Photo

octicon-link" viewBox="0 0 16 16" version="1.1" width="16" height="16" aria-hidden="true">Unsplash\Photo::all($page, $per_page, $order_by)

octicon-link" viewBox="0 0 16 16" version="1.1" width="16" height="16" aria-hidden="true">Unsplash\Photo::find($id)

octicon-link" viewBox="0 0 16 16" version="1.1" width="16" height="16" aria-hidden="true">Unsplash\Photo::update($parameters = [])

octicon-link" viewBox="0 0 16 16" version="1.1" width="16" height="16" aria-hidden="true">Unsplash\Photo::photographer()

octicon-link" viewBox="0 0 16 16" version="1.1" width="16" height="16" aria-hidden="true">Unsplash\Photo::random([featured => $value, username => $value, query => $value, w => $value, h => $value])

octicon-link" viewBox="0 0 16 16" version="1.1" width="16" height="16" aria-hidden="true">Unsplash\Photo::like()

octicon-link" viewBox="0 0 16 16" version="1.1" width="16" height="16" aria-hidden="true">Unsplash\Photo::unlike()

octicon-link" viewBox="0 0 16 16" version="1.1" width="16" height="16" aria-hidden="true">Unsplash\Photo::statistics(string $resolution, int $quantity)

octicon-link" viewBox="0 0 16 16" version="1.1" width="16" height="16" aria-hidden="true">Unsplash\Photo::download()

octicon-link" viewBox="0 0 16 16" version="1.1" width="16" height="16" aria-hidden="true">User

octicon-link" viewBox="0 0 16 16" version="1.1" width="16" height="16" aria-hidden="true">Unsplash\User::find($username)

octicon-link" viewBox="0 0 16 16" version="1.1" width="16" height="16" aria-hidden="true">Unsplash\User::portfolio($username)

octicon-link" viewBox="0 0 16 16" version="1.1" width="16" height="16" aria-hidden="true">Unsplash\User::current()

octicon-link" viewBox="0 0 16 16" version="1.1" width="16" height="16" aria-hidden="true">Unsplash\User::photos($page, $per_page, $order_by)

octicon-link" viewBox="0 0 16 16" version="1.1" width="16" height="16" aria-hidden="true">Unsplash\User::collections($page, $per_page)

octicon-link" viewBox="0 0 16 16" version="1.1" width="16" height="16" aria-hidden="true">Unsplash\User::likes($page, $per_page, $order_by)

octicon-link" viewBox="0 0 16 16" version="1.1" width="16" height="16" aria-hidden="true">Unsplash\User::update([$key => value])

octicon-link" viewBox="0 0 16 16" version="1.1" width="16" height="16" aria-hidden="true">Unsplash\User::statistics(string $resolution, int $quantity)

octicon-link" viewBox="0 0 16 16" version="1.1" width="16" height="16" aria-hidden="true">Contributing

OPEN ISSUES

RELEASES

PHP Unsplash Wrapper

Installation

Usage

Configuration

User Authorization workflow

Permission Scopes

API methods

Search

Photos

Collections

Users

Collections

Unsplash\Collection::photos($page, $per_page)

Unsplash\Collection::related($page, $per_page)

Unsplash\Collection::create($title, $description, $private)

Unsplash\Collection::update($parameters)

Unsplash\Collection::destroy()

Unsplash\Collection::add($photo_id)

Unsplash\Collection::remove($photo_id)

Photo

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

Unsplash\Photo::find($id)

Unsplash\Photo::update($parameters = [])

Unsplash\Photo::photographer()

Unsplash\Photo::random([featured => $value, username => $value, query => $value, w => $value, h => $value])

Unsplash\Photo::like()

Unsplash\Photo::unlike()

Unsplash\Photo::statistics(string $resolution, int $quantity)

Unsplash\Photo::download()

User

Unsplash\User::find($username)

Unsplash\User::portfolio($username)

Unsplash\User::current()

Unsplash\User::photos($page, $per_page, $order_by)

Unsplash\User::collections($page, $per_page)

Unsplash\User::likes($page, $per_page, $order_by)

Unsplash\User::update([$key => value])

Unsplash\User::statistics(string $resolution, int $quantity)

Contributing