Internally, the metadata representing and describing the package consists of a
monolithic data structure with sequential and associative entries. This page
explains the schema of the structure
part of these entries.
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.
- The explicit semantic "release" part
==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.
States
The states
array entry may contain directories with mutable content that extend the
default behavior, where the shift task
only recycles the cache
folder.
For example, a website package might update its public
directory via the
copy lifecycle callback due to a new
dependency, and instruct Fusion to recycle this directory from the new state
prebuilt in the cache, as follows:
$metadata["structure"]["states"] = [
// relative to root
// leading forward slash
"/public"
// nth ...
];
As the example shows, each directory has the following properties:
- Relative to own package root directory.
- Starts with a forward slash.