Edit on GitHub

Command Line Interface

Introduction

Winter includes several command-line interface (CLI) commands and utilities that allow to install and manage Winter and its plugins and themes, perform site maintenance and speed up the development process. The console commands are executed through Laravel's Artisan command-line tool.

Commands are executed by using your terminal or shell and running the following command in the root folder of your project:

php artisan [command]

You can get a list of available commands by not providing any command to the Artisan tool:

php artisan

If you require help or a list of available arguments and options for each command, simply suffix the command with the --help flag:

php artisan [command] --help

List of available commands

The following commands are made available to every Winter installation. Click the name of a command to view more information about the usage of that command.

Command Description
Setup & Maintenance
winter:install Install Winter via command line.
winter:update Update Winter and its plugins using the Marketplace via the command line.
winter:up Run database migrations.
winter:passwd Change the password of an administrator.
winter:env Use environment files and configuration for Winter.
winter:version Display the version of Winter in use.
winter:fresh Remove the demo plugin and theme.
winter:mirror Mirror publicly accessible files in another directory.
Plugin management
plugin:install Download and install a plugin for Winter.
plugin:list List installed plugins.
plugin:rollback Rolls back a plugin and its database tables.
plugin:refresh Rolls back a plugin and its database tables, and re-runs all updates.
plugin:disable Disables a plugin.
plugin:enable Enables a plugin.
plugin:remove Removes a plugin.
Theme management
theme:install Download and install a theme for Winter.
theme:list List available themes.
theme:use Switches Winter to the given theme.
theme:remove Removes a theme.
theme:sync Synchronises a theme between the filesystem and the database, if you use the Database Templates feature.
Scaffolding
create:theme Create a theme.
create:plugin Create a plugin.
create:component Create a component in a plugin.
create:model Create a model in a plugin.
create:settings Create a settings model in a plugin.
create:controller Create a controller in a plugin.
create:formwidget Create a form widget in a plugin.
create:reportwidget Create a report widget in a plugin.
create:command Create a console command in a plugin.
Utilities
cache:clear Clear the application cache.
winter:test Run unit tests on Winter and plugins.
winter:util A collection of utilities for Winter development.

Building a command

Plugins can also provide additional commands to augment additional functionality to Winter.

If you wanted to create a console command called myauthor:mycommand, you can run the php artisan create:command MyAuthor.MyPlugin MyCommand scaffolding command which would create the associated class for that command in a file called plugins/myauthor/myplugin/console/MyCommand.php with the following contents:

<?php namespace MyAuthor\MyPlugin\Console;

use Illuminate\Console\Command;
use Symfony\Component\Console\Input\InputOption;
use Symfony\Component\Console\Input\InputArgument;

class MyCommand extends Command
{
    /**
     * @var string The console command name.
     */
    protected $name = 'myauthor:mycommand';

    /**
     * @var string The console command description.
     */
    protected $description = 'Does something cool.';

    /**
     * Execute the console command.
     * @return void
     */
    public function handle()
    {
        $this->output->writeln('Hello world!');
    }

    /**
     * Get the console command arguments.
     * @return array
     */
    protected function getArguments()
    {
        return [];
    }

    /**
     * Get the console command options.
     * @return array
     */
    protected function getOptions()
    {
        return [];
    }
}

Once your class is created you should fill out the name and description properties of the class, which will be used when displaying your command on the command list screen.

The handle method will be called when your command is executed. You may place any command logic in this method.

Defining arguments

Arguments are defined by returning an array value from the getArguments method are where you may define any arguments your command receives. For example:

/**
 * Get the console command arguments.
 * @return array
 */
protected function getArguments()
{
    return [
        ['example', InputArgument::REQUIRED, 'An example argument.'],
    ];
}

When defining arguments, the array definition values represent the following:

array($name, $mode, $description, $defaultValue)

The argument mode may be any of the following: InputArgument::REQUIRED or InputArgument::OPTIONAL.

Defining options

Options are defined by returning an array value from the getOptions method. Like arguments this method should return an array of commands, which are described by a list of array options. For example:

/**
 * Get the console command options.
 * @return array
 */
protected function getOptions()
{
    return [
        ['example', null, InputOption::VALUE_OPTIONAL, 'An example option.', null],
    ];
}

When defining options, the array definition values represent the following:

array($name, $shortcut, $mode, $description, $defaultValue)

For options, the argument mode may be: InputOption::VALUE_REQUIRED, InputOption::VALUE_OPTIONAL, InputOption::VALUE_IS_ARRAY, InputOption::VALUE_NONE.

The VALUE_IS_ARRAY mode indicates that the switch may be used multiple times when calling the command:

php artisan foo --option=bar --option=baz

The VALUE_NONE option indicates that the option is simply used as a "switch":

php artisan foo --option

Retrieving input

While your command is executing, you will obviously need to access the values for the arguments and options accepted by your application. To do so, you may use the argument and option methods:

Retrieving the value of a command argument

$value = $this->argument('name');

Retrieving all arguments

$arguments = $this->argument();

Retrieving the value of a command option

$value = $this->option('name');

Retrieving all options

$options = $this->option();

Writing output

To send output to the console, you may use the info, comment, question and error methods. Each of these methods will use the appropriate ANSI colors for their purpose.

Sending information

$this->info('Display this on the screen');

Sending an error message

$this->error('Something went wrong!');

Asking the user for input

You may also use the ask and confirm methods to prompt the user for input:

$name = $this->ask('What is your name?');

Asking the user for secret input

$password = $this->secret('What is the password?');

Asking the user for confirmation

if ($this->confirm('Do you wish to continue? [yes|no]'))
{
    //
}

You may also specify a default value to the confirm method, which should be true or false:

$this->confirm($question, true);

Progress Bars

For long running tasks, it could be helpful to show a progress indicator. Using the output object, we can start, advance and stop the Progress Bar. First, define the total number of steps the process will iterate through. Then, advance the Progress Bar after processing each item:

$users = App\User::all();

$bar = $this->output->createProgressBar(count($users));

foreach ($users as $user) {
    $this->performTask($user);

    $bar->advance();
}

$bar->finish();

For more advanced options, check out the Symfony Progress Bar component documentation.

Registering commands

Registering a console command

Once your command class is finished, you need to register it so it will be available for use. This is typically done in the register method of a Plugin registration file using the registerConsoleCommand helper method.

class MyPlugin extends PluginBase
{
    public function pluginDetails()
    {
        [...]
    }

    public function register()
    {
        $this->registerConsoleCommand('myauthor.mycommand', \MyAuthor\MyPlugin\Console\MyCommand::class);
    }
}

Alternatively, plugins can supply a file named init.php in the plugin directory that you can use to place command registration logic. Within this file, you could use the Artisan::add method to register the command:

Artisan::add(new MyAuthor\MyPlugin\Console\MyCommand);

Registering a command in the application container

If your command is registered in the application container, you may use the Artisan::resolve method to make it available to Artisan:

Artisan::resolve('myauthor.mycommand');

Registering commands in a service provider

If you need to register commands from within a service provider, you should call the commands method from the provider's boot method, passing the container binding for the command:

public function boot()
{
    $this->app->singleton('myauthor.mycommand', function() {
        return new \MyAuthor\MyCommand\Console\MyCommand;
    });

    $this->commands('myauthor.mycommand');
}

Calling other commands

Sometimes you may wish to call other commands from your command. You may do so using the call method:

$this->call('winter:up');

You can also pass arguments as an array:

$this->call('plugin:refresh', ['name' => 'Winter.Demo']);

As well as options:

$this->call('winter:update', ['--force' => true]);

Keep informed

Sign up to our newsletter to receive updates on Winter CMS releases, new features in the works, and much more.
We'll never spam or give this address away.

Latest blog post

Winter.Notes plugin now available

Published January 14, 2022
Winter.Notes has just been released, a first-party Winter CMS plugin to add notes to any records in Winter through the use of a custom `notes` FormWidget that has a user experience similar to that of the Mac OS Notes app.

View this post Read all posts

Latest Winter CMS release

v1.1.7

Released November 13, 2021
3 UX/UI Improvements, 3 API Changes, 6 Bug Fixes, 4 Translation Improvements, 3 Community Improvements

View details View all releases