Getting Started

yii2tech/illuminate is a bridge that lets a Yii2 application use Laravel's standalone Illuminate components (query builder, validation, events, queue, pagination, PSR-3 logging) without abandoning the Yii2 framework. It is not a Yii-to-Laravel converter — think of it as a "Laravel components inside Yii" toolbox, useful when you want to migrate incrementally or reuse Laravel libraries in a Yii2 codebase.

Minimal setup:

composer require yii2tech/illuminate

return [
    'components' => [
        'illuminateDb' => [
            'class' => yii2tech\illuminate\Db::class,
            'dsn'       => 'mysql:host=localhost;dbname=app',
            'username'  => 'app',
            'password'  => 'secret',
            'charset'   => 'utf8mb4',
        ],
        'illuminateEvent' => [
            'class' => yii2tech\illuminate\EventDispatcher::class,
        ],
        'illuminateLog' => [
            'class' => yii2tech\illuminate\Log::class,
            'logger' => /* PSR-3 logger */,
        ],
    ],
];

Where to look first:

README.md at the repo root — it enumerates each component and shows the wrapper class for each Illuminate subsystem.
src/ — each wrapper is small; read the target class before using it, because the wrapper mostly delegates to Illuminate and the delegation rules matter.
tests/ — the most reliable spec for how the wrappers are meant to be composed.

First use case: run a Laravel-style query builder query from a Yii2 controller after configuring illuminateDb:

$rows = Yii::$app->illuminateDb->table('user')
    ->where('status', 'active')
    ->limit(10)
    ->get();

Once that works, you have a validated path for adopting the rest (validation, events, queue) one component at a time.

Implementation Patterns

Incremental adoption, not big-bang migration. The realistic pattern is: pick one Illuminate subsystem, wrap it, and leave the rest of the app alone. Typical order is query builder → validation → events → queue/logging. Mixing Yii2 ActiveRecord and Illuminate query builder in the same codebase is expected, but keep each write path in one style to avoid transactional confusion.

Query builder alongside Yii AR. Use the Illuminate connection for read-heavy reporting or new modules while existing Yii2 AR models stay untouched. This works well when a new feature needs fluent builder ergonomics that Yii's query builder doesn't offer.

$latest = Yii::$app->illuminateDb->table('order')
    ->join('user', 'user.id', '=', 'order.user_id')
    ->select('user.email', Yii::$app->illuminateDb->raw('COUNT(*) AS c'))
    ->groupBy('user.email')
    ->orderByDesc('c')
    ->limit(20)
    ->get();

Active Record variant. The package ships an AR base that sits on top of Illuminate's connection. Use it when a new model needs Illuminate's semantics (e.g., chunkById, builder reuse) but you still want Yii2-style model classes. Do not retrofit it onto legacy Yii models with behaviors and relations — those assume the native Yii connection.

Event bridging. EventDispatcher lets Yii2 events be visible to Illuminate listeners and vice-versa. The useful pattern is: keep Yii2's on()/trigger() for framework events and use the Illumimate dispatcher as the bus for domain events that new modules and queued jobs need. Register a single bridge in the bootstrap rather than scattering Event::listen calls.

Validation. Use the Illuminate validator inside Yii2 controllers or form models for request payload validation when you need rule strings and message bags that match Laravel semantics (e.g., API endpoints that will later move to Laravel). Keep Yii2 Model::rules() for models that must stay portable.

$v = Yii::$app->illuminateValidation->make($request->post(), [
    'email'    => 'required|email',
    'password' => 'required|min:8',
]);
if ($v->fails()) { /* ... */ }

Queue jobs. Wrap Illuminate queue jobs for background work that already exists as Laravel-style jobs. Treat the queue component as the integration point and don't mix Yii's queue component on the same table — pick one.

Console commands. The package offers an artisan-like command base for Yii2. Good uses: scheduled maintenance tasks written in Laravel style that must run inside a Yii2 console app.

Gotchas and Tips

Two containers, two lives. Yii's DI container and Illuminate's container are independent. Do not expect Yii Yii::$container bindings to resolve inside Illuminate-managed objects, or vice-versa. Explicitly pass dependencies.
Duplicate DB configuration is a footgun. illuminateDb and the native Yii db component will each hold their own connection. Pointing them at the same database is fine for reads, but concurrent writes across the two connections can deadlock. Prefer one write path per table.
Transactions don't span connections. Yii::$app->db->beginTransaction() does not wrap the Illuminate connection. If you mix them in one logical operation, do it in one component or use two-phase-style compensation. This is the most common bug in mixed codebases.
Illumiate version pinning. The package targets a specific illuminate/* range. If you add another Laravel package that pulls in a newer illuminate/database, composer will resolve to a version this wrapper wasn't tested against. Check composer.json in the repo and align versions before adding more Laravel dependencies.
ActiveRecord wrapper is not a drop-in. Relations, behaviors, with(), and via() assume the Yii2 connection. If you subclass the Illuminate-backed AR, expect to reimplement or avoid those features. Test relation-heavy models before trusting them.
Event bridge ordering. Yii2 events and Illuminate events have different propagation semantics (Yii allows $event->handled = true short-circuiting; Illuminate does not). Bridge handlers in a defined order and don't rely on stopPropagation() behavior crossing the bridge.
Logging context differs. The PSR-3 log target's context keys are not Yii2's trace_level/category; when you switch a log target from FileTarget to the PSR-3 bridge, your log-parsing dashboards may break. Keep category logging on Yii targets and add the PSR-3 target alongside.
License and maintenance risk. License: NOASSERTION means the repo's license field isn't machine-detected — read LICENSE in the repo before shipping. At 115 stars with a low activity footprint, vet whether it's maintained for your Yii2/PHP version. Prefer it for greenfield or tooling code where a future swap back to native Yii or forward to Laravel is cheap.
Debugging tip. When an Illuminate-side exception surfaces as an unhelpful Yii error, attach the illuminateLog component and enable SQL logging on illuminateDb; the wrapper often swallows context that Laravel would surface. Reproduce the failing call in a standalone Laravel Capsule\Manager script to isolate whether the bug is in the wrapper or in the underlying component.
Extension point. Nearly every wrapper accepts injected Illuminate objects (logger, dispatcher, connection). That's the supported customization seam — subclass the wrapper and override the constructor wiring rather than monkey-patching the Illuminate class.
Not a migration shortcut. If the end goal is Laravel, this package buys you a partial Laravel idiom inside Yii2 — it does not move controllers, routing, Blade, or middleware. Budget the actual migration separately; treat this as a compatibility layer, not a bridge to artisan.

Illuminate Laravel Package

Getting Started

Implementation Patterns

Gotchas and Tips