Command Line Tools (Spark)
Relevant source files
The following files were used as context for generating this wiki page:
CodeIgniter 4 features a command-line interface (CLI) tool named Spark, which provides utilities to aid in development and application management. Spark is extensible, allowing developers to create custom commands for their own application needs. It is an essential part of the framework for tasks like running migrations, seeding data, generating boilerplate code, and starting the local development server.
The CLI environment is managed through a specialized CLIRequest class, which parses command-line arguments and options, distinct from the standard IncomingRequest used for web requests. This ensures that CLI interactions are handled robustly and separately from HTTP traffic. The core of the CLI functionality is built around a system of commands that can be listed, described, and executed through the spark script.
Sources: source/cli/index.rst:3-10, source/cli/cli_request.rst:3-10
Running Commands
All CLI operations are initiated via the spark script located in the project's root directory. To run a command, you use the php spark prefix followed by the command's name and any necessary arguments or options.
Sources: source/cli/index.rst:12-14
Launching the Interactive Shell (REPL)
CodeIgniter provides an interactive shell, or REPL (Read-Eval-Print-Loop), which allows you to execute PHP code within the application's context without creating a controller or route. This is useful for testing small pieces of code, interacting with models, or debugging. It is launched with the spark shell command.
Sources: source/cli/spark_commands.rst:352-355
Starting the Development Server
A local development server can be started using Spark, which is useful for testing your application without configuring a full web server like Apache or Nginx.
php spark serve
By default, the server runs on localhost:8080. You can customize the host and port using options.
Sources: source/cli/spark_commands.rst:12-15
The following diagram illustrates the basic flow of executing a Spark command.
This diagram shows the process from command execution to console output.
Sources: source/cli/index.rst, source/cli/cli_request.rst
Core Spark Commands
CodeIgniter ships with a set of built-in commands to handle common development tasks. You can view all available commands by running php spark list or simply php spark.
Sources: source/cli/spark_commands.rst:3-6
| Command Group | Command Name | Description |
|---|---|---|
| CodeIgniter | cache:clear | Clears the current system caches. |
cache:info | Shows information about the cache. | |
env | Retrieves the value of an environment variable. | |
routes | Displays all defined routes. | |
serve | Launches the CodeIgniter development server. | |
shell | Launches the interactive CodeIgniter REPL shell. | |
dbrepair | Repairs a database table. | |
help | Displays help for a command. | |
list | Lists the available commands. | |
| Generators | make:cell | Creates a new view cell file. |
make:command | Creates a new Spark command. | |
make:controller | Creates a new controller file. | |
make:entity | Creates a new entity file. | |
make:filter | Creates a new filter file. | |
make:migration | Creates a new migration file. | |
make:model | Creates a new model file. | |
make:seeder | Creates a new seeder file. | |
make:validation | Creates a new validation file. | |
session:migration | Generates the migration file for the session database table. | |
| Migrations | migrate | Locates and runs all new migrations. |
migrate:rollback | Rolls back the last migration. | |
migrate:refresh | Does a rollback and then a fresh migration. | |
migrate:status | Displays the status of all migrations. | |
| Database | db:seed | Runs a specific seeder to populate the database. |
db:table | Retrieves information on the selected table. |
Sources: source/cli/spark_commands.rst:10-370, source/cli/cli_generators.rst:3-10
Code Generators
The make:* commands are code generators that create boilerplate files for various application components like controllers, models, and migrations. This speeds up development by reducing manual file creation. For example, to create a new controller named User:
php spark make:controller User
This will create a UserController.php file in the app/Controllers directory. You can use options like --suffix to add a Controller suffix to the class name automatically.
Sources: source/cli/cli_generators.rst:3-17
The generation process can be visualized as follows:
This sequence shows how a developer's command leads to the creation of a new file on the filesystem.
Sources: source/cli/cli_generators.rst:19-35
Creating Custom Commands
You can create your own CLI commands to automate tasks specific to your application.
Sources: source/cli/cli_commands.rst:3-5
Command Structure
A custom command is a PHP class that extends CodeIgniter\CLI\BaseCommand. It must implement the run() method, which contains the logic for the command.
Key properties to define in your command class:
$group: The group the command belongs to (e.g., 'App', 'Database').$name: The command's name (e.g.,app:do-something).$description: A short description shown in thelistcommand.$usage: The usage pattern (e.g.,app:do-something [arguments]).$arguments: An array defining the command's arguments.$options: An array defining the command's options.
Sources: source/cli/cli_commands.rst:27-44
The class hierarchy for commands is straightforward.
This diagram shows a custom command inheriting from the abstract BaseCommand.
Sources: source/cli/cli_commands.rst:27-31
Creating a Command with Spark
The easiest way to create a new command is by using the built-in make:command generator:
php spark make:command MyCommand
This will generate a new command file at app/Commands/MyCommand.php with a basic template that you can modify.
Sources: source/cli/cli_commands.rst:10-14
The CLI Library
CodeIgniter provides a CLI library (CodeIgniter\CLI\CLI) to help with command-line interactions, such as writing output, reading input, and formatting text. This library is automatically available within any command class via $this->cli.
Sources: source/cli/cli_library.rst:3-10
Writing Output
The CLI class provides several methods for outputting text to the console with different colors and formatting.
| Method | Description |
|---|---|
CLI::write() | Writes a string to the console, optionally with a foreground color. |
CLI::print() | An alias for write(). |
CLI::error() | Writes a string to the console in a red "error" color. |
CLI::color() | Wraps a string with the appropriate ANSI color codes. |
CLI::table() | Displays data in a formatted table. |
CLI::progressBar() | Displays an ASCII progress bar. |
Example of writing colored output:
// In a command's run() method
$this->cli->write('This is green text.', 'green');
$this->cli->error('This is an error!');
Sources: source/cli/cli_library.rst:27-100
Reading Input
To prompt the user for input, you can use the CLI::prompt() method.
// In a command's run() method
$name = $this->cli->prompt('What is your name?');
You can also provide a default value and specify validation rules for the input.
Sources: source/cli/cli_library.rst:133-145
Conclusion
The Spark command-line tool is a powerful and integral part of the CodeIgniter 4 framework. It streamlines common development workflows through its built-in commands for code generation, database management, and running a local server. Furthermore, its extensibility allows developers to create custom commands tailored to their application's specific needs, making it an indispensable tool for building and maintaining CodeIgniter applications.