Basic Package Example

Production Metadata

To use Fusion in your project, you need at least a production metadata file at the root directory.

Because of this requirement, we start by creating the fusion.json file in an empty directory of your choice with the following dummy content:

                {
    "name": "Package",
    "description": "Example package.",
    "id": "valvoid/package",
    "version": "0.1.0",
    "structure": {
        "/state": "stateful"
    },
    "environment": {
        "php": {
            "version": "8.1.0"
        }
    }
}
            

This minimal metadata defines all required primitive, structure, and environment entries. For now, the package id and stateful directory indicator are the most relevant, as the next sections build on them.

After this step, our project directory contains:

• fusion.json

Loadable Code

Most packages have loadable code files with application logic, which Fusion automatically indexes by namespace and package id from the metadata.

To illustrate this, we create two hello-world-like dummy files, each returning its own code type and using a namespace that corresponds to the dummy package identifier valvoid/package defined earlier:

• Package.php: lazy auto-loadable class
• util.php: preloadable ASAP (as soon as possible) script

For lazy, on-demand code, create a src directory in the root of the package, and add a file Package.php inside it with the following code:

                namespace Valvoid\Package;

class Package
{
    public function getCodeType(): string
    {
        return "Lazy";
    }
}
            

For ASAP code, create a Util directory inside the previously created src directory, and add a file util.php inside it with the following content:

                namespace Valvoid\Package\Util;

function getCodeType(): string
{
    return "ASAP";
}
            

Now Fusion can scan our project directory and index the code:

• src
  • Util
    • util.php
  • Package.php
• fusion.json

State Directory

Earlier, we created dummy metadata with a stateful directory indicator. This tells Fusion to store generated data for our package in the state directory, which does not exist yet. To generate it, open a terminal in the project root and run the lightweight register command:

                fusion register
            

Once done, the project directory now includes the generated PrefixAutoloader.php in the state directory, along with other files Fusion creates (not shown here for simplicity):

• src
  • Util
    • util.php
  • Package.php
• state
  • PrefixAutoloader.php
• fusion.json

The generated PrefixAutoloader.php is the file you require when booting your application. Let's say, in our example, the project is a standalone package we can interact with via the terminal. To boot it, create a cli.php file at the root of the project with the following content:

                use Valvoid\Package\Package;

require __DIR__ . "/state/PrefixAutoloader.php";

$autoloader = new PrefixAutoloader;
$autoloader->register();

$package = new Package;

echo $package->getCodeType() . " code\n";
echo Valvoid\Package\Util\getCodeType() . " code\n";
            

Running this script should output:

                Lazy code
ASAP code
            

This demonstrates that Fusion has correctly indexed and loaded both lazy and ASAP code from our package.