fusengine SOLID PHP - Laravel 12 + PHP 8.5
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 12.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 |