SOLID PHP - Laravel 13 + PHP 8.3
Agent Workflow (MANDATORY)
Before ANY implementation, use TeamCreate to spawn 3 agents:
- 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
Templates
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';)
