A sample REST API for the Phalcon Framework. It showcases JWT authentication, a JSON:API response layer (sparse fieldsets, includes, sorting), a lazy middleware chain, and the model / repository / transformer split behind it.

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

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

cp resources/.env.example .env
docker compose up -d --build

# Create the database schema (migrations are not run on boot)
docker compose exec app composer install
docker compose exec app composer migrate

The API is then served at http://localhost:8080. There are no bundled fixtures, so every collection starts empty; see docs/usage.md for the request and response format and how authentication works.

Note: app is the Compose service name, used as-is by docker compose exec. The running container is named ${PROJECT_PREFIX}-app (rest-api-app by default, set via PROJECT_PREFIX in .env). If you address it with plain docker exec, use the container name, e.g. docker exec rest-api-app composer migrate.

docker compose up -d --build                      # v5 (C extension, default)
PHALCON_VARIANT=v6 docker compose up -d --build   # v6 (phalcon/phalcon)

PHP_VERSION=8.1 docker compose up -d --build       # pick a PHP version (8.1+)

The two Phalcon variants are mutually exclusive: the v5 image installs the C extension, the v6 image installs the pure-PHP package instead. APP_PORT in .env changes the host port, so this app can run alongside the other Phalcon sample applications. docs/installation.md covers running several versions side by side.

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

composer create-project phalcon/rest-api rest-api
cd rest-api

The post-create hook copies resources/.env.example to .env and prints the next steps. docs/installation.md has the full local walkthrough (installing the Phalcon extension with PIE, the database, and serving).

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.

• JWT authentication - JSON Web Tokens let a client authenticate once at /login and then carry a bearer token; the token lifetime is configurable in .env.
• JSON:API responses - every response follows the JSON:API standard: a uniform envelope, compound documents, includes (related data), sparse fieldsets, and sorting.
• A lazy middleware chain - NotFound, Authentication, and Response, each attached to the Micro application and resolved only when a request reaches it.
• Public fields are opt-in per model - a model declares exactly which columns the API may publish, so adding a column never exposes it by accident (Users, for instance, never returns its password or token secrets).

See docs/usage.md for the endpoints, query parameters, and response format.

The suite is split into four PHPUnit testsuites - unit, integration, api, and cli - orchestrated by phalcon/talon. The api suite drives the running application over real HTTP, so it needs the web server up (nginx in the Docker stack, reached via TALON_REST_URL in tests/.env.test).

docker compose exec app composer migrate    # once - create the schema
docker compose exec app composer test       # the default (unit) suite
docker compose exec app vendor/bin/talon run all   # every suite, one process each

composer test-mutation runs Infection. The dependency is not shipped - it pulls thecodingmachine/safe at dev-master, which deprecation-warns on newer PHP - so install it on demand:

docker compose exec app composer require --dev infection/infection
docker compose exec app composer test-mutation
docker compose exec app composer remove --dev infection/infection

The configuration in resources/infection.json5 stays in the repository. Runs are single-threaded on purpose: the suite shares one MySQL database, so parallel mutants would corrupt each other's data.

Follows the PDS skeleton:

bin/        command-line entry point (bin/cli)
public/     web server root (index.php)
resources/  tooling configs, docker, phinx, migrations
src/        application source
tests/      PHPUnit suites (unit, integration, api, cli)
storage/    runtime cache and logs

• docs/installation.md - Docker and local (non-Docker) setup
• docs/usage.md - endpoints, includes, sparse fields, sorting, and the response format

Phalcon REST API is open-sourced software licensed under the New BSD License. See LICENSE.