PHP Unsplash Wrapper
A PHP client for the Unsplash API.
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 application ID and secret. If you don't have an application ID and secret, follow the steps from the Unsplash API to register your application.
Note that if you're just using actions that require the public permission scope, only the applicationId is required.
Note that if utmSource is omitted from $credentials a notice will be raised
Crew\Unsplash\HttpClient::init([
'applicationId' => 'YOUR APPLICATION ID',
'secret' => 'YOUR APPLICATION SECRET',
'callbackUrl' => 'https://your-application.com/oauth/callback',
'utmSource' => 'NAME OF YOUR APPLICATION'
]);
Authorization workflow
To access actions that are non-public (i.e. uploading a photo to a specific account), you'll need a user's permission 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'];
Crew\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:
Crew\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)
API methods
For more information about the 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
Crew\Unsplash\Search::photos($search, $page, $per_page, $orientation, $collections)
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)
Example
$search = 'forest';
$page = 3;
$per_page = 15;
$orientation = 'landscape';
Crew\Unsplash\Search::photos($search, $page, $per_page, $orientation);
Crew\Unsplash\Search::collections($search, $page, $per_page)
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
Crew\Unsplash\Search::collections($search, $page, $per_page);
Crew\Unsplash\Search::users($search, $page, $per_page)
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
Crew\Unsplash\Search::users($search, $page, $per_page);
Curated Collection
Crew\Unsplash\CuratedCollection::all($page, $per_page)
Retrieve the list of curated collections.
Arguments
Argument, Type, Opt/Required
---------------, ------, --------------
$per_page, int, Opt (Default: 10 / Maximum: 30)
$page, int, Opt (Default: 1)
Example
Crew\Unsplash\CuratedCollection::all($page, $per_page);
Crew\Unsplash\CuratedCollection::find($id)
Retrieve a specific curated collection.
Arguments
Argument, Type, Opt/Required
---------------, ------, --------------
$id, int, Required
Example
Crew\Unsplash\CuratedCollection::find(integer $id);
Crew\Unsplash\CuratedCollection::photos($page, $per_page)
Retrieve photos from a curated collection.
Note: You need to instantiate a curated collection object first.
Arguments
Argument, Type, Opt/Required
---------------, ------, --------------
$per_page, int, Opt (Default: 10 / Maximum: 30)
$page, int, Opt (Default: 1)
Example
$collection = Crew\Unsplash\CuratedCollection::find(integer $id);
$photos = $collection->photos($page, $per_page);
Collection
Crew\Unsplash\Collection::all($page, $per_page)
Retrieve the list of collections.
Arguments
Argument, Type, Opt/Required
---------------, ------, --------------
$per_page, int, Opt (Default: 10 / Maximum: 30)
$page, int, Opt (Default: 1)
Example
Crew\Unsplash\Collection::all($page, $per_page);
Crew\Unsplash\Collection::featured($page, $per_page)
Retrieve list of featured collections.
Arguments
Argument, Type, Opt/Required
---------------, ------, --------------
$per_page, int, Opt (Default: 10 / Maximum: 30)
$page, int, Opt (Default: 1)
Example
Crew\Unsplash\Collection::featured($page, $per_page);
Crew\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 = Crew\Unsplash\Collection::find($id);
$collection->related();
Crew\Unsplash\Collection::find($id)
Retrieve a specific collection.
Arguments
Argument, Type, Opt/Required
---------------, ------, --------------
$id, int, Required
Example
Crew\Unsplash\Collection::find(integer $id);
Crew\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 = Crew\Unsplash\Collection::find(integer $id);
$photos = $collection->photos($page, $per_page);
Crew\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 = Crew\Unsplash\Collection::create($title);
Crew\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 = Crew\Unsplash\Collection::find(int $id);
$collection->update(['private' => true])
Crew\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 = Crew\Unsplash\Collection::find(int $id);
$collection->destroy()
Crew\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 = Crew\Unsplash\Collection::find(int $id);
$collection->add(int $photo_id)
Crew\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 = Crew\Unsplash\Collection::find(int $id);
$collection->remove(int $photo_id)
Photo
Crew\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
Crew\Unsplash\Photo::all($page, $per_page, $order_by);
Crew\Unsplash\Photo::curated($page, $per_page, $order_by)
Retrieve a list of curated 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
Crew\Unsplash\Photo::curated($page, $per_page, $order_by);
Crew\Unsplash\Photo::find($id)
Retrieve a specific photo.
Arguments
Argument, Type, Opt/Required
---------------, ------, --------------
$id, int, Required
Example
Crew\Unsplash\Photo::find($id);
Crew\Unsplash\Photo::create($file_path)
Post a photo on the user's behalf.
Note: You need the write_photos permission scope
Arguments
Argument, Type, Opt/Required
---------------, --------, --------------
$file_path, string, Required
Example
Crew\Unsplash\Photo::create( $file_path);
Crew\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 = Crew\Unsplash\Photo::find(string $id)
$photo->update(array $parameters);
Crew\Unsplash\Photo::photographer()
Retrieve the photo's photographer.
Note: You need to instantiate a photo object first
Arguments
N/A
Example
$photo = Crew\Unsplash\Photo::find(string $id);
$photo->photographer();
Crew\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 = [
'featured' => true,
'username' => 'andy_brunner',
'query' => 'coffee',
'w' => 100,
'h' => 100
];
Crew\Unsplash\Photo::random($filters);
Crew\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 = Crew\Unsplash\Photo::find(string $id);
$photo->like();
Crew\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 = Crew\Unsplash\Photo::find(string $id);
$photo->unlike();
Crew\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 = Crew\Unsplash\Photo::find($id);
$photo->statistics('days', 7);
Crew\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 = Crew\Unsplash\Photo::find();
$photo->download();
User
Crew\Unsplash\User::find($username)
Retrieve a user's information.
Arguments
Argument, Type, Opt/Required
---------------, --------, --------------
$username, string, Required
Example
Crew\Unsplash\User::find($username)
Crew\Unsplash\User::portfolio($username)
Retrieve a link to the user's portfolio page.
Arguments
Argument, Type, Opt/Required
---------------, --------, --------------
$username, string, Required
Example
Crew\Unsplash\User::portfolio($username)
Crew\Unsplash\User::current()
Retrieve the user's private information.
Note: You need the read_user permission scope
Arguments
N/A
Example
$user = Crew\Unsplash\User::current();
Crew\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 = Crew\Unsplash\User::find($username);
$user->photos($page, $per_page);
Crew\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 = Crew\Unsplash\User::find($username);
$user->collections($page, $per_page);
Crew\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 = Crew\Unsplash\User::find($username);
$user->likes($page, $per_page, $order_by);
Crew\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 = Crew\Unsplash\User::current();
$user->update(['first_name' => 'Elliot', 'last_name' => 'Alderson']);
Crew\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 = Crew\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.