activitypub-php-conventions

PHP file naming conventions in ActivityPub plugins follow a pattern tied to their purpose: regular classes use PascalCase filenames matching the class name, while handler and transformer classes include their role in the filename (e.g., ActivityHandler.php). Namespaces mirror directory structure under the plugin's root namespace, and all files declare their namespace at the top to enable proper autoloading and text domain usage within namespaced code.

Transformers convert WordPress content into ActivityPub format; Handlers process incoming ActivityPub activities and route them to appropriate actions; Collections manage lists of ActivityPub objects. Each follows a documented pattern: Transformers inherit from a base class and implement conversion methods, Handlers contain activity routing logic, and Collections provide iteration and filtering over ActivityPub object groups.

The includes directory holds core ActivityPub classes organized by function—Transformers, Handlers, Collections, and REST controllers go in appropriately named subdirectories. The integration directory contains adapters that connect ActivityPub to other WordPress components. Both directories follow the same namespace and naming conventions, enabling consistent structure across the plugin.

Yes, WordPress global functions work in namespaced code without modification because they are defined in the global namespace. Reference them directly by name—PHP automatically resolves them to the global scope. The plugin enforces proper escaping standards for all output, regardless of namespace depth.

REST API controllers inherit from a base controller class and register routes under the plugin's REST namespace. Each endpoint maps to a controller method that handles the HTTP verb and returns ActivityPub-formatted JSON. Controllers follow a consistent pattern for parameter validation, permission checking, and response formatting.

Consistent conventions reduce technical debt by making code predictable: developers know where to find functionality, how new files should be named, and which patterns to follow. This uniformity speeds up code reviews, onboarding, and refactoring across a large plugin codebase.