Built-in console commands
Now that we know how to run console commands, let's take a look at the built-in commands to see how they work. As shown previously, Yii2 has seven built-in console commands: help, asset, cache, fixtures, gii, message, and migrate. During the development of our application, we're likely to use all seven in order to make our application more robust. Let's take a look at each one in more detail.
The help command
The first command built in to Yii2 is the help command. Often when running console commands, you may not know what options a certain command needs. Rather than referencing the Yii2 documentation, you can use the help command to provide you with all the core information you need.
At the most basic level, the help command will output all the currently available console commands:
$ ./yii help
Some commands contain additional subcommands that can be run. To view a list of all the available subcommands for a given command, you can run this:
$ ./yii help <command>
Some subcommands, such as those found in the Gii tool, require additional options to be passed to them in order for them to function. To see a list of all the required and optional flags for a given subcommand, you can run the following:
$ ./yii help <command/sub>
As we move through the next sections, ensure that you use the help command to see all the possible options and requirements for each command.
The asset command
The second default set of commands in our toolbox is the set of asset commands, which include asset/template and asset/compress.
The first command, asset/template, is used to generate a configuration file to automate the compression and minification of JavaScript and CSS assets, and it is used as follows:
$ ./yii asset/template path/to/asset.php
Running this command will generate a new file at path/to/asset.php, containing build instructions that are used by the next command, asset/compress. This file outlines which CSS and JavaScript compressor to use, a list of asset bundles to be compressed, a set of targets that the compressed assets will be outputted to, and any custom configuration for our assetManager.
The next command, asset/compress, reads our generated configuration file and builds the compressed asset files and a referable asset bundle configuration that we can load into our layouts and/or views. This command is called using the following:
$ ./yii asset/compress path/to/asset.php path/to/asset-bundle.php
Note
In Chapter 6, Asset Management, we will take an in-depth look at how we can use these commands in addition to the assetManager class in order to manage our assets in more detail.
The cache command
The third built-in command in our toolbox is the cache command. The cache command provides the functionality to flush caches that are generated by our application. These commands are cache, cache/flush, cache/flush-all, and cache/flush-schema.
The first command, cache, returns a named list of all the available caches defined in our configuration file and can be run using the following command:
$ ./yii cache
Here's the output:
The following caches were found in the system: * cache (yii\caching\FileCache)
The output of this command takes the following format so that we can identify which caches are in use. In our default application, only one cache is predefined: our file cache.
<cache_name> (<cache_type>)
Once we know what caches are in use, we can then use the cache/flush command to flush that cache by name. Using the output of the previous command, we can clear the cache component by name by running this:
./yii cache/flush cache
Here's the output:
The following cache components will be flushed: * cache The following cache components were processed: * cache (yii\caching\FileCache)
Tip
Some commands in Yii2 are interactive and prompt for confirmation before running. This may be problematic when you need to automate the use of a command, such as on deployment. You can bypass this behavior by appending --interactive=0 to the command. When running commands noninteractively, additional arguments may be required. Ensure that you reference the help command to determine what arguments you need to pass when running noninteractive commands.
Alternatively, if we want to flush the entire cache for our application, we can use the cache/flush-all option:
$ ./yii cache/flush-all
In our production environments, we'll want to reduce the load on our database server by caching our database schema. Yii2 will maintain a cache of the currently active db component (the database) and the database schema when instructed to. When making schema changes, such as when applying new migrations, we need to clear this cache so that Yii2 becomes aware of our updated database structure. We can clear the database schema cache by running this:
$ ./yii cache/flush-schema
Tip
We'll cover how to enable the schema cache and improve the performance of our database in the next chapter.
The fixture command
When testing our application, we'll often want to set up our database such that our tests always run in a predictable and repeatable way. One way in which we can do this is by creating fixtures, which will represent database objects in our application for testing. Yii2 provides a set of commands to both load and unload fixtures; these commands are fixture/load and fixture/unload, and they do exactly what you expect them to do.
When using fixtures, our typical test flow is as follows:
- Apply database migrations.
- Execute our test cases in the following manner:
- Load our database fixtures.
- Execute a specific test.
- Unload our database fixtures.
- Repeat as required until all tests have run.
The fixture/load and fixture/unload commands are called in the same way from the command line:
$ ./yii fixture/load <FixtureName> $ ./yii fixture/unload <FixtureName>
Tip
Fixtures are a powerful way to create repeatable tests for our applications. Additionally, the yii2-codeception package provides additional support for the loading and unloading of fixtures when our tests run. In them with Codeception.
The Gii command
The next set of commands in our toolbox is the Gii command. If you are familiar with Yii1, Gii provides the functionality to generate controllers, models, forms, and even basic CRUD functionality. In Yii2, Gii has been extended from a web application module to both a web and console application and has been enhanced to include additional features as well.
The Gii module in Yii2 provides these console commands to automatically generate code: gii/controller, gii/model, gii/crud, gii/form, gii/extension, and gii/module. Each of these commands, when supplied with the right options, will generate the respective item identified by the subcommand. For a complete list of requirements and options, ensure that you use the help command on the Gii subcommands.
Tip
As a development tool, Gii has the ability to arbitrarily generate and override existing code in your application. For security purposes, you should conditionally load the Gii module only in your development environment. Moreover, the Gii module itself should never be deployed to your production environment. For this reason, it is advised that you only load the Gii module in the require-dev section of your composer.json file.
The require-dev section is a special section within our composer.json file, which allows us to separate our development dependencies from our production dependencies. By default, running Composer will install all packages in our require and require-dev sections. In production environments, we will want to exclude our development environments by passing the --no-dev flag to our Composer installation command. For more information on the Composer CLI, ensure that you reference the Composer documentation at https://getcomposer.org/doc/03-cli.md.
The message command
The next set of commands is the message commands, which provide functionalities to automatically generate message translations for our application in a variety of different formats.
The first subcommand is the message/config command, which generates a configuration file that the message/extract command will then use to output the translation files. Before generating any translations, we must run the message/config command as follows:
$ ./yii message/config /path/to/translation/config.php
This command generates a configuration file at /path/to/translation/config.php that contains all the information message/extract will need in order to generate the message output files.
After configuring your message configuration file to your liking, you can then run the message/extract command as follows:
$ ./yii message /path/to/translation/config.php
Depending upon your configuration file and the use of \Yii::t(), the built-in Yii translation tool in your application, this command will generate either a PHP file containing a list of messages, a .po file, and a command translation file format, or it will populate the specified table in your database with the necessary message lists.
Tip
In Chapter 11, Internationalization and Localization, we'll go into more depth about how to use these commands to generate PHP message files and .po files and how to populate our database. We'll also cover the use of the Yii::t() method in detail.
The migration command
The final built-in command set with Yii2 is the migration command. The migration commands provide functionalities to generate, apply, revert, and review database migrations. This tool provides these subcommands: migrate/create, migrate/history, migrate/mark, migrate/up, migrate/down, migrate/to, migrate/new, and migrate/redo.
Tip
We'll cover how to completely use this tool and work with databases in general in more detail in Chapter 3, Migrations, DAO, and Query Building. For now, use the ./yii help migrate command to view more information on the migration tool.