SOLID PHP - Laravel 13 + PHP 8.3
Agent Workflow (MANDATORY)
Before ANY implementation, spawn 3 agents in parallel, one Agent call each with a name:
- fuse-ai-pilot:explore-codebase - Analyze existing architecture
- fuse-ai-pilot:research-expert - Verify Laravel/PHP docs via Context7
- mcp__context7__query-docs - Check SOLID patterns
After implementation, run fuse-ai-pilot:sniper for validation.
DRY - Reuse Before Creating (MANDATORY)
Before writing ANY new code:
- Grep the codebase for similar class names, methods, or logic
- Check shared locations:
FuseCore/Core/App/Services/, FuseCore/Core/App/Traits/, FuseCore/[Module]/App/Contracts/
- If similar code exists → extend/reuse instead of duplicate
- If code will be used by 2+ features → create it in shared Services or Traits
- Extract repeated logic (3+ occurrences) into shared helpers or Traits
- Verify no duplication introduced after writing
Auto-Detection (Modular MANDATORY)
| Files Detected |
Architecture |
Interfaces Location |
FuseCore/ directory |
FuseCore Modular |
FuseCore/[Module]/App/Contracts/ |
module.json in modules |
FuseCore Modular |
FuseCore/[Module]/App/Contracts/ |
Verification: php artisan --version → Laravel 13.x
Structure: Always FuseCore modular. Shared in FuseCore/Core/App/.
Decision Tree: Where to Put Code? (FuseCore Modular)
New code needed?
├── HTTP validation → FuseCore/[Module]/App/Http/Requests/
├── Single action → FuseCore/[Module]/App/Actions/
├── Business logic → FuseCore/[Module]/App/Services/
├── Data access → FuseCore/[Module]/App/Repositories/
├── Data transfer → FuseCore/[Module]/App/DTOs/
├── Interface → FuseCore/[Module]/App/Contracts/
├── Event → FuseCore/[Module]/App/Events/
└── Authorization → FuseCore/[Module]/App/Policies/
Decision Tree: Which Pattern?
| Need |
Pattern |
Location |
Max Lines |
| HTTP handling |
Controller |
Controllers/ |
50 |
| Validation |
FormRequest |
Requests/ |
50 |
| Single operation |
Action |
Actions/ |
50 |
| Complex logic |
Service |
Services/ |
100 |
| Data access |
Repository |
Repositories/ |
100 |
| Data structure |
DTO |
DTOs/ |
50 |
| Abstraction |
Interface |
Contracts/ |
30 |
Critical Rules (MANDATORY)
1. Files < 100 lines
- Split at 90 lines - Never exceed 100
- Controllers < 50 lines
- Models < 80 lines (excluding relations)
- Services < 100 lines
2. Interfaces Separated (FuseCore Modular MANDATORY)
FuseCore/[Module]/App/Contracts/ # Module interfaces ONLY
├── UserRepositoryInterface.php
└── PaymentGatewayInterface.php
FuseCore/Core/App/Contracts/ # Shared interfaces
3. PHPDoc Mandatory
/**
* Create a new user from DTO.
*
* @param CreateUserDTO $dto User data transfer object
* @return User Created user model
* @throws ValidationException If email already exists
*/
public function create(CreateUserDTO $dto): User
Reference Guide
Concepts
| Topic |
Reference |
When to consult |
| SOLID Overview |
solid-principles.md |
Quick reference all principles |
| SRP |
single-responsibility.md |
File too long, fat controller/model |
| OCP |
open-closed.md |
Adding payment methods, channels |
| LSP |
liskov-substitution.md |
Interface contracts, swapping providers |
| ISP |
interface-segregation.md |
Fat interfaces, unused methods |
| DIP |
dependency-inversion.md |
Tight coupling, testing, mocking |
| Anti-Patterns |
anti-patterns.md |
Code smells detection |
| Decisions |
decision-guide.md |
Pattern selection |
| PHP 8.5 |
php85-features.md |
Modern PHP features |
| Structure |
laravel12-structure.md |
Standard Laravel |
| FuseCore |
fusecore-structure.md |
Modular architecture |
Templates
| Template |
When to use |
| code-templates.md |
Service, DTO, Repository, Interface |
| controller-templates.md |
Controller, Action, FormRequest, Policy |
| refactoring-guide.md |
Step-by-step migration from legacy code |
Forbidden
| Anti-Pattern |
Detection |
Fix |
| Files > 100 lines |
Line count |
Split into smaller files |
| Controllers > 50 lines |
Line count |
Extract to Service |
| Interfaces in impl files |
Location |
Move to FuseCore/[Module]/App/Contracts/ |
| Business logic in Models |
Code in model |
Extract to Service |
| Concrete dependencies |
new Class() |
Inject via ModuleServiceProvider |
| Missing PHPDoc |
No doc block |
Add documentation |
| Missing strict_types |
No declare |
Add to all files |
| Fat classes |
> 5 public methods |
Split responsibilities |
| Duplicated logic |
Same code in 2+ files |
Extract to Service/Trait |
| No Grep before coding |
Creating without search |
Grep codebase first |
Best Practices
| DO |
DON'T |
| Use constructor property promotion |
Use property assignment |
| Depend on interfaces |
Depend on concrete classes |
Use final readonly class |
Use mutable classes |
Use declare(strict_types=1) |
Skip type declarations |
| Split at 90 lines |
Wait until 100 lines |
| Use DTOs for data transfer |
Use arrays |
Laravel 13 Notes
PHP 8.3 minimum
Laravel 13 exige PHP 8.3 (était 8.2 sur L12). Fonctionnalités SOLID-friendly :
readonly classes : final readonly class UserDto (immutabilité totale)
- Typed class constants :
const int MAX_RETRIES = 3;
#[\Override] attribute : déclare explicitement une override de méthode parente (catch typos)
json_validate() natif (plus rapide que json_decode + try/catch)
- Dynamic class constant fetch :
$class::{$name}
use Override;
final readonly class PaymentService implements PaymentContract
{
public const int DEFAULT_TIMEOUT = 30;
public function __construct(
private StripeClient $stripe,
private LoggerInterface $logger,
) {}
#[Override]
public function process(PaymentDto $payment): PaymentResult
{
// ...
}
}
Règles SOLID renforcées L13
- Préférer
final readonly class pour tous les DTO/Value Objects
- Utiliser
#[\Override] sur toute méthode héritée (CI catch)
- Typer les constantes (
const string ROLE = 'admin';)
1---2name: solid-php3description: Use when applying SOLID principles to Laravel 13 / PHP 8.3+ code — file size limits, interface placement, or PHPDoc enforcement.4versions:5 laravel: "13.0"6 php: "8.3"7user-invocable: true8references: references/solid-principles.md, references/single-responsibility.md, references/open-closed.md, references/liskov-substitution.md, references/interface-segregation.md, references/dependency-inversion.md, references/anti-patterns.md, references/decision-guide.md, references/php85-features.md, references/laravel12-structure.md, references/fusecore-structure.md, references/templates/code-templates.md, references/templates/controller-templates.md, references/templates/refactoring-guide.md9related-skills: laravel-architecture, fusecore10metadata:11 source: https://skillmd.com/skills/fusengine/solid-php12---1314<objective>15Enforces SOLID principles and DRY on Laravel 13 + PHP 8.3+ code: files under16100 lines (split at 90), interfaces separated into17FuseCore/[Module]/App/Contracts/ (or FuseCore/Core/App/Contracts/ for shared18ones), and mandatory PHPDoc on all public methods. Auto-detects Laravel vs19FuseCore modular architecture and routes code placement accordingly20(Controllers/Requests/Actions/Services/Repositories/DTOs/Contracts/Events/21Policies), with anti-pattern detection (fat classes, business logic in22models, concrete dependencies, missing strict_types) and refactoring23guidance per SOLID principle (SRP/OCP/LSP/ISP/DIP).24</objective>2526# SOLID PHP - Laravel 13 + PHP 8.32728## Agent Workflow (MANDATORY)2930Before ANY implementation, spawn 3 agents in parallel, one `Agent` call each with a `name`:31321. **fuse-ai-pilot:explore-codebase** - Analyze existing architecture332. **fuse-ai-pilot:research-expert** - Verify Laravel/PHP docs via Context7343. **mcp__context7__query-docs** - Check SOLID patterns3536After implementation, run **fuse-ai-pilot:sniper** for validation.3738---3940## DRY - Reuse Before Creating (MANDATORY)4142**Before writing ANY new code:**431. **Grep the codebase** for similar class names, methods, or logic442. Check shared locations: `FuseCore/Core/App/Services/`, `FuseCore/Core/App/Traits/`, `FuseCore/[Module]/App/Contracts/`453. If similar code exists → extend/reuse instead of duplicate464. If code will be used by 2+ features → create it in shared Services or Traits475. Extract repeated logic (3+ occurrences) into shared helpers or Traits486. Verify no duplication introduced after writing4950---5152## Auto-Detection (Modular MANDATORY)5354| Files Detected | Architecture | Interfaces Location |55|----------------|--------------|---------------------|56| `FuseCore/` directory | FuseCore Modular | `FuseCore/[Module]/App/Contracts/` |57| `module.json` in modules | FuseCore Modular | `FuseCore/[Module]/App/Contracts/` |5859**Verification**: `php artisan --version` → Laravel 13.x60**Structure**: Always FuseCore modular. Shared in `FuseCore/Core/App/`.6162---6364## Decision Tree: Where to Put Code? (FuseCore Modular)6566```67New code needed?68├── HTTP validation → FuseCore/[Module]/App/Http/Requests/69├── Single action → FuseCore/[Module]/App/Actions/70├── Business logic → FuseCore/[Module]/App/Services/71├── Data access → FuseCore/[Module]/App/Repositories/72├── Data transfer → FuseCore/[Module]/App/DTOs/73├── Interface → FuseCore/[Module]/App/Contracts/74├── Event → FuseCore/[Module]/App/Events/75└── Authorization → FuseCore/[Module]/App/Policies/76```7778---7980## Decision Tree: Which Pattern?8182| Need | Pattern | Location | Max Lines |83|------|---------|----------|-----------|84| HTTP handling | Controller | Controllers/ | 50 |85| Validation | FormRequest | Requests/ | 50 |86| Single operation | Action | Actions/ | 50 |87| Complex logic | Service | Services/ | 100 |88| Data access | Repository | Repositories/ | 100 |89| Data structure | DTO | DTOs/ | 50 |90| Abstraction | Interface | Contracts/ | 30 |9192---9394## Critical Rules (MANDATORY)9596### 1. Files < 100 lines97- **Split at 90 lines** - Never exceed 10098- Controllers < 50 lines99- Models < 80 lines (excluding relations)100- Services < 100 lines101102### 2. Interfaces Separated (FuseCore Modular MANDATORY)103```104FuseCore/[Module]/App/Contracts/ # Module interfaces ONLY105├── UserRepositoryInterface.php106└── PaymentGatewayInterface.php107FuseCore/Core/App/Contracts/ # Shared interfaces108```109110### 3. PHPDoc Mandatory111```php112/**113 * Create a new user from DTO.114 *115 * @param CreateUserDTO $dto User data transfer object116 * @return User Created user model117 * @throws ValidationException If email already exists118 */119public function create(CreateUserDTO $dto): User120```121122---123124## Reference Guide125126### Concepts127128| Topic | Reference | When to consult |129|-------|-----------|-----------------|130| **SOLID Overview** | [solid-principles.md](references/solid-principles.md) | Quick reference all principles |131| **SRP** | [single-responsibility.md](references/single-responsibility.md) | File too long, fat controller/model |132| **OCP** | [open-closed.md](references/open-closed.md) | Adding payment methods, channels |133| **LSP** | [liskov-substitution.md](references/liskov-substitution.md) | Interface contracts, swapping providers |134| **ISP** | [interface-segregation.md](references/interface-segregation.md) | Fat interfaces, unused methods |135| **DIP** | [dependency-inversion.md](references/dependency-inversion.md) | Tight coupling, testing, mocking |136| **Anti-Patterns** | [anti-patterns.md](references/anti-patterns.md) | Code smells detection |137| **Decisions** | [decision-guide.md](references/decision-guide.md) | Pattern selection |138| **PHP 8.5** | [php85-features.md](references/php85-features.md) | Modern PHP features |139| **Structure** | [laravel12-structure.md](references/laravel12-structure.md) | Standard Laravel |140| **FuseCore** | [fusecore-structure.md](references/fusecore-structure.md) | Modular architecture |141142### Templates143144| Template | When to use |145|----------|-------------|146| [code-templates.md](references/templates/code-templates.md) | Service, DTO, Repository, Interface |147| [controller-templates.md](references/templates/controller-templates.md) | Controller, Action, FormRequest, Policy |148| [refactoring-guide.md](references/templates/refactoring-guide.md) | Step-by-step migration from legacy code |149150---151152## Forbidden153154| Anti-Pattern | Detection | Fix |155|--------------|-----------|-----|156| Files > 100 lines | Line count | Split into smaller files |157| Controllers > 50 lines | Line count | Extract to Service |158| Interfaces in impl files | Location | Move to `FuseCore/[Module]/App/Contracts/` |159| Business logic in Models | Code in model | Extract to Service |160| Concrete dependencies | `new Class()` | Inject via ModuleServiceProvider |161| Missing PHPDoc | No doc block | Add documentation |162| Missing strict_types | No declare | Add to all files |163| Fat classes | > 5 public methods | Split responsibilities |164| Duplicated logic | Same code in 2+ files | Extract to Service/Trait |165| No Grep before coding | Creating without search | Grep codebase first |166167---168169## Best Practices170171| DO | DON'T |172|----|-------|173| Use constructor property promotion | Use property assignment |174| Depend on interfaces | Depend on concrete classes |175| Use `final readonly class` | Use mutable classes |176| Use `declare(strict_types=1)` | Skip type declarations |177| Split at 90 lines | Wait until 100 lines |178| Use DTOs for data transfer | Use arrays |179180---181182## Laravel 13 Notes183184### PHP 8.3 minimum185Laravel 13 exige PHP 8.3 (était 8.2 sur L12). Fonctionnalités SOLID-friendly :186187- **`readonly` classes** : `final readonly class UserDto` (immutabilité totale)188- **Typed class constants** : `const int MAX_RETRIES = 3;`189- **`#[\Override]` attribute** : déclare explicitement une override de méthode parente (catch typos)190- **`json_validate()`** natif (plus rapide que `json_decode` + try/catch)191- **Dynamic class constant fetch** : `$class::{$name}`192193```php194use Override;195196final readonly class PaymentService implements PaymentContract197{198 public const int DEFAULT_TIMEOUT = 30;199200 public function __construct(201 private StripeClient $stripe,202 private LoggerInterface $logger,203 ) {}204205 #[Override]206 public function process(PaymentDto $payment): PaymentResult207 {208 // ...209 }210}211```212213### Règles SOLID renforcées L13214- Préférer `final readonly class` pour tous les DTO/Value Objects215- Utiliser `#[\Override]` sur toute méthode héritée (CI catch)216- Typer les constantes (`const string ROLE = 'admin';`)