Basic Custom Serializer Example

This page explains the basic steps for creating a custom log serializer that extends Fusion. The example builds on the basic extender package example, so it assumes that you have already implemented that setup. For the complete result of this example, see the GitLab repository. Note that this repository contains content for other examples as well, as the documentation uses a single package for all examples.

Additionally, for real-world examples and potential workloads, refer to Fusion's default serializers located in the /src/Log/Serializers directory.

Source Code

The relative root for all the directories within this section is the extension group within the custom source code files directory.

Serializer

To maintain consistency with the original package, it is recommended to follow the existing implementation pattern within stackable extension. Create the directory /Log/Serializers/Custom and add the Custom.php file with the following content:

                <?php

namespace Valvoid\Fusion\Valvoid\Package\Log\Serializers\Custom;

use Valvoid\Fusion\Log\Events\Event;
use Valvoid\Fusion\Log\Events\Level;
use Valvoid\Fusion\Log\Serializers\Streams\Stream;

class Custom implements Stream
{
    public function __construct(array $config)
    {
    }

    public function log(Level $level, string|Event $event): void
    {
        if ($event instanceof Id)
            echo "\n# Hi, custom serializer here. ---- " . 
                $event->getId();
    }
}

Note that the namespace prefix Valvoid\Fusion\Valvoid\Package consists of segments from two package identifiers. It starts with the origin package identifier, allowing Fusion to inflate the custom code, and it ends with extender identifier to prevent conflicts in case of multiple extensions.

In the root directory of the nested Fusion package, execute the inflate command:

                php fusion inflate

After running the command, the cached lazy.php file located in the /cache/loadable directory, relative to the nested Fusion package root, will contain the custom serializer along with the default entries:

                // Auto-generated by Fusion package manager. 
// Do not modify.
return [
    'Valvoid\Fusion\Valvoid\Package\Log\Serializers\Custom\Custom' => '/extensions/src/valvoid/package/Log/Serializers/Custom/Custom.php',
    // another entries
    // ...
];

The custom serializer is now loadable and can be added to the config. If required, optionally you can validate and manipulate the config for your serializer. To do so, inside the custom serializer directory /Log/Serializers/Custom, create the /Config directory and add at least one of the following config files:

Interpreter

Create the optional Interpreter.php file with the following content:

                <?php

namespace Valvoid\Fusion\Valvoid\Package\Log\Serializers\Custom\Config;

use Valvoid\Fusion\Config\Interpreter as ConfigInterpreter;

class Interpreter extends ConfigInterpreter
{
    public static function interpret(array $breadcrumb, mixed $entry): void
    {
    }
}

To make this file loadable, execute the inflate command again:

                php fusion inflate

The interpreter is the first file that gets called. It validates the static config to ensure that the parser and normalizer can handle it. In this case, it does nothing.

Parser

Create the optional Parser.php file with the following content:

                <?php

namespace Valvoid\Fusion\Valvoid\Package\Log\Serializers\Custom\Config;

use Valvoid\Fusion\Config\Parser as ConfigParser;

class Parser extends ConfigParser
{
    public static function parse(array $breadcrumb, array &$config): void
    {
    }
}

To make this file loadable, execute the inflate command again:

                php fusion inflate

The parser is the file that gets called after the interpreter. It prepares entries for overlay. In this case, it does nothing.

Normalizer

Create the optional Normalizer.php file with the following content:

                <?php

namespace Valvoid\Fusion\Valvoid\Package\Tasks\Custom\Config;

use Valvoid\Fusion\Config\Normalizer as ConfigNormalizer;

class Normalizer extends ConfigNormalizer
{
    public static function normalize(array $breadcrumb, array &$config): void
    {
    }
}

To make this file loadable, execute the inflate command again:

                php fusion inflate

The normalizer is the last file that gets called. It finalizes the config and ensures that all necessary values are set. In this case, it does nothing.

Config

In the custom config files directory, create the log.php file with the following content:

                <?php

use Valvoid\Fusion\Valvoid\Package\Log\Serializers\Custom\Custom;

return [
    "log" => [
        "serializers" => [
            "custom" => Custom::class,
        ]
    ]
];

Now, execute one of the commands. For example, the inflate command to see the duplicated output:

                php fusion inflate

On This Page

Source Code

Serializer

Interpreter

Parser

Normalizer

Config