From 65105ae6017fbc71bc5963a1b50678a1982c9f8d Mon Sep 17 00:00:00 2001
From: "google-labs-jules[bot]"
<161369871+google-labs-jules[bot]@users.noreply.github.com>
Date: Thu, 26 Jun 2025 08:41:50 +0000
Subject: [PATCH 1/4] docs: Update README with Unsplash dev page insights and
add Arabic translation
- Refined README.md with notes on production rate limits and dynamic image resizing, linking to relevant Unsplash documentation.
- Created ReadMe-Arabic.md containing the full Arabic translation of the updated README.md, preserving Markdown formatting.
---
README.md | 964 +++++++-----------------
ReadMe-Arabic.md | 331 ++++++++
composer.json | 37 +-
config/unsplash.php | 68 ++
src/Laravel/Facades/Unsplash.php | 25 +
src/Laravel/UnsplashService.php | 146 ++++
src/Laravel/UnsplashServiceProvider.php | 45 ++
7 files changed, 927 insertions(+), 689 deletions(-)
create mode 100644 ReadMe-Arabic.md
create mode 100644 config/unsplash.php
create mode 100644 src/Laravel/Facades/Unsplash.php
create mode 100644 src/Laravel/UnsplashService.php
create mode 100644 src/Laravel/UnsplashServiceProvider.php
diff --git a/README.md b/README.md
index 43dfd19..cfc56a4 100644
--- a/README.md
+++ b/README.md
@@ -1,716 +1,316 @@
-# PHP Unsplash Wrapper
+# Unsplash PHP Client for Laravel
[](https://travis-ci.org/unsplash/unsplash-php)
+[](https://packagist.org/packages/unsplash/unsplash)
+[](https://packagist.org/packages/unsplash/unsplash)
+[](https://packagist.org/packages/unsplash/unsplash)
-A PHP client for the [Unsplash API](https://unsplash.com/documentation).
+This package provides a simple and eloquent way to interact with the [Unsplash API](https://unsplash.com/documentation) within your Laravel application. It builds upon the official `unsplash/unsplash` PHP client, offering Laravel-specific features like auto-configuration, a Facade, and caching.
-- [Official documentation](https://unsplash.com/documentation)
-- [Changelog](https://github.com/unsplash/unsplash-pHP/blob/master/CHANGELOG.md)
+- [Unsplash API Official Documentation](https://unsplash.com/documentation)
+- [Unsplash API Guidelines](https://help.unsplash.com/en/articles/2511245-unsplash-api-guidelines) (Please read and adhere to these!)
+- [Original PHP Client Changelog](https://github.com/unsplash/unsplash-php/blob/master/CHANGELOG.md)
-Quick links to methods you're likely to care about:
+**Important:** Every application using the Unsplash API must abide by the [API Guidelines](https://help.unsplash.com/en/articles/2511245-unsplash-api-guidelines). This includes:
+- Correctly [hotlinking images](https://help.unsplash.com/en/articles/2511253-hotlinking-images).
+- [Attributing photographers and Unsplash](https://help.unsplash.com/en/articles/2511243-guideline-attribution).
+- [Triggering a download event](https://help.unsplash.com/en/articles/2511258-guideline-triggering-a-download) when a user downloads an image. (This package helps with fetching data; download tracking needs to be implemented based on your app's functionality).
-- [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) 🕵️♂️
+## Key Features
-**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).
+- Seamless integration with Laravel (8.x, 9.x, 10.x, 11.x).
+- `Unsplash` Facade for easy, static-like API calls.
+- Automatic registration of Service Provider and Facade.
+- Configuration through `.env` file and a publishable config file.
+- Built-in caching for API responses to improve performance and reduce API rate limit consumption.
+- Helper methods for common tasks, like fetching a random photo URL.
## Installation
-`unsplash-php` uses [Composer](https://getcomposer.org/). To use it, require the library
+Install the package via Composer:
-```
+```bash
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](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.
-
-```php
-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](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):
-
-```php
-$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:
-
-```php
-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](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
-
-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:
-
- 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
-
-
-
-#### Photos
-
-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)*
-`$order_by` | string | How to sort the photos. *(Optional; default: relevant)*. Valid values are *latest* and *relevant*.
-
-**Example**
-
-
-```php
-$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.
-
-**Arguments**
-
- Argument | Type | Opt/Required
----------------|--------|--------------
-`$search` | string | Required
-`$per_page` | int | Opt *(Default: 10 / Maximum: 30)*
-`$page` | int | Opt *(Default: 1)*
-
-**Example**
-
-
-```php
-Unsplash\Search::collections($search, $page, $per_page);
-```
-
-----
-
-#### Users
-
-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**
-
-
-```php
-Unsplash\Search::users($search, $page, $per_page);
-```
-
-----
-
-### Collections
-
-####
-Retrieve the list of collections.
-
-**Arguments**
-
- Argument | Type | Opt/Required
----------------|------|--------------
-`$per_page` | int | Opt *(Default: 10 / Maximum: 30)*
-`$page` | int | Opt *(Default: 1)*
-
-**Example**
-
-
-```php
-Unsplash\Collection::all($page, $per_page);
-```
-
-----
-
-#### 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**
-
-```php
-$collection = Unsplash\Collection::find(integer $id);
-$photos = $collection->photos($page, $per_page);
-```
-
-----
-
-#### Unsplash\Collection::related($page, $per_page)
-Retrieve list of featured collections.
-
-*Note* You must instantiate a collection first
-
-**Arguments**
-
- Argument | Type | Opt/Required
----------------|------|--------------
-
-
-**Example**
-
-
-```php
-$collection = Unsplash\Collection::find($id);
-$collection->related();
-```
-
-----
-
-#### 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**
-
-```php
-$collection = Unsplash\Collection::create($title);
-```
-
-----
-
-#### 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**
-
-```php
-$collection = Unsplash\Collection::find(int $id);
-$collection->update(['private' => true])
-```
-
-----
-
-#### 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**
-
-```php
-$collection = Unsplash\Collection::find(int $id);
-$collection->destroy()
-```
-
-----
-
-#### 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**
-
-```php
-$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.
-
-*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**
-
-```php
-$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.
-
-**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**
-
-```php
-Unsplash\Photo::all($page, $per_page, $order_by);
-```
-
-----
-
-#### Unsplash\Photo::find($id)
-Retrieve a specific photo.
-
-**Arguments**
-
- Argument | Type | Opt/Required
----------------|------|--------------
-`$id` | int | Required
-
-**Example**
-
-```php
-Unsplash\Photo::find($id);
-```
-
-----
-
-#### 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**
-
-```php
-$photo = Unsplash\Photo::find(string $id)
-$photo->update(array $parameters);
-```
-
-----
-
-#### Unsplash\Photo::photographer()
-Retrieve the photo's photographer.
-
-*Note:* You need to instantiate a photo object first
-
-**Arguments**
-
-*N/A*
-
-**Example**
-
-
-```php
-$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](https://unsplash.com/documentation#get-a-random-photo).
-
-*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**
-
-
-```php
-
-// 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.
-
-*Note:* You need to instantiate a photo object first
-
-*Note:* You need the `like_photos` permission scope
-
-**Arguments**
-
-*N/A*
-
-**Example**
-
-
-```php
-$photo = Unsplash\Photo::find(string $id);
-$photo->like();
-```
-
-----
-
-#### 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**
-
-
-```php
-$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).
-
-*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**
-
-
-```php
-
-
-$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](https://help.unsplash.com/api-guidelines/more-on-each-guideline/guideline-triggering-a-download).
-
-*Note:* You must instantiate a Photo object first
-
-**Arguments**
-
-
- Argument | Type | Opt/Required
----------------|------|--------------
-
-
-**Example**
-
-
-```php
-$photo = Unsplash\Photo::find();
-$photo->download();
-```
-
-----
-
-### User
-
-#### Unsplash\User::find($username)
-Retrieve a user's information.
-
-**Arguments**
-
- Argument | Type | Opt/Required
----------------|--------|--------------
-`$username` | string | Required
-
-**Example**
+The package will automatically register its service provider and facade.
+
+## Configuration
+
+1. **Publish the configuration file (optional):**
+ If you need to customize the default settings, publish the configuration file using:
+ ```bash
+ php artisan vendor:publish --provider="Unsplash\Laravel\UnsplashServiceProvider" --tag="config"
+ ```
+ This will create a `config/unsplash.php` file in your application.
+
+2. **Set up your Environment Variables:**
+ Add the following to your `.env` file:
+
+ ```env
+ UNSPLASH_APPLICATION_ID="YOUR_UNSPLASH_ACCESS_KEY"
+ UNSPLASH_UTM_SOURCE="Your Laravel App Name"
+ UNSPLASH_CACHE_DURATION=60 # Cache duration in minutes (default: 60)
+ # UNSPLASH_CACHE_STORE=null # Specify a cache store, or null for default (e.g., 'redis', 'memcached')
+ ```
+
+ - `UNSPLASH_APPLICATION_ID`: **Required.** Your Unsplash Application ID (Access Key). You can obtain one by [registering your application](https://unsplash.com/oauth/applications) on Unsplash.
+ - `UNSPLASH_UTM_SOURCE`: **Required.** The name of your application. This is used in API requests and attribution links as per Unsplash guidelines.
+ - `UNSPLASH_CACHE_DURATION`: The number of minutes API responses should be cached.
+ - `UNSPLASH_CACHE_STORE`: (Optional) Specify a specific Laravel cache store to use. If `null` or not set, your default cache store will be used.
+
+## Basic Usage (Laravel Facade)
+
+The `Unsplash` facade provides a convenient way to access the API.
+
+### Getting a Random Photo
+
+- **Get a random photo object:**
+ ```php
+ use Unsplash\Laravel\Facades\Unsplash;
+
+ $photo = Unsplash::getRandomPhoto(['query' => 'nature', 'orientation' => 'landscape']);
+
+ if ($photo) {
+ // $photo is an instance of Unsplash\Photo
+ echo "Photo ID: " . $photo->id;
+ echo "Regular URL: " . $photo->urls['regular'];
+ // See "Accessing Photo Data" and "Attribution" below
+ }
+ ```
+
+- **Get a random photo URL directly:**
+ ```php
+ use Unsplash\Laravel\Facades\Unsplash;
+
+ // Get a regular-sized photo URL
+ $url = Unsplash::getRandomPhotoUrl(['query' => 'minimalist wallpaper']);
+ //
+
+ // Get a specific size (e.g., 'small', 'thumb', 'raw', 'full')
+ $smallUrl = Unsplash::getRandomPhotoUrl(['query' => 'cats'], 'small');
+ ```
+ Available URL types generally include `raw`, `full`, `regular`, `small`, `thumb`.
+
+### Getting a Specific Photo by ID
+
+- **Get a photo object by its ID:**
+ ```php
+ use Unsplash\Laravel\Facades\Unsplash;
+
+ $photoId = 'some_photo_id'; // Replace with an actual photo ID
+ $photo = Unsplash::findPhoto($photoId);
+
+ if ($photo) {
+ echo "Photo Description: " . $photo->description;
+ }
+ ```
+
+### Displaying an Image in Blade
+
+Here's an example of how you might display a random background image on your Laravel welcome page (`resources/views/welcome.blade.php`) or any other Blade view:
+
+```blade
+{{-- At the top of your Blade file or in a relevant section --}}
+@php
+ $unsplashUımSource = config('unsplash.utm_source', 'Your Laravel App');
+ $photo = Unsplash::getRandomPhoto([
+ 'query' => 'beautiful landscape', // Customize your theme
+ 'orientation' => 'landscape'
+ ]);
+ $bgUrl = $photo ? $photo->urls['regular'] : 'default_background.jpg'; // Fallback image
+@endphp
+
+
+
+
+
+
+ Laravel with Unsplash Background
+
+
+
+ {{-- Your page content here --}}
+
+ @endif
+
+
+```
+
+### Accessing Photo Data
+
+The `getRandomPhoto()` and `findPhoto()` methods return an `Unsplash\Photo` object (which extends `Unsplash\Endpoint`). You can access its properties directly:
```php
-Unsplash\User::find($username)
-```
-
-----
-
-#### Unsplash\User::portfolio($username)
-Retrieve a link to the user's portfolio page.
-
-**Arguments**
-
- Argument | Type | Opt/Required
----------------|--------|--------------
-`$username` | string | Required
-
-**Example**
-
-```php
-Unsplash\User::portfolio($username)
-```
-
-----
-
-#### Unsplash\User::current()
-Retrieve the user's private information.
-
-*Note:* You need the *read_user* permission scope
-
-**Arguments**
-
-*N/A*
-
-**Example**
-
-```php
-$user = Unsplash\User::current();
-```
-
-----
+$photo = Unsplash::getRandomPhoto();
-#### Unsplash\User::photos($page, $per_page, $order_by)
-Retrieve user's photos.
+if ($photo) {
+ $id = $photo->id;
+ $description = $photo->description ?? 'A beautiful Unsplash image.';
+ $regularUrl = $photo->urls['regular'];
+ $smallUrl = $photo->urls['small'];
+ $rawUrl = $photo->urls['raw']; // For downloads
-*Note:* You need to instantiate a user object first
+ // Photographer details
+ $photographerName = $photo->user['name'];
+ $photographerUsername = $photo->user['username'];
+ $photographerProfileLink = $photo->user['links']['html'];
-**Arguments**
+ // Links object
+ $photoHtmlLink = $photo->links['html']; // Link to the photo on Unsplash
+ $downloadLocation = $photo->links['download_location']; // Important for triggering downloads
- 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**
-
-```php
-$user = Unsplash\User::find($username);
-$user->photos($page, $per_page);
+ // For more details on available properties, inspect the $photo object
+ // or refer to the Unsplash API documentation for the photo endpoint.
+}
```
-----
-
-
-#### Unsplash\User::collections($page, $per_page)
-Retrieve user's collections.
+## Using the Service Directly
-*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**
+If you prefer dependency injection, you can type-hint `Unsplash\Laravel\UnsplashService` in your controllers or other classes:
```php
-$user = Unsplash\User::find($username);
-$user->collections($page, $per_page);
-```
-
-----
-
-#### 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**
-
+use Unsplash\Laravel\UnsplashService;
+use Illuminate\Http\Request;
+
+class MyController
+{
+ protected UnsplashService $unsplashService;
+
+ public function __construct(UnsplashService $unsplashService)
+ {
+ $this->unsplashService = $unsplashService;
+ }
+
+ public function showRandomImage(Request $request)
+ {
+ $photoUrl = $this->unsplashService->getRandomPhotoUrl(['query' => 'technology']);
+ return view('my_view', ['imageUrl' => $photoUrl]);
+ }
+}
+```
+
+## Caching
+
+API responses for photo lookups are automatically cached to improve performance and stay within API rate limits.
+- The cache duration is controlled by the `UNSPLASH_CACHE_DURATION` environment variable (or `cache_duration` in `config/unsplash.php`), specified in minutes.
+- You can specify a cache store using `UNSPLASH_CACHE_STORE` (or `cache_store` in the config). If not set, Laravel's default cache store is used.
+
+## API Guidelines & Attribution
+
+**It is crucial to follow the Unsplash API Guidelines.**
+
+- **Hotlinking:** Always hotlink images directly from Unsplash URLs (e.g., `images.unsplash.com/...`). This package uses the URLs provided by the API.
+- **Attribution:** You **must** credit the photographer and Unsplash.
+ A typical attribution looks like:
+ > Photo by [Photographer Name] on Unsplash
+
+ Replace `YOUR_APP_NAME` with your `utmSource` (configured via `UNSPLASH_UTM_SOURCE`).
+ The `Unsplash\Photo` object contains the necessary user and links information:
+ ```php
+ $photo = Unsplash::getRandomPhoto();
+ $appName = config('unsplash.utm_source'); // Or your actual app name
+
+ if ($photo) {
+ $attributionHtml = sprintf(
+ 'Photo by %s on Unsplash',
+ $photo->user['links']['html'],
+ urlencode($appName),
+ $photo->user['name'],
+ urlencode($appName)
+ );
+ // echo $attributionHtml;
+ }
+ ```
+ See the Blade example above for a practical implementation.
+
+- **Triggering Downloads:** If your application allows users to download images (not just view them), you must [trigger a download event via the API](https://unsplash.com/documentation#track-a-photo-download). The `Photo` object contains a `download_location` URL in its `links` property. You need to make a GET request to this URL when a user initiates a download.
+ ```php
+ // $photo = Unsplash::findPhoto('some_id');
+ // if ($photo && isset($photo->links['download_location'])) {
+ // // When user clicks a download button:
+ // // Make a GET request to $photo->links['download_location']
+ // // Then provide $photo->urls['raw'] or $photo->urls['full'] to the user.
+ // // Note: The Unsplash\Photo class has a download() method that does this.
+ // // $downloadableUrl = $photo->download(); // This hits the download_location endpoint
+ // }
+ ```
+ The `Unsplash\Photo->download()` method from the underlying library handles this:
+ ```php
+ $photoObject = Unsplash::findPhoto('PHOTO_ID');
+ if ($photoObject) {
+ $actualDownloadUrl = $photoObject->download(); // This triggers the download endpoint AND returns the actual image URL
+ // You can then redirect the user to $actualDownloadUrl or offer it for download.
+ }
+ ```
+
+## Advanced Usage
+
+This Laravel package primarily simplifies fetching public photo data. For more advanced interactions like searching, managing collections, user-specific actions (likes, uploads), etc., you can still leverage the full power of the underlying `unsplash/unsplash` client.
+
+The `Unsplash\Photo`, `Unsplash\Collection`, `Unsplash\Search`, and `Unsplash\User` classes from the core library are available. The `UnsplashService` initializes `Unsplash\HttpClient` with your credentials, so you can use these classes directly if needed.
+
+Example (Search):
```php
-$user = Unsplash\User::find($username);
-$user->likes($page, $per_page, $order_by);
-```
-
-----
+use Unsplash\Search;
+// Ensure HttpClient is initialized by UnsplashService (which happens automatically if Facade is used or service is injected)
-
-#### 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
-
-```php
-$user = Unsplash\User::current();
-$user->update(['first_name' => 'Elliot', 'last_name' => 'Alderson']);
+$results = Search::photos('puppies', 1, 10, 'landscape'); // query, page, per_page, orientation
+foreach ($results as $photo) {
+ // $photo is an Unsplash\Photo instance
+ echo $photo->urls['small'] . "\n";
+}
```
-#### 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**
-
+### User Authorization (OAuth)
- Argument | Type | Opt/Required
----------------|------|--------------
-resolution | string | Opt *(Accepts only days currently)*
-quantity | int | Opt *(Defaults to 30, can be between 1 and 30)*
-
-
-**Example**
-
-
-```php
-$user = Unsplash\User::find($id);
-$user->statistics('days', 7);
-```
-
-----
+For actions requiring user authentication (e.g., liking a photo on behalf of a user, uploading photos), you'll need to implement the [Unsplash OAuth2 flow](https://unsplash.com/documentation#user-authentication-workflow). This package does not provide out-of-the-box OAuth handling, but the underlying `unsplash/unsplash` client has the necessary tools. Refer to its documentation and the `/examples/oauth-flow.php` in the original library for guidance.
## 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](http://contributor-covenant.org/) code of conduct.
+
+## License
+
+The MIT License (MIT). Please see [License File](LICENSE) for more information.
diff --git a/ReadMe-Arabic.md b/ReadMe-Arabic.md
new file mode 100644
index 0000000..be7e034
--- /dev/null
+++ b/ReadMe-Arabic.md
@@ -0,0 +1,331 @@
+# عميل Unsplash PHP لـ Laravel (إصدار Laravel)
+
+[](https://travis-ci.org/unsplash/unsplash-php)
+[](https://packagist.org/packages/unsplash/unsplash)
+[](https://packagist.org/packages/unsplash/unsplash)
+[](https://packagist.org/packages/unsplash/unsplash)
+
+توفر هذه الحزمة طريقة بسيطة وأنيقة للتفاعل مع [واجهة برمجة تطبيقات Unsplash](https://unsplash.com/documentation) داخل تطبيق Laravel الخاص بك. تعتمد هذه الحزمة على عميل `unsplash/unsplash` PHP الرسمي، وتقدم ميزات خاصة بـ Laravel مثل التكوين التلقائي، وواجهة (Facade)، والتخزين المؤقت (Caching).
+
+- [الوثائق الرسمية لواجهة برمجة تطبيقات Unsplash](https://unsplash.com/documentation)
+- [إرشادات واجهة برمجة تطبيقات Unsplash](https://help.unsplash.com/en/articles/2511245-unsplash-api-guidelines) (يرجى قراءتها والالتزام بها!)
+- [سجل تغييرات عميل PHP الأصلي](https://github.com/unsplash/unsplash-php/blob/master/CHANGELOG.md)
+
+**هام:** يجب على كل تطبيق يستخدم واجهة برمجة تطبيقات Unsplash الالتزام بـ [إرشادات واجهة برمجة التطبيقات](https://help.unsplash.com/en/articles/2511245-unsplash-api-guidelines). يشمل هذا:
+- [ربط الصور مباشرة (Hotlinking)](https://help.unsplash.com/en/articles/2511253-hotlinking-images) بشكل صحيح.
+- [نسب الصور إلى المصورين و Unsplash](https://help.unsplash.com/en/articles/2511243-guideline-attribution).
+- [تتبع حدث التنزيل (Triggering a download event)](https://help.unsplash.com/en/articles/2511258-guideline-triggering-a-download) عندما يقوم المستخدم بتنزيل صورة. (تساعد هذه الحزمة في جلب البيانات؛ يجب تنفيذ تتبع التنزيل بناءً على وظائف تطبيقك).
+
+## الميزات الرئيسية
+
+- تكامل سلس مع Laravel (8.x, 9.x, 10.x, 11.x).
+- واجهة `Unsplash` (Facade) لسهولة استدعاءات API المشابهة للثابتة.
+- تسجيل تلقائي لمزود الخدمة (Service Provider) والواجهة (Facade).
+- التكوين من خلال ملف `.env` وملف تكوين قابل للنشر.
+- تخزين مؤقت مدمج لاستجابات API لتحسين الأداء وتقليل استهلاك حدود معدل API.
+- دوال مساعدة للمهام الشائعة، مثل جلب عنوان URL لصورة عشوائية.
+
+## التثبيت
+
+قم بتثبيت الحزمة عبر Composer:
+
+```bash
+composer require unsplash/unsplash
+```
+
+ستقوم الحزمة تلقائيًا بتسجيل مزود الخدمة والواجهة الخاصة بها.
+
+## الإعداد
+
+1. **نشر ملف التكوين (اختياري):**
+ إذا كنت بحاجة إلى تخصيص الإعدادات الافتراضية، قم بنشر ملف التكوين باستخدام:
+ ```bash
+ php artisan vendor:publish --provider="Unsplash\Laravel\UnsplashServiceProvider" --tag="config"
+ ```
+ سيؤدي هذا إلى إنشاء ملف `config/unsplash.php` في تطبيقك.
+
+2. **إعداد متغيرات البيئة الخاصة بك:**
+ أضف ما يلي إلى ملف `.env` الخاص بك:
+
+ ```env
+ UNSPLASH_APPLICATION_ID="YOUR_UNSPLASH_ACCESS_KEY"
+ UNSPLASH_UTM_SOURCE="Your Laravel App Name"
+ UNSPLASH_CACHE_DURATION=60 # مدة التخزين المؤقت بالدقائق (الافتراضي: 60)
+ # UNSPLASH_CACHE_STORE=null # حدد مخزنًا مؤقتًا، أو null للافتراضي (مثل 'redis', 'memcached')
+ ```
+
+ - `UNSPLASH_APPLICATION_ID`: **مطلوب.** معرف تطبيق Unsplash الخاص بك (مفتاح الوصول). يمكنك الحصول عليه عن طريق [تسجيل تطبيقك](https://unsplash.com/oauth/applications) على Unsplash. تذكر اتباع إرشادات Unsplash لنقل تطبيقك إلى وضع الإنتاج للاستفادة من حدود معدل API الأعلى.
+ - `UNSPLASH_UTM_SOURCE`: **مطلوب.** اسم تطبيقك. يُستخدم هذا في طلبات API وروابط الإسناد وفقًا لإرشادات Unsplash.
+ - `UNSPLASH_CACHE_DURATION`: عدد الدقائق التي يجب تخزين استجابات API مؤقتًا خلالها.
+ - `UNSPLASH_CACHE_STORE`: (اختياري) حدد مخزن Laravel المؤقت المحدد لاستخدامه. إذا كانت القيمة `null` أو لم يتم تعيينها، فسيتم استخدام مخزنك المؤقت الافتراضي.
+
+## الاستخدام الأساسي (واجهة Laravel)
+
+توفر واجهة `Unsplash` طريقة ملائمة للوصول إلى API.
+
+### الحصول على صورة عشوائية
+
+- **الحصول على كائن صورة عشوائي:**
+ ```php
+ use Unsplash\Laravel\Facades\Unsplash;
+
+ $photo = Unsplash::getRandomPhoto(['query' => 'nature', 'orientation' => 'landscape']);
+
+ if ($photo) {
+ // $photo هو مثيل من Unsplash\Photo
+ echo "معرف الصورة: " . $photo->id;
+ echo "URL العادي: " . $photo->urls['regular'];
+ // انظر "الوصول إلى بيانات الصورة" و "الإسناد" أدناه
+ }
+ ```
+
+- **الحصول على URL صورة عشوائية مباشرة:**
+ ```php
+ use Unsplash\Laravel\Facades\Unsplash;
+
+ // الحصول على URL صورة بالحجم العادي
+ $url = Unsplash::getRandomPhotoUrl(['query' => 'minimalist wallpaper']);
+ //
+
+ // الحصول على حجم معين (مثل 'small', 'thumb', 'raw', 'full')
+ $smallUrl = Unsplash::getRandomPhotoUrl(['query' => 'cats'], 'small');
+ ```
+ تشمل أنواع URL المتاحة عمومًا `raw`، `full`، `regular`، `small`، `thumb`.
+
+### الحصول على صورة معينة بواسطة المعرف الخاص بها
+
+- **الحصول على كائن صورة بواسطة معرفها:**
+ ```php
+ use Unsplash\Laravel\Facades\Unsplash;
+
+ $photoId = 'some_photo_id'; // استبدل بمعرف صورة فعلي
+ $photo = Unsplash::findPhoto($photoId);
+
+ if ($photo) {
+ echo "وصف الصورة: " . $photo->description;
+ }
+ ```
+
+### عرض صورة في Blade
+
+إليك مثال على كيفية عرض صورة خلفية عشوائية على صفحة الترحيب في Laravel (`resources/views/welcome.blade.php`) أو أي عرض Blade آخر:
+
+```blade
+{{-- في أعلى ملف Blade الخاص بك أو في قسم ذي صلة --}}
+@php
+ $unsplashUımSource = config('unsplash.utm_source', 'Your Laravel App');
+ $photo = Unsplash::getRandomPhoto([
+ 'query' => 'beautiful landscape', // خصص المظهر الخاص بك
+ 'orientation' => 'landscape'
+ ]);
+ $bgUrl = $photo ? $photo->urls['regular'] : 'default_background.jpg'; // صورة احتياطية
+@endphp
+
+
+
+
+
+
+ Laravel مع خلفية Unsplash
+
+
+
+ {{-- محتوى صفحتك هنا --}}
+