Yii2 Adapter Laravel Package

Getting Started

Minimal Setup

1. Installation Add the package via Composer in your Craft 6 package:

   composer require craftcms/yii2-adapter
   

   Ensure your composer.json includes "craftcms/cms": "^6.0" as a dependency.

2. Namespace & Autoloading In your package’s composer.json, ensure the adapter is autoloaded:

   "autoload": {
       "psr-4": {
           "your\\Package\\": "src/",
           "craftcms\\yii2-adapter\\": "vendor/craftcms/yii2-adapter/src/"
       }
   }
   

3. First Use Case: Yii 2 Components in Craft 6 Use the adapter to integrate Yii 2 components (e.g., yii\base\Component, yii\db\Connection) into a Craft 6 package:

   use craftcms\yii2-adapter\BaseComponent;
   use yii\base\Component as YiiComponent;
   
   class MyCraftComponent extends BaseComponent {
       public function someYii2Method() {
           // Access Yii 2 features via the adapter
           return YiiComponent::t('app', 'Hello from Yii 2!');
       }
   }
   

4. Key Files to Reference

   • src/BaseComponent.php: Core adapter class for Yii 2 components.
   • src/DependencyTrait.php: For dependency injection patterns.
   • src/ServiceTrait.php: For service-based architectures.

Implementation Patterns

1. Component Integration

Workflow:

• Extend BaseComponent for Yii 2-style components in Craft 6.
• Override Yii 2 methods while leveraging Craft 6’s service container:

  use craftcms\yii2-adapter\BaseComponent;
  use yii\base\Event;
  
  class MyComponent extends BaseComponent {
      public function init() {
          parent::init();
          $this->on('someEvent', [$this, 'handleEvent']);
      }
  
      public function handleEvent(Event $event) {
          // Yii 2 event handling in Craft 6
      }
  }
  

2. Dependency Injection

Pattern: Use DependencyTrait to resolve Yii 2 dependencies via Craft’s container:

use craftcms\yii2-adapter\DependencyTrait;

class MyService {
    use DependencyTrait;

    public function __construct() {
        $this->setDependencies([
            'db' => ['class' => \yii\db\Connection::class],
            'logger' => ['class' => \yii\log\Logger::class],
        ]);
    }
}

3. Database Integration

Tip: Wrap Yii 2’s DbConnection in the adapter to work with Craft’s Db service:

use craftcms\yii2-adapter\DbAdapter;

class MyDbService extends DbAdapter {
    public function getCraftDb() {
        return \Craft::$app->getDb();
    }
}

4. Event-Driven Architecture

Integration: Bridge Yii 2 events to Craft 6’s event system:

use yii\base\Event;
use craft\events\RegisterComponentTypesEvent;

class MyPlugin extends \craft\base\Plugin {
    public function init() {
        parent::init();
        Event::on(
            RegisterComponentTypesEvent::class,
            RegisterComponentTypesEvent::EVENT_NAME,
            [$this, 'registerComponents']
        );
    }

    public function registerComponents(RegisterComponentTypesEvent $event) {
        $event->componentTypes[] = MyComponent::class;
    }
}

5. Configuration Management

Pattern: Use Yii 2’s Config with Craft’s config system:

use yii\base\Configurable;

class MyConfigurableComponent extends BaseComponent implements Configurable {
    public $someSetting = 'default';

    public function init() {
        parent::init();
        $this->configure(\Craft::$app->getConfig()->getConfigFromFile('my-plugin'));
    }
}

Gotchas and Tips

Pitfalls

1. Namespace Collisions

   • Yii 2’s yii\base\* classes may conflict with Craft’s namespaces. Prefix or alias where needed:

     use yii\base\Component as YiiComponent;
     

2. Circular Dependencies

   • Avoid circular references between Yii 2 components and Craft services. Use lazy loading or interfaces:

     interface DbInterface {
         public function getConnection();
     }
     

3. Event System Quirks

   • Yii 2’s Event class differs from Craft’s Event. Ensure proper type-hinting:

     // Yii 2 style
     public function handleEvent(\yii\base\Event $event) { ... }
     
     // Craft 6 style
     public function handleEvent(\craft\events\SomeEvent $event) { ... }
     

4. Configuration Overrides

   • Craft’s config system may override Yii 2 defaults. Explicitly merge configs:

     $config = array_merge(
         require(__DIR__ . '/config.php'),
         \Craft::$app->getConfig()->get('my-plugin', [])
     );
     

Debugging Tips

1. Dependency Resolution

   • Use var_dump($this->getDependency('db')) to debug unresolved dependencies.

2. Event Listeners

   • Verify event attachments with:

     \Yii::debug('Listeners: ' . print_r(\yii\base\Event::getHandlers('someEvent'), true));
     

3. Database Queries

   • Log raw SQL via Yii 2’s logger:

     \Yii::debug('SQL: ' . $connection->getLogger()->logs[0]['message']);
     

Extension Points

1. Custom Adapters

   • Extend BaseComponent for domain-specific adapters:

     class CraftDbAdapter extends BaseComponent {
         public function craftQuery() {
             return \Craft::$app->getDb()->createCommand('SELECT * FROM ...');
         }
     }
     

2. Plugin-Specific Config

   • Override Yii 2 configs via Craft’s config.php:

     return [
         'components' => [
             'myComponent' => [
                 'class' => MyComponent::class,
                 'someSetting' => 'value',
             ],
         ],
     ];
     

3. Testing

   • Mock Yii 2 dependencies in PHPUnit:

     $this->mockApplicationComponents([
         'db' => $this->createMock(\yii\db\Connection::class),
     ]);