Weave Code
Coding Guidelines Laravel Package
codebar-ag/coding-guidelines
A set of Laravel and PHP coding guideline rules for consistent, maintainable codebases, covering formatting, naming, and best practices enforced through tooling.
Skills
actions
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
Albatros accounting API integration via Saloon. Use when working with app/Services/Albatros/, AlbatrosConnector, or Albatros DTOs.
blade
Laravel Blade template conventions covering components, output escaping, security, structure, and formatting.
commands
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.
controllers
Thin HTTP entry points that validate input, delegate to Actions or Services, and return a response. Controllers contain no business logic.
design
Component-first design system for Blade views. Use when creating UI components, designing responsive layouts, or implementing accessible interfaces.
documentation
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
DocuWare document management integration patterns. Use when working with DocuWare connector, webhooks, document imports, or app/Services/DocuWare/.
dto
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.
enums
PHP backed string enums used instead of constants or magic strings. Enums include `label()` and `color()` helper methods and are cast on Eloquent models.
events
Decoupled communication between application layers. Events are plain data objects describing what happened; listeners react to those events with a single, specific side effect.
exceptions
Named, meaningful failure states in your domain. Custom exceptions communicate precise failure reasons to callers and optionally carry domain-specific data.
formrequests
Dedicated validation classes for all controller input. Form Requests encapsulate validation rules, authorization, and error messages outside of controllers.
helperfunctions
Always prefer Laravel's built-in helper classes over native PHP functions. Use `Arr::`, `Str::`, and Collection methods instead of native PHP equivalents.
helpers
Stateless utility classes providing shared formatting, conversion, or calculation logic needed across multiple parts of the application.
icons
Icon conventions. Lucide is the default icon set in every codebar project (Blade, Livewire, Vue); brand logos come from Simple Icons. Use when adding, replacing or reviewing icons. Font Awesome is not used.
interfaces
Contracts defining the shape a class must conform to. Used for decoupling dependent classes from concrete implementations, enabling multiple implementations and easier testing.
jobs
Queueable units of work for background processing. Jobs handle queue configuration and failure handling — they delegate business logic to Actions or Services.
livewire
Laravel Livewire conventions for building interactive UI without custom JavaScript. Components are PHP classes with reactive properties, computed properties, and event dispatching.
middleware
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.
migrations
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.
models
Eloquent model conventions for mass assignment, casts, relationship naming, activity logging, and mandatory model tests (CRUD + relations).
observers
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.
pest-browser
End-to-end browser testing with Pest 5 browser testing (pestphp/pest-plugin-browser, Playwright). Used for full user flows that need a real browser — JavaScript interactions, multi-step forms, modals and visual assertions. Laravel Dusk is not used.
pesttesting
Laravel testing conventions using the Pest PHP framework. Covers test structure, AAA pattern, HTTP assertions, datasets, mocking, browser tests, and architecture tests.
php
General PHP coding standards covering strict typing, formatting, control flow, and error handling. Applies to all PHP files in the application.
phpstan
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
PHPUnit test structure, naming, assertions, and factory conventions for Laravel feature and unit tests.
policies
Centralised authorization logic for a given Eloquent model. Policies define per-ability access control and are enforced at the controller level.
requests
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.
resources
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.
routing
Route file conventions for organising API and web routes. Covers file separation, naming, grouping, middleware, and route model binding.
saloon
Saloon-based service layer pattern for all external API integrations. Every new external API integration must use Saloon — no raw HTTP calls.
services
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
Tailwind CSS v4 styling conventions. Use when working with CSS, Tailwind utilities, or customizing the theme in Laravel projects.
traits
Reusable behaviour shared across multiple unrelated classes. Traits provide shared Eloquent scopes, accessors, lifecycle hooks, and small stateless helper methods.
translations
Translation and localization conventions for Laravel. Use when adding user-facing strings, creating translation files, or working with lang/ directory.
General
name: general description: Project-wide Laravel conventions that always apply: configuration access, database patterns, logging, activity logging, and code formatting. compatibleagents:
Weaver
How can I help you explore Laravel packages today?