Valvoıd.
search hotlink icon profile hotlink icon

Basic Custom Task Example

This page explains the basic steps for creating a custom task 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 tasks located in the /src/Tasks directory.

On This Page

Source Code

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

Task

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

                <?php

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

use Valvoid\Fusion\Log\Log;
use Valvoid\Fusion\Tasks\Task;

class Custom extends Task
{
    public function execute(): void
    {
        Log::info($this->config["message"]);
    }
}

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 task along with the default entries: 

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

The custom task is now loadable and can be added to the config. If required, optionally you can validate and manipulate the config for your task. To do so, inside the custom task directory /Tasks/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\Tasks\Custom\Config;

use Valvoid\Fusion\Bus\Bus;
use Valvoid\Fusion\Bus\Events\Config as ConfigEvent;
use Valvoid\Fusion\Config\Interpreter as ConfigInterpreter;
use Valvoid\Fusion\Log\Events\Level;

class Interpreter extends ConfigInterpreter
{
    public static function interpret(array $breadcrumb, mixed $entry): void
    {
        if (isset($entry["message"]) && $entry["message"] == "")
            Bus::broadcast(new ConfigEvent(
                "The value of the \"message\" " .
                "index must be a non-empty string.",
                Level::ERROR,
                [...$breadcrumb, "message"]
            ));
    }
}

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 notifies an error if the message is an empty string.

Parser

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

                <?php

namespace Valvoid\Fusion\Valvoid\Package\Tasks\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
    {
        $config["message"] ??= "### normalized message value";
    }
}

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 provides a default message value if none has been specified, ensuring the task can proceed with the required configuration.

Config

The working directory for all the files within this section is the extension group within the custom config files directory.

Individual Task

Create the tasks.php file with the following content: 

                <?php

use Valvoid\Fusion\Valvoid\Package\Tasks\Custom\Custom;

return [
    "tasks" => [
    
        // task ID key
        // configured task value
        "custom" => [
            "task" => Custom::class,
            "message" => "### static message value"
        ]
    ]
];

Execute the custom command: 

                php fusion custom

Since the config contains the configured task (array value), you should see the output with the static message: 

                 ___ _   _ ___ ___ ___  _  _
| __| | | / __|_ _/ _ \| \| |
| _|| |_| \__ \| | (_) | .` |
|_|  \___/|___/___\___/|_|\_|
------
boot via command line interface
execute custom id
### static message value

Now, change the content of the tasks.php file as follows to rely on the default task behavior, and run the custom command again: 

                <?php

use Valvoid\Fusion\Valvoid\Package\Tasks\Custom\Custom;

return [
    "tasks" => [
    
        // task ID key
        // default task value
        "custom" => Custom::class
    ]
];

You should now see the output with the normalized message: 

                 ___ _   _ ___ ___ ___  _  _
| __| | | / __|_ _/ _ \| \| |
| _|| |_| \__ \| | (_) | .` |
|_|  \___/|___/___\___/|_|\_|
------
boot via command line interface
execute custom id
### normalized message value

Finally, pass the runtime layer config to see the dynamic message: 

                php fusion custom message="### runtime message value"

Task Group

Your task can also be in a group. Change the content of the tasks.php file as follows: 

                <?php

use Valvoid\Fusion\Tasks\Image\Image;
use Valvoid\Fusion\Valvoid\Package\Tasks\Custom\Custom;

return [
    "tasks" => [
        "custom" => [
        
            // default task
            "image" => Image::class,
            "custom" => Custom::class
        ]
    ]
];

If you now pass the runtime config, prefix the message key with the custom task key separated by a dot .: 

                php fusion custom custom.message="### runtime message value"

The output should be: 

                 ___ _   _ ___ ___ ___  _  _
| __| | | / __|_ _/ _ \| \| |
| _|| |_| \__ \| | (_) | .` |
|_|  \___/|___/___\___/|_|\_|
------
boot via command line interface
execute custom id

image
image internal metas
[=| valvoid/package | 0.1.0
[=| valvoid/fusion | 1.0.0

custom
### runtime message value