Phel comes with some configuration options. They are stored in the composer.json file in the extra section.


These are all Phel specific configuration options available.

"extra": {
    "phel": {
        "loader": {
            "hello-world\\": "src/"
        "loader-dev": {
            "hello-world\\tests\\": "tests/"
        "tests": [
        "export": {
            "directories": [
            "namespace-prefix": "PhelGenerated",
            "target-directory": "src/PhelGenerated"

Options in detail#

This chapter contains all configuration options explained in detail.


Autoload mapping for a Phel autoloader.

The loader configuration defines a mapping from namespaces to paths. The paths are relative to the package root. When autoloading a module like hello-world\boot a namespace prefix hello-world pointing to a directory src/ means that the autoloader will look for a file named src/boot.phel and include it if present.

Namespace prefixes must end with a backslash (\\) to avoid conflicts between similar prefixes. For example hello would match modules in the hello-world namespace so the trailing backslashes solve the problem: hello\\ and hello-world\\ are distinct.

The loader references are all added whenever a package is updated or installed, to the Phel Runtime which can be found in the generated file vendor/PhelRuntime.php.


This section allows us to define autoload rules for development purposes.

Modules needed to run the test suite should not be included in the main autoload rules to avoid polluting the autoloader in production and when other people use the package as a dependency. Therefore, it is a good idea to rely on a dedicated path for your unit tests and to add it within the loader-dev section.

The loader-dev configuration section is equivalent to the loader configuration section. Namespaces and paths are defined in the same way.


This configuration entry defines a list of folders where the test files of a project can be found.


These configuration options are used for the Phel export command that is described in the PHP Interop chapter. Currently, the export command requires three options:

Phel Composer Plugin#

Phel Runtime is configured automatically by the plugin. Whenever a package is updated or installed a file is generated in vendor/PhelRuntime.php. This file initializes the Phel Runtime according to the defined loader and loader-dev configuration options.

The generated Runtime can be loaded like this.

// src/index.php

$rt = require __DIR__ .'/../vendor/PhelRuntime.php';


The source of Phel's composer plugin can be found in a separate repository.

Manually initializing and configuring the Runtime#

It is possible to manually initialize and configure the Runtime as shown in this example.

// src/index.php

use Phel\Runtime\RuntimeSingleton;

require __DIR__ .'/../vendor/autoload.php';

$rt = RuntimeSingleton::initialize();
$rt->addPath('hello-world\\', [__DIR__]);