Download the PHP package phalcon/vokuro without Composer

Vökuró

Vökuró is the sample application for the Phalcon Framework. It showcases authentication, ACL-based permissions, user/profile management, forms, mailing and more.

It runs on Phalcon v5 (the C extension, default) and on Phalcon v6 (the phalcon/phalcon package, currently alpha) from the same source.

Requirements

• PHP 8.1 - 8.5
• MySQL 8.0 (provided by the Docker stack)
• Docker + Docker Compose (recommended), or a local PHP with the Phalcon extension (see docs/installation.md)

Quick start (Docker)

Note: app is the Compose service name, used as-is by docker compose exec above. The running container, however, is named ${PROJECT_PREFIX}-app - vokuro-app by default, set via PROJECT_PREFIX in .env. If you address it with plain docker exec, type your container name instead, e.g. docker exec vokuro-app composer migrate (substitute your own prefix).

Then open:

• Application: http://localhost:8080
• Mailpit (captured e-mails): http://localhost:8025

The container waits for MySQL and serves the app; migrations are decoupled from boot - apply them with the commands above. Log in with one of the seeded accounts, e.g. [email protected] / password1.

Choosing the Phalcon version

The two are mutually exclusive: the v5 image installs the C extension, the v6 image installs the pure-PHP package instead.

Choosing the PHP version

The image is built for one PHP version at a time, selected with the PHP_VERSION build arg (default 8.5; supported 8.1-8.5):

PIE compiles the Phalcon C extension (and pcov) from source for the selected version. The container keeps the same name (vokuro-app), so each rebuild replaces the previous one. To run several versions side by side, give each its own Compose project and prefix:

Quick start (Composer)

Prefer a local PHP over Docker? Bootstrap a fresh copy straight from Packagist:

The post-create hook copies resources/.env.example to .env and prints the next steps; docs/installation.md has the full local walkthrough (environment, database, serving). Out of the box the app runs on the bundled phalcon/phalcon (v6) package - no extension needed. To run on the Phalcon v5 C extension instead, install it with PIE as described in step 1 of the local setup; once the extension is loaded, PHP prefers it automatically and the bundled v6 package is simply shadowed - it can stay installed.

Composer scripts

Run them inside the container, e.g. docker compose exec app composer cs:

composer analyze resolves Phalcon classes from the phalcon/phalcon (v6) source, so run it where the v5 C extension is not loaded (the CI quality job, or a plain host). The coding-standard and test scripts are unaffected.

Debug Bar

Vökuró wires up the Phalcon debug bar. A single events manager is registered as a shared service (src/Providers/EventsManagerProvider.php) and handed to the database, view, router, and dispatcher providers; src/Providers/DebugBarProvider.php then boots the bar against the application. Once the app is running, a status bar appears at the bottom of every HTML page with per-request diagnostics - timing, the matched route, database queries and their bound parameters, rendered views, and the session, config, and request data.

The bar runs in development only. It is gated by APP_ENV, which resources/.env.example sets to development; it does not boot when APP_ENV is production or prod. See the debug bar package for configuration and the full list of collectors.

Running the tests

The suite is split into three PHPUnit testsuites - unit, functional, and browser (in-process browser testing through phalcon/talon). The Docker stack provides everything they need: a seeded MySQL database and a Mailpit SMTP catcher, so no e-mail ever leaves the host.

Test secrets

The test configuration lives in tests/.env.test and is loaded automatically by tests/bootstrap.php - you do not need to supply anything by hand:

Real OS / CI environment variables take precedence over tests/.env.test, so the same suite runs unchanged inside Docker (service-name hosts mysql / mailpit) and on a native host or in CI (loopback 127.0.0.1). The only secret that is not local is SONAR_TOKEN, a GitHub Actions secret used solely by the sonarqube job.

Updating Phalcon

• v5 - bump PHALCON_V5_CONSTRAINT in resources/docker/Dockerfile and rebuild: docker compose build app. PIE compiles the C extension from source (this is the only way to update a C extension).
• v6 - docker compose exec app composer update phalcon/phalcon (no rebuild). Dependabot opens the bump PR automatically.

Project layout

Follows the PDS skeleton:

License

Vökuró is open-sourced software licensed under the New BSD License. See LICENSE.