<spanclass="line"><spanstyle="--shiki-light:#22863A;--shiki-dark:#85E89D;"> prefer-stable</span><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><spanstyle="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">true</span></span></code></pre></div><p>There are two ways to define an artifact and associate it with a package: <strong>inline</strong> (defined directly inside the package file) or <strong>standalone</strong> (defined in a separate file and referenced by name):</p><divclass="vp-code-group"><divclass="tabs"><inputtype="radio"name="group-16"id="tab-17"checked><labeldata-title="Inline Artifact"for="tab-17">Inline Artifact</label><inputtype="radio"name="group-16"id="tab-18"><labeldata-title="Standalone Artifact"for="tab-18">Standalone Artifact</label><inputtype="radio"name="group-16"id="tab-19"><labeldata-title="Package Referencing a Standalone Artifact"for="tab-19">Package Referencing a Standalone Artifact</label></div><divclass="blocks"><divclass="language-yaml active"><buttontitle="Copy Code"class="copy"></button><spanclass="lang">yaml</span><preclass="shiki shiki-themes github-light github-dark"style="--shiki-light:#24292e;--shiki-dark:#e1e4e8;--shiki-light-bg:#fff;--shiki-dark-bg:#24292e;"tabindex="0"dir="ltr"><code><spanclass="line"><spanstyle="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># This is a package declaration</span></span>
<spanclass="line"><spanstyle="--shiki-light:#22863A;--shiki-dark:#85E89D;"> prefer-stable</span><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><spanstyle="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">true</span></span></code></pre></div><divclass="language-yaml"><buttontitle="Copy Code"class="copy"></button><spanclass="lang">yaml</span><preclass="shiki shiki-themes github-light github-dark"style="--shiki-light:#24292e;--shiki-dark:#e1e4e8;--shiki-light-bg:#fff;--shiki-dark-bg:#24292e;"tabindex="0"dir="ltr"><code><spanclass="line"><spanstyle="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># This is a standalone artifact declaration, typically placed under config/artifact/</span></span>
<spanclass="line"><spanstyle="--shiki-light:#22863A;--shiki-dark:#85E89D;"> prefer-stable</span><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><spanstyle="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">true</span></span></code></pre></div><divclass="language-yaml"><buttontitle="Copy Code"class="copy"></button><spanclass="lang">yaml</span><preclass="shiki shiki-themes github-light github-dark"style="--shiki-light:#24292e;--shiki-dark:#e1e4e8;--shiki-light-bg:#fff;--shiki-dark-bg:#24292e;"tabindex="0"dir="ltr"><code><spanclass="line"><spanstyle="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># This is a package declaration</span></span>
<spanclass="line"><spanstyle="--shiki-light:#22863A;--shiki-dark:#85E89D;"> artifact</span><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><spanstyle="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">curl-src</span></span></code></pre></div></div></div><h2id="structure"tabindex="-1">Structure <aclass="header-anchor"href="#structure"aria-label="Permalink to “Structure”"></a></h2><p>An artifact has three top-level sections: <code>source</code>, <code>binary</code>, and <code>metadata</code>.</p><ul><li><code>source</code> — the source code archive</li><li><code>binary</code> — pre-built binaries for specific platforms</li><li><code>metadata</code> — additional information such as license paths</li></ul><p>Both <code>source</code> and <code>binary</code> accept either an inline source object or a reference to a standalone artifact by name (as shown above).</p><p>Full artifact object format:</p><divclass="language-yaml"><buttontitle="Copy Code"class="copy"></button><spanclass="lang">yaml</span><preclass="shiki shiki-themes github-light github-dark"style="--shiki-light:#24292e;--shiki-dark:#e1e4e8;--shiki-light-bg:#fff;--shiki-dark-bg:#24292e;"tabindex="0"dir="ltr"><code><spanclass="line"><spanstyle="--shiki-light:#D73A49;--shiki-dark:#F97583;">&</span><spanstyle="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">:</span></span>
<spanclass="line"><spanstyle="--shiki-light:#22863A;--shiki-dark:#85E89D;"> license-files</span><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: [</span><spanstyle="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"LICENSE"</span><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">] </span><spanstyle="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># License files from the source directory</span></span>
<spanclass="line"><spanstyle="--shiki-light:#22863A;--shiki-dark:#85E89D;"> source-root</span><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><spanstyle="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"subdir"</span><spanstyle="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # (optional) Use if the actual source root is inside a subdirectory</span></span></code></pre></div><p>The basic format of a <code>source-object</code>:</p><divclass="language-yaml"><buttontitle="Copy Code"class="copy"></button><spanclass="lang">yaml</span><preclass="shiki shiki-themes github-light github-dark"style="--shiki-light:#24292e;--shiki-dark:#e1e4e8;--shiki-light-bg:#fff;--shiki-dark-bg:#24292e;"tabindex="0"dir="ltr"><code><spanclass="line"><spanstyle="--shiki-light:#D73A49;--shiki-dark:#F97583;">&</span><spanstyle="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">:</span></span>
<spanclass="line"><spanstyle="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # ...: Additional keys depend on the type; see below</span></span>
<spanclass="line"><spanstyle="--shiki-light:#22863A;--shiki-dark:#85E89D;"> extract</span><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><spanstyle="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"path/to/dir"</span><spanstyle="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # (optional) Override extract path; default: SOURCE_PATH/{artifact-name}</span></span></code></pre></div><h2id="metadata"tabindex="-1">Metadata <aclass="header-anchor"href="#metadata"aria-label="Permalink to “Metadata”"></a></h2><p>The <code>metadata</code> field provides supplementary information about an artifact. It supports three subfields:</p><h3id="license"tabindex="-1">license <aclass="header-anchor"href="#license"aria-label="Permalink to “license”"></a></h3><ul><li><strong>Type</strong>: <code>string</code> (optional)</li><li><strong>Description</strong>: The open-source license identifier for this package, following the <ahref="https://spdx.org/licenses/"target="_blank"rel="noreferrer">SPDX License Identifier</a> format (e.g. <code>MIT</code>, <code>Apache-2.0</code>, <code>GPL-2.0-only</code>). This is used only for annotation in the license summary of the build output and has no effect on the build process itself.</li></ul><divclass="language-yaml"><buttontitle="Copy Code"class="copy"></button><spanclass="lang">yaml</span><preclass="shiki shiki-themes github-light github-dark"style="--shiki-light:#24292e;--shiki-dark:#e1e4e8;--shiki-light-bg:#fff;--shiki-dark-bg:#24292e;"tabindex="0"dir="ltr"><code><spanclass="line"><spanstyle="--shiki-light:#22863A;--shiki-dark:#85E89D;">metadata</span><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<spanclass="line"><spanstyle="--shiki-light:#22863A;--shiki-dark:#85E89D;"> license</span><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><spanstyle="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">MIT</span></span></code></pre></div><h3id="license-files"tabindex="-1">license-files <aclass="header-anchor"href="#license-files"aria-label="Permalink to “license-files”"></a></h3><ul><li><strong>Type</strong>: <code>string[]</code> (optional)</li><li><strong>Description</strong>: A list of paths to license files. After a successful build, the framework collects these files and places them in the <code>license/</code> directory of the build output. Two path formats are supported: <ul><li><strong>Relative paths</strong> (e.g. <code>LICENSE</code>, <code>COPYING</code>, <code>gettext-runtime/intl/COPYING.LIB</code>): resolved relative to the artifact's source root directory.</li><li><strong><code>@/</code> prefix</strong> (e.g. <code>@/bzip2.txt</code>): references a license file bundled with the framework itself, resolved to <code>src/globals/licenses/</code>. 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 <code>@/</code>.</li></ul></li></ul><p>The following built-in license files are currently available: <code>bzip2.txt</code>, <code>gmp.txt</code>, <code>icu.txt</code>, <code>postgresql.txt</code>, <code>sqlite.txt</code>, <code>zlib.txt</code>.</p><divclass="language-yaml"><buttontitle="Copy Code"class="copy"></button><spanclass="lang">yaml</span><preclass="shiki shiki-themes github-light github-dark"style="--shiki-light:#24292e;--shiki-dark:#e1e4e8;--shiki-light-bg:#fff;--shiki-dark-bg:#24292e;"tabindex="0"dir="ltr"><code><spanclass="line"><spanstyle="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># Common case: read from the source directory</span></span>
<spanclass="line"><spanstyle="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># Use a built-in license file when the source package does not include one</span></span>
<spanclass="line"><spanstyle="--shiki-light:#22863A;--shiki-dark:#85E89D;"> license-files</span><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: [</span><spanstyle="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">'@/bzip2.txt'</span><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">]</span></span></code></pre></div><h3id="source-root"tabindex="-1">source-root <aclass="header-anchor"href="#source-root"aria-label="Permalink to “source-root”"></a></h3><ul><li><strong>Type</strong>: <code>string</code> (optional)</li><li><strong>Description</strong>: 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.</li></ul><divclass="language-yaml"><buttontitle="Copy Code"class="copy"></button><spanclass="lang">yaml</span><preclass="shiki shiki-themes github-light github-dark"style="--shiki-light:#24292e;--shiki-dark:#e1e4e8;--shiki-light-bg:#fff;--shiki-dark-bg:#24292e;"tabindex="0"dir="ltr"><code><spanclass="line"><spanstyle="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># krb5's actual source root is in the src/ subdirectory after extraction</span></span>
<spanclass="line"><spanstyle="--shiki-light:#22863A;--shiki-dark:#85E89D;"> source-root</span><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><spanstyle="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">src</span></span></code></pre></div><h2id="download-types"tabindex="-1">Download Types <aclass="header-anchor"href="#download-types"aria-label="Permalink to “Download Types”"></a></h2><p>Artifacts support a variety of download types. Choose the one that best fits where the package is hosted.</p><tabletabindex="0"><thead><tr><th>Type</th><th>Description</th></tr></thead><tbody><tr><td><code>url</code></td><td>Download from a fixed URL. Supports <code>filename</code> (custom local filename) and <code>version</code> (manually set version).</td></tr><tr><td><code>git</code></td><td>Clone from a Git repository. Supports <code>rev</code> (branch/tag/commit), <code>submodules</code> (fetch submodules), and <code>extract</code>.</td></tr><tr><td><code>ghrel</code></td><td>Download from GitHub Release Assets by regex match. Requires <code>repo</code> (<code>owner/repo</code>) and <code>match</code> (filename regex). Supports <code>prefer-stable</code>.</td></tr><tr><td><code>ghtar</code></td><td>Download the source tarball from a GitHub Release (<code>/releases</code> API), matching by release name with <code>match</code>. Supports <code>prefer-stable</code>.</td></tr><tr><td><code>ghtagtar</code></td><td>Download the source tarball from a GitHub Tag (<code>/tags</code> API), matching by tag name with <code>match</code>. Supports <code>prefer-stable</code>.</td></tr><tr><td><code>filelist</code></td><td>Scrape an HTML page for a file listing, extract the filename and version via <code>regex</code>, then download the matched file. Suitable for official download index pages (e.g. ftp.gnu.org, openssl.org).</td></tr><tr><td><code>pecl</code></td><td>Download a PHP extension from <ahref="https://pecl.php.net"target="_blank"rel="noreferrer">PECL</a> by <code>name</code>. Supports <code>prefer-stable</code>.</td></tr><tr><td><code>pie</code></td><td>Download a PHP extension from Packagist via the <ahref="https://github.com/php/pie"target="_blank"rel="noreferrer">PIE</a> spec. Requires <code>repo</code> (<code>vendor/package</code>).</td></tr><tr><td><code>php-release</code></td><td>Download official PHP source from php.net. The version is controlled by the <code>--with-php</code> build argument.</td></tr><tr><td><code>bitbuckettag</code></td><td>Download source tarball from the latest Bitbucket tag. Requires <code>repo</code> (<code>workspace/repo</code>).</td></tr><tr><td><code>local</code></td><td>Use a pre-existing local directory as the source. Requires <code>dirname</code>. Useful for offline or development scenarios.</td></tr><tr><td><code>custom</code></td><td>Fully custom download logic implemented in a PHP class under <code>src/Package/Artifact/</code>. Optionally calls a specific method via <code>func</code>.</td></tr></tbody></table><h2id="type-reference"tabindex="-1">Type Reference <aclass="header-anchor"href="#type-reference"aria-label="Permalink to “Type Reference”"></a></h2><h3id="url"tabindex="-1">url <aclass="header-anchor"href="#url"aria-label="Permalink to “url”"></a></h3><p>Downloads a file from a fixed URL and extracts it automatically.</p><ul><li><strong>Class</strong>: <code>StaticPHP\Artifact\Downloader\Type\Url</code></li><li><strong>Capabilities</strong>: Basic download only; no automatic version update checking</li><li><strong>Required</strong>: <code>url</code> — the download address</li><li><strong>Optional</strong>: <ul><li><code>filename</code> — local filename to save as (defaults to the last path segment of the URL)</li><li><code>version</code> — manually specify a version string (this type cannot auto-detect versions)</li><li><code>extract</code> — override the extraction directory (default: <code>SOURCE_PATH/{artifact-name}</code>)</li></ul></li></ul><divclass="language-yaml"><buttontitle="Copy Code"class="copy"></button><spancl
<spanclass="line"><spanstyle="--shiki-light:#22863A;--shiki-dark:#85E89D;"> url</span><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><spanstyle="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">'https://www.sqlite.org/2024/sqlite-autoconf-3450200.tar.gz'</span></span></code></pre></div><divclass="tip custom-block"><pclass="custom-block-title custom-block-title-default">TIP</p><p>Inside an artifact, a bare string starting with <code>http://</code> or <code>https://</code> is automatically expanded into a <code>type: url</code> object, so you can often just write the URL directly:</p><divclass="language-yaml"><buttontitle="Copy Code"class="copy"></button><spanclass="lang">yaml</span><preclass="shiki shiki-themes github-light github-dark"style="--shiki-light:#24292e;--shiki-dark:#e1e4e8;--shiki-light-bg:#fff;--shiki-dark-bg:#24292e;"tabindex="0"dir="ltr"><code><spanclass="line"><spanstyle="--shiki-light:#22863A;--shiki-dark:#85E89D;">artifact</span><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<spanclass="line"><spanstyle="--shiki-light:#22863A;--shiki-dark:#85E89D;"> source</span><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><spanstyle="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">'https://www.sqlite.org/2024/sqlite-autoconf-3450200.tar.gz'</span></span></code></pre></div></div><hr><h3id="git"tabindex="-1">git <aclass="header-anchor"href="#git"aria-label="Permalink to “git”"></a></h3><p>Clones a Git repository as the source. Supports two modes: clone a specific branch/tag/commit (<code>rev</code>), or use a regex to match the highest-versioned branch from all remote refs (<code>regex</code>).</p><ul><li><strong>Class</strong>: <code>StaticPHP\Artifact\Downloader\Type\Git</code></li><li><strong>Capabilities</strong>: Version update checking (<code>CheckUpdateInterface</code>)</li><li><strong>Required</strong>: <code>url</code> — repository URL</li><li><strong>Optional</strong> (at least one of <code>rev</code> or <code>regex</code> is required): <ul><li><code>rev</code> — clone a specific branch, tag, or commit hash</li><li><code>regex</code> — match remote branch names with a PCRE regex; the highest matching version is selected (must include a named capture group <code>(?P<version>...)</code>)</li><li><code>submodules</code> — whether to fetch git submodules (boolean)</li><li><code>extract</code> — override the clone target directory</li></ul></li></ul><divclass="language-yaml"><buttontitle="Copy Code"class="copy"></button><spanclass="lang">yaml</span><preclass="shiki shiki-themes github-light github-dark"style="--shiki-light:#24292e;--shiki-dark:#e1e4e8;--shiki-light-bg:#fff;--shiki-dark-bg:#24292e;"tabindex="0"dir="ltr"><code><spanclass="line"><spanstyle="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># php-glfw cloned from the master branch</span></span>
<spanclass="line"><spanstyle="--shiki-light:#22863A;--shiki-dark:#85E89D;"> rev</span><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><spanstyle="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">master</span></span></code></pre></div><hr><h3id="ghrel"tabindex="-1">ghrel <aclass="header-anchor"href="#ghrel"aria-label="Permalink to “ghrel”"></a></h3><p>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.</p><ul><li><strong>Class</strong>: <code>StaticPHP\Artifact\Downloader\Type\GitHubRelease</code></li><li><strong>Capabilities</strong>: Version update checking (<code>CheckUpdateInterface</code>), integrity verification (<code>ValidatorInterface</code>, SHA256)</li><li><strong>Required</strong>: <ul><li><code>repo</code> — repository path in <code>owner/repo</code> format</li><li><code>match</code> — PCRE regex (without delimiters) to match the asset filename, e.g. <code>openssl.+\.tar\.gz</code></li></ul></li><li><strong>Optional</strong>: <ul><li><code>prefer-stable</code> — skip pre-release versions (default: <code>true</code>)</li><li><code>query</code> — query string appended to the API URL (e.g. <code>?per_page=5</code>)</li><li><code>extract</code> — override extraction directory</li></ul></li></ul><divclass="language-yaml"><buttontitle="Copy Code"class="copy"></button><spanclass="lang">yaml</span><preclass="shiki shiki-themes github-light github-dark"style="--shiki-light:#24292e;--shiki-dark:#e1e4e8;--shiki-light-bg:#fff;--shiki-dark-bg:#24292e;"tabindex="0"dir="ltr"><code><spanclass="line"><spanstyle="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># openssl downloaded from GitHub Release Assets</span></span>
<spanclass="line"><spanstyle="--shiki-light:#22863A;--shiki-dark:#85E89D;"> prefer-stable</span><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><spanstyle="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">true</span></span></code></pre></div><hr><h3id="ghtar"tabindex="-1">ghtar <aclass="header-anchor"href="#ghtar"aria-label="Permalink to “ghtar”"></a></h3><p>Downloads the source tarball automatically generated by a GitHub Release (the "Source code" archive on the Release page). Unlike <code>ghrel</code> which downloads uploaded assets, <code>ghtar</code> uses the auto-generated tarball from the <code>/releases</code> API.</p><ul><li><strong>Class</strong>: <code>StaticPHP\Artifact\Downloader\Type\GitHubTarball</code></li><li><strong>Capabilities</strong>: Version update checking (<code>CheckUpdateInterface</code>)</li><li><strong>Required</strong>: <code>repo</code> — repository path in <code>owner/repo</code> format</li><li><strong>Optional</strong>: <ul><li><code>prefer-stable</code> — skip pre-release versions (default: <code>true</code>)</li><li><code>match</code> — regex filter applied to <code>tarball_url</code> (if omitted, the first result is used)</li><li><code>query</code> — query string appended to the API URL</li><li><code>extract</code> — override extraction directory</li></ul></li></ul><divclass="language-yaml"><buttontitle="Copy Code"class="copy"></button><spanclass="lang">yaml</span><preclass="shiki shiki-themes github-light github-dark"style="--shiki-light:#24292e;--shiki-dark:#e1e4e8;--shiki-light-bg:#fff;--shiki-dark-bg:#24292e;"tabindex="0"dir="ltr"><code><spanclass="line"><spanstyle="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># librdkafka downloaded via GitHub Release tarball</span></span>
<spanclass="line"><spanstyle="--shiki-light:#22863A;--shiki-dark:#85E89D;"> repo</span><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><spanstyle="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">confluentinc/librdkafka</span></span></code></pre></div><hr><h3id="ghtagtar"tabindex="-1">ghtagtar <aclass="header-anchor"href="#ghtagtar"aria-label="Permalink to “ghtagtar”"></a></h3><p>Downloads a source tarball from a GitHub Tag via the <code>/tags</code> API. Functionally identical to <code>ghtar</code>, but targets the tags endpoint instead of releases — useful for repositories that tag releases without creating a formal GitHub Release.</p><ul><li><strong>Class</strong>: <code>StaticPHP\Artifact\Downloader\Type\GitHubTarball</code> (shared with <code>ghtar</code>)</li><li><strong>Capabilities</strong>: Version update checking (<code>CheckUpdateInterface</code>)</li><li><strong>Required</strong>: <code>repo</code> — repository path in <code>owner/repo</code> format</li><li><strong>Optional</strong>: <ul><li><code>prefer-stable</code> — skip pre-release versions (default: <code>true</code>)</li><li><code>match</code> — regex filter applied to tag names (if omitted, the latest tag is used)</li><li><code>query</code> — query string appended to the API URL</li><li><code>extract</code> — override extraction directory</li></ul></li></ul><divclass="language-yaml"><buttontitle="Copy Code"class="copy"></button><spanclass="lang">yaml</span><preclass="shiki shiki-themes github-light github-dark"style="--shiki-light:#24292e;--shiki-dark:#e1e4e8;--shiki-light-bg:#fff;--shiki-dark-bg:#24292e;"tabindex="0"dir="ltr"><code><spanclass="line"><spanstyle="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># brotli: only match v1.x tags</span></span>
<spanclass="line"><spanstyle="--shiki-light:#22863A;--shiki-dark:#85E89D;"> query</span><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><spanstyle="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">'?per_page=150'</span></span></code></pre></div><hr><h3id="filelist"tabindex="-1">filelist <aclass="header-anchor"href="#filelist"aria-label="Permalink to “filelist”"></a></h3><p>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.</p><p><strong>Best for</strong>: projects without GitHub that publish versioned archives on their own FTP or web index, such as <code>https://ftp.gnu.org/pub/gnu/ncurses/</code>.</p><ul><li><strong>Class</strong>: <code>StaticPHP\Artifact\Downloader\Type\FileList</code></li><li><strong>Capabilities</strong>: Version update checking (<code>CheckUpdateInterface</code>)</li><li><strong>Required</strong>: <ul><li><code>url</code> — URL of the HTML page containing the file listing</li><li><code>regex</code> — PCRE regex to extract filenames and versions from the page (must include named capture groups <code>(?<file>...)</code> and <code>(?<version>...)</code>)</li></ul></li><li><strong>Optional</strong>: <ul><li><code>extract</code> — override extraction directory</li><li><code>download-url</code> — custom download URL template supporting <code>{file}</code> and <code>{version}</code> placeholders (by default the filename is appended directly to <code>url</code>)</li></ul></li></ul><divclass="language-yaml"><buttontitle="Copy Code"class="copy"></button><spanclass="lang">yaml</span><preclass="shiki shiki-themes github-light github-dark"style="--shiki-light:#24292e;--shiki-dark:#e1e4e8;--shiki-light-bg:#fff;--shiki-dark-bg:#24292e;"tabindex="0"dir="ltr"><code><spanclass="line"><spanstyle="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># ncurses: scrape latest version from the GNU FTP index</span></span>
<spanclass="line"><spanstyle="--shiki-light:#22863A;--shiki-dark:#85E89D;"> regex</span><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><spanstyle="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">'/href="(?<file>openssl-(?<version>[^"]+)\.tar\.gz)"/'</span></span></code></pre></div><hr><h3id="pecl"tabindex="-1">pecl <aclass="header-anchor"href="#pecl"aria-label="Permalink to “pecl”"></a></h3><p>Downloads a PHP extension source package from <ahref="https://pecl.php.net"target="_blank"rel="noreferrer">PECL</a> using the PECL REST API. The latest stable version is selected automatically.</p><ul><li><strong>Class</strong>: <code>StaticPHP\Artifact\Downloader\Type\PECL</code></li><li><strong>Capabilities</strong>: Version update checking (<code>CheckUpdateInterface</code>)</li><li><strong>Required</strong>: <code>name</code> — PECL package name (case-insensitive, e.g. <code>APCu</code>)</li><li><strong>Optional</strong>: <ul><li><code>prefer-stable</code> — download stable releases only (default: <code>true</code>)</li><li><code>extract</code> — override extraction directory (default: <code>php-src/ext/{name}</code>)</li></ul></li></ul><divclass="language-yaml"><buttontitle="Copy Code"class="copy"></button><spanclass="lang">yaml</span><preclass="shiki shiki-themes github-light github-dark"style="--shiki-light:#24292e;--shiki-dark:#e1e4e8;--shiki-light-bg:#fff;--shiki-dark-bg:#24292e;"tabindex="0"dir="ltr"><code><spanclass="line"><spanstyle="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># APCu downloaded from PECL</span></span>
<spanclass="line"><spanstyle="--shiki-light:#22863A;--shiki-dark:#85E89D;"> name</span><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><spanstyle="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">APCu</span></span></code></pre></div><hr><h3id="pie"tabindex="-1">pie <aclass="header-anchor"href="#pie"aria-label="Permalink to “pie”"></a></h3><p>Downloads a PHP extension from <ahref="https://repo.packagist.org"target="_blank"rel="noreferrer">Packagist</a> following the <ahref="https://github.com/php/pie"target="_blank"rel="noreferrer">PIE</a> specification. Package metadata is fetched via the Packagist <code>p2/</code> API, and the source archive is downloaded from the <code>dist</code> field.</p><ul><li><strong>Class</strong>: <code>StaticPHP\Artifact\Downloader\Type\PIE</code></li><li><strong>Capabilities</strong>: Version update checking (<code>CheckUpdateInterface</code>)</li><li><strong>Required</strong>: <code>repo</code> — Packagist package path in <code>vendor/package</code> format</li><li><strong>Optional</strong>: <ul><li><code>extract</code> — override extraction directory</li></ul></li></ul><divclass="language-yaml"><buttontitle="Copy Code"class="copy"></button><spanclass="lang">yaml</span><preclass="shiki shiki-themes github-light github-dark"style="--shiki-light:#24292e;--shiki-dark:#e1e4e8;--shiki-light-bg:#fff;--shiki-dark-bg:#24292e;"tabindex="0"dir="ltr"><code><spanclass="line"><spanstyle="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># xdebug downloaded from Packagist</span></span>
<spanclass="line"><spanstyle="--shiki-light:#22863A;--shiki-dark:#85E89D;"> extract</span><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><spanstyle="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">php-src/ext/spx</span></span></code></pre></div><hr><h3id="php-release"tabindex="-1">php-release <aclass="header-anchor"href="#php-release"aria-label="Permalink to “php-release”"></a></h3><p>Downloads the official PHP source from <ahref="https://www.php.net"target="_blank"rel="noreferrer">php.net</a>. The version is determined at build time by the <code>--with-php</code> argument. SHA256 integrity is verified automatically. Passing <code>git</code> as the version will clone the <code>master</code> branch of <code>php/php-src</code> directly.</p><ul><li><strong>Class</strong>: <code>StaticPHP\Artifact\Downloader\Type\PhpRelease</code></li><li><strong>Capabilities</strong>: Version update checking (<code>CheckUpdateInterface</code>), integrity verification (<code>ValidatorInterface</code>, SHA256)</li><li><strong>Required</strong>: <code>domain</code> — download domain (e.g. <code>https://www.php.net</code> or a custom mirror)</li><li><strong>Optional</strong>: <ul><li><code>extract</code> — override extraction directory</li></ul></li></ul><divclass="language-yaml"><buttontitle="Copy Code"class="copy"></button><spanclass="lang">yaml</span><preclass="shiki shiki-themes github-light github-dark"style="--shiki-light:#24292e;--shiki-dark:#e1e4e8;--shiki-light-bg:#fff;--shiki-dark-bg:#24292e;"tabindex="0"dir="ltr"><code><spanclass="line"><spanstyle="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># php-src with primary and mirror sources</span></span>
<spanclass="line"><spanstyle="--shiki-light:#22863A;--shiki-dark:#85E89D;"> domain</span><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><spanstyle="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">'https://phpmirror.static-php.dev'</span></span></code></pre></div><hr><h3id="bitbuckettag"tabindex="-1">bitbuckettag <aclass="header-anchor"href="#bitbuckettag"aria-label="Permalink to “bitbuckettag”"></a></h3><p>Downloads a source tarball from the latest tag of a Bitbucket repository via the Bitbucket REST API.</p><ul><li><strong>Class</strong>: <code>StaticPHP\Artifact\Downloader\Type\BitBucketTag</code></li><li><strong>Capabilities</strong>: Basic download only; no automatic version update checking</li><li><strong>Required</strong>: <code>repo</code> — repository path in <code>workspace/repo</code> format</li><li><strong>Optional</strong>: <ul><li><code>extract</code> — override extraction directory</li></ul></li></ul><divclass="language-yaml"><buttontitle="Copy Code"class="copy"></button><spanclass="lang">yaml</span><preclass="shiki shiki-themes github-light github-dark"style="--shiki-light:#24292e;--shiki-dark:#e1e4e8;--shiki-light-bg:#fff;--shiki-dark-bg:#24292e;"tabindex="0"dir="ltr"><code><spanclass="line"><spanstyle="--shiki-light:#22863A;--shiki-dark:#85E89D;">artifact</span><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<spanclass="line"><spanstyle="--shiki-light:#22863A;--shiki-dark:#85E89D;"> repo</span><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><spanstyle="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">snappy-m-o/php-snappy</span></span></code></pre></div><hr><h3id="local"tabindex="-1">local <aclass="header-anchor"href="#local"aria-label="Permalink to “local”"></a></h3><p>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.</p><ul><li><strong>Class</strong>: <code>StaticPHP\Artifact\Downloader\Type\LocalDir</code></li><li><strong>Capabilities</strong>: Basic download only; no automatic version update checking</li><li><strong>Required</strong>: <code>dirname</code> — absolute path to the local directory</li><li><strong>Optional</strong>: <ul><li><code>extract</code> — override extraction directory</li></ul></li></ul><divclass="language-yaml"><buttontitle="Copy Code"class="copy"></button><spanclass="lang">yaml</span><preclass="shiki shiki-themes github-light github-dark"style="--shiki-light:#24292e;--shiki-dark:#e1e4e8;--shiki-light-bg:#fff;--shiki-dark-bg:#24292e;"tabindex="0"dir="ltr"><code><spanclass="line"><spanstyle="--shiki-light:#22863A;--shiki-dark:#85E89D;">artifact</span><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<spanclass="line"><spanstyle="--shiki-light:#22863A;--shiki-dark:#85E89D;"> dirname</span><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><spanstyle="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">/path/to/local/source</span></span></code></pre></div><hr><h3id="custom"tabindex="-1">custom <aclass="header-anchor"href="#custom"aria-label="Permalink to “custom”"></a></h3><p>Delegates download logic entirely to a PHP class under <code>src/Package/Artifact/</code>. If <code>func</code> is not specified, the class's default download method is called.</p><ul><li><strong>Optional</strong>: <code>func</code> — name of the specific method to invoke in the implementation class</li></ul><divclass="language-yaml"><buttontitle="Copy Code"class="copy"></button><spanclass="lang">yaml</span><preclass="shiki shiki-themes github-light github-dark"style="--shiki-light:#24292e;--shiki-dark:#e1e4e8;--shiki-light-bg:#fff;--shiki-dark-bg:#24292e;"tabindex="0"dir="ltr"><code><spanclass="line"><spanstyle="--shiki-light:#22863A;--shiki-dark:#85E89D;">artifact</span><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
