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';)
fusengine