PHPackages moodpaper/unsplash - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [API Development](/categories/api) 4. / 5. moodpaper/unsplash ActiveLibrary[API Development](/categories/api) moodpaper/unsplash ================== Wrapper to access the Unsplash API and photo library 3.1.1(4y ago)032MITPHPPHP >=7.3.0 Since Jul 31Pushed 4y agoCompare [ Source](https://github.com/MoodPaper/unsplash-php)[ Packagist](https://packagist.org/packages/moodpaper/unsplash)[ RSS](/packages/moodpaper-unsplash/feed)WikiDiscussions master Synced 1mo ago READMEChangelogDependencies (8)Versions (32)Used By (0) PHP Unsplash Wrapper ==================== [](#php-unsplash-wrapper) [![Build Status](https://camo.githubusercontent.com/8e95d80aa86bc7c74e28ec2c25ab166c8e9ed4dffa20644c3bc31a08dcada6c1/68747470733a2f2f7472617669732d63692e6f72672f756e73706c6173682f756e73706c6173682d7068702e7376673f6272616e63683d6d6173746572)](https://travis-ci.org/unsplash/unsplash-php) A PHP client for the [Unsplash API](https://unsplash.com/documentation). - [Official documentation](https://unsplash.com/documentation) - [Changelog](https://github.com/unsplash/unsplash-pHP/blob/master/CHANGELOG.md) Quick links to methods you're likely to care about: - [Get a list of new photos](#photo-all) πŸŽ‰ - [Get a random photo](#photo-random) πŸŽ‘ - [Trigger a photo download](#photo-download) πŸ“‘ - [Search for a photo by keyword](#search-photos) πŸ•΅οΈβ€β™‚οΈ **Note:** Every application must abide by the [API Guidelines](https://help.unsplash.com/api-guidelines/unsplash-api-guidelines). Specifically, remember to [hotlink images](https://help.unsplash.com/api-guidelines/more-on-each-guideline/guideline-hotlinking-images) and [trigger a download when appropriate](https://help.unsplash.com/api-guidelines/more-on-each-guideline/guideline-triggering-a-download). Installation ------------ [](#installation) `unsplash-php` uses [Composer](https://getcomposer.org/). To use it, require the library ``` composer require unsplash/unsplash ``` Usage ----- [](#usage) ### Configuration [](#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](https://unsplash.com/documentation#creating-a-developer-account) to register your application. Note: if you're just using actions that require the [public permission scope](#permission-scopes), 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 [](#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](https://unsplash.com/documentation/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 [](#permission-scopes) The current permission scopes defined by the [Unsplash API](https://unsplash.com/documentation/user-authentication-workflow#permission-scopes) 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 [](#api-methods) For more information about the responses for each call, refer to the [official documentation](https://unsplash.com/documentation). Some parameters are identical across all methods: paramDescription`$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 [](#search) #### Photos [](#photos) Retrieve a single page of photo results depending on search results. **Arguments** ArgumentTypeOpt/Required`$search`stringRequired`$page`intOpt *(Default: 1)*`$per_page`intOpt *(Default: 10 / Maximum: 30)*`$orientation`stringOpt *(Default: null / Available: "landscape", "portrait", "squarish")*`$collections`stringOpt *(Default: null / If multiple, comma-separated)*`$order_by`stringHow 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 [](#collections) Retrieve a single page of collection results depending on search results. **Arguments** ArgumentTypeOpt/Required`$search`stringRequired`$per_page`intOpt *(Default: 10 / Maximum: 30)*`$page`intOpt *(Default: 1)***Example** ``` Unsplash\Search::collections($search, $page, $per_page); ``` --- #### Users [](#users) Retrieve a single page of user results depending on search results. **Arguments** ArgumentTypeOpt/Required`$search`stringRequired`$per_page`intOpt *(Default: 10 / Maximum: 30)*`$page`intOpt *(Default: 1)***Example** ``` Unsplash\Search::users($search, $page, $per_page); ``` --- ### Collections [](#collections-1) Retrieve the list of collections. **Arguments** ArgumentTypeOpt/Required`$per_page`intOpt *(Default: 10 / Maximum: 30)*`$page`intOpt *(Default: 1)***Example** ``` Unsplash\Collection::all($page, $per_page); ``` --- #### Unsplash\\Collection::photos($page, $per\_page) [](#unsplashcollectionphotospage-per_page) Retrieve photos from a collection. *Note:* You need to instantiate a collection object first. **Arguments** ArgumentTypeOpt/Required`$per_page`intOpt *(Default: 10 / Maximum: 30)*`$page`intOpt *(Default: 1)***Example** ``` $collection = Unsplash\Collection::find(integer $id); $photos = $collection->photos($page, $per_page); ``` --- #### Unsplash\\Collection::related($page, $per\_page) [](#unsplashcollectionrelatedpage-per_page) Retrieve list of featured collections. *Note* You must instantiate a collection first **Arguments** ArgumentTypeOpt/Required**Example** ``` $collection = Unsplash\Collection::find($id); $collection->related(); ``` --- #### Unsplash\\Collection::create($title, $description, $private) [](#unsplashcollectioncreatetitle-description-private) Create a collection on the user's behalf. *Note:* You need the `write_collections` permission scope **Arguments** ArgumentTypeOpt/Required`$title`stringRequired`$description`stringOpt *(Default: '')*`$private`booleanOpt *(Default: false)***Example** ``` $collection = Unsplash\Collection::create($title); ``` --- #### Unsplash\\Collection::update($parameters) [](#unsplashcollectionupdateparameters) 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() [](#unsplashcollectiondestroy) 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) [](#unsplashcollectionaddphoto_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** ArgumentTypeOpt/Required`$photo_id`integerRequired**Example** ``` $collection = Unsplash\Collection::find(int $id); $collection->add(int $photo_id) ``` --- #### Unsplash\\Collection::remove($photo\_id) [](#unsplashcollectionremovephoto_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** ArgumentTypeOpt/Required`$photo_id`integerRequired**Example** ``` $collection = Unsplash\Collection::find(int $id); $collection->remove(int $photo_id) ``` --- ### Photo [](#photo) #### Unsplash\\Photo::all($page, $per\_page, $order\_by) [](#unsplashphotoallpage-per_page-order_by) Retrieve a list of photos. **Arguments** ArgumentTypeOpt/Required`$per_page`intOpt *(Default: 10 / Maximum: 30)*`$page`intOpt *(Default: 1)*`$order_by`stringOpt *(Default: latest / Available: oldest, popular)***Example** ``` Unsplash\Photo::all($page, $per_page, $order_by); ``` --- #### Unsplash\\Photo::find($id) [](#unsplashphotofindid) Retrieve a specific photo. **Arguments** ArgumentTypeOpt/Required`$id`intRequired**Example** ``` Unsplash\Photo::find($id); ``` --- #### Unsplash\\Photo::update($parameters = \[\]) [](#unsplashphotoupdateparameters--) 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** ArgumentTypeOpt/Required`$parameters`arrayRequired**Example** ``` $photo = Unsplash\Photo::find(string $id) $photo->update(array $parameters); ``` --- #### Unsplash\\Photo::photographer() [](#unsplashphotophotographer) 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\]) [](#unsplashphotorandomfeatured--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](https://unsplash.com/documentation#get-a-random-photo). *Note:* An array needs to be passed as a parameter. **Arguments** ArgumentTypeOpt/RequiredfeaturedbooleanOpt *(Limit selection to featured photos)*usernamestringOpt *(Limit selection to a single user)*querystringOpt *(Limit selection to photos matching a search term)*wintOpt *(Image width in pixels)*hintOpt *(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() [](#unsplashphotolike) 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() [](#unsplashphotounlike) 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) [](#unsplashphotostatisticsstring-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** ArgumentTypeOpt/RequiredresolutionstringOpt *(Accepts only days currently)*quantityintOpt *(Defaults to 30, can be between 1 and 30)***Example** ``` $photo = Unsplash\Photo::find($id); $photo->statistics('days', 7); ``` --- #### Unsplash\\Photo::download() [](#unsplashphotodownload) Trigger a download for a photo. This is needed to follow the ['trigger a download' API Guideline](https://help.unsplash.com/api-guidelines/more-on-each-guideline/guideline-triggering-a-download). *Note:* You must instantiate a Photo object first **Arguments** ArgumentTypeOpt/Required**Example** ``` $photo = Unsplash\Photo::find(); $photo->download(); ``` --- ### User [](#user) #### Unsplash\\User::find($username) [](#unsplashuserfindusername) Retrieve a user's information. **Arguments** ArgumentTypeOpt/Required`$username`stringRequired**Example** ``` Unsplash\User::find($username) ``` --- #### Unsplash\\User::portfolio($username) [](#unsplashuserportfoliousername) Retrieve a link to the user's portfolio page. **Arguments** ArgumentTypeOpt/Required`$username`stringRequired**Example** ``` Unsplash\User::portfolio($username) ``` --- #### Unsplash\\User::current() [](#unsplashusercurrent) 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) [](#unsplashuserphotospage-per_page-order_by) Retrieve user's photos. *Note:* You need to instantiate a user object first **Arguments** ArgumentTypeOpt/Required`$per_page`intOpt *(Default: 10 / Maximum: 30)*`$page`intOpt *(Default: 1)*`$order_by`stringOpt *(Default: latest / Available: oldest, popular)***Example** ``` $user = Unsplash\User::find($username); $user->photos($page, $per_page); ``` --- #### Unsplash\\User::collections($page, $per\_page) [](#unsplashusercollectionspage-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** ArgumentTypeOpt/Required`$per_page`intOpt *(Default: 10 / Maximum: 30)*`$page`intOpt *(Default: 1)***Example** ``` $user = Unsplash\User::find($username); $user->collections($page, $per_page); ``` --- #### Unsplash\\User::likes($page, $per\_page, $order\_by) [](#unsplashuserlikespage-per_page-order_by) Retrieve user's collections. *Note:* You need to instantiate a user object first **Arguments** ArgumentTypeOpt/Required`$per_page`intOpt *(Default: 10 / Maximum: 30)*`$page`intOpt *(Default: 1)*`$order_by`stringOpt *(Default: latest / Available: oldest, popular)***Example** ``` $user = Unsplash\User::find($username); $user->likes($page, $per_page, $order_by); ``` --- #### Unsplash\\User::update(\[$key => value\]) [](#unsplashuserupdatekey--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** ArgumentTypeOpt/RequiredNote`$key`stringRequiredThe following keys are accepted: `username`, `first_name`, `last_name`, `email`, `url`, `location`, `bio`, `instagram_username``$value`mixedrequired``` $user = Unsplash\User::current(); $user->update(['first_name' => 'Elliot', 'last_name' => 'Alderson']); ``` #### Unsplash\\User::statistics(string $resolution, int $quantity) [](#unsplashuserstatisticsstring-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** ArgumentTypeOpt/RequiredresolutionstringOpt *(Accepts only days currently)*quantityintOpt *(Defaults to 30, can be between 1 and 30)***Example** ``` $user = Unsplash\User::find($id); $user->statistics('days', 7); ``` --- Contributing ------------ [](#contributing) Bug reports and pull requests are welcome on GitHub at . This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org/) code of conduct. ### Health Score 30 β€” LowBetter than 64% of packages Maintenance20 Infrequent updates β€” may be unmaintained Popularity7 Limited adoption so far Community16 Small or concentrated contributor base Maturity69 Established project with proven stability Bus Factor2 2 contributors hold 50%+ of commits How is this calculated?**Maintenance (25%)** β€” Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** β€” Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** β€” Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** β€” Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~81 days Recently: every ~179 days Total 28 Last Release 1743d ago Major Versions 1.2.0 β†’ 2.0.02016-04-14 2.5.1 β†’ 3.0.02020-06-04 PHP version history (3 changes)1.0.0PHP >=5.5.0 2.3.2PHP >=5.6.0 3.0.0PHP >=7.3.0 ### Community Maintainers ![](https://www.gravatar.com/avatar/70b21e6b484c6002743ff4f2fe205cdeac6934cbac45161418a05e97dd0063f9?d=identicon)[HarriesChen](/maintainers/HarriesChen) --- Top Contributors [![aaronklaassen](https://avatars.githubusercontent.com/u/1580121?v=4)](https://github.com/aaronklaassen "aaronklaassen (52 commits)")[![HughbertD](https://avatars.githubusercontent.com/u/1580021?v=4)](https://github.com/HughbertD "HughbertD (41 commits)")[![lukechesser](https://avatars.githubusercontent.com/u/808452?v=4)](https://github.com/lukechesser "lukechesser (37 commits)")[![dechuck](https://avatars.githubusercontent.com/u/1096674?v=4)](https://github.com/dechuck "dechuck (26 commits)")[![zembrowski](https://avatars.githubusercontent.com/u/2451083?v=4)](https://github.com/zembrowski "zembrowski (3 commits)")[![dannyweeks](https://avatars.githubusercontent.com/u/4365775?v=4)](https://github.com/dannyweeks "dannyweeks (3 commits)")[![freezy-sk](https://avatars.githubusercontent.com/u/661637?v=4)](https://github.com/freezy-sk "freezy-sk (3 commits)")[![HarriesCC](https://avatars.githubusercontent.com/u/70427383?v=4)](https://github.com/HarriesCC "HarriesCC (3 commits)")[![janhenckens](https://avatars.githubusercontent.com/u/755428?v=4)](https://github.com/janhenckens "janhenckens (3 commits)")[![KevinBatdorf](https://avatars.githubusercontent.com/u/1478421?v=4)](https://github.com/KevinBatdorf "KevinBatdorf (3 commits)")[![AMS777](https://avatars.githubusercontent.com/u/32177639?v=4)](https://github.com/AMS777 "AMS777 (2 commits)")[![Anzoel](https://avatars.githubusercontent.com/u/7801512?v=4)](https://github.com/Anzoel "Anzoel (2 commits)")[![tommienu](https://avatars.githubusercontent.com/u/1025989?v=4)](https://github.com/tommienu "tommienu (2 commits)")[![seojtix](https://avatars.githubusercontent.com/u/154022?v=4)](https://github.com/seojtix "seojtix (1 commits)")[![SiroDiaz](https://avatars.githubusercontent.com/u/7469286?v=4)](https://github.com/SiroDiaz "SiroDiaz (1 commits)")[![spekulatius](https://avatars.githubusercontent.com/u/8433587?v=4)](https://github.com/spekulatius "spekulatius (1 commits)")[![BenMorel](https://avatars.githubusercontent.com/u/1952838?v=4)](https://github.com/BenMorel "BenMorel (1 commits)")[![pvessel](https://avatars.githubusercontent.com/u/4034876?v=4)](https://github.com/pvessel "pvessel (1 commits)") ### Code Quality TestsPHPUnit ### Embed Badge ![Health badge](/badges/moodpaper-unsplash/health.svg) ``` [![Health](https://phpackages.com/badges/moodpaper-unsplash/health.svg)](https://phpackages.com/packages/moodpaper-unsplash) ``` ### Alternatives [tencentcloud/tencentcloud-sdk-php TencentCloudApi php sdk 3731.2M42](/packages/tencentcloud-tencentcloud-sdk-php)[dcblogdev/laravel-microsoft-graph A Laravel Microsoft Graph API (Office365) package 168285.5k1](/packages/dcblogdev-laravel-microsoft-graph)[dcblogdev/laravel-xero A Laravel Xero package 53129.1k1](/packages/dcblogdev-laravel-xero)[mapado/rest-client-sdk Rest Client SDK for hydra API 1125.9k2](/packages/mapado-rest-client-sdk) PHPackages Β© 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)