How to Create a Console Controller in CraftCMS

Console controllers are perfect for background tasks, cron jobs, data imports/exports, testing, or any operation you want to execute from the command line.

1. Create a Module (with Sample Module.php)

If you don’t already have a module, you’ll need to create one. Modules are a great way to organize your custom CraftCMS code, including console controllers.

Get Mark Lopez’s stories in your inbox

Join Medium for free to get updates from this writer.

Remember me for faster sign in

Directory Structure:

modules/
└── mymodule/
    ├── Module.php
    └── console/
        └── controllers/

Sample Module.php:

<?php
namespace modules\mymodule;

use Craft;
class Module extends \yii\base\Module
{
    public function init()
    {
        parent::init();
        // Define a custom alias named after the namespace.
        Craft::setAlias('@mymodule', __DIR__);
        // Set the controllerNamespace based on the request type
        if (Craft::$app instanceof \craft\web\Application) {
            $this->controllerNamespace = 'modules\mymodule\controllers';
        } else {
            $this->controllerNamespace = 'modules\mymodule\console\controllers';
        }
    }
}

Register the module in your config/app.php (or config/app.console.php for console-only):

return [
    'modules' => [
        'my-module' => [
            'class' => \modules\mymodule\Module::class,
        ],
    ],
    'bootstrap' => ['my-module'],
];

Now your module is ready to host custom console controllers!

2. Create the Console Controller

Inside your module, create a console/controllers directory. Then, create a controller file, e.g., ExampleController.php:

modules/
└── mymodule/
    └── console/
        └── controllers/
            └── ExampleController.php

3. Write the Console Controller Class

Here’s a basic example:

<?php
namespace modules\mymodule\console\controllers;
use yii\console\Controller;
use yii\console\ExitCode;
class ExampleController extends Controller
{
    /**
     * This command echoes the provided message.
     * 
     * Usage: ./craft my-module/example/echo "Hello World"
     */
    public function actionEcho($message = 'Hello World')
    {
        $this->stdout("Message: $message\n");
        return ExitCode::OK;
    }
}

Key Points:

• The class must extend yii\console\Controller.
• Method names must start with action (e.g., actionEcho).
• The command will be available as ./craft <module-id>/<controller-id>/<action-id>.
• You can use $this->stdout() to output to the console.

4. Run Your Command

Open your terminal and run:

./craft my-module/example/echo "Hello from CraftCMS Console!"

You should see:

Message: Hello from CraftCMS Console!

5. Add More Actions

You can add as many actions as you need. Each public method prefixed with action becomes a console command.

public function actionTest()
{
    $this->stdout("This is a test action.\n");
    return ExitCode::OK;
}

6. Tips

• Use PHPDoc comments to document your commands and arguments.
• You can use dependency injection, services, and all Craft/Yii features in your controller.
• For more advanced usage, check the Yii2 console controller documentation.

Conclusion

Creating a console controller in CraftCMS is straightforward and unlocks powerful automation and scripting capabilities. Use this pattern for scheduled jobs, data processing, or any task you want to run from the command line.

If you have questions or want to see more advanced examples, let me know!