TruCMS Coding Conventions and Rules

The project's own guidelines, collected in one place. Follow them and your plugin will look like the bundled modules — which is the point.

Architecture rules

• No front-end framework. Build UI in Blade under resources/themes/{admin,echo}/… or in a module's resources/views, with small vanilla JavaScript where needed. The Vue-based Translations screen comes from a package and is not a pattern to follow.
• Business modules live in Modules/{Name}. Core routes/*.php never load module routes; each module wires its own through its RouteServiceProvider. Do not add e-commerce, booking or payment code to app/.
• Core ↔ module coupling is hook-based only (the AdminBooting event and the App\Facades\{AppPages,Dashboard,Widgets,…} registries). No direct Modules\* references from app/Models.
• Authorisation is an inline ->can('permission string') on the route (Spatie permissions), not policy classes — except per-instance ownership checks like Team and Ticket.
• Slugs are dual-tracked (legacy column plus the global slugs table) through HasSlug. New sluggable models implement ResolvableSlug and a ResolvedSlugRenderer, not a bespoke route.
• The blog has a single fixed design (App\Services\Blog\Publication). Configurable blog layouts were tried and removed on purpose; do not add a layout registry, picker or blog settings store.
• Status fields are plain strings/ints in the core (Post.status, Ticket.state). Booking and TruPayments do declare a few enums of their own (for example AppointmentStatus, PaymentStatus); match the convention of the area you work in.
• Queues default to sync and broadcasting is dormant (BROADCAST_DRIVER=log). Check the deployment before you depend on either.
• Leave the core's dependencies alone. A plugin must not need edits to the root composer.json or package.json; if it needs a PHP library, declare it in the module's own composer.json and document the Composer step. Do not add new top-level folders.

PHP style

The code is formatted with Laravel Pint (preset: laravel, one space around string concatenation). Run vendor/bin/pint --dirty (or vendor/bin/pint Modules/YourPlugin) before finishing any PHP change.

• Every file starts with declare(strict_types=1);.
• Always use curly braces for control structures, even one-line bodies.
• Use constructor property promotion; do not leave an empty zero-parameter __construct().
• Explicit return types and parameter types everywhere (function isAccessible(User $user, ?string $path = null): bool).
• Prefer PHPDoc blocks over inline comments; use array-shape types (array{id: string, name?: string}). Inline comments only for genuinely complex logic.
• Descriptive names (isRegisteredForDiscounts, not discount()). Enum cases (when you do use enums) are TitleCase.
• Check sibling files for structure and naming before creating a new file.
• Use php artisan make:* (or module:make-* inside a module) with --no-interaction so the stubs and namespaces are right.
• PHPStan runs at level 4 and forbids env() outside config/; read configuration with config().

Naming conventions

Views and front-end

• Prefer Bootstrap utilities and the existing component classes; avoid new CSS when an existing class exists. Echo's spacer scale is custom (mb-5 = 2.5rem, mb-6 = 3.5rem) — read the compiled CSS, do not assume Bootstrap defaults.
• All user-visible strings go through __() / @lang. Add keys to the language file of your module (lang/en/{file}.php).
• Add the Vite entry points of a module to the root vite.config.jsinput list (see Build and assets).
• Theme colours come from theme options at runtime (var(--bs-primary), color-mix), never hard-coded hex values.
• Saved page content is compiled with Blade::render(), so never let data you bake into a page contain unescaped {{ }} or @php.

Database

• Migrations live in the module (database/migrations); module paths are auto-discovered by nwidart. A module's tables are never dropped when the module is deactivated or deleted.
• Seeders for permissions are idempotent (firstOrCreate / updateOrInsert) and are also written as migrations when a permission is added after release (see the Booking refund permissions migration).
• New models get a factory and a seeder where useful. Tests create data with factories, not by hand.

Testing rules

• Add or update tests for behaviour and logic changes; styling and copy-only changes do not need tests.
• Run the narrowest set that covers the change (php artisan test --compact path), and re-run after each change.
• Prefer a feature test that goes through HTTP over a throw-away script: it keeps proving the behaviour after the next change.
• Seeders that write media must be tested with Storage::fake('public').
• More in Testing.

Area-specific rules

A few areas carry decisions the code cannot express. In the source repository each has a rule file in .ai/rules/; the essence is below. Follow it whenever you change or override files in these areas: