Console commands
Console Commands¶
ZubZet provides a built-in console interface that allows you to manage and interact with the framework directly from the command line. Console commands enable automation, debugging, and execution of application logic outside the HTTP context.
How to Run a Command¶
To execute a console command inside the Docker container, first access the container shell:
npm run shell
Then navigate to the root directory of your project (where the index.php file is located) and run:
php index.php {command}
The package registers no Composer scripts and no bin executable (its only require-dev entry is a test-coverage library), so the CLI is reached through the project: php index.php <command>, or php zubzet <command> and ./project <command> in a generated project. A command's return value becomes the process exit status (0 on success, 1 on failure).
Available Commands¶
completion¶
Dumps the shell completion script for the ZubZet console. This improves command-line usability by enabling tab completion.
help¶
Displays help information for a specific command or for the console in general.
Symfony's global options (-h, -q, -v|-vv|-vvv, -V, --ansi, --no-ansi, -n) apply to every command.
list¶
Lists all available console commands; php index.php without a command prints the same list.
run¶
Executes a controller action directly from the console environment. This is useful for running application logic, maintenance tasks, or background operations without an HTTP request.
info:startup¶
Prints a startup banner with the ZubZet version (as Composer reports it, e.g. v1.2.0, or unknown), application name, environment, PHP version, and asset
version — a quick health check after deployment. A missing pageName, execution_type, assetVersion or host prints Unknown. Set <key> in settings! (host prints Unknown / Check docker-compose-base.yml) instead.
php index.php info:startup
Pass --pwd "$(pwd)" so clickable file links in the error page resolve to your
host paths (the dev stack's npm run info does this for you). The value is stored in
z_config/z_automated_setting.ini as automated_host_working_directory.
project¶
Every generated project ships a project script in its root for the everyday tasks:
| Command | Description |
|---|---|
./project start |
Build and start the Docker stack, then run composer install, db:seed and info:startup. |
./project stop |
Stop the stack and remove it, including its volumes. |
./project shell |
Open a shell inside the application container. |
./project tests |
Run the Cypress suite headless; extra arguments (e.g. --spec) are passed through. |
./project cypress |
Open the interactive Cypress UI. |
Any other arguments are forwarded to php zubzet: inside the application container when it
is running, otherwise directly with the host's PHP.
./project db:status
tests and cypress need Node.js and Cypress on the host. They are never installed
automatically; if they are missing, the script prints the npm install command to run.
Database commands¶
| Command | Description |
|---|---|
db:migrate |
Run all pending migrations (framework-bundled and your own under app/Database/migrations). |
db:seed |
Drop and recreate the database, run all migrations, then load seed data from app/Database/seed. All existing data is lost unless --skip-migrations is passed. |
db:status |
Show whether the migration lock is set; exit code 0 when unlocked, 1 when locked. |
db:sync |
Mark migrations as applied up to a version/date without running their SQL. |
db:unlock-migration |
Release a stuck migration lock. |
db:seed accepts path filters (relative to app/Database/seed) to control which seed folders run. Every file starts selected, so --environments-included alone changes nothing; it only brings back paths removed by --environments-excluded:
# Only seed "Environments/Dev": exclude the folder, then re-include the subset
php index.php db:seed --environments-excluded=Environments --environments-included=Environments/Dev
# Seed everything except "Prod" (repeatable)
php index.php db:seed --environments-excluded=Prod
# Keep the database and only run the seed files (no drop, no migrations)
php index.php db:seed --skip-migrations
See Migrations for the full migration workflow.
Repair commands¶
Repair commands fix an installation that drifted into a broken state. They are never run automatically; run one when you hit the problem it names.
repair:database-collation¶
Tables with different collations make queries across them fail, for example with
Illegal mix of collations for operation 'UNION' on every authenticated request. This happens
when tables were created under different server or database defaults, e.g. older tables from
before a server upgrade next to newer ones.
The framework creates its tables as utf8mb4 with the collation utf8mb4_uca1400_ai_ci
(ZubZet\Framework\Database\Connection::COLLATION). The command converts the framework tables
(z_ prefix) to it with
ALTER TABLE ... CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_uca1400_ai_ci:
php index.php repair:database-collation
Application tables and the database default are left alone. Add --include-app-tables to convert
every table of the database and to set the database default to the same collation, so tables
created later without an explicit collation match:
php index.php repair:database-collation --include-app-tables
Only tables whose own collation or any text column's collation differs are converted; a rerun
with nothing left to convert changes nothing. Columns that deliberately use another collation
(e.g. a case-sensitive utf8mb4_bin column) are converted as well.
Warning
Converting rewrites the whole table and blocks writes to it meanwhile, which can take a long time on large tables. Take a backup and run it in a maintenance window.
auth:migrate-hashing¶
Wraps every legacy password hash in an Argon2id layer and marks the row onion; rows without a password are skipped. Idempotent, so
it is safe to run more than once, but the update does not re-check the scheme, so a password changed during the run can be overwritten. See Password Handling.
php index.php auth:migrate-hashing
With --dry (-d) it only prints how many legacy passwords it found.
module:setup¶
Merges missing default settings from installed modules into
z_config/z_settings.ini. Append-only and idempotent: existing keys are never touched, and a
rerun with nothing to merge changes nothing.
php index.php module:setup
Your own commands¶
Beyond run, the application (and every module) can ship dedicated Symfony commands in
app/Commands/; they register automatically and appear in list. See
Commands for the file convention and precedence rules.
Coverage¶
Coverage is a development feature: the underlying phpunit/php-code-coverage library is a
development dependency of ZubZet and is not installed with your application by default.
Install it before using the coverage commands:
composer require --dev "phpunit/php-code-coverage:9.*"
Without it, the coverage commands fail with an error explaining this requirement.
Collect a runtime code-coverage report:
php index.php testing:coverage:start
# ... exercise the app via tests or manual requests ...
php index.php testing:coverage:stop
start writes a session id to .coverage.session in the working directory; while that file exists, every web request and CLI call collects coverage (an Xdebug or PCOV driver is required). testing:coverage:stop writes the HTML report to .coverage/report/; add --cli (-c) to print a text report (PHPUnit summary plus a per-file tree, green from 90 %, yellow from 50 %, red below) to stdout instead. To include tests that do not go through the application, such as a PHPUnit suite, pass the file PHPUnit writes with --coverage-php as --merge <file> (-m, repeatable); the paths of the source files have to match, so run PHPUnit in the same environment. Merging many collected files is memory-hungry; CI runs it as php -d memory_limit=4G index.php testing:coverage:stop.