unsplash/unsplash

Wrapper to access the Unsplash API and photo library

PHP Unsplash Wrapper

, _(*1)

A PHP client for the Unsplash API., _(*2)

• Official documentation
• Changelog

Quick links to methods you're likely to care about:, _(*3)

• 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., _(*4)

Installation

unsplash-php uses Composer. To use it, require the library, _(*5)

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., _(*6)

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., _(*7)

Note: if utmSource is omitted from $credentials a notice will be raised., _(*8)

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., _(*9)

An example of this flow can be found in /examples/oauth-flow.php, _(*10)

Direct them to an authorization URL (configuring any scopes before generating the authorization URL):, _(*11)

$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:, _(*12)

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

With the token you can now access any additional non-public actions available for the authorized user., _(*13)

Permission Scopes

The current permission scopes defined by the Unsplash API are:, _(*14)

• 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., _(*15)

Some parameters are identical across all methods:, _(*16)

Note: The methods that return multiple objects return an ArrayObject, which acts like a normal stdClass., _(*17)

Search

Photos

Retrieve a single page of photo results depending on search results., _(*18)

Arguments, _(*19)

Example, _(*20)

$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., _(*21)

Arguments, _(*22)

Example, _(*23)

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

Users

Retrieve a single page of user results depending on search results., _(*24)

Arguments, _(*25)

Example, _(*26)

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

Collections

#

Retrieve the list of collections., _(*27)

Arguments, _(*28)

Example, _(*29)

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

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

Retrieve photos from a collection., _(*30)

Note: You need to instantiate a collection object first., _(*31)

Arguments, _(*32)

Example, _(*33)

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

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

Retrieve list of featured collections., _(*34)

Note You must instantiate a collection first, _(*35)

Arguments, _(*36)

Example, _(*37)

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

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

Create a collection on the user's behalf., _(*38)

Note: You need the write_collections permission scope, _(*39)

Arguments, _(*40)

Example, _(*41)

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

Unsplash\Collection::update($parameters)

Update a collection on the user's behalf., _(*42)

Note: You need to instantiate a collection object first, _(*43)

Note: You need the write_collections permission scope, _(*44)

Arguments, _(*45)

Example, _(*46)

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

Unsplash\Collection::destroy()

Delete a collection on the user's behalf., _(*47)

Note: You need to instantiate a collection object first, _(*48)

Note: You need the write_collections permission scope, _(*49)

Example, _(*50)

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

Unsplash\Collection::add($photo_id)

Add a photo in the collection on the user's behalf., _(*51)

Note: You need to instantiate a collection object first, _(*52)

Note: You need the write_collections permission scope, _(*53)

Arguments, _(*54)

Example, _(*55)

$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., _(*56)

Note: You need to instantiate a collection object first, _(*57)

Note: You need the write_collections permission scope, _(*58)

Arguments, _(*59)

Example, _(*60)

$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., _(*61)

Arguments, _(*62)

Example, _(*63)

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

Unsplash\Photo::find($id)

Retrieve a specific photo., _(*64)

Arguments, _(*65)

Example, _(*66)

Unsplash\Photo::find($id);

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

Post a photo on the user's behalf., _(*67)

Note: You need the write_photos permission scope You need to instantiate the Photo object first, _(*68)

Arguments, _(*69)

Example, _(*70)

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

Unsplash\Photo::photographer()

Retrieve the photo's photographer., _(*71)

Note: You need to instantiate a photo object first, _(*72)

Arguments, _(*73)

N/A, _(*74)

Example, _(*75)

$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., _(*76)

Note: An array needs to be passed as a parameter., _(*77)

Arguments, _(*78)

Example, _(*79)

// 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., _(*80)

Note: You need to instantiate a photo object first, _(*81)

Note: You need the like_photos permission scope, _(*82)

Arguments, _(*83)

N/A, _(*84)

Example, _(*85)

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

Unsplash\Photo::unlike()

Unlike a photo on the user's behalf., _(*86)

Note: You need to instantiate a photo object first, _(*87)

Note: You need the like_photos permission scope, _(*88)

Arguments, _(*89)

N/A, _(*90)

Example, _(*91)

$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)., _(*92)

Note: You must instantiate a Photo object first, _(*93)

Arguments, _(*94)

Example, _(*95)

$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., _(*96)

Note: You must instantiate a Photo object first, _(*97)

Arguments, _(*98)

Example, _(*99)

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

User

Unsplash\User::find($username)

Retrieve a user's information., _(*100)

Arguments, _(*101)

Example, _(*102)

Unsplash\User::find($username)

Unsplash\User::portfolio($username)

Retrieve a link to the user's portfolio page., _(*103)

Arguments, _(*104)

Example, _(*105)

Unsplash\User::portfolio($username)

Unsplash\User::current()

Retrieve the user's private information., _(*106)

Note: You need the read_user permission scope, _(*107)

Arguments, _(*108)

N/A, _(*109)

Example, _(*110)

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

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

Retrieve user's photos., _(*111)

Note: You need to instantiate a user object first, _(*112)

Arguments, _(*113)

Example, _(*114)

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

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

Retrieve user's collections., _(*115)

Note: You need to instantiate a user object first Note: You need the read_collections permission scope to retrieve user's private collections, _(*116)

Arguments, _(*117)

Example, _(*118)

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

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

Retrieve user's collections., _(*119)

Note: You need to instantiate a user object first, _(*120)

Arguments, _(*121)

Example, _(*122)

$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., _(*123)

Note: You need to instantiate a user object first, _(*124)

Note: You need the write_user permission scope., _(*125)

Arguments, _(*126)

$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)., _(*127)

Note: You must instantiate the User object first, _(*128)

Arguments, _(*129)

Example, _(*130)

$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., _(*131)