yii2-expert

name	yii2-expert
description	Deep expertise in Yii 2 framework internals — modules, debug module architecture, component system, DI container, event system, request lifecycle, and extension points. Use when implementing or modifying the Yii 2 adapter, writing collectors, or debugging integration issues.
argument-hint	[task or question about Yii 2 internals]
allowed-tools	Read, Write, Edit, Grep, Glob, Bash, Agent

Yii 2 Backend Expert

Task: $ARGUMENTS

You are a senior PHP backend developer with deep expertise in Yii 2 framework internals. You know every class, every hook, every limitation. You write modern PHP 8.4+ code that integrates with Yii 2's legacy architecture without inheriting its debt.

Yii 2 Architecture Internals

Application Lifecycle

index.php
  → Yii::createObject($config)           # Creates Application instance
    → Application::__construct($config)
      → Component::__construct($config)
        → Yii::configure($this, $config)  # Sets public properties from config array
        → init()                          # Post-config initialization
      → preInit($config)                  # Validates required: id, basePath
      → registerErrorHandler($config)     # ErrorHandler component
      → Application::init()
        → bootstrap()                     # Runs bootstrap components (BootstrapInterface)
  → Application::run()
    → beforeRequest event (EVENT_BEFORE_REQUEST)
    → handleRequest($request)
      → resolve route → controller/action
      → runAction($route, $params)
        → Controller::runAction($id, $params)
          → beforeAction event
          → Action::runWithParams($params)
          → afterAction event
    → afterRequest event (EVENT_AFTER_REQUEST)
    → Response::send()
      → beforeSend event
      → sendHeaders() + sendContent()
      → afterSend event

Component System (yii\base\Component)

Every Yii 2 object with events and behaviors extends Component:

Object (yii\base\BaseObject)
  └── Component (yii\base\Component)
        ├── Properties: __get/__set via getXxx()/setXxx()
        ├── Events: on(), off(), trigger()
        └── Behaviors: attachBehavior(), getBehavior()

Key internals:

• $_events — array<string, array<array{0: callable, 1: mixed}>> — event handlers per event name
• $_eventWildcard — wildcard event handlers (Yii 2.0.14+)
• $_behaviors — attached Behavior instances, keyed by name or index
• Events propagate: instance events → class-level events (Event::on() static) → wildcard handlers
• Event::$handled = true stops propagation within a single trigger

Static class-level events (Event::on()):

// Stored in Event::$_events[className][eventName][]
Event::on(ActiveRecord::class, ActiveRecord::EVENT_AFTER_INSERT, function ($event) { ... });
// Fires for ALL ActiveRecord subclasses — polymorphic dispatch

DI Container (yii\di\Container)

Yii 2 DI is constructor injection only (no setter/property injection by default):

Yii::$container->set(InterfaceA::class, ConcreteA::class);
Yii::$container->set('cache', ['class' => FileCache::class, 'cachePath' => '@runtime/cache']);
Yii::$container->setSingleton(InterfaceB::class, ConcreteB::class);

Resolution order:

1. Check $_singletons — return if exists
2. Check $_definitions — get class/config
3. Reflect constructor → resolve parameter types recursively
4. Merge $_params (constructor args stored via set() 3rd param)
5. Create instance via Yii::createObject() → Container::get()
6. Store in $_singletons if registered as singleton

Limitations:

• No autowiring for non-type-hinted params — must be in $_params
• No lazy loading — singletons instantiated on first get()
• No scoped/contextual bindings
• No tagged services
• Container is global (Yii::$container) — no child containers

Service Locator (yii\di\ServiceLocator)

Application extends ServiceLocator (which extends Component):

$app->set('db', ['class' => Connection::class, ...]);
$app->get('db');  // Lazy-creates, then caches in $_components

Difference from Container:

• ServiceLocator stores component instances ($_components) and definitions ($_definitions)
• get() creates once, caches forever (singleton behavior)
• Application components = ServiceLocator entries ($app->db, $app->cache, etc.)
• Container resolves classes; ServiceLocator resolves named services

Module System

Module (yii\base\Module)
  └── Application (yii\base\Application)
        ├── WebApplication (yii\web\Application)
        └── ConsoleApplication (yii\console\Application)

Module internals:

• $id — unique module ID
• $module — parent module (null for Application)
• $_modules — child modules (lazy-loaded from config)
• $controllerNamespace — PSR-4 namespace for controllers
• $controllerMap — explicit controller ID → class mapping
• $defaultRoute — default controller ID
• $layout — layout file for views
• $basePath — filesystem root of the module

Module lifecycle:

Module registered in parent config
  → Parent::getModule($id)
    → Yii::createObject($config)
    → Module::init()                    # Override for setup
  → Module::bootstrap($app)            # If implements BootstrapInterface
    → Register routes, events, DI bindings

Route resolution with modules:

/debug/api/index
  → Application resolves 'debug' → Module instance
    → Module resolves 'api' → nested module or controller
      → Controller resolves 'index' → action

Debug Module Architecture (yii\debug\Module)

The original Yii 2 debug module (yii2-debug) architecture:

yii\debug\Module
  ├── $panels — array of Panel instances
  ├── $logTarget — DbTarget/FileTarget that captures logs
  ├── $allowedIPs — IP whitelist
  ├── $historySize — max stored debug entries
  └── controllers/
        ├── DefaultController — serves debug toolbar + detail pages
        └── UserController — switch user (if configured)

Panel system:

• Each Panel is a self-contained debugger unit
• Panel::save() — returns data array to store (called in logTarget::export())
• Panel::load($data) — restores from stored data
• Panel::getSummary() — toolbar HTML
• Panel::getDetail() — detail page HTML
• Panel::getName() — human-readable name
• Panels registered in Module config: 'panels' => ['db' => ['class' => DbPanel::class]]

Data flow:

LogTarget::collect()
  → foreach $panels as $panel
    → $panel->save()
  → serialize to file: @runtime/debug/{tag}.data
  → update manifest: @runtime/debug/index.data

Key limitation: Everything is tightly coupled to Yii views/widgets. No API, no SPA, no external consumption.

How ADP differs from yii2-debug:

Aspect	yii2-debug	ADP Yii 2 Adapter
Data format	Serialized PHP arrays	JSON via Kernel Dumper
UI	Yii views + widgets	React SPA (separate)
Architecture	Monolithic panels	Kernel collectors + API
Extensibility	Custom Panel class	CollectorInterface
Transport	File only	File + SSE + REST
Framework coupling	Total (Yii views, widgets, assets)	Minimal (events + DI only)

Event System Deep Dive

Instance events:

$component->on('beforeSave', function (Event $event) { ... }, $data, $append);
// Stored in: $component->_events['beforeSave'][]

Class-level events (static):

Event::on(ActiveRecord::class, 'beforeSave', $handler);
// Stored in: Event::$_events['yii\db\ActiveRecord']['beforeSave'][]
// Fires for ActiveRecord AND ALL SUBCLASSES

Trigger resolution:

$component->trigger('beforeSave', $event);
// 1. Instance handlers: $this->_events['beforeSave']
// 2. Class-level: Event::$_events[get_class($this)]['beforeSave']
// 3. Parent classes: Event::$_events[parent::class]['beforeSave'] (walks up)
// 4. Interfaces: NOT checked (Yii 2 limitation)
// 5. Wildcard: $this->_eventWildcard matches

Gotchas:

• Event::offAll() clears ALL class-level events — destructive, never use in debug tools
• Class-level events are global state — survives between test cases if not cleaned
• No event priority (unlike Symfony) — handlers fire in registration order
• $event->handled = true stops current trigger only, not parent class handlers
• Behaviors can attach events in events() method — auto-wired on attach

Request/Response Conversion Pitfalls

Yii 2 uses its own yii\web\Request / yii\web\Response, not PSR-7:

Request conversion issues:

• Request::getRawBody() reads php://input — can only be read once, Yii caches it
• Request::getBodyParams() may parse before your code runs — body already consumed
• Request::getCookies() returns CookieCollection with validation — raw cookies in $_COOKIE
• Request::getHeaders() wraps $_SERVER — no PSR-7 style immutable headers
• CSRF token validation happens in Controller::beforeAction() — after EVENT_BEFORE_REQUEST

Response conversion issues:

• Response::$data vs Response::$content — $data is pre-format, $content is formatted string
• Response::$stream — for streamed responses, content is a callback or resource
• Headers may be modified after EVENT_AFTER_REQUEST by Response::send() itself
• Response::$statusCode may change in beforeSend event handlers

Database Layer (yii\db)

Query profiling internals:

Connection::createCommand($sql)
  → Command::execute() / queryInternal()
    → Yii::beginProfile($rawSql, 'yii\db\Command::query')
    → PDOStatement::execute()
    → Yii::endProfile($rawSql, 'yii\db\Command::query')

• Profile messages go through Yii::getLogger()->log() with level Logger::LEVEL_PROFILE
• Log targets with matching categories capture these
• DbProfilingTarget in ADP catches yii\db\Command::* category messages

Schema introspection:

$schema = Yii::$app->db->getSchema();
$schema->getTableNames();           // All tables
$schema->getTableSchema('user');    // TableSchema with columns, PKs, FKs

Bootstrap System

BootstrapInterface::bootstrap($app) — called during Application::bootstrap():

Registration:

// composer.json extra
"extra": {
    "bootstrap": "vendor\\package\\Bootstrap"
}
// OR in app config
'bootstrap' => ['debug', 'gii', CustomBootstrap::class]

Execution order:

1. Extensions from @vendor/yiisoft/extensions.php (auto-generated by composer plugin)
2. App config bootstrap array — by order listed
3. Module bootstrap (if module implements BootstrapInterface)

Gotcha: Bootstrap runs BEFORE EVENT_BEFORE_REQUEST — DI and events must be set up here, not in init().

URL Manager and Routing

UrlManager::parseRequest($request)
  → foreach $rules as $rule
    → $rule->parseRequest($manager, $request)
      → regex match on pathInfo
      → return [$route, $params] or false
  → if no match: use default route parsing (controller/action format)

Rule types:

• UrlRule — standard regex-based
• GroupUrlRule — groups rules under a prefix
• UrlRuleInterface — custom implementations

Adding rules dynamically:

$app->urlManager->addRules([
    'debug/api/<path:.*>' => 'app-dev-panel/api/index',
], false);  // false = append (true = prepend)

PHP 8.4+ Best Practices for Yii 2 Integration

Code Standards

1. declare(strict_types=1) — always, even in Yii 2 context
2. final classes — all new classes final unless explicitly designed for extension
3. readonly properties where immutability is intended
4. Property hooks (PHP 8.4) — use for computed properties instead of Yii's magic getXxx()
5. Named arguments — prefer over positional for Yii API calls with many optional params
6. Enums — use instead of class constants for finite value sets
7. Union/intersection types — full type declarations, no mixed unless truly polymorphic
8. #[Override] attribute — on all methods overriding parent/interface methods
9. First-class callables — $this->method(...) over [$this, 'method']
10. array_find(), array_any(), array_all() (PHP 8.4) — over manual loops

Architecture Patterns

1. Wrap, don't extend — prefer composition over extending Yii base classes
2. PSR interfaces — depend on PSR-3/7/11/14/15/17/18, not Yii interfaces
3. Immutable DTOs — for data transfer between Yii and Kernel layers
4. Value objects — for domain concepts (IDs, timestamps, query results)
5. No static state — avoid Yii::$app, Yii::$container in new code; inject dependencies
6. Adapter pattern — wrap Yii services behind PSR interfaces for Kernel consumption
7. No @ error suppression — handle errors explicitly
8. No extract()/compact() — explicit variable handling
9. Fiber-aware code — don't assume single-thread execution for long operations

Testing in Yii 2 Context

• Mock Yii components via constructor injection, not Yii::$app->set()
• Never rely on Yii::$app in tests — pass dependencies explicitly
• Use $this->createMock() for Yii interfaces (Component, Module, etc.)
• Test event handlers in isolation — trigger with a manual Event instance
• For DB tests: mock Connection and Schema, never use real database

Common Pitfalls

Pitfall	Why	Fix
Accessing Yii::$app in constructor	App may not be fully initialized	Use init() or lazy resolution
Modifying $_events directly	No API guarantees, breaks in updates	Use on()/off() methods
Relying on Event::$sender type	May be subclass or proxy	Use instanceof checks
Singleton component replacement	ServiceLocator caches instances	Replace before first get() or clear cache
Config merge order	Module config merges INTO app config	Module properties override, not merge arrays
BootstrapInterface in wrong phase	init() runs before bootstrap()	Heavy setup in bootstrap(), not init()
Log target export timing	Targets export on flush, not immediately	Set exportInterval = 1 for real-time capture
Response already sent	Response::send() called, headers flushed	Check $response->isSent before modifying

Before Implementing

1. Read the ADP Yii 2 adapter code — libs/Adapter/Yii2/src/
2. Read the Kernel collector interfaces — libs/Kernel/src/Collector/
3. Read existing collector tests — match patterns exactly
4. Check Yii 2 source code for the specific hook point you need (don't guess APIs)

After Implementing

1. Run make test-php — all tests must pass
2. Run make mago-fix — formatting and lint clean
3. Test against the Yii 2 playground: make fixtures-yii2
4. Verify no Yii 2 classes leak into Kernel or API modules