framework-integration

name

framework-integration

description

Use this skill when applying clean-architecture, DDD, or hexagonal patterns inside a specific PHP framework. Provides framework-specific port mapping, adapter patterns, and pitfalls to avoid for Laravel, Symfony, Slim, CakePHP, CodeIgniter, Yii, Laminas, Mezzio, Zend Framework, and legacy/maintenance-mode frameworks. Triggers when a framework is named or when clean-architecture principles need framework-specific wiring guidance.

Framework Integration for Clean Architecture & DDD

This skill assumes familiarity with the framework-agnostic skills (domain-modeling, application-layer, infrastructure-boundaries, etc.). It provides framework-specific mappings for ports, adapters, DI wiring, and common anti-patterns.

Note that not every feature needs full DDD wiring. The domain-modeling skill defines lighter defaults — a Transaction Script (one procedure per request) or a Table Module (one class per table operating on a recordset) — for simple or data-centric features. This skill still applies to those patterns: keep the framework controller thin and delegate to the script/module, and keep the framework ORM in an adapter rather than treating it as the domain. Reach for the full DDD port/adapter wiring below only when the feature's rules justify it.

When to Apply This Guidance

Use this skill when the project already decided which framework to use and needs to apply clean architecture patterns within that framework. Do not use it to choose a framework.

Available References

Category	Framework	Reference File
Modern	Laravel	references/laravel.md
Modern	Symfony	references/symfony.md
Modern	Slim	references/slim.md
Modern	CakePHP 5.x	references/cakephp-5.md
Modern	CodeIgniter 4	references/codeigniter-4.md
Modern	Yii 3	references/yii-3.md
Modern	Laminas	references/laminas.md
Modern	Mezzio	references/mezzio.md
Legacy	Zend Framework 1	references/zend-framework-1.md
Legacy	Zend Framework 2	references/zend-framework-2.md
Legacy	CakePHP 2.x	references/cakephp-2.md
Legacy	CakePHP 3.x/4.x	references/cakephp-3-4.md
Legacy	Yii 1.1	references/yii-1.md
Legacy	Yii 2	references/yii-2.md
Legacy	CodeIgniter 3	references/codeigniter-3.md

Read the relevant reference file for framework-specific anti-patterns and guidance. The mapping table below applies across all frameworks.

Port-to-Framework Mapping

Concept	Laravel	Symfony	Slim	CakePHP 3.x/4.x	CakePHP 5.x	CodeIgniter 4	Yii 2	Yii 3	Laminas	Mezzio
Driver Entry	Route -> Controller -> Handler	Controller -> Handler	Route -> Callable -> Handler	Controller/Table -> Handler	Controller/Command -> Handler	Controller -> Handler	Controller -> Handler	Route -> Handler	Controller -> Handler	Middleware -> Handler
Repository Port	Interface in domain/	Interface in domain/	Interface in domain/	Interface in domain/	Interface in domain/	Interface in domain/	Interface in domain/	Interface in domain/	Interface in domain/	Interface in domain/
Repository Adapter	Eloquent in infrastructure/persistence	Doctrine in infrastructure/persistence	PDO/ORM in infrastructure/persistence	Table in infrastructure/persistence	Table in infrastructure/persistence	Model in infrastructure/persistence	ActiveRecord in infrastructure/persistence	ActiveRecord in infrastructure/persistence	TableGateway in infrastructure/persistence	Laminas Db in infrastructure/persistence
DI Composition Root	AppServiceProvider / singleton()	services.yaml / config/services.php	Custom factory or foreach bind	src/Application.php or bootstrap.php	src/Application.php or bootstrap.php	Config/App.php / Controllers	config/web.php / DI container	config/container.php	Module config + DI	config/autoload/dependencies.config.php
Event Bus	Laravel Events (native)	Symfony EventDispatcher	Third-party (e.g., opis/event)	CakePHP EventManager	CakePHP EventManager	Events class (manual)	Yii Event / yii2-event	Yii 3 Event	Laminas EventManager	Laminas EventManager
Domain Dispatcher	Event::dispatch in handler	Publish via EventDispatcher	Manual dispatch	EventManager->dispatch	EventManager->dispatch	Manual publish	Publish via event class	Publish via event class	Publish via EventManager	Publish via EventManager

Boundaries

Always Do

• Always keep framework-specific objects (Request, Eloquent Model, AR Entity, Table) in driver/driven adapters.
• Always register adapter-to-port bindings in a single composition root.
• Always write domain logic in plain PHP classes with zero framework dependencies.
• Always convert framework request/response objects to domain-neutral DTOs at the boundary.

Ask First

• Ask before using a framework's built-in "magic" (Facades, Service Locators, Gii, Behaviors) in a new codebase. Is there a cleaner explicit alternative?
• Ask before deciding to fight the framework's conventions if the project is small and short-lived. Sometimes the convention is the right trade-off. For simple or data-centric features, prefer a Transaction Script or Table Module over either full DDD wiring or dumping logic in the controller.

Never Do

• Never import framework base classes, facades, or static service locators into domain or application code.
• Never use framework-specific exceptions or response objects as return types from handlers.
• Never treat a framework's default persistence model (Eloquent AR, Doctrine, Cake Table) as your aggregate root. It is an adapter, not the domain.
• Never assume that "the framework does it" is a reason to skip clean-architecture boundaries in a complex, long-lived application.
• Never put business logic directly in a framework controller, even for lighter patterns. Delegate to a Transaction Script or Table Module and keep the controller as a thin adapter.

For the web/HTTP layer specifically — how the framework "controller" maps onto Action-Domain-Responder, and how to extract a true Responder that owns the whole HTTP response — see the action-domain-responder skill and its adr-by-framework.md guide.