webware/webware

The Webware application skeleton - a Mezzio application that binds the Webware components together. Per the standing composition doctrine, the skeleton is what binds acl, usermanager and admin; no component is required to require another. It is also the first place routing and the ACL decision path run end to end.

What ships here

Everything in this repository is either a package of record consumed from webware/webware-tools, or the thin per-repo wiring that cannot live in a shared config:

Path	Role
mago.toml	Extends the centre (vendor/webware/webware-tools/mago.toml), pins php-version locally, and points the linter and analyzer at the local baselines. General rules stay in the centre; never add them here.
webware-ci.json	The required CI workflow's parameter contract - read from the repository root by webinertia/.github.
phpunit.xml.dist	PHPUnit 13 strict mode: requireCoverageMetadata, failOnNotice, failOnWarning, failOnDeprecation.
compose.yml / Dockerfile / .devcontainer/	The containerized toolchain (Composer, PHPUnit, Mago, Infection, PHPBench, roave BC-check).
src/App/src/ConfigProvider.php	The application's wiring entry point, declared under extra.laminas.config-provider.
config/	The Mezzio config: the aggregator (config.php), the container (container.php), the middleware pipeline (pipeline.php), and the layered autoload/ files.
public/index.php	The front controller - public/ is the document root.
data/cache/	The config cache target, held in git by .gitkeep only. Dropped by dev:mode, which clears it on --enable, --disable and --clear-cache.
docs/	Prose that has to stay true: configuration.md is the configuration reference.

mago.toml, phpunit.xml.dist, .gitattributes, codecov.yml, Dockerfile, .dockerignore, infection.json5.dist, phpbench.json.dist and devcontainer config are byte-identical to the canonical artifacts in webware-tools/presets/webware-alignment/artifacts/ - copy updates from there rather than editing them here.

Quality gates

The MSI gates are declared per repository in webware-ci.json, and this repository sets both to 95. The required workflow reads them and passes them to Infection as --min-msi and --min-covered-msi, so they are enforced from CI rather than from infection.json5.dist, which declares no thresholds at all. Lower them only with a deliberate decision, and never silently:

"min_msi": "95",
"min_covered_msi": "95"

Four Mago gates run in CI and must be clean: format --check, lint, analyze, guard. Run mago fmt first when making changes, and fix findings at source rather than adding @mago-expect - a suppression needs to be a decision, not a reflex.

Configuration

docs/configuration.md is the configuration reference: every key the application must supply, where each value is read from, and how to override a value a component supplies.

The short version, because these are what a fresh clone does not have:

• The database connection, in config/autoload/mysql.local.php. That file is gitignored and no .dist ships for it, so it has to be created by hand; the reference carries the full shape. Sessions are database backed, so this is required for an anonymous visit, not only a signed-in one.
• The schema, created by the component commands user:init-db, session:init-db, log:init-db and acl:init-db, with acl:seed re-publishing the rules afterwards. They read the same database configuration, so the connection has to work before they will run.
• Everything else required (debug, view_helper_config.base_path, the three Webware\Core\UserInterface::class keys, the mail adapter and session.gc_maxlifetime) ships committed with working defaults for this repository and only needs revisiting for a different host.

Editing any configuration file has no effect while the config cache is on. Clear it, or toggle development mode, then reload.

Development

The toolchain runs in a container, so the host needs no PHP install. With VS Code, reopen in the container; without it:

docker compose up -d
docker compose exec tooling composer install
docker compose exec tooling composer test
docker compose exec tooling composer test-integration
docker compose exec tooling mago lint
docker compose down

To boot the application itself:

composer serve   # php -S 0.0.0.0:8080 -t public/
composer menu    # php vendor/bin/webware menu, the console host's interactive menu

composer menu opens the console host (webware/webware-console), which discovers the commands the installed components register: dev:mode, the schema commands (user:init-db, session:init-db, log:init-db, acl:init-db, acl:seed), and the Laminas servicemanager:* generators. Development mode is driven from there, or directly:

vendor/bin/webware dev:mode --enable       # copy the dist file, drop the config cache
vendor/bin/webware dev:mode --disable      # remove the active file, drop the config cache
vendor/bin/webware dev:mode --clear-cache  # drop the config cache without changing the mode

Routes are registered by the component that owns them: the home page at / from App\RouteProvider, the user trees under /user from webware-usermanager, and the admin trees under /admin from webware-admin, webware-acl and webware-usermanager's admin segment. A request matching none of them falls through to Mezzio's NotFoundHandler and answers 404.

Packages whose tests need MySQL uncomment the mysql service in compose.yml, mirroring the db_image / db_env_json / db_port values they declare in webware-ci.json.