🛠️ DX

dx is a framework-agnostic bash CLI that orchestrates the full development lifecycle for PHP projects — Docker, Apache, Traefik, environment config, migrations, and tests — across multiple frameworks (Yii2, Laravel).

The dx script at the project root is the entrypoint. It loads dxkit/bootstrap.sh and dispatches to the command and module system inside dxkit/.

Prerequisites

• Bash (Linux/macOS native; Windows via Git Bash or WSL)
• Docker + Docker Compose
• dx must be executable: chmod +x dx

Quick start

./dx setup              # first time: build image + init environment
./dx up                 # start the stack
./dx shell              # enter the app container
./dx console migrate    # run database migrations

Command reference

Setup & initialization

Command	Description
dx build	Build the Docker image and generate the compose stack
dx init [env]	Bring the project to a runnable state for an environment (default: dev)
dx setup	build + init in one step

dx build flags

Flag	Description
--dev / --qly / --prd	Target environment (default: --dev)
--project=NAME	Override the project name
--port=PORT	Override the app HTTP port
--db=mysql|mssql	Database engine (default: mysql)
--db-port=PORT	Override the database port
--sync-hosts	Write the project domain to /etc/hosts after build
--no-vhosts	Skip Apache virtual host generation
--no-interact	Non-interactive mode (no prompts)
--debug	Enable shell trace output

dx init flags

Flag	Description
--skip-vendors	Skip composer install
--skip-framework-init	Skip framework init script
--skip-framework-config	Skip framework config generation
--skip-proxy	Skip starting the reverse proxy
--debug	Enable shell trace output

---

Runtime

Command	Description
dx up	Start the Docker stack
dx down	Stop the Docker stack
dx logs	Tail container logs
dx shell / dx bash	Open an interactive shell inside the app container
dx exec <cmd> [args]	Run a command inside the app container
dx list / dx ls	List stack containers
dx test [args]	Run PHPUnit tests inside the container

dx up flags

Flag	Description
--sync-hosts	Sync domain entries to /etc/hosts before starting
--skip-proxy	Do not ensure the reverse proxy is running
--recreate	Force container recreation
--build	Rebuild the image before starting
--foreground	Run in foreground (don't detach)
--debug	Enable shell trace output

dx down flags

Flag	Description
--volumes	Also remove Docker volumes
--orphans	Remove orphan containers
--debug	Enable shell trace output

---

Framework console

Command	Description
dx console <cmd> [args]	Run a framework console command
dx yii <cmd>	Alias for Yii2 (php yii <cmd>)
dx artisan <cmd>	Alias for Laravel (php artisan <cmd>)

---

Migration shortcuts

These are resolved by the active framework driver.

Yii2

Command	Description
dx migrate	Run all pending migrations
dx migrate-create <name>	Generate a new timestamped migration file in console/migrations/
dx migrate-down [n]	Revert n migrations (default: 1)
dx migrate-new	Show pending migrations
dx migrate-history	Show migration history

Laravel

Command	Description
dx migrate	Run all pending migrations
dx migrate-create <name>	Create a migration via artisan make:migration
dx migrate-rollback [--step=N]	Revert migrations
dx migrate-status	Show migration status
dx migrate-fresh	Drop all tables and re-run all migrations

---

Apache

Command	Description
dx apache validate	Validate vhost configuration
dx apache reload	Graceful reload (picks up config changes without downtime)
dx apache restart	Full restart
dx apache vhosts	List all loaded virtual hosts
dx apache modules	List all loaded Apache modules
dx apache version	Show Apache version
dx apache logs [error|access]	Tail error or access logs

---

Proxy (Traefik)

Command	Description
dx proxy start	Start the Traefik reverse proxy
dx proxy stop	Stop the proxy
dx proxy restart	Restart the proxy
dx proxy status	Show proxy status
dx proxy logs	Tail proxy logs

---

Network & hosts

Command	Description
dx network status	Show resolved port assignments
dx network resolve	Re-run port resolution and show changes
dx network hosts	Alias for the hosts command
dx hosts sync	Write project domain entries to /etc/hosts (requires root/sudo)
dx hosts remove	Remove project entries from /etc/hosts
dx hosts list	Show current /etc/hosts entries for this project
dx hosts preview	Preview entries that would be written

---

Workspace

Command	Description
dx workspace / dx ws	Drop into a subshell where all dx commands and framework driver commands are available without the dx prefix

---

Global flags

These flags are accepted by all commands:

Flag	Description
--framework=NAME	Override auto-detected framework
--debug	Enable shell trace output (set -x)

---

Environments

Three built-in environments:

Name	Use
dev	Development (default)
qly	Quality
prd	Production

Environment variables are layered in order:

1. dxkit/env/globals.env — shared defaults, source-controlled
2. .project/artifacts/env/${ENVIRONMENT}.env — local overrides, gitignored
3. .project/artifacts/env/${ENVIRONMENT}.resolved.env — generated resolved values, gitignored

Resolved port assignments are written to .project/artifacts/ports and loaded back on subsequent runs.

Port values in env files may use the auto:PORT syntax — dxkit will find the next available port starting from that number.

---

Framework support

Framework detection reads composer.json at project root.

Framework	Detected by	Console binary	dx console alias
Yii2 Advanced	yiisoft/yii2 + advanced template structure	yii	dx yii
Yii2 Basic	yiisoft/yii2 + basic template structure	yii	dx yii
Laravel	laravel/framework	artisan	dx artisan

Use --framework=NAME to override detection (e.g. --framework=yii2-advanced).

---

Architecture

For contributors and maintainers.

dx                          # project-level entrypoint; defines aliases, calls dx::dispatch()
dxkit/
├── bootstrap.sh            # loads core.sh, exports PROJECT_ROOT, defines dx::load_modules()
├── core.sh                 # sources all core subsystems in order
├── core/                   # low-level infrastructure
│   ├── platform.sh         # OS detection, privilege elevation
│   ├── context.sh          # execution context management
│   ├── utils.sh            # general utilities
│   ├── string.sh           # string helpers
│   ├── hook.sh             # pre/post hook system
│   ├── module.sh           # module loader
│   ├── command.sh          # command registration framework
│   ├── loader.sh           # dynamic file loader
│   ├── flag.sh             # flag/argument parsing
│   └── runtime/runtime.sh  # runtime abstraction entry
├── commands/               # one file per command, loaded dynamically by the dispatcher
│   ├── build.command.sh
│   ├── init.command.sh
│   ├── setup.command.sh
│   ├── console.command.sh
│   ├── apache.command.sh
│   ├── hosts.command.sh
│   ├── network.command.sh
│   ├── proxy.command.sh
│   ├── workspace.command.sh
│   ├── docker/             # low-level docker subcommands
│   └── runtime/            # runtime-abstracted subcommands (used by default)
├── modules/                # reusable function libraries sourced at startup
│   ├── app.module.sh       # framework abstraction layer (scaffold, init, config, console)
│   ├── docker.module.sh    # Docker and Docker Compose wrappers
│   ├── env.module.sh       # environment variable loading and derivation
│   ├── log.module.sh       # structured logging with icons and context prefixes
│   ├── fs.module.sh        # cross-platform file write and sed utilities
│   ├── network.module.sh   # port resolution and persistence
│   ├── apache.module.sh    # Apache management functions
│   ├── proxy.module.sh     # proxy abstraction (delegates to docker/proxy.module.sh)
│   ├── artifact.module.sh  # runtime artifact directory management
│   ├── composer.module.sh  # composer operations (install, update, require, auth)
│   ├── template.module.sh  # envsubst-based template rendering
│   ├── yii.module.sh       # Yii2 shared utilities (exec, env name mapping)
│   ├── phpstorm.module.sh  # PhpStorm datasource config generation
│   ├── docker/
│   │   ├── db.module.sh    # database port/path/env helpers (MySQL + MSSQL)
│   │   └── proxy.module.sh # Traefik container lifecycle and label generation
│   └── framework/
│       ├── yii2-advanced.module.sh
│       ├── yii2-basic.module.sh
│       └── laravel.module.sh
├── drivers/                # framework-specific command registration
│   ├── dispatcher.sh       # resolves framework → driver, populates DRIVER_COMMANDS
│   ├── yii2/
│   │   ├── driver.sh       # registers yii, migrate-* commands
│   │   └── migrate.sh      # migration file generation helpers
│   └── laravel/
│       ├── driver.sh       # registers artisan, migrate-* commands
│       └── migrate.sh      # artisan make:migration wrappers
├── runtime/                # runtime abstraction (Docker vs. native execution)
│   ├── runtime.sh          # selects active runtime
│   ├── docker.runtime.sh   # implements runtime::exec via docker compose exec
│   └── native.runtime.sh   # implements runtime::exec directly on host
├── templates/              # envsubst-rendered config templates
│   ├── docker/
│   │   ├── Dockerfile.template
│   │   └── docker-compose.yml.template
│   ├── apache/
│   │   ├── yii2-advanced/vhosts.conf.template
│   │   └── yii2-basic/vhosts.conf.template
│   ├── yii2-advanced/
│   │   ├── main-local.php.template
│   │   └── components/     # db.mysql, db.mssql, log php templates
│   └── yii2-basic/
│       ├── db.mysql.php.template
│       └── db.mssql.php.template
├── env/                    # layered environment variable files
│   ├── globals.env
│   ├── dev.env
│   ├── qly.env
│   └── prd.env
└── docker/
    └── entrypoint.sh       # container entrypoint script

How command dispatch works

1. dx <command> [args] calls dx::dispatch()
2. Aliases in dx are resolved first (e.g. sh → runtime/shell, ls → runtime/list)
3. Built-ins (help, elevate) are handled inline
4. Driver commands registered in DRIVER_COMMANDS (via dxkit/drivers/dispatcher.sh) are checked next
5. Remaining commands are matched to files in dxkit/commands/ and loaded dynamically

Adding a new command

1. Create dxkit/commands/<name>.command.sh with a function command::<name>()
2. Optionally register an alias in dx under the alias map
3. For framework-specific commands, register the command name in the driver file (dxkit/drivers/<framework>/driver.sh)