--- outline: 'deep' --- # Artifact Model An **Artifact** is a core concept in the StaticPHP build system. It represents a source archive or pre-built binary required to build a package. Each artifact describes where to download the file, how to extract it, and the resulting path layout. Packages reference one or more artifacts via the `artifact` field to obtain the source code or binaries they need. ## Defining an Artifact Here is a minimal artifact object that points to a source archive (curl's source code): ```yaml &: source: type: ghrel repo: curl/curl match: curl.+\.tar\.xz prefer-stable: true ``` There are two ways to define an artifact and associate it with a package: **inline** (defined directly inside the package file) or **standalone** (defined in a separate file and referenced by name): ::: code-group ```yaml [Inline Artifact] # This is a package declaration curl: type: target artifact: source: type: ghrel repo: curl/curl match: curl.+\.tar\.xz prefer-stable: true ``` ```yaml [Standalone Artifact] # This is a standalone artifact declaration, typically placed under config/artifact/ curl-src: source: type: ghrel repo: curl/curl match: curl.+\.tar\.xz prefer-stable: true ``` ```yaml [Package Referencing a Standalone Artifact] # This is a package declaration curl: type: target artifact: curl-src ``` ::: ## Structure An artifact has three top-level sections: `source`, `binary`, and `metadata`. - `source` — the source code archive - `binary` — pre-built binaries for specific platforms - `metadata` — additional information such as license paths Both `source` and `binary` accept either an inline source object or a reference to a standalone artifact by name (as shown above). Full artifact object format: ```yaml &: source: {source-object} # (optional) binary: windows-x86_64: {source-object} # (optional) linux-x86_64: {source-object} # (optional) linux-aarch64: {source-object} # (optional) macos-x86_64: {source-object} # (optional) macos-aarch64: {source-object} # (optional) metadata: # (optional) license: "" # (optional) SPDX identifier license-files: ["LICENSE"] # License files from the source directory source-root: "subdir" # (optional) Use if the actual source root is inside a subdirectory ``` The basic format of a `source-object`: ```yaml &: type: "url" # Download type # ...: Additional keys depend on the type; see below extract: "path/to/dir" # (optional) Override extract path; default: SOURCE_PATH/{artifact-name} ``` ## Metadata The `metadata` field provides supplementary information about an artifact. It supports three subfields: ### license - **Type**: `string` (optional) - **Description**: The open-source license identifier for this package, following the [SPDX License Identifier](https://spdx.org/licenses/) format (e.g. `MIT`, `Apache-2.0`, `GPL-2.0-only`). This is used only for annotation in the license summary of the build output and has no effect on the build process itself. ```yaml metadata: license: MIT ``` ### license-files - **Type**: `string[]` (optional) - **Description**: A list of paths to license files. After a successful build, the framework collects these files and places them in the `license/` directory of the build output. Two path formats are supported: - **Relative paths** (e.g. `LICENSE`, `COPYING`, `gettext-runtime/intl/COPYING.LIB`): resolved relative to the artifact's source root directory. - **`@/` prefix** (e.g. `@/bzip2.txt`): references a license file bundled with the framework itself, resolved to `src/globals/licenses/`. This is useful when the upstream source package does not include a license file (or the license text is embedded in other documentation) — in such cases, the license text can be placed in the built-in directory and referenced with `@/`. The following built-in license files are currently available: `bzip2.txt`, `gmp.txt`, `icu.txt`, `postgresql.txt`, `sqlite.txt`, `zlib.txt`. ```yaml # Common case: read from the source directory metadata: license-files: [LICENSE] # Multiple license files metadata: license-files: [LICENSE, COPYING.LESSER] # License file inside a subdirectory metadata: license-files: [gettext-runtime/intl/COPYING.LIB] # Use a built-in license file when the source package does not include one metadata: license-files: ['@/bzip2.txt'] ``` ### source-root - **Type**: `string` (optional) - **Description**: When the actual source root is located inside a subdirectory of the extracted archive, this field specifies that subdirectory name. The framework will use this path as the working directory during the build instead of the top-level extraction directory. ```yaml # krb5's actual source root is in the src/ subdirectory after extraction metadata: source-root: src ``` ## Download Types Artifacts support a variety of download types. Choose the one that best fits where the package is hosted. | Type | Description | |---|---| | `url` | Download from a fixed URL. Supports `filename` (custom local filename) and `version` (manually set version). | | `git` | Clone from a Git repository. Supports `rev` (branch/tag/commit), `submodules` (fetch submodules), and `extract`. | | `ghrel` | Download from GitHub Release Assets by regex match. Requires `repo` (`owner/repo`) and `match` (filename regex). Supports `prefer-stable`. | | `ghtar` | Download the source tarball from a GitHub Release (`/releases` API), matching by release name with `match`. Supports `prefer-stable`. | | `ghtagtar` | Download the source tarball from a GitHub Tag (`/tags` API), matching by tag name with `match`. Supports `prefer-stable`. | | `filelist` | Scrape an HTML page for a file listing, extract the filename and version via `regex`, then download the matched file. Suitable for official download index pages (e.g. ftp.gnu.org, openssl.org). | | `pecl` | Download a PHP extension from [PECL](https://pecl.php.net) by `name`. Supports `prefer-stable`. | | `pie` | Download a PHP extension from Packagist via the [PIE](https://github.com/php/pie) spec. Requires `repo` (`vendor/package`). | | `php-release` | Download official PHP source from php.net. The version is controlled by the `--with-php` build argument. | | `bitbuckettag` | Download source tarball from the latest Bitbucket tag. Requires `repo` (`workspace/repo`). | | `local` | Use a pre-existing local directory as the source. Requires `dirname`. Useful for offline or development scenarios. | | `custom` | Fully custom download logic implemented in a PHP class under `src/Package/Artifact/`. Optionally calls a specific method via `func`. | ## Type Reference ### url Downloads a file from a fixed URL and extracts it automatically. - **Class**: `StaticPHP\Artifact\Downloader\Type\Url` - **Capabilities**: Basic download only; no automatic version update checking - **Required**: `url` — the download address - **Optional**: - `filename` — local filename to save as (defaults to the last path segment of the URL) - `version` — manually specify a version string (this type cannot auto-detect versions) - `extract` — override the extraction directory (default: `SOURCE_PATH/{artifact-name}`) ```yaml # sqlite downloaded from a fixed URL artifact: source: type: url url: 'https://www.sqlite.org/2024/sqlite-autoconf-3450200.tar.gz' ``` ::: tip Inside an artifact, a bare string starting with `http://` or `https://` is automatically expanded into a `type: url` object, so you can often just write the URL directly: ```yaml artifact: source: 'https://www.sqlite.org/2024/sqlite-autoconf-3450200.tar.gz' ``` ::: --- ### git Clones a Git repository as the source. Supports two modes: clone a specific branch/tag/commit (`rev`), or use a regex to match the highest-versioned branch from all remote refs (`regex`). - **Class**: `StaticPHP\Artifact\Downloader\Type\Git` - **Capabilities**: Version update checking (`CheckUpdateInterface`) - **Required**: `url` — repository URL - **Optional** (at least one of `rev` or `regex` is required): - `rev` — clone a specific branch, tag, or commit hash - `regex` — match remote branch names with a PCRE regex; the highest matching version is selected (must include a named capture group `(?P...)`) - `submodules` — whether to fetch git submodules (boolean) - `extract` — override the clone target directory ```yaml # php-glfw cloned from the master branch artifact: source: type: git url: 'https://github.com/mario-deluna/php-glfw' rev: master ``` --- ### ghrel Downloads a file from GitHub Release Assets using a regex to match the asset filename. Best suited for repositories that upload pre-compiled packages or source archives as release assets. - **Class**: `StaticPHP\Artifact\Downloader\Type\GitHubRelease` - **Capabilities**: Version update checking (`CheckUpdateInterface`), integrity verification (`ValidatorInterface`, SHA256) - **Required**: - `repo` — repository path in `owner/repo` format - `match` — PCRE regex (without delimiters) to match the asset filename, e.g. `openssl.+\.tar\.gz` - **Optional**: - `prefer-stable` — skip pre-release versions (default: `true`) - `query` — query string appended to the API URL (e.g. `?per_page=5`) - `extract` — override extraction directory ```yaml # openssl downloaded from GitHub Release Assets artifact: source: type: ghrel repo: openssl/openssl match: openssl.+\.tar\.gz prefer-stable: true ``` --- ### ghtar Downloads the source tarball automatically generated by a GitHub Release (the "Source code" archive on the Release page). Unlike `ghrel` which downloads uploaded assets, `ghtar` uses the auto-generated tarball from the `/releases` API. - **Class**: `StaticPHP\Artifact\Downloader\Type\GitHubTarball` - **Capabilities**: Version update checking (`CheckUpdateInterface`) - **Required**: `repo` — repository path in `owner/repo` format - **Optional**: - `prefer-stable` — skip pre-release versions (default: `true`) - `match` — regex filter applied to `tarball_url` (if omitted, the first result is used) - `query` — query string appended to the API URL - `extract` — override extraction directory ```yaml # librdkafka downloaded via GitHub Release tarball artifact: source: type: ghtar repo: confluentinc/librdkafka ``` --- ### ghtagtar Downloads a source tarball from a GitHub Tag via the `/tags` API. Functionally identical to `ghtar`, but targets the tags endpoint instead of releases — useful for repositories that tag releases without creating a formal GitHub Release. - **Class**: `StaticPHP\Artifact\Downloader\Type\GitHubTarball` (shared with `ghtar`) - **Capabilities**: Version update checking (`CheckUpdateInterface`) - **Required**: `repo` — repository path in `owner/repo` format - **Optional**: - `prefer-stable` — skip pre-release versions (default: `true`) - `match` — regex filter applied to tag names (if omitted, the latest tag is used) - `query` — query string appended to the API URL - `extract` — override extraction directory ```yaml # brotli: only match v1.x tags artifact: source: type: ghtagtar repo: google/brotli match: 'v1\.\d.*' # libpng: match v1.6.x tags, with pagination artifact: source: type: ghtagtar repo: pnggroup/libpng match: v1\.6\.\d+ query: '?per_page=150' ``` --- ### filelist Fetches an HTML page (typically an official download index), extracts filenames and version numbers from the page content using a regex, then automatically selects and downloads the highest stable version. Pre-release versions (those containing keywords like alpha, beta, rc, dev, nightly, or snapshot) are automatically skipped. **Best for**: projects without GitHub that publish versioned archives on their own FTP or web index, such as `https://ftp.gnu.org/pub/gnu/ncurses/`. - **Class**: `StaticPHP\Artifact\Downloader\Type\FileList` - **Capabilities**: Version update checking (`CheckUpdateInterface`) - **Required**: - `url` — URL of the HTML page containing the file listing - `regex` — PCRE regex to extract filenames and versions from the page (must include named capture groups `(?...)` and `(?...)`) - **Optional**: - `extract` — override extraction directory - `download-url` — custom download URL template supporting `{file}` and `{version}` placeholders (by default the filename is appended directly to `url`) ```yaml # ncurses: scrape latest version from the GNU FTP index artifact: source: type: filelist url: 'https://ftp.gnu.org/pub/gnu/ncurses/' regex: '/href="(?ncurses-(?[^"]+)\.tar\.gz)"/' # openssl: mirror source using filelist artifact: source-mirror: type: filelist url: 'https://www.openssl.org/source/' regex: '/href="(?openssl-(?[^"]+)\.tar\.gz)"/' ``` --- ### pecl Downloads a PHP extension source package from [PECL](https://pecl.php.net) using the PECL REST API. The latest stable version is selected automatically. - **Class**: `StaticPHP\Artifact\Downloader\Type\PECL` - **Capabilities**: Version update checking (`CheckUpdateInterface`) - **Required**: `name` — PECL package name (case-insensitive, e.g. `APCu`) - **Optional**: - `prefer-stable` — download stable releases only (default: `true`) - `extract` — override extraction directory (default: `php-src/ext/{name}`) ```yaml # APCu downloaded from PECL artifact: source: type: pecl name: APCu ``` --- ### pie Downloads a PHP extension from [Packagist](https://repo.packagist.org) following the [PIE](https://github.com/php/pie) specification. Package metadata is fetched via the Packagist `p2/` API, and the source archive is downloaded from the `dist` field. - **Class**: `StaticPHP\Artifact\Downloader\Type\PIE` - **Capabilities**: Version update checking (`CheckUpdateInterface`) - **Required**: `repo` — Packagist package path in `vendor/package` format - **Optional**: - `extract` — override extraction directory ```yaml # xdebug downloaded from Packagist artifact: source: type: pie repo: xdebug/xdebug # php-spx with a custom extraction path artifact: source: type: pie repo: noisebynorthwest/php-spx extract: php-src/ext/spx ``` --- ### php-release Downloads the official PHP source from [php.net](https://www.php.net). The version is determined at build time by the `--with-php` argument. SHA256 integrity is verified automatically. Passing `git` as the version will clone the `master` branch of `php/php-src` directly. - **Class**: `StaticPHP\Artifact\Downloader\Type\PhpRelease` - **Capabilities**: Version update checking (`CheckUpdateInterface`), integrity verification (`ValidatorInterface`, SHA256) - **Required**: `domain` — download domain (e.g. `https://www.php.net` or a custom mirror) - **Optional**: - `extract` — override extraction directory ```yaml # php-src with primary and mirror sources artifact: source: type: php-release domain: 'https://www.php.net' source-mirror: type: php-release domain: 'https://phpmirror.static-php.dev' ``` --- ### bitbuckettag Downloads a source tarball from the latest tag of a Bitbucket repository via the Bitbucket REST API. - **Class**: `StaticPHP\Artifact\Downloader\Type\BitBucketTag` - **Capabilities**: Basic download only; no automatic version update checking - **Required**: `repo` — repository path in `workspace/repo` format - **Optional**: - `extract` — override extraction directory ```yaml artifact: source: type: bitbuckettag repo: snappy-m-o/php-snappy ``` --- ### local Uses a pre-existing local directory as the source without performing any download. Useful for offline environments or local development where the source has already been placed on disk. - **Class**: `StaticPHP\Artifact\Downloader\Type\LocalDir` - **Capabilities**: Basic download only; no automatic version update checking - **Required**: `dirname` — absolute path to the local directory - **Optional**: - `extract` — override extraction directory ```yaml artifact: source: type: local dirname: /path/to/local/source ``` --- ### custom Delegates download logic entirely to a PHP class under `src/Package/Artifact/`. If `func` is not specified, the class's default download method is called. - **Optional**: `func` — name of the specific method to invoke in the implementation class ```yaml artifact: source: type: custom ```