Skip to content

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.