coding-guidelines

Readonly data containers with typed factory methods (`fromArray`, `fromModel`, `fromCollection`, `fromRequest`) used to pass structured data between application layers — especially for external API responses, Eloquent models, and service boundaries. Use this skill whenever creating, reviewing, or refactoring DTOs, Data Transfer Objects, value objects for inter-layer communication, or mapping payloads from APIs, models, or collections into typed PHP objects. Also trigger when the user mentions spatie/laravel-data alternatives, data mapping, or payload normalization in a Laravel context.

Eloquent model conventions for mass assignment, casts, relationship naming, activity logging, and mandatory model tests (CRUD + relations).

Single-purpose business logic classes that encapsulate one well-defined business operation. Actions are the primary location for business logic in Laravel applications, invoked from controllers, commands, or jobs.

Albatros accounting API integration via Saloon. Use when working with app/Services/Albatros/, AlbatrosConnector, or Albatros DTOs.

Laravel Blade template conventions covering components, output escaping, security, structure, and formatting.

Artisan console command classes that serve as the CLI entry point for operations. Commands validate input and delegate all business logic to Actions or Services.

Thin HTTP entry points that validate input, delegate to Actions or Services, and return a response. Controllers contain no business logic.

Component-first design system for Blade views. Use when creating UI components, designing responsive layouts, or implementing accessible interfaces.

Keep README, guidelines, and feature documentation in sync with the actual behaviour of the codebase, focusing on behaviour, examples, and how to apply the skills in practice.

DocuWare document management integration patterns. Use when working with DocuWare connector, webhooks, document imports, or app/Services/DocuWare/.

End-to-end browser testing with Laravel Dusk. Used exclusively for full user flows requiring a real Chrome browser — JavaScript interactions, multi-step forms, and visual assertions.

PHP backed string enums used instead of constants or magic strings. Enums include `label()` and `color()` helper methods and are cast on Eloquent models.

Decoupled communication between application layers. Events are plain data objects describing what happened; listeners react to those events with a single, specific side effect.

Named, meaningful failure states in your domain. Custom exceptions communicate precise failure reasons to callers and optionally carry domain-specific data.

Dedicated validation classes for all controller input. Form Requests encapsulate validation rules, authorization, and error messages outside of controllers.

Project-wide Laravel conventions that always apply: configuration access, database patterns, logging, activity logging, and code formatting.

Always prefer Laravel's built-in helper classes over native PHP functions. Use `Arr::`, `Str::`, and Collection methods instead of native PHP equivalents.

Stateless utility classes providing shared formatting, conversion, or calculation logic needed across multiple parts of the application.

Contracts defining the shape a class must conform to. Used for decoupling dependent classes from concrete implementations, enabling multiple implementations and easier testing.

Queueable units of work for background processing. Jobs handle queue configuration and failure handling — they delegate business logic to Actions or Services.

Laravel Livewire conventions for building interactive UI without custom JavaScript. Components are PHP classes with reactive properties, computed properties, and event dispatching.

HTTP request/response pipeline handlers that inspect, modify, or reject requests before or after they reach a controller. Used for authentication, throttling, header manipulation, and logging.

Database schema change files. Always create new files for changes — never modify existing migrations. Use descriptive names, proper foreign key constraints, and reversible `down()` methods.

Centralised classes that react to Eloquent model lifecycle events. Used for side effects that should always fire regardless of where a model is mutated — such as notifications, cache invalidation, and audit logging.

Laravel testing conventions using the Pest PHP framework. Covers test structure, AAA pattern, HTTP assertions, datasets, mocking, browser tests, and architecture tests.

General PHP coding standards covering strict typing, formatting, control flow, and error handling. Applies to all PHP files in the application.

Static analysis tool configured at Level 9. All code must pass PHPStan Level 9 with strict typing, no untyped signatures, and minimal suppression of errors.

PHPUnit test structure, naming, assertions, and factory conventions for Laravel feature and unit tests.

Centralised authorization logic for a given Eloquent model. Policies define per-ability access control and are enforced at the controller level.

Dedicated Form Request validation classes for all controller input. Every endpoint that accepts user input must use a `FormRequest` class — validation never happens directly inside a controller.

API resource classes that transform Eloquent models into JSON-ready arrays. Resources control exactly what is exposed in API responses and handle relationships, conditional attributes, and date formatting.

Route file conventions for organising API and web routes. Covers file separation, naming, grouping, middleware, and route model binding.

Saloon-based service layer pattern for all external API integrations. Every new external API integration must use Saloon — no raw HTTP calls.

Orchestration classes that coordinate multiple Actions, external APIs, or domain operations into a cohesive workflow. Services own transaction boundaries and third-party API integrations.

Tailwind CSS v4 styling conventions. Use when working with CSS, Tailwind utilities, or customizing the theme in Laravel projects.

Reusable behaviour shared across multiple unrelated classes. Traits provide shared Eloquent scopes, accessors, lifecycle hooks, and small stateless helper methods.

Translation and localization conventions for Laravel. Use when adding user-facing strings, creating translation files, or working with lang/ directory.