From eb5da729ca5bf4a8254ebcc8994414181aa8dedb Mon Sep 17 00:00:00 2001 From: Snider Date: Fri, 13 Mar 2026 13:38:02 +0000 Subject: [PATCH] docs: add CLAUDE.md project instructions Co-Authored-By: Virgil --- CLAUDE.md | 55 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 55 insertions(+) create mode 100644 CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..c23f598 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,55 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. + +## Project Overview + +Composer library (`lthn/php-plug-business`) providing business platform integrations for the Plug framework. Currently implements Google My Business API. Licensed under EUPL-1.2. + +## Commands + +```bash +composer install # Install dependencies +composer dump-autoload # Regenerate autoloader after adding classes +``` + +No test suite is configured in this repository. No linter/formatter config present. + +## Architecture + +This is a **Plug provider package** — part of the `lthn/php` (core Plug framework) ecosystem. Each platform integration follows a consistent class-per-operation pattern. + +### Plug Framework Pattern + +Every operation class uses three traits from `Core\Plug\Concern\` and implements one contract from `Core\Plug\Contract\`: + +| Trait | Purpose | +|-------|---------| +| `BuildsResponse` | Wraps results into `Core\Plug\Response` objects (`ok()`, `error()`, `fromHttp()`) | +| `ManagesTokens` | Stores/retrieves OAuth tokens via `withToken()` / `accessToken()` | +| `UsesHttp` | Provides Laravel HTTP client via `http()` | + +| Contract | Method | Used by | +|----------|--------|---------| +| `Authenticable` | `getAuthUrl()`, `requestAccessToken()` | Auth | +| `Refreshable` | `refresh()` | Auth | +| `Postable` | `publish()` | Post | +| `Listable` | `listEntities()` | Locations | +| `Readable` | `get()`, `me()`, `list()` | Read | +| `Deletable` | `delete()` | Delete | + +### Adding a New Platform + +Create a new directory under `src/` (e.g., `src/Yelp/`) with classes following the same trait+contract pattern. Each class should use `BuildsResponse`, `ManagesTokens`, and `UsesHttp`, and implement the appropriate contract. + +### Namespace + +`Core\Plug\Business\` maps to `src/` via PSR-4 autoloading. Requires PHP 8.2+. + +## Conventions + +- `declare(strict_types=1)` on every file +- All public API methods return `Core\Plug\Response` (except static helpers like `getAuthUrl()`, `externalAccountUrl()`) +- Token-dependent methods check `$this->accessToken()` first and return `$this->error()` if missing +- Google API responses are normalized through `$this->fromHttp($response, fn ($data) => [...])` callbacks +- Uses Laravel HTTP client (via `UsesHttp` trait) and `Illuminate\Support\Collection` for media