Hydra App

The skeleton every Hydra PHP framework project starts from. Documentation: hydra.williamhleucka.com/docs.

Status

Experimental. This is a personal project, built in the open for my own use.

• Breaking changes are expected, between any two versions and without notice.
• Anyone curious enough to use it is doing so at their own risk.

Requirements

• PHP 8.4+ and Composer
• Docker + Compose (for the full stack: PHP-FPM, nginx, MariaDB, Redis)

composer.json pins config.platform.php to the oldest version above, so the committed lock installs on every version the skeleton claims rather than only on the one it happened to be generated with.

Setup

cp .env.example .env             # runs as-is; set APP_DEBUG=true for local dev
composer install                 # resolves the framework packages
php bin/console key:generate     # writes a fresh APP_KEY into .env

The defaults are the safe ones, not the convenient ones: APP_DEBUG=false, and the Docker base stack builds with prod.ini. ./bin/dev layers the development overrides on top, so debugging is something you ask for rather than something you remember to turn off.

Run

With Docker (full stack):

./bin/dev up -d --build          # PHP-FPM + nginx + MariaDB + Redis

Open http://localhost:8080 (the port is APP_PORT in .env).

./bin/dev also opens storage/logs, storage/uploads and storage/public to every user (mode 1777): PHP-FPM writes the log and uploaded files as www-data, and the scheduler writes the log as root. It also links public/storage to the public disk so nginx can serve it.

In production: ./bin/prod runs the same stack behind Caddy on the host. The whole path, from an empty server to https and shipping a change, is https://hydra.williamhleucka.com/docs/deploy.html.

Without Docker (public site only):

composer start                   # php -S localhost:8000 -t public/

Open http://localhost:8000.

The console

./hydra                          # the command list
./hydra admin:check
./hydra make:source invoice --writable

./hydra is ./bin/exec bin/console — the console inside the php container, which is where the database and Redis are reachable. php bin/console works directly too, on a machine with the extensions installed.

Checks

composer qa                      # static analysis, style, tests

The three also run on their own as composer stan, composer lint and composer test; composer lint:fix applies the style fixes instead of reporting them. CI runs the same tools on PHP 8.4 and 8.5, and once more against the framework's main branch, so a change upstream that breaks the skeleton fails before it is released rather than after.

---

Everything else (commands, architecture, configuration, migrations, tests) lives in the wiki: https://hydra.williamhleucka.com/docs/. AGENTS.md is the short form for coding agents: the commands, where things go, and one way to do each thing.