laravel-conventions

Enforces Laravel architecture conventions for controllers, actions, services, and error handling.

Updated Aug 25, 2017
One-click install
npx skills add https://github.com/loki495/dotfiles --skill laravel-conventions-loki495
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: laravel-conventions
Source: https://github.com/loki495/dotfiles/tree/main/ai/skills/laravel-conventions
Command: npx skills add https://github.com/loki495/dotfiles --skill laravel-conventions-loki495

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Laravel codebases often drift into fat controllers, untyped methods, and blanket try/catch blocks that hide real bugs. This Skill gives an AI assistant a consistent set of architecture rules so generated or reviewed Laravel/Livewire code follows a thin controllers → actions → services pattern with strict typing and deliberate error handling. ## Core Features & Use Cases - Layered Architecture Rules: Controllers handle validation only, invokable action classes hold business logic, and services own third-party or network calls. - Action Return Value Guidance: Create/update actions return Eloquent models, deletes return bool, and custom actions return natural result types without forced wrappers. - Transactions and Error Handling: Multi-write actions wrap work in DB transactions, expected failures are caught and handled, while real bugs are allowed to throw. - Use Case: Ask the assistant to write a new order-processing endpoint, and it will scaffold a thin controller, a typed invokable action with a transaction, and a service for the payment provider call. ## Quick Start Use the laravel-conventions skill to review this Laravel controller and refactor its business logic into a typed action class.

Frequently Asked Questions about laravel-conventions

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I structure Laravel controllers with action classes?▼

Keep controllers thin: they validate the request and call a single-purpose invokable action class with one public handle() method. All business logic lives in the action, and tests should call actions directly rather than only through HTTP tests.

What should a Laravel action class return?▼

Create and update actions return the Eloquent model, delete actions return bool, and custom actions return whatever fits naturally, such as a DTO, array, or string. Avoid forcing a generic wrapper type when it does not fit the operation.

When should Laravel actions use database transactions?▼

Wrap an action in a DB transaction whenever it performs multiple related database writes, so a partial failure cannot leave inconsistent data. Rollbacks should be logged or reported clearly rather than silently swallowed.

Does this convention apply to OpenCart or legacy PHP projects?▼

No, these conventions apply to Laravel and Livewire projects only; OpenCart follows separate legacy guidance. Also verify the project PHP version before requiring declare(strict_types=1), since older legacy PHP may not support it.

How should Laravel code handle expected errors versus real exceptions?▼

Expected failures like third-party API timeouts or malformed external JSON should be caught with try/catch in the action or service layer and handled gracefully. Real bugs and invariant violations should be allowed to throw so they surface instead of being hidden by blanket catch blocks.