Official PHP wrapper for the Unsplash API
PHP
Latest commit 1504a5f Sep 4, 2016 @dechuck dechuck committed on GitHub Fix parameters order (#42)

README.md

PHP Unsplash Wrapper

Build Status Dependency Status Coverage Status

A PHP client for the Unsplash API.

Installation

Unsplash-PHP uses Composer. To use it, require the library

composer require crewlabs/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.

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

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. 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.

Category

Crew\Unsplash\Category::all()

Retrieve the list of categories.

Arguments

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

Example

Crew\Unsplash\Category::all($page, $per_page);

Crew\Unsplash\Category::find($id)

Retrieve a specific category.

Arguments

Argument Type Opt/Required
$id int Required

Example

Crew\Unsplash\Category::find(integer $id);

Crew\Unsplash\Category::photos($page, $per_page)

Retrieve photos from a specific category.

Note: You need to instantiate a category object first.

Arguments

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

Example

$category = Crew\Unsplash\Category::find(integer $id);
$photos = $category->photos($page, $per_page)

Curated Batch (Deprecated)

Crew\Unsplash\CuratedBatch::all($page, $per_page)

Retrieve the list of curated batches.

Arguments

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

Example

Crew\Unsplash\CuratedBatch::all($page, $per_page);

Crew\Unsplash\CuratedBatch::find($id)

Retrieve a specific curated batch.

Arguments

Argument Type Opt/Required
$id int Required

Example

Crew\Unsplash\CuratedBatch::find(integer $id);

Crew\Unsplash\CuratedBatch::photos($page, $per_page)

Retrieve photos from a curated batch.

Note: You need to instantiate a curated batch object first.

Arguments

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

Example

$batch = Crew\Unsplash\CuratedBatch::find(integer $id);
$photos = $batch->photos($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::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)

Retrieve a list of photos.

Arguments

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

Example

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

Crew\Unsplash\Photo::curated($page, $per_page)

Retrieve a list of curated photos.

Arguments

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

Example

Crew\Unsplash\Photo::curated($page, $per_page);

Crew\Unsplash\Photo::search($keyword, $category_id, $page, $per_page);

Retrieve photos from a search by keyword or category.

Arguments

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

Example

Crew\Unsplash\Photo::search(string $search, integer $category_id, $page, $per_page);

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::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([category => $value, 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
category array Opt (Retrieve photos matching the category ID/IDs)
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 = [
    'category' => [3, 6],
    '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();

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::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)

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)

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::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']);

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/CrewLabs/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.