Yii2 App Advanced Laravel Package

Getting Started

Minimal Steps to Begin

1. Installation Clone the template and set up dependencies:

   git clone https://github.com/yiisoft/yii2-app-advanced.git my-project
   cd my-project
   composer install --prefer-dist
   

2. Environment Setup

   • Copy .env.example to .env and configure database (DB_*), mail (MAIL_*), and security keys (APP_KEY, SECURITY_KEY).
   • Update common/config/main-local.php with local overrides (e.g., debug mode, logging).

3. First Use Case: Console Commands Run a built-in command (e.g., migrations):

   php yii migrate/up
   

   Key files to inspect:

   • console/config/main.php (console app config)
   • common/console/controllers/ (custom commands)

Implementation Patterns

Core Workflows

1. Modular Structure

   • Frontend/Backend Separation: Use frontend/ and backend/ for distinct user roles. Share logic via common/ (models, components).
   • Example: Extend common/models/User and reuse in both apps.

2. API Integration

   • RESTful API: Leverage api/ for headless services. Share models/components with common/.
   • Example: Extend api/controllers/v1/BaseController for auth middleware.

3. Asset Management

   • Bundles: Use yii\web\AssetBundle in frontend/web/assets/ for frontend assets.
   • Example:

     // frontend/views/site/index.php
     yii\web\JqueryAsset::register($this);
     

4. Database Migrations

   • Shared Migrations: Place in common/migrations/ for cross-app tables.
   • Workflow:

     php yii migrate/create --migrationPath=common/migrations --name=20230101_000000_create_users
     

Integration Tips

• Authentication: Use yii\filters\AccessControl in backend/config/main.php for role-based access.
• Logging: Configure common/config/main.php to log to runtime/logs/ (shared across apps).
• Testing: Use common/tests/ for unit tests; frontend/tests/ for integration tests.

Gotchas and Tips

Pitfalls

1. Environment Confusion

   • Issue: Forgetting to set YII_ENV=dev in .env causes production-like behavior locally.
   • Fix: Add to common/config/main.php:

     'components' => [
         'request' => [
             'cookieValidationKey' => YII_ENV_PROD ? $config['params']['cookieValidationKey'] : 'dev-key',
         ],
     ],
     

2. Asset Paths

   • Issue: Frontend assets (e.g., CSS/JS) fail to load due to incorrect @web aliases.
   • Fix: Ensure frontend/config/main.php has:

     'components' => [
         'assetManager' => [
             'basePath' => '@frontend/web/assets',
             'baseUrl' => '@web/assets',
         ],
     ],
     

3. Database Connections

   • Issue: common/config/main.php DB config overrides frontend/ or backend/ configs.
   • Fix: Use db component aliases:

     'components' => [
         'db' => [
             'class' => 'yii\db\Connection',
             'dsn' => 'mysql:host=localhost;dbname=frontend_db',
         ],
         'dbBackend' => ['class' => 'yii\db\Connection', 'dsn' => 'mysql:host=localhost;dbname=backend_db'],
     ],
     

Debugging Tips

• Enable Debug Mode: Set 'enableErrorHandler' => true in common/config/main-local.php.
• Log Levels: Use Yii::debug() and Yii::error() in common/components/Logger.php for granular logging.
• Xdebug: Configure php.ini for remote debugging with IDEs (e.g., PhpStorm).

Extension Points

1. Custom Modules

   • How: Create a module in common/modules/MyModule/ with:

     // common/modules/MyModule/MyModule.php
     namespace app\modules\MyModule;
     class MyModule extends \yii\base\Module { ... }
     

   • Register in common/config/main.php:

     'modules' => ['myModule' => 'app\modules\MyModule\MyModule'],
     

2. Event-Driven Architecture

   • Example: Listen for yii\base\Application::EVENT_AFTER_REQUEST in common/components/RequestHandler.php:

     Yii::$app->on(Application::EVENT_AFTER_REQUEST, function() {
         // Post-request logic (e.g., analytics)
     });
     

3. Custom Console Commands

   • Example: Create common/console/controllers/GenerateSitemapController.php:

     namespace app\console\controllers;
     use yii\console\Controller;
     class GenerateSitemapController extends Controller {
         public function actionIndex() { ... }
     }
     

   • Run:

     php yii generate-sitemap