Structure Schema

On This Page

Sources

The sources entry contains required packages represented by external inline sources, consisting of segments separated by forward slashes, and directories indicating where to save them.

By default, the value is an empty array, or, for example, a package like Fusion may contain a recursive entry to maintain itself, such as:

                $metadata["structure"]["sources"] = [

    // empty
    // recursive root directory
    // location inside structure
    // override itself
    "" => [
    
        // normalized array of entries
        // in this case
        // recursive root is only one entry
        "valvoid.com/valvoid/fusion/1.0.0"
        
        // no other sources ...
    ]
];
            

In addition to recursive entry, the value may contain nested entries, such as:

                $metadata["structure"]["sources"] = [

    // nested relative to root directory
    // location inside structure
    "/dependencies" => [
    
        // exclude non-ID segments
        // 'php/'code
        "gitlab.com/valvoid/fusion/'php/'code/1.0.0"
        
        // more nth sources ...
    ]
];
            

Directory

As shown in the examples above, the associative array key directory has the following properties:

• Relative to own package root directory.
• Points to an array value containing one or more sources.
• Is an empty recursive "" or a nested directory like /dependencies that starts with a forward slash.

API

The first separated segment of each source corresponds to one of the configured hub APIs:

• valvoid.com
• gitlab.com
• github.com
• bitbucket.org
• git
• dir

Path

The source segments in the middle, between the first API segment and the last reference segment, represent the path to the package on the external host, which, depending on the platform, may include a naming convention such as package, organization/project, project, or whatever identifier.

Additionally, the path segments also serve as the package identifier segments. In the case of a superset path, non-identifier segments are excluded by the single quote ' character prefix. As shown in the second example above, this approach can also apply to a local machine filesystem with non-canonical segments, such as:

                $metadata["structure"]["sources"] = [

    // nested relative to root directory
    // location inside structure
    "/dependencies" => [
    
        // git API root starts at projects parent dir 
        // then two parent dirs up to dev
        // exclude non-ID segments
        // '../'../'dev
        "git/'../'../'dev/valvoid/fusion/1.0.0"
        
        // more nth sources ...
    ]
];
            

Reference

The last source segment is a logical expression that the required package versions must satisfy. In addition to the semantic version, the expression may consist of the following parts:

• The && and || operators.
• The condition brackets ().
• The version tag name [a-zA-Z]{0, 10}} indicator.
• The offset : indicator.
• One of the signs as prefix before the version:
  • != not equal.
  • == equal.
  • >= bigger than or equal.
  • <= less than or equal.
  • > bigger than.
  • < less than.

In the first example above, Fusion requires itself by the 1.0.0 reference. This is shorthand for >=1.0.0 && <2.0.0, indicating that the package version must be at least 1.0.0 but less than 2.0.0.

In the case where the source points to a VCS repository, the reference segment may consist of a version tag name prefix indicator, such as v1.2.3, or an offset, such as:

• ==v1.2.3-dev:main branch.
  • The explicit semantic "release" part -dev unlocks non-production versions.
• ==v1.2.3:541bae1712ad746fecc67b633ae4e1f2de73851e commit.
• ==v1.2.3+23453:v1.0.0 tag.

An absolute non-existing internal usage pseudo version followed by a real existing reference. A more complex example of the path example could therefore be as follows:

                $metadata["structure"]["sources"] = [

    // nested relative to root directory
    // location inside structure
    "/dependencies" => [
    
        // git API root starts at projects parent dir 
        // then two parent dirs up to dev
        // exclude non-ID segments
        // '../'../'dev
        "git/'../'../'dev/example/package/basic/" .
        
            // production only
            "!=v1.0.0 || " . 
            
            // illogical && condition
            "(v1.0.3 && ==v1.2.3:541bae1712ad746fecc67b633ae4e1f2de73851e) || ". 
            
            // get all >=v1.0.0-dev && <2.0.0
            "v1.0.0-dev"
        
        // more nth sources ...
    ]
];
            

Due to the last pattern v1.0.0-dev, the following tag references would be satisfiable:

• v1.34.2
• v1.34.2-whatever+23453
• v1.0.0+23453
• v1.0.0-dev

Cache

The cache entry contains a directory where Fusion stores generated content, such as:

                $metadata["structure"]["cache"] = [
    
    // normalized array value
    // actually only one directory
    "/cache"
];
            

As the example shows, the directory has the following properties:

• Relative to own package root directory.
• Starts with a forward slash.

Namespaces

The namespaces entry contains custom namespace-related code structures maintained by the inflate task. By default, the value is an empty array. The inflate task stores all identified code in the common loadable cache subdirectory because the package identifier segments are always a subset of the namespace segments. An explicit entry changes/extends this behavior.

For example, Fusion publishes along with the code its own inflated production registry for out-of-the-box usage and therefore separates its test code in the development file as follows:

                $metadata["structure"]["namespaces"] = [

    // cache test code with namespace prefix
    // in /cache/loadable/tests subdirectory 
    "Valvoid\Fusion\Tests" => "/tests"
];
            

As the example shows, this description instructs the inflate task to extract the code with the namespace prefix Valvoid\Fusion\Tests into the separate subdirectory /tests.

Extensions

The extensions entry contains directories for customization. By default, it's an empty array, but in some cases, like Fusion, it can include directories such as:

                $metadata["structure"]["extensions"] = [

    // relative to root
    // leading forward slash
    "/extensions/config",
    "/extensions/src"
    
    // nth ...
];
            

As the example shows, each directory has the following properties:

• Relative to own package root directory.
• Starts with a forward slash.