Command line application for Phalcon - generators, introspection and project tooling.
- PHP
^8.1 - Phalcon, either the
ext-phalconC extension (^5.18) or thephalcon/phalconPHP implementation (^6) - crest itself needs neither to run
In a project:
composer require --dev phalcon/crest
To create projects, also install crest globally. The global composer vendor/bin
directory must be in your PATH:
composer global require phalcon/crest
Run crest in a project. The commands that work on the project need the project
autoloader and its Phalcon, so a global crest passes them to the project's
vendor/bin/crest and returns its exit status:
crest list available commands
crest about environment and version report
crest make:action GET /company/all
new, init, up, down, install and --version always run in the crest that you
type. Without a global crest, run vendor/bin/crest in the project, or ./crest on a
host with docker and no PHP.
crest finds the project by its crest.php: the file that --config names, or the
nearest crest.php above the working directory or --directory. Without crest.php,
crest stops and tells you to run crest init. If the project has no vendor/bin/crest
yet, crest stops and tells you to run crest install or composer install, or
composer require --dev phalcon/crest when the project does not require crest.
To create a project, use the global crest. The new project requires phalcon/crest, so
after composer install it has its own vendor/bin/crest:
crest new my-app create an ADR project
In a terminal, new asks for each value that no option gives. --no-interaction takes
the defaults:
| Option | Purpose |
|---|---|
--namespace=<name> |
root namespace for the generated code; defaults to App |
--php=<major.minor> |
PHP version for composer.json and the Dockerfile; defaults to 8.4, and must be 8.1 or later |
--phalcon=v5|v6 |
v5 requires the C extension, 5.18 or later; v6 the phalcon/phalcon package; defaults to v5 |
--runtime=host|docker |
where the project commands run (the runtime key of crest.php); defaults to docker |
--service=<name> |
the docker compose service, for docker; defaults to app |
--force |
write into a directory that is not empty, and overwrite files with the same names |
new also writes ./crest, a launcher for a host with docker and no PHP. ./crest up,
./crest down and ./crest install run docker compose on the host: they start the
containers, stop them, and install the dependencies. All other commands run
vendor/bin/crest in the service of the project. Before ./crest install, they stop
with a hint. On Windows, run it in WSL2.
For an existing project, crest init writes crest.php:
crest init write crest.php for this project
| Option | Purpose |
|---|---|
--config=<file> |
explicit path to crest.php |
--directory=<dir> |
where crest starts to look for crest.php; for new and init, the directory to use |
--trace |
full exception trace |
--help, -h |
usage for the current command |
--quiet, -q |
suppress non-essential output |
--no-interaction, -n |
ask no questions; use the default answers |
--version |
crest version |
Each project has a crest.php at its root. crest new writes it. For an existing
project, crest init writes it. init proposes the values that it finds in the project:
the namespace and the folder of the first psr-4 entry whose folder exists, the front
controller <namespace>\AppFront when AppFront.php is in that folder, and the docker
runtime when the project has a compose file. It asks you to confirm each one.
--no-interaction accepts the proposals. --force overwrites an existing crest.php.
return [
'flavor' => 'adr',
'namespace' => 'App',
'bootstrap' => App\AppFront::class,
'paths' => [
'action' => 'src/Action',
'command' => 'src/Command',
'middleware' => 'src/Middleware',
'provider' => 'src/Provider',
'responder' => 'src/Responder',
],
'runtime' => ['type' => 'docker', 'service' => 'app'],
];A key that is not in the file takes its default: flavor adr, namespace App, the
ADR paths above, and the host runtime.
runtime says where the project commands run. With ['type' => 'host'], a global crest
runs the project's vendor/bin/crest with the PHP of the host. With
['type' => 'docker', 'service' => 'app'], it runs
docker compose exec app vendor/bin/crest ... in the project root. Use docker when
Phalcon is only in the container, for example a v5 project on a host without
ext-phalcon. The containers must be up (crest up). The service must mount the project
folder, with vendor/ in it, and its working_dir must be the project root. The compose
file of crest new does this. crest install runs composer in the same service. With the
host runtime, it uses the service app; run composer install on the host instead.
crest serve always runs on the host: PHP's built-in server must listen there. With
docker, crest up serves the project.
Namespaces are resolved from your psr-4 map, so a path must be covered by an autoload rule -
src/Action under App\ => src/ becomes App\Action. If you write to a directory your
autoloader does not cover, declare the namespace outright:
return [
'paths' => ['action' => 'app/Handlers'],
'namespaces' => ['action' => 'Shop\Handlers'],
];container:list and event:list report services and listeners, which exist only once the
application has registered them, so those two start your front controller. Name it in
crest.php:
return [
'bootstrap' => App\Front\ApiFront::class,
];The class is constructed with the project root and has to declare boot(). There is no
base class and no interface - boot() is the whole contract, and what it returns has to
implement Phalcon\Contracts\Container\Service\Collection, which
Phalcon\Container\Container does. See docs/index.md for the rest.
Every other command - the generators, about, config:show and route:list - reads the
filesystem and keeps working on a project that does not currently run.
Copy a stub into resources/stubs/<flavor>/ in your project and crest uses yours instead
of the packaged one.
The project-* stubs that new renders are published by name only. See
docs/index.md.
docker compose up -d
docker exec crest-app composer install
docker exec crest-app composer test
docker exec crest-app composer cs
docker exec crest-app composer analyze
Set PHALCON_VARIANT=v6 in .env and rebuild to test against phalcon/phalcon instead
of the C extension.
BSD-3-Clause. See LICENSE.