### Install PHP Stock Media via Composer

Source: https://github.com/irazasyed/php-stock-media/blob/main/README.md

This command installs the PHP Stock Media library using Composer, the dependency manager for PHP. Ensure Composer is installed and accessible in your environment.

```bash
composer require irazasyed/php-stock-media
```

--------------------------------

### Run Project Tests

Source: https://github.com/irazasyed/php-stock-media/blob/main/README.md

This command executes the test suite for the PHP Stock Media project. It's recommended to run tests after installation or before making changes to ensure the library functions correctly.

```bash
composer test
```

--------------------------------

### Install PHP Stock Media via Composer and Publish Config

Source: https://context7.com/irazasyed/php-stock-media/llms.txt

Installs the PHP Stock Media package using Composer. For Laravel projects, it also publishes the configuration file using Artisan.

```bash
composer require irazasyed/php-stock-media

# For Laravel: Publish config file
php artisan vendor:publish --tag="php-stock-media-config"
```

--------------------------------

### Handle Stock Media API Errors and Exceptions

Source: https://context7.com/irazasyed/php-stock-media/llms.txt

Illustrates how to implement robust error handling for stock media API interactions using built-in exception classes. It covers `CouldNotInitializeService` for setup issues and `CouldNotFetch` for API response errors, along with general `JsonException`.

```php
<?php

use Irazasyed\StockMedia\Services\Unsplash;
use Irazasyed\StockMedia\Exceptions\CouldNotFetch;
use Irazasyed\StockMedia\Exceptions\CouldNotInitializeService;

try {
    $unsplash = Unsplash::new('YOUR_UNSPLASH_API_KEY');
    $results = $unsplash->search(['query' => 'nature']);

    foreach ($results['results'] as $photo) {
        echo $photo['urls']['regular'] . "\n";
    }
} catch (CouldNotInitializeService $e) {
    // Thrown when:
    // - API key is not set: "API Key for the Stock Service [Unsplash] Not Provided"
    // - Service not supported: "Stock Service [CustomService] Not Supported"
    // - Service not compatible: "Stock Service [InvalidService] Not Compatible. Must implement StockServiceContract"
    echo "Initialization Error: " . $e->getMessage() . "\n";
} catch (CouldNotFetch $e) {
    // Thrown when API returns an error response
    // Message format: "Stock service responded with an error: Status Code: 401 | Response: {...}"
    echo "API Error: " . $e->getMessage() . "\n";
} catch (\JsonException $e) {
    // Thrown when response cannot be parsed as JSON
    echo "JSON Parse Error: " . $e->getMessage() . "\n";
}

// Check for API key before making requests
$service = new Unsplash();
try {
    $apiKey = $service->getApiKey(); // Throws if not set
} catch (CouldNotInitializeService $e) {
    $service->setApiKey('YOUR_API_KEY');
}

```

--------------------------------

### Unsplash Service: Search and Get Random Photos

Source: https://context7.com/irazasyed/php-stock-media/llms.txt

Utilizes the Unsplash service class to search for photos based on various parameters like query, orientation, and color, or to retrieve random photos. Requires an Unsplash API key.

```php
<?php

use Irazasyed\StockMedia\Services\Unsplash;

$unsplash = Unsplash::new('YOUR_UNSPLASH_API_KEY');

// Search photos
$photos = $unsplash->search([
    'query' => 'mountains',
    'page' => 1,
    'per_page' => 15,
    'orientation' => 'landscape',  // landscape, portrait, squarish
    'color' => 'blue',             // black_and_white, black, white, yellow, orange, red, purple, magenta, green, teal, blue
]);

// Get random photos
$randomPhotos = $unsplash->searchRandom([
    'query' => 'office',
    'count' => 5,
    'orientation' => 'portrait',
]);

// Access results
foreach ($photos['results'] as $photo) {
    echo "Photo ID: " . $photo['id'] . "\n";
    echo "URL: " . $photo['urls']['regular'] . "\n";
    echo "Photographer: " . $photo['user']['name'] . "\n";
}
```

--------------------------------

### Direct Service Instantiation with Unsplash, Pexels, and Pixabay

Source: https://context7.com/irazasyed/php-stock-media/llms.txt

This snippet illustrates how to directly instantiate service objects for Unsplash, Pexels, and Pixabay without using a factory. It shows two methods: using the static `new()` method and using the constructor with method chaining. This approach is useful for simpler use cases or when specific configurations like HTTP options or custom base URLs are needed.

```php
<?php

use Irazasyed\StockMedia\Services\Unsplash;
use Irazasyed\StockMedia\Services\Pexels;
use Irazasyed\StockMedia\Services\Pixabay;

// Using static new() method
$unsplash = Unsplash::new('YOUR_UNSPLASH_API_KEY');
$results = $unsplash->search(['query' => 'cats']);

// Using constructor with method chaining
$pexels = (new Pexels())
    ->setApiKey('YOUR_PEXELS_API_KEY')
    ->setHttpOptions([
        'timeout' => 30,
        'connect_timeout' => 10,
    ]);
$results = $pexels->search(['query' => 'dogs']);

// Override base URL if needed (useful for testing/mocking)
$pixabay = Pixabay::new('YOUR_PIXABAY_API_KEY')
    ->setBaseURL('https://custom-pixabay-proxy.example.com/api');

```

--------------------------------

### Register Custom Stock Media Services with Factory

Source: https://context7.com/irazasyed/php-stock-media/llms.txt

Demonstrates how to extend the `BaseService` and implement `StockServiceContract` to create custom stock media services. These services can then be registered with the `StockMediaFactory` for use within the `StockMedia` class. This allows for integration with services beyond the default ones.

```php
<?php

use Irazasyed\StockMedia\StockMedia;
use Irazasyed\StockMedia\StockMediaFactory;
use Irazasyed\StockMedia\Contracts\StockServiceContract;
use Irazasyed\StockMedia\Services\BaseService;

// Create a custom service by extending BaseService
class ShutterstockService extends BaseService implements StockServiceContract
{
    protected string $baseURL = 'https://api.shutterstock.com/v2';

    public function search(array $params): array
    {
        $options = [
            'query' => $params,
            'headers' => [
                'Authorization' => 'Bearer ' . $this->getApiKey(),
            ],
        ];

        $response = $this->httpClient()->get('/images/search', $options);

        return $this->responseToArray($response);
    }
}

// Register and use custom service
$stockMedia = new StockMedia();

// Add custom service to factory
$stockMedia->factory()->addService(ShutterstockService::class);

// Or add multiple services at once
$stockMedia->factory()->addServices([
    ShutterstockService::class,
    AnotherCustomService::class,
]);

// Get all registered services
$services = $stockMedia->factory()->getServices();
// Returns: [Pexels::class, Pixabay::class, Unsplash::class, ShutterstockService::class, ...]

// Use the custom service
$stockMedia->setDefault(ShutterstockService::class);
$stockMedia->setApiKey('YOUR_SHUTTERSTOCK_API_KEY');
$results = $stockMedia->search(['query' => 'business']);

```

--------------------------------

### Laravel Integration for Stock Media Services

Source: https://context7.com/irazasyed/php-stock-media/llms.txt

This snippet details how to integrate the Stock Media library with Laravel applications. It includes configuration for default services and API keys in `config/stock-media.php` and `.env` file. It also demonstrates how to use the `StockMedia` facade in controllers to search for media, specifying the default service or switching to a different one.

```php
// config/stock-media.php
return [
    'default' => \Irazasyed\StockMedia\Services\Pexels::class,

    'services' => [
        \Irazasyed\StockMedia\Services\Pexels::class => env('PEXELS_API_KEY'),
        \Irazasyed\StockMedia\Services\Pixabay::class => env('PIXABAY_API_KEY'),
        \Irazasyed\StockMedia\Services\Unsplash::class => env('UNSPLASH_API_KEY'),
    ],
];

// .env
PEXELS_API_KEY=your_pexels_api_key
PIXABAY_API_KEY=your_pixabay_api_key
UNSPLASH_API_KEY=your_unsplash_api_key

```

```php
// In your Laravel controller or service
use Irazasyed\StockMedia\Laravel\Facades\StockMedia;

class MediaController extends Controller
{
    public function searchPhotos(Request $request)
    {
        // Uses the default service from config (Pexels)
        $results = StockMedia::search([
            'query' => $request->input('query', 'landscape'),
            'per_page' => $request->input('per_page', 15),
        ]);

        return response()->json($results);
    }

    public function searchWithService(Request $request)
    {
        // Switch to a different service
        $stockMedia = app(\Irazasyed\StockMedia\StockMedia::class);
        $stockMedia->setDefault(\Irazasyed\StockMedia\Services\Unsplash::class);
        $stockMedia->setApiKey(config('stock-media.services.' . \Irazasyed\StockMedia\Services\Unsplash::class));

        $results = $stockMedia->search([
            'query' => $request->input('query'),
        ]);

        return response()->json($results);
    }
}

```

--------------------------------

### Search Images and Videos with Pixabay Service

Source: https://context7.com/irazasyed/php-stock-media/llms.txt

This snippet demonstrates how to use the Pixabay service to search for images and videos. It requires a Pixabay API key and allows for extensive filtering options such as image type, category, orientation, and color. The output includes details about the search results, including preview and large image URLs, download counts, and likes.

```php
<?php

use Irazasyed\StockMedia\Services\Pixabay;

$pixabay = Pixabay::new('YOUR_PIXABAY_API_KEY');

// Search images
$images = $pixabay->search([
    'q' => 'yellow flowers',
    'page' => 1,
    'per_page' => 20,
    'image_type' => 'photo',        // all, photo, illustration, vector
    'orientation' => 'horizontal',   // all, horizontal, vertical
    'category' => 'nature',          // backgrounds, fashion, nature, science, education, feelings, health, people, religion, places, animals, industry, computer, food, sports, transportation, travel, buildings, business, music
    'min_width' => 1920,
    'min_height' => 1080,
    'colors' => 'yellow,green',      // grayscale, transparent, red, orange, yellow, green, turquoise, blue, lilac, pink, white, gray, black, brown
    'safesearch' => true,
    'editors_choice' => true,
]);

// Search videos
$videos = $pixabay->searchVideo([
    'q' => 'ocean waves',
    'page' => 1,
    'per_page' => 10,
    'video_type' => 'film',          // all, film, animation
    'min_width' => 1920,
    'min_height' => 1080,
]);

// Access image results
foreach ($images['hits'] as $image) {
    echo "Image ID: " . $image['id'] . "\n";
    echo "Preview: " . $image['previewURL'] . "\n";
    echo "Large: " . $image['largeImageURL'] . "\n";
    echo "Downloads: " . $image['downloads'] . "\n";
    echo "Likes: " . $image['likes'] . "\n";
}

```

--------------------------------

### Publish Laravel Configuration

Source: https://github.com/irazasyed/php-stock-media/blob/main/README.md

This command publishes the configuration file for PHP Stock Media if you are using Laravel. This allows for customization of the library's settings within your Laravel application.

```bash
php artisan vendor:publish --tag="php-stock-media-config"
```

--------------------------------

### Basic Usage: Search Media with StockMedia Class

Source: https://context7.com/irazasyed/php-stock-media/llms.txt

Demonstrates how to use the main StockMedia class to set a default service (e.g., Unsplash), authenticate, and perform searches. It returns an array of media results.

```php
<?php

use Irazasyed\StockMedia\StockMedia;
use Irazasyed\StockMedia\Services\Unsplash;
use Irazasyed\StockMedia\Services\Pexels;
use Irazasyed\StockMedia\Services\Pixabay;

// Initialize StockMedia
$stockMedia = new StockMedia();

// Set Unsplash as the default service and search
$stockMedia->setDefault(Unsplash::class);
$service = $stockMedia->setApiKey('YOUR_UNSPLASH_API_KEY');
$results = $service->search(['query' => 'nature', 'per_page' => 10]);

// Results array contains photo data from Unsplash API
// {
//     "total": 10000,
//     "total_pages": 1000,
//     "results": [
//         {
//             "id": "abc123",
//             "urls": {
//                 "raw": "https://images.unsplash.com/",
//                 "full": "https://images.unsplash.com/",
//                 "regular": "https://images.unsplash.com/",
//                 "small": "https://images.unsplash.com/",
//                 "thumb": "https://images.unsplash.com/"
//             },
//             "description": "A beautiful nature scene"
//         }
//     ]
// }
```

--------------------------------

### Search Stock Media using Unsplash API in PHP

Source: https://github.com/irazasyed/php-stock-media/blob/main/README.md

This PHP code snippet demonstrates how to use the StockMedia library to search for images on Unsplash. It requires an Unsplash API key and initializes the library to use the Unsplash service.

```php
use Irazasyed\StockMedia;
use Irazasyed\StockMedia\Services\Unsplash;

$apiKey = 'UNSPLASH_API_KEY';

$stockMedia = new StockMedia();
$stockMedia->setDefault(Unsplash::class);

$service = $stockMedia->setApiKey($apiKey);
$result = $service->search(['query' => 'nature']);

```

--------------------------------

### Pexels Service: Search Photos and Videos

Source: https://context7.com/irazasyed/php-stock-media/llms.txt

Employs the Pexels service class to search for photos and videos separately, supporting Pexels API parameters like query, orientation, size, and minimum dimensions. Requires a Pexels API key.

```php
<?php

use Irazasyed\StockMedia\Services\Pexels;

$pexels = Pexels::new('YOUR_PEXELS_API_KEY');

// Search photos
$photos = $pexels->search([
    'query' => 'technology',
    'page' => 1,
    'per_page' => 20,
    'orientation' => 'landscape',  // landscape, portrait, square
    'size' => 'large',             // large, medium, small
    'color' => 'blue',
]);

// Search videos
$videos = $pexels->searchVideo([
    'query' => 'nature',
    'page' => 1,
    'per_page' => 10,
    'min_width' => 1920,
    'min_height' => 1080,
]);

// Access photo results
foreach ($photos['photos'] as $photo) {
    echo "Photo ID: " . $photo['id'] . "\n";
    echo "Original: " . $photo['src']['original'] . "\n";
    echo "Large: " . $photo['src']['large'] . "\n";
    echo "Photographer: " . $photo['photographer'] . "\n";
}

// Access video results
foreach ($videos['videos'] as $video) {
    echo "Video ID: " . $video['id'] . "\n";
    echo "Duration: " . $video['duration'] . " seconds\n";
    foreach ($video['video_files'] as $file) {
        echo "Quality: " . $file['quality'] . " - " . $file['link'] . "\n";
    }
}
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.