/solid-php

name: solid-php
description: Use when applying SOLID principles to Laravel 13 / PHP 8.3+ code — file size limits, interface placement, or PHPDoc enforcement.
versions:
  laravel: "13.0"
  php: "8.3"
user-invocable: true
references: 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.md
related-skills: laravel-architecture, fusecore

<objective> Enforces SOLID principles and DRY on Laravel 13 + PHP 8.3+ code: files within the hook ceiling `FUSE_SOLID_MAX_LINES`, interfaces separated into FuseCore/[Module]/App/Contracts/ (or FuseCore/Core/App/Contracts/ for shared ones), and mandatory PHPDoc on all public methods. Auto-detects Laravel vs FuseCore modular architecture and routes code placement accordingly (Controllers/Requests/Actions/Services/Repositories/DTOs/Contracts/Events/ Policies), with anti-pattern detection (fat classes, business logic in models, concrete dependencies, missing strict_types) and refactoring guidance per SOLID principle (SRP/OCP/LSP/ISP/DIP). </objective>

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`:

1. **fuse-ai-pilot:explore-codebase** - Analyze existing architecture 2. **fuse-ai-pilot:research-expert** - Verify Laravel/PHP docs via Context7 3. **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:** 1. **Grep the codebase** for similar class names, methods, or logic 2. Check shared locations: `FuseCore/Core/App/Services/`, `FuseCore/Core/App/Traits/`, `FuseCore/[Module]/App/Contracts/` 3. If similar code exists → extend/reuse instead of duplicate 4. If code will be used by 2+ features → create it in shared Services or Traits 5. Extract repeated logic (3+ occurrences) into shared helpers or Traits 6. 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 | |------|---------|----------| | HTTP handling | Controller | Controllers/ | | Validation | FormRequest | Requests/ | | Single operation | Action | Actions/ | | Complex logic | Service | Services/ | | Data access | Repository | Repositories/ | | Data structure | DTO | DTOs/ | | Abstraction | Interface | Contracts/ |

---

Critical Rules (MANDATORY)

1. Files within `FUSE_SOLID_MAX_LINES`

• **Split well before the hook ceiling** - never work around it
• Controllers: HTTP concerns only
• Models: relations + casts only
• Services: business logic only

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](references/solid-principles.md) | Quick reference all principles | | **SRP** | [single-responsibility.md](references/single-responsibility.md) | File too long, fat controller/model | | **OCP** | [open-closed.md](references/open-closed.md) | Adding payment methods, channels | | **LSP** | [liskov-substitution.md](references/liskov-substitution.md) | Interface contracts, swapping providers | | **ISP** | [interface-segregation.md](references/interface-segregation.md) | Fat interfaces, unused methods | | **DIP** | [dependency-inversion.md](references/dependency-inversion.md) | Tight coupling, testing, mocking | | **Anti-Patterns** | [anti-patterns.md](references/anti-patterns.md) | Code smells detection | | **Decisions** | [decision-guide.md](references/decision-guide.md) | Pattern selection | | **PHP 8.5** | [php85-features.md](references/php85-features.md) | Modern PHP features | | **Structure** | [laravel12-structure.md](references/laravel12-structure.md) | Standard Laravel | | **FuseCore** | [fusecore-structure.md](references/fusecore-structure.md) | Modular architecture |

Templates

| Template | When to use | |----------|-------------| | [code-templates.md](references/templates/code-templates.md) | Service, DTO, Repository, Interface | | [controller-templates.md](references/templates/controller-templates.md)