php-plug-web3/CLAUDE.md

CLAUDE.md

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

Project Overview

PHP Composer library (lthn/php-plug-web3) providing decentralised/Web3 social media provider integrations for the Plug framework. Depends on lthn/php which supplies the base contracts, concerns, and Response class.

Commands

No build step — this is a library. Install dependencies:

composer install

No test suite or linter is configured in this repository.

Architecture

Namespace: Core\Plug\Web3\ (PSR-4 from src/)

Six providers, each under src/{Provider}/:

• Bluesky — AT Protocol, app passwords, optional custom PDS via withPds()
• Farcaster — Neynar API, managed signers via withSigner() + withApiKey()
• Lemmy — REST API v3, username/password JWT auth, federated via forInstance()
• Mastodon — REST API v1, OAuth 2.0, federated via forInstance()
• Nostr — Cryptographic key pairs (secp256k1), relay-based publishing, no HTTP auth
• Threads — Meta Graph API, OAuth 2.0, two-step container+publish flow

Each provider has up to 5 classes implementing contracts from Core\Plug\Contract\:

• Auth implements Authenticable — authentication/token exchange
• Post implements Postable — publishing content (publish(string $text, Collection $media, array $params))
• Read implements Readable — fetching content (get(), me(), list())
• Delete implements Deletable — removing content
• Media implements MediaUploadable — file uploads (Mastodon, Bluesky only)
• Lemmy also has Comment and Communities (implements Listable)

Shared behaviour via concerns from Core\Plug\Concern\:

• BuildsResponse — wraps API responses into Core\Plug\Response (fromHttp(), ok(), error())
• UsesHttp — provides $this->http() (Laravel HTTP client)
• ManagesTokens — withToken(), accessToken(), getToken()

Key patterns:

• All public methods return Core\Plug\Response
• Federated providers (Mastodon, Lemmy) require instance URL set via forInstance() before API calls
• Post::publish() has a uniform signature across all providers; provider-specific options go in $params
• Each provider has static externalPostUrl() and externalAccountUrl() helpers for generating web URLs
• Strict types declared in every file; PHP 8.2+ required