[TOC]
Nix is probably the easiest way to set up the development environment.
Before you start, make sure that Nix is installed. If it is not installed, follow the official documentation to install it.
After you install Nix, go to the project folder and run this command to start your development environment:
nix-shellThe first time that you use Nix, the download of all the dependencies takes some time.
For full isolation, use the
nix-shell --purecommand. Nix then isolates your development environment from the system.
This command gives you all the tools and dependencies of the project in a new shell. The default shell has Node.js 24.
By default, the shell uses Starship for the bash prompt.
To override it, create /.nix/shell/starship.toml from the /.nix/shell/starship.toml.dist file.
After a change, run nix-shell again to apply it.
To use the php version from nix in your IDE, start a nix shell with nix-shell
and type:
type phpThis command shows the path to the php version of the nix shell. The output looks like this:
php is /nix/store/p2m5bamh01ncpwjxscdl11p2m9xy8aq6-php-with-extensions-8.x.y/bin/phpThe nix shell has a predefined php.ini. If it is not sufficient for you, create your own php.ini file at this path:
./.nix/php/lib/php.ini
If that file is not there, the shell uses the default php.ini.dist from the same location.
pcov: necessary for code coverage
To start the nix shell without the pcov extension, use the --arg with-pcov false flag:
nix-shell --arg with-pcov falseTo configure pcov, create a file ./.nix/php/lib/pcov.ini with your pcov configuration.
xdebug: necessary for debugging
To install the xdebug extension, start the nix shell with the --arg with-xdebug true flag:
nix-shell --arg with-xdebug trueTo configure xdebug, create a file ./.nix/php/lib/xdebug.ini with your xdebug configuration.
blackfire: necessary for profiling
To install the blackfire extension, start the nix shell with the --arg with-blackfire true flag:
nix-shell --arg with-blackfire trueThe flag also appends ./.nix/php/lib/benchmark.ini.dist to php.ini, as --arg with-php-benchmark true does. A
profile then runs with the same OPcache, JIT and zend.assertions configuration as a timed run.
To configure blackfire, create a file ./.nix/php/lib/blackfire.ini with your blackfire configuration.
gh, composer and blackfire in the nix shell run through fnox.
fnox reads the secrets below from the provider that you choose. It gives them to the tool only. Nothing is exported to the shell.
| Secret | Used by | Becomes |
|---|---|---|
GH_TOKEN |
gh, composer |
GH_TOKEN, COMPOSER_AUTH |
BLACKFIRE_CLIENT_ID |
blackfire |
BLACKFIRE_CLIENT_ID |
BLACKFIRE_CLIENT_TOKEN |
blackfire |
BLACKFIRE_CLIENT_TOKEN |
fnox.toml names the secrets. Your provider goes into fnox.local.toml, which git ignores. Without that file, the
tools run without secrets.
To use them, add a [providers] section and the three secrets to fnox.local.toml. The
fnox providers page shows the configuration of each provider.
An example for 1Password, where each value is item/field in the vault:
if_missing = "error"
[providers.op]
type = "1password"
vault = "my-vault"
[secrets]
GH_TOKEN = { provider = "op", value = "github-token/credential" }
BLACKFIRE_CLIENT_ID = { provider = "op", value = "blackfire/client-id" }
BLACKFIRE_CLIENT_TOKEN = { provider = "op", value = "blackfire/credential" }fnox runs the op CLI from your PATH. With if_missing = "error", a secret that fnox cannot read stops the tool
with the reason.
A COMPOSER_AUTH that you set yourself is kept. A command that prints its own secret, such as gh auth token, shows
it.
The default shell runs PHP with a development configuration. OPcache is off for the CLI, so the JIT is also off.
zend.assertions is 1. pcov is loaded. To time Flow with a production configuration:
nix-shell --arg with-php-benchmark trueThe flag removes pcov, xdebug and blackfire. If you combine the flag with one of them, the shell fails at evaluation.
The flag appends ./.nix/php/lib/benchmark.ini.dist to php.ini:
opcache.enable=1
opcache.enable_cli=1
opcache.jit=tracing
opcache.jit_buffer_size=128M
opcache.memory_consumption=256
opcache.interned_strings_buffer=32
opcache.max_accelerated_files=20000
opcache.validate_timestamps=1
zend.assertions=-1On Linux, the flag also sets opcache.huge_code_pages=1. To override a value, create ./.nix/php/lib/benchmark.ini.
To change the PHP version, start the nix shell with the --arg php-version 8.3 flag:
nix-shell --arg php-version 8.3Usually, do not change the PHP version. Development must always use the lowest supported PHP version.
This feature is mostly for tests of new integrations or of the lowest and highest versions of dependencies.
The nix shell has optional tool groups. You enable each group with a flag. The default shell stays small, and you can still get the special tools.
nix-shell --arg with-wasm trueFor more information, read the WASM Interactive Playground Build page.
To add Terraform for infrastructure development:
nix-shell --arg with-terraform truenix-shell --arg with-pg-query-ext false --arg with-c trueFor more information, read the C pg-query Extension Development page.
nix-shell --arg with-rust truewith-arrow-ext and with-flow-php-ext both default to !with-rust. This one flag therefore turns off the prebuilt
extensions for both.
For more information, read the Rust Extension Development page.
This flag adds protoc and grpc_php_plugin to the shell. You need them to generate the OTLP protobuf and gRPC PHP
classes again with just gen-protobuf-otlp.
nix-shell --arg with-protoc trueThe default shell has the ext-protobuf and ext-grpc PHP extensions (with-protobuf / with-grpc, both default
true). To remove them, give false.
Each engine has its own flag. Enable only the engines that a comparison needs:
nix-shell --arg with-duckdb true --arg with-polars true --arg with-spark true --arg with-php-benchmark truewith-duckdbadds theduckdbCLI.with-polarsadds apython3withpolarsandpyarrow.with-sparkaddsspark-submitwith its JDK, without R.
The scripts and the measurement rules are on the Benchmarks page.
You can combine many arguments:
nix-shell --arg with-terraform true --arg with-wasm trueTo run the local webserver for the development of the Flow website, use the Symfony CLI app. The nix shell contains it.
cd web/landing
symfony proxy:start
symfony server:start -d For more information, read: