Authoring libraries

    The reason to create a Phel library is to be able to use the same code across both PHP and Phel projects without manually copying the code around.

    Important files#

    There are two files to keep in mind while developing a Phel library:

    • composer.json
    • phel-config.php

    To better provide you with an example, you can view the source code of the first Phel library mabasic/phel-json. The library has been merged to core Phel in namespace phel\json, but you can still install it and see how it all works. Read more about phel\json in the blog post Release: v0.8.0.

    composer.json#

    The most important part in this file is the require section. In here, you need to declare which Phel version your library supports.

    "require": {
    "phel-lang/phel-lang": "^0.13"
}

    For example, the above code specifies that the library supports Phel starting from version 0.7 and up to version 1.0 when released. You can be more specific here or less specific depending on what you want to do. See Composer documentation for more info on version constraints.

    phel-config.php#

    Since the mabasic/phel-json library was written, there is a new way of writing the configuration file. The old way used an array (you can still use this today), but the newer way is much more elegant and preferred way of configuring your Phel project.

    Here is an example config:

    <?php
declare(strict_types=1);

use Phel\Config\PhelConfig;
use Phel\Config\PhelOutConfig;

return (new PhelConfig())
    ->setSrcDirs(['src'])
    ->setTestDirs(['tests'])
    ->setOut((new PhelOutConfig())
        ->setMainPhelNamespace('your-ns\main')
        ->setMainPhpPath('out/main.php'))
    ->setFormatDirs(['src', 'tests'])
    ->setIgnoreWhenBuilding(['local.phel'])
    ->setKeepGeneratedTempFiles(false);

    To find out more about what each configuration option means read the documentation for Configuration.

    Topics of interest#

    Namespaces#

    You can namespace your library however you want, but to keep to best practices your library should follow this convention: {username}\{library-name}.

    Read the documentation on Namespaces.

    Testing#

    Having tests for your library makes it more stable because you can easily see which Phel version makes your library not work.

    Read the documentation on Testing.

    PHP interop#

    This applies when you want to use your Phel library from PHP. Be sure to double check the configuration file.

    Read the documentation on PHP interop.

    Private code#

    When writing a library you get to decide what function, variables or macros you want to expose to the library users. This is important in cases where you don't want the library users to use a specific function or value for some reason.

    Available macros:

    • def- - Define a private value that will not be exported.
    • defn- - Define a private function that will not be exported.
    • defmacro- - Define a private macro that will not be exported.

    Publishing#

    Phel library is just like any PHP library in the sense that the process for publishing is the same. You login to Packagist and submit your repository. Then, you can install the library in your Phel or PHP application in the same way:

    # For example:
composer require mabasic/phel-json

    Happy Pheling!