phpengine/specs/conventions-backend.md

Read this when changing PHP, Fat-Free Framework integration, plugins, or API controllers.

Backend Conventions

Namespaces and Plugins

• Composer maps OpenMind\ to src/OpenMind/ and Modules\ to src/Modules/.
• A discovered plugin lives in a directory containing <DirectoryName>.php; its derived class must extend PluginStrategy.
• ApplicationComposition boots System before the remaining plugins. Register plugin initialization work in constructors.
• Use PluginStrategy::AddRoute() for F3 route registration and AddMenuItem() for permission-filtered menu entries.

API Controllers

• API route declarations belong in OpenMind\Api\Api; controllers extend Controller.
• Use sendJson() / sendError() rather than emitting ad hoc response formats. They set JSON, status, and Cache-Control: no-store.
• Decode request objects through decodeJsonRequest() and return 400 for invalid JSON or required-field failures.
• Call requireAuthentication() for protected reads; call requireRole() plus validateCsrfToken() before protected mutations.
• Return DTOs, never a mapper or credential fields directly. See api-routes.md and identity/spec.md.

Persistence and Errors

• F3 globals ($f3, $frameworkUtils) are the established dependency access pattern; retain it where surrounding code does.
• User and Notifications are DB\SQL\Mapper classes. Use parameterized mapper predicates for request values.
• Wrap multi-step user mutation checks and writes in a transaction; use the existing row-locking pattern where the invariant requires serialization.
• Unexpected controller failures are logged server-side and return a safe generic message.
• API errors are JSON; ErrorHandlers identifies /api/v1 requests before setting the status.

Formatting

Modern API/composition files use strict types, typed properties, trailing commas, and tabs. Older system files are mixed-style; make surgical changes and preserve their local style.

See rules/add-api-endpoint.md and rules/add-plugin.md.