{"id":18883972,"url":"https://github.com/unsplash/unsplash-php","last_synced_at":"2025-05-15T13:07:12.221Z","repository":{"id":33992418,"uuid":"37745425","full_name":"unsplash/unsplash-php","owner":"unsplash","description":"👻 Official PHP wrapper for the Unsplash API","archived":false,"fork":false,"pushed_at":"2023-08-11T18:59:56.000Z","size":1597,"stargazers_count":417,"open_issues_count":14,"forks_count":76,"subscribers_count":20,"default_branch":"master","last_synced_at":"2025-05-08T09:16:18.328Z","etag":null,"topics":["api-wrapper","images","photographer","photos","php","search","unsplash"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/unsplash.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2015-06-19T20:54:52.000Z","updated_at":"2025-05-07T16:10:14.000Z","dependencies_parsed_at":"2024-06-18T11:28:41.173Z","dependency_job_id":null,"html_url":"https://github.com/unsplash/unsplash-php","commit_stats":{"total_commits":187,"total_committers":29,"mean_commits":6.448275862068965,"dds":0.7967914438502673,"last_synced_commit":"429ad0daa4f498b9ed42fe4f0053a44fb47645b7"},"previous_names":[],"tags_count":30,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/unsplash%2Funsplash-php","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/unsplash%2Funsplash-php/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/unsplash%2Funsplash-php/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/unsplash%2Funsplash-php/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/unsplash","download_url":"https://codeload.github.com/unsplash/unsplash-php/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254346624,"owners_count":22055808,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api-wrapper","images","photographer","photos","php","search","unsplash"],"created_at":"2024-11-08T07:10:05.060Z","updated_at":"2025-05-15T13:07:07.207Z","avatar_url":"https://github.com/unsplash.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# PHP Unsplash Wrapper\n\n[![Build Status](https://travis-ci.org/unsplash/unsplash-php.svg?branch=master)](https://travis-ci.org/unsplash/unsplash-php)\n\nA PHP client for the [Unsplash API](https://unsplash.com/documentation).\n\n- [Official documentation](https://unsplash.com/documentation)\n- [Changelog](https://github.com/unsplash/unsplash-pHP/blob/master/CHANGELOG.md)\n\nQuick links to methods you're likely to care about:\n\n- [Get a list of new photos](#photo-all) 🎉\n- [Get a random photo](#photo-random) 🎑\n- [Trigger a photo download](#photo-download) 📡\n- [Search for a photo by keyword](#search-photos) 🕵️‍♂️\n\n**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).\n\n## Installation\n\n`unsplash-php` uses [Composer](https://getcomposer.org/). To use it, require the library\n\n```\ncomposer require unsplash/unsplash\n```\n\n## Usage\n\n### Configuration\n\nBefore 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.\n\nNote: 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.\n\nNote: if utmSource is omitted from $credentials a notice will be raised.\n\n```php\nUnsplash\\HttpClient::init([\n\t'applicationId'\t=\u003e 'YOUR ACCESS KEY',\n\t'secret'\t=\u003e 'YOUR APPLICATION SECRET',\n\t'callbackUrl'\t=\u003e 'https://your-application.com/oauth/callback',\n\t'utmSource' =\u003e 'NAME OF YOUR APPLICATION'\n]);\n```\n\n### User Authorization workflow\n\nIf 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.\n\nAn example of this flow can be found in /examples/oauth-flow.php\n\nDirect them to an authorization URL (configuring any scopes before generating the authorization URL):\n\n```php\n$scopes = ['public', 'write_user'];\nUnsplash\\HttpClient::$connection-\u003egetConnectionUrl($scopes);\n```\n\nUpon authorization, Unsplash will return to you an authentication code via your OAuth\ncallback handler. Use it to generate an access token:\n\n```php\nUnsplash\\HttpClient::$connection-\u003egenerateToken($code);\n```\n\nWith the token you can now access any additional non-public actions available for the authorized user.\n\n\n#### Permission Scopes\n\nThe current permission scopes defined by the [Unsplash API](https://unsplash.com/documentation/user-authentication-workflow#permission-scopes) are:\n\n- `public` (Access a user's public data)\n- `read_user` (Access a user's private data)\n- `write_user` (Edit and create user data)\n- `read_photos` (Access private information from a user's photos)\n- `write_photos` (Post and edit photos for a user)\n- `write_likes` (Like a photo for a user)\n- `read_collections` (View a user’s private collections)\n- `write_collections` (Create and update a user’s collections)\n\n----\n\n### API methods\n\nFor more information about the responses for each call, refer to the [official documentation](https://unsplash.com/documentation).\n\nSome parameters are identical across all methods:\n\n  param     | Description\n------------|-----------------------------------------------------\n`$per_page` | Defines the number of objects per page. *Default 10*\n`$page`     | Defines the offset page. *Default 1*\n\n*Note: The methods that return multiple objects return an `ArrayObject`, which acts like a normal stdClass.*\n\n----\n\n### Search\n\n\u003cdiv id=\"search-photos\" /\u003e\n\n#### Photos\n\nRetrieve a single page of photo results depending on search results.\n\n**Arguments**\n\n  Argument     | Type   | Opt/Required\n---------------|--------|--------------\n`$search`      | string | Required\n`$page`        | int    | Opt *(Default: 1)*\n`$per_page`    | int    | Opt *(Default: 10 / Maximum: 30)*\n`$orientation` | string | Opt *(Default: null / Available: \"landscape\", \"portrait\", \"squarish\")*\n`$collections` | string | Opt *(Default: null / If multiple, comma-separated)*\n`$order_by`    | string | How to sort the photos. *(Optional; default: relevant)*. Valid values are *latest* and *relevant*.\n\n**Example**\n\n\n```php\n$search = 'forest';\n$page = 3;\n$per_page = 15;\n$orientation = 'landscape';\n\nUnsplash\\Search::photos($search, $page, $per_page, $orientation);\n```\n\n----\n\n#### Collections\n\nRetrieve a single page of collection results depending on search results.\n\n**Arguments**\n\n  Argument     | Type   | Opt/Required\n---------------|--------|--------------\n`$search`      | string | Required\n`$per_page`    | int    | Opt *(Default: 10 / Maximum: 30)*\n`$page`        | int    | Opt *(Default: 1)*\n\n**Example**\n\n\n```php\nUnsplash\\Search::collections($search, $page, $per_page);\n```\n\n----\n\n#### Users\n\nRetrieve a single page of user results depending on search results.\n\n**Arguments**\n\n  Argument     | Type   | Opt/Required\n---------------|--------|--------------\n`$search`      | string | Required\n`$per_page`    | int    | Opt *(Default: 10 / Maximum: 30)*\n`$page`        | int    | Opt *(Default: 1)*\n\n**Example**\n\n\n```php\nUnsplash\\Search::users($search, $page, $per_page);\n```\n\n----\n\n### Collections\n\n####\nRetrieve the list of collections.\n\n**Arguments**\n\n  Argument     | Type | Opt/Required\n---------------|------|--------------\n`$per_page`    | int  | Opt *(Default: 10 / Maximum: 30)*\n`$page`        | int  | Opt *(Default: 1)*\n\n**Example**\n\n\n```php\nUnsplash\\Collection::all($page, $per_page);\n```\n\n----\n\n#### Unsplash\\Collection::photos($page, $per_page)\nRetrieve photos from a collection.\n\n*Note:* You need to instantiate a collection object first.\n\n**Arguments**\n\n  Argument     | Type | Opt/Required\n---------------|------|--------------\n`$per_page`    | int  | Opt *(Default: 10 / Maximum: 30)*\n`$page`        | int  | Opt *(Default: 1)*\n\n**Example**\n\n```php\n$collection = Unsplash\\Collection::find(integer $id);\n$photos = $collection-\u003ephotos($page, $per_page);\n```\n\n----\n\n#### Unsplash\\Collection::related($page, $per_page)\nRetrieve list of featured collections.\n\n*Note* You must instantiate a collection first\n\n**Arguments**\n\n  Argument     | Type | Opt/Required\n---------------|------|--------------\n\n\n**Example**\n\n\n```php\n$collection = Unsplash\\Collection::find($id);\n$collection-\u003erelated();\n```\n\n----\n\n#### Unsplash\\Collection::create($title, $description, $private)\nCreate a collection on the user's behalf.\n\n*Note:* You need the `write_collections` permission scope\n\n**Arguments**\n\n  Argument     | Type    | Opt/Required\n---------------|---------|--------------\n`$title`       | string  | Required\n`$description` | string  | Opt *(Default: '')*\n`$private`     | boolean | Opt *(Default: false)*\n\n**Example**\n\n```php\n$collection = Unsplash\\Collection::create($title);\n```\n\n----\n\n#### Unsplash\\Collection::update($parameters)\nUpdate a collection on the user's behalf.\n\n*Note:* You need to instantiate a collection object first\n\n*Note:* You need the `write_collections` permission scope\n\n**Arguments**\n\n  Argument     | Type    | Opt/Required | Note\n---------------|---------|----------------------\n`$parameters`  | array   | Required     | The following keys can be set in the array : `title`, `description`, `private`\n\n**Example**\n\n```php\n$collection = Unsplash\\Collection::find(int $id);\n$collection-\u003eupdate(['private' =\u003e true])\n```\n\n----\n\n#### Unsplash\\Collection::destroy()\nDelete a collection on the user's behalf.\n\n*Note:* You need to instantiate a collection object first\n\n*Note:* You need the `write_collections` permission scope\n\n**Example**\n\n```php\n$collection = Unsplash\\Collection::find(int $id);\n$collection-\u003edestroy()\n```\n\n----\n\n#### Unsplash\\Collection::add($photo_id)\nAdd a photo in the collection on the user's behalf.\n\n*Note:* You need to instantiate a collection object first\n\n*Note:* You need the `write_collections` permission scope\n\n**Arguments**\n\n  Argument     | Type    | Opt/Required |\n---------------|---------|---------------\n`$photo_id`    | integer | Required     |\n\n**Example**\n\n```php\n$collection = Unsplash\\Collection::find(int $id);\n$collection-\u003eadd(int $photo_id)\n```\n\n----\n\n#### Unsplash\\Collection::remove($photo_id)\nRemove a photo from the collection on the user's behalf.\n\n*Note:* You need to instantiate a collection object first\n\n*Note:* You need the `write_collections` permission scope\n\n**Arguments**\n\n  Argument     | Type    | Opt/Required |\n---------------|---------|---------------\n`$photo_id`    | integer | Required     |\n\n**Example**\n\n```php\n$collection = Unsplash\\Collection::find(int $id);\n$collection-\u003eremove(int $photo_id)\n```\n\n----\n\n\n### Photo\n\n\u003cdiv id=\"photo-all\" /\u003e\n\n#### Unsplash\\Photo::all($page, $per_page, $order_by)\nRetrieve a list of photos.\n\n**Arguments**\n\n  Argument     | Type | Opt/Required\n---------------|------|--------------\n`$per_page`    | int  | Opt *(Default: 10 / Maximum: 30)*\n`$page`        | int  | Opt *(Default: 1)*\n`$order_by` | string | Opt *(Default: latest / Available: oldest, popular)*\n\n**Example**\n\n```php\nUnsplash\\Photo::all($page, $per_page, $order_by);\n```\n\n----\n\n#### Unsplash\\Photo::find($id)\nRetrieve a specific photo.\n\n**Arguments**\n\n  Argument     | Type | Opt/Required\n---------------|------|--------------\n`$id`          | int  | Required\n\n**Example**\n\n```php\nUnsplash\\Photo::find($id);\n```\n\n----\n\n#### Unsplash\\Photo::update($parameters = [])\nPost a photo on the user's behalf.\n\n*Note:* You need the `write_photos` permission scope\nYou need to instantiate the Photo object first\n\n**Arguments**\n\n  Argument     | Type   | Opt/Required\n---------------|--------|--------------\n`$parameters`   | array | Required\n\n**Example**\n\n```php\n$photo = Unsplash\\Photo::find(string $id)\n$photo-\u003eupdate(array $parameters);\n```\n\n----\n\n#### Unsplash\\Photo::photographer()\nRetrieve the photo's photographer.\n\n*Note:* You need to instantiate a photo object first\n\n**Arguments**\n\n*N/A*\n\n**Example**\n\n\n```php\n$photo = Unsplash\\Photo::find(string $id);\n$photo-\u003ephotographer();\n```\n\n----\n\n\u003cdiv id=\"photo-random\" /\u003e\n\n#### Unsplash\\Photo::random([featured =\u003e $value, username =\u003e $value, query =\u003e $value, w =\u003e $value, h =\u003e $value])\nRetrieve a random photo from specified filters. For more information regarding filtering, [refer to the Offical documentation](https://unsplash.com/documentation#get-a-random-photo).\n\n*Note:* An array needs to be passed as a parameter.\n\n**Arguments**\n\n\n  Argument     | Type | Opt/Required\n---------------|------|--------------\nfeatured | boolean | Opt *(Limit selection to featured photos)*\nusername | string | Opt *(Limit selection to a single user)*\nquery | string | Opt *(Limit selection to photos matching a search term)*\nw | int | Opt *(Image width in pixels)*\nh | int | Opt *(Image height in pixels)*\n\n\n**Example**\n\n\n```php\n\n// Or apply some optional filters by passing a key value array of filters\n$filters = [\n    'username' =\u003e 'andy_brunner',\n    'query'    =\u003e 'coffee',\n    'w'        =\u003e 100,\n    'h'        =\u003e 100\n];\nUnsplash\\Photo::random($filters);\n```\n\n----\n\n#### Unsplash\\Photo::like()\nLike a photo on the user's behalf.\n\n*Note:* You need to instantiate a photo object first\n\n*Note:* You need the `like_photos` permission scope\n\n**Arguments**\n\n*N/A*\n\n**Example**\n\n\n```php\n$photo = Unsplash\\Photo::find(string $id);\n$photo-\u003elike();\n```\n\n----\n\n#### Unsplash\\Photo::unlike()\nUnlike a photo on the user's behalf.\n\n*Note:* You need to instantiate a photo object first\n\n*Note:* You need the `like_photos` permission scope\n\n**Arguments**\n\n*N/A*\n\n**Example**\n\n\n```php\n$photo = Unsplash\\Photo::find(string $id);\n$photo-\u003eunlike();\n```\n\n----\n\n#### Unsplash\\Photo::statistics(string $resolution, int $quantity)\nRetrieve 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).\n\n*Note:* You must instantiate a Photo object first\n\n**Arguments**\n\n\n  Argument     | Type | Opt/Required\n---------------|------|--------------\nresolution | string | Opt *(Accepts only days currently)*\nquantity | int | Opt *(Defaults to 30, can be between 1 and 30)*\n\n\n**Example**\n\n\n```php\n\n\n$photo = Unsplash\\Photo::find($id);\n$photo-\u003estatistics('days', 7);\n```\n\n----\n\n\u003cdiv id=\"photo-download\" /\u003e\n\n#### Unsplash\\Photo::download()\nTrigger 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).\n\n*Note:* You must instantiate a Photo object first\n\n**Arguments**\n\n\n  Argument     | Type | Opt/Required\n---------------|------|--------------\n\n\n**Example**\n\n\n```php\n$photo = Unsplash\\Photo::find();\n$photo-\u003edownload();\n```\n\n----\n\n### User\n\n#### Unsplash\\User::find($username)\nRetrieve a user's information.\n\n**Arguments**\n\n  Argument     | Type   | Opt/Required\n---------------|--------|--------------\n`$username`    | string | Required\n\n**Example**\n\n```php\nUnsplash\\User::find($username)\n```\n\n----\n\n#### Unsplash\\User::portfolio($username)\nRetrieve a link to the user's portfolio page.\n\n**Arguments**\n\n  Argument     | Type   | Opt/Required\n---------------|--------|--------------\n`$username`    | string | Required\n\n**Example**\n\n```php\nUnsplash\\User::portfolio($username)\n```\n\n----\n\n#### Unsplash\\User::current()\nRetrieve the user's private information.\n\n*Note:* You need the *read_user* permission scope\n\n**Arguments**\n\n*N/A*\n\n**Example**\n\n```php\n$user = Unsplash\\User::current();\n```\n\n----\n\n#### Unsplash\\User::photos($page, $per_page, $order_by)\nRetrieve user's photos.\n\n*Note:* You need to instantiate a user object first\n\n**Arguments**\n\n  Argument     | Type | Opt/Required\n---------------|------|--------------\n`$per_page`    | int  | Opt *(Default: 10 / Maximum: 30)*\n`$page`        | int  | Opt *(Default: 1)*\n`$order_by` | string | Opt *(Default: latest / Available: oldest, popular)*\n\n**Example**\n\n```php\n$user = Unsplash\\User::find($username);\n$user-\u003ephotos($page, $per_page);\n```\n\n----\n\n\n#### Unsplash\\User::collections($page, $per_page)\nRetrieve user's collections.\n\n*Note:* You need to instantiate a user object first\n*Note:* You need the *read_collections* permission scope to retrieve user's private collections\n\n**Arguments**\n\n  Argument     | Type | Opt/Required\n---------------|------|--------------\n`$per_page`    | int  | Opt *(Default: 10 / Maximum: 30)*\n`$page`        | int  | Opt *(Default: 1)*\n\n**Example**\n\n```php\n$user = Unsplash\\User::find($username);\n$user-\u003ecollections($page, $per_page);\n```\n\n----\n\n#### Unsplash\\User::likes($page, $per_page, $order_by)\nRetrieve user's collections.\n\n*Note:* You need to instantiate a user object first\n\n**Arguments**\n\n  Argument     | Type | Opt/Required\n---------------|------|--------------\n`$per_page`    | int  | Opt *(Default: 10 / Maximum: 30)*\n`$page`        | int  | Opt *(Default: 1)*\n`$order_by` | string | Opt *(Default: latest / Available: oldest, popular)*\n\n\n**Example**\n\n```php\n$user = Unsplash\\User::find($username);\n$user-\u003elikes($page, $per_page, $order_by);\n```\n\n----\n\n\n#### Unsplash\\User::update([$key =\u003e value])\nUpdate current user's fields. Multiple fields can be passed in the array.\n\n*Note:* You need to instantiate a user object first\n\n*Note:* You need the *write_user* permission scope.\n\n**Arguments**\n\n  Argument     | Type   | Opt/Required | Note  |\n---------------|--------|--------------|-------|\n`$key`         | string | Required     | The following keys are accepted: `username`, `first_name`, `last_name`, `email`, `url`, `location`, `bio`, `instagram_username`\n`$value`       | mixed  | required\n\n```php\n$user = Unsplash\\User::current();\n$user-\u003eupdate(['first_name' =\u003e 'Elliot', 'last_name' =\u003e 'Alderson']);\n```\n\n#### Unsplash\\User::statistics(string $resolution, int $quantity)\nRetrieve 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).\n\n*Note:* You must instantiate the User object first\n\n**Arguments**\n\n\n  Argument     | Type | Opt/Required\n---------------|------|--------------\nresolution | string | Opt *(Accepts only days currently)*\nquantity | int | Opt *(Defaults to 30, can be between 1 and 30)*\n\n\n**Example**\n\n\n```php\n$user = Unsplash\\User::find($id);\n$user-\u003estatistics('days', 7);\n```\n\n----\n\n## Contributing\n\nBug 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](http://contributor-covenant.org/) code of conduct.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Funsplash%2Funsplash-php","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Funsplash%2Funsplash-php","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Funsplash%2Funsplash-php/lists"}