Custom Package Manager Example

Production Metadata

Like any project, start by creating the fusion.json file in an empty directory of your choice with the following dummy content:

                {
    "name": "Package",
    "description": "Custom package manager.",
    "id": "valvoid/package",
    "version": "0.1.0",
    "structure": {
        "/config": ":valvoid/fusion/config",
        "/dependencies": "valvoid.com/valvoid/fusion/2.0.0",
        "/state": "stateful"
    },
    "environment": {
        "php": {
            "version": "8.2.0"
        }
    }
}
            

Beyond the required basic entries, the metadata declares Fusion as a dependency and maps its exposed configuration path to the project's own config path. For this example, the path does not need to point to an existing directory, so the build command can be run directly from the project directory:

                fusion build
            

Once complete, the project directory includes the downloaded Fusion package with the generated extensions.php file in the state directory (other files not shown here for simplicity):

• dependencies
  • valvoid/fusion: Nested Fusion package
    • state/extensions.php: Built-in extension
• fusion.json

This file is where the built-in extension logic records the mapped directories as a persistence layer. In this example, it contains the following simplified content:

                return [

    // Fusion's virtual path
    "/config" => [
    
        // mapped to ordered custom extension
        1 => "/config",
    ]
];
            

Now, when loading the configuration, Fusion reads the mapped config directory on top of its own default files, allowing the customization to be applied or completely override the defaults.

User-Wide Terminal Interaction

Fusion isolates the user scoped config, state, and cache paths using the root package identifier, which you can list with the -p option:

                fusion -p
            

For the standalone version, these paths end with the case-insensitive valvoid/fusion segments. Running the nested version from its root directory shows paths ending with valvoid/package segments:

                php ./dependencies/valvoid/fusion/fusion -p
            

Due to this separation, the in-development custom package manager can run user-wide alongside the standalone installation without conflicts. The system already includes the standalone fusion executable, so link the user-wide version as custom-fusion:

• dependencies
  • valvoid/fusion: Nested Fusion package
    • fusion: CLI file we link

Linux and macOS Commands

Ensure the user-wide binary directory exists:

                mkdir -p $HOME/.local/bin
            

From the project root, link Fusion's CLI file to the user-wide binary directory:

                ln -s $PWD/dependencies/valvoid/fusion/fusion $HOME/.local/bin/custom-fusion
            

The file used to extend the PATH variable for user-wide binaries depends on your shell. On Linux, Bash users typically update .bashrc, while on macOS, Zsh users typically update .zshrc. If the appropriate file does not exist, create it in your home directory. For other shells, locate the configuration file yourself and ensure it is loaded by your shell so the user-wide Fusion CLI is available in future sessions:

                echo '
if [ -d "$HOME/.local/bin" ]; then
    case ":$PATH:" in
        *":$HOME/.local/bin:"*) ;;
        *) PATH="$HOME/.local/bin:$PATH"; export PATH ;;
    esac
fi
' >> ~/.bashrc
            

Reload your shell:

                source ~/.bashrc
            

Verify the installation:

                custom-fusion -v
            

Windows Commands

Ensure the user-wide binary directory exists:

                New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\bin"
            

From the project root, create a launcher batch file pointing to the CLI file:

                Set-Content "$env:USERPROFILE\bin\custom-fusion.bat" `
    -Value '@php "%CD%\dependencies\valvoid\fusion\fusion" %*'
            

Add the binary directory to your PATH variable (takes effect in new sessions) and restart PowerShell or open a new session to load it:

                setx PATH "$env:USERPROFILE\bin;$env:PATH"
            

Verify the installation:

                custom-fusion -v