Basic Dependencies Example

This page explains dependencies (sources) by building upon the environments example. 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.

Recursive Dependency

A recursive dependency is described by a source without a related directory. It points to the root directory of the package and enables self-maintenance.

Let's make this example link itself. Modify the content in the production file fusion.json as follows:

                {
    "name": "Package",
    "description": "Basic example package.",
    "id": "valvoid/package",
    "version": "0.1.0",
    "structure": {
        "gitlab.com/valvoid/'fusion/'php": "package/==1.0.0-dev:main",
        "/cache": "cache"
    },
    "environment": {
        "php": {
            "version": "8.1.0"
        }
    }
}

Note that the source is a key-value pair. Like the directory entry, it can also be a key segmented by a forward slash separator. To differentiate between the two associative key types, unlike the directory, the source does not start with a forward slash. Additionally, in order to explain as much as possible in this example, the source is built as follows:

The source starts with the gitlab.com API.
The superset /valvoid/'fusion/'php/package path, which represents the package identifier valvoid/package without the segments with the single-quote prefix '.
The ==1.0.0-dev:main offset reference to pull the last commit in the main branch, which Fusion then handles as the 1.0.0-dev version.

Since sources link only production packages, reset the recursive source for the shared development. Modify the shared fusion.dev.php file as follows:

                <?php

// metadata array
return [
    "structure" => [

        // directory prefix segments
        // relative to package root
        "/cache/loadable/tests" => "Valvoid\Package\Tests",

        // API
        "gitlab.com" => [

            // path
            "valvoid" => [
                "'fusion" => [
                    "'php" => [
                        "package" =>

                            // reference
                            null
                    ]
                ]
            ]
        ]
    ]
];

To illustrate the overlay and reset logic within the parser/normalizer, the source is completely segmented. This is how both directory and source entries appear during the overlay process. The reset value null must be the last segment. Otherwise, the parser creates two different source entries.

For example, if you attempt to reset the source at the 'php segment, the value would look like this:

                // ...
"'php" => [
    "package" => "==1.0.0-dev:main",
    null
]

In your terminal, set the working directory to any directory within the package and execute the following build command:

                php fusion build

Once done, the /cache directory will contain the files snapshot.json, snapshot.dev.json, and snapshot.local.json, created by the helper snap task. Share and publish these files (even if empty) to enable replication for your package.

Nested Dependency

A nested dependency is described by a source that points to a directory relative to the package root.

For further examples in the Extensions chapter, we will need Fusion as a dependency. To prepare for this, you could (but don't do this yet) modify the content in the production file fusion.json as follows:

                {
    "name": "Package",
    "description": "Basic example package.",
    "id": "valvoid/package",
    "version": "0.1.0",
    "structure": {
        "/cache": "cache",
        "gitlab.com/valvoid": {
            "'fusion/'php/": "package/1.0.0-dev:main",
            "/dependencies": "fusion/'php/'code/1.0.0"
        }
    },
    "environment": {
        "php": {
            "version": "8.1.0"
        }
    }
}

Note that in this example metadata, both sources share a common prefix that also wraps Fusion's directory. Within developer-optimized input, you can split sources and directories by segments and mix them as needed. As mentioned above, the directory key starts with a slash /.

Alright, back to the "(but don't do this yet)" part. Modify the content in the production file fusion.json as follows:

                {
    "name": "Package",
    "description": "Basic example package.",
    "id": "valvoid/package",
    "version": "0.1.0",
    "structure": {
        "gitlab.com/valvoid/'fusion/'php": "package/==1.0.0-dev:main",
        "/cache": "cache",
        "/dependencies": [
            "valvoid.com/valvoid/fusion/1.0.0"
        ]
    },
    "environment": {
        "php": {
            "version": "8.1.0"
        }
    }
}

Since Fusion is a real-world default package, this metadata describes a pull from the default registry. It is recommended to pull production releases if possible. Use development platform APIs only for development purposes.

Now, execute the following build command again:

                php fusion build

Once done, the snapshot.json file in the /cache directory will contain the following content:

                {
    "valvoid/fusion": "1.0.0"
}

On This Page

Recursive Dependency

Nested Dependency