The console package contains a set of classes required to route and dispatch incoming console requests. Moreover it contains the console front-controller file (`lithium.php`) as well as wrappers for both *nix and Windows environments (`li3` and `li3.bat` respectively), allowing to easily invoke the console front-controller from the command line.
A command is to the command line what an action controller is to the HTTP request/response flow. In that commands are quite similar to controllers. Commands don't leverage the full MVC as they don't utilize views, but directly interact with the user through `in()` and `out()`.
Lithium itself provides amongst others commands for creating new applications or parts thereof. However commands can also be provided through other libraries or by your application. Commands running in the application context will have complete access to your application. This is especially useful to reuse existing logic in an application's model when creating a command to be run as i.e. a cron-job.
- Invoking the front-controller
However it is recommended you add the path containing the wrapper to the paths searched by your system. This is `$PATH` for *nix and `%PATH%` for Windows.
- A: Configuring your $PATH on *nix
Once you've followed these steps, save your modified the file and reload your environment settings by sourcing the modified profile through the following command.
If you are unable, or don't wish, to modify your `$PATH` there are two other techniques you may use to make the wrapper available as `li3`. You can either symlink the wrapper into one of the paths found in the `$PATH` environment variable or create an alias. If you choose an alias, you can make it permanent by adding the alias command to the `.bashrc` file in your home directory.
- B: Configuring your %PATH% on Windows
- Open _System_ from within the _Control Panel_. - Open the _Advanced_ tab. - Clicking the _Environment Variables_ button open a dialog where you can edit the variables. - Double click the _PATH_ entry in order to edit it. - Add `;C:\path\to\php;C:\path\to\libraries\lithium\console` to the end of the value.
- Finishing up
- Built-in commands
- Creating custom commands
- All commands inherit from `lithium\console\Command`. - Commands are normally placed in your application or library's `extensions/command` directory.
Here's an example command:
If you would like to try this command, create an application or use an existing application, place the command into the application's `extensions/commands` directory and save it as `HelloWorld.php`. After doing so open a shell and change directory to your application's directory and run the following command:
Although it's probably obvious, when this command runs it will output a nice header with the text `Welcome to the Hello World command!` and some regular text `Hello, World!` after it.
The public method `run()` is called on your command instance every time your command has been requested to run. From this method you can add your own command logic.
- Parsing options and arguments
Short and long (GNU-style) options in the form of `-f`, `--foo`, `--foo-bar` and `--foo=bar` are automatically parsed and exposed to your command instance through its properties. XF68-style long options (i.e. `-foo`) are not supported by default but support can be added by extending the console router.
Arguments are passed directly to the invoked method.
Let's look at an example, going back to the `hello_world` command from earlier:
Notice the additional property `$recipient`? Great! Now when `--recipient` is passed to the `hello_world` command, the recipient property on your command instance will be set to whatever was passed into the command at runtime.
Try it out with the following command:
You should get a special greeting from our good old `hello_world` command.