php-plug-stock/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

lthn/php-plug-stock is a PHP library providing stock imagery provider integrations for the Plug framework. Currently implements Unsplash as the sole provider. Licensed under EUPL-1.2.

Dependencies

• PHP ^8.2
• lthn/php (core Plug framework) — provides Core\Plug\Concern\BuildsResponse, Core\Plug\Concern\UsesHttp, and Core\Plug\Response
• Laravel (used for config(), HTTP client, queue system)

Commands

composer install          # Install dependencies

No test suite, linter, or build step is configured in this repository.

Architecture

Namespace: Core\Plug\Stock\ mapped to src/ via PSR-4.

All provider classes live under a provider subdirectory (e.g. src/Unsplash/). Each class follows the same pattern:

• Constructor reads config via config('services.unsplash.client_id') and throws Exception::notConfigured() if missing
• Uses traits BuildsResponse and UsesHttp from the core Plug framework for HTTP calls and standardised Response objects
• Photo::transform() is the shared normaliser — used by Search, Collection, and Photo to produce a consistent photo data structure

Key classes:

• Search — keyword search with fallback to random default terms
• Photo — single photo retrieval + static transform() normaliser
• Collection — list collections and their photos
• Download — triggers Unsplash download tracking (required by API guidelines)
• Jobs\TriggerDownload — Laravel queued job wrapping Download (3 retries, 60s backoff)
• Exception — named constructors for domain-specific errors

Configuration

Requires UNSPLASH_CLIENT_ID environment variable, accessed via config('services.unsplash.client_id').