static-php-cli/assets/en_develop_registry.md.B5tf5XnG.js

import{_ as a,c as i,o as e,aj as t}from"./chunks/framework.C2AwuPrQ.js";const k=JSON.parse('{"title":"Registry & Plugin System","description":"","frontmatter":{},"headers":[],"relativePath":"en/develop/registry.md","filePath":"en/develop/registry.md"}'),n={name:"en/develop/registry.md"};function l(r,s,o,c,p,d){return e(),i("div",null,[...s[0]||(s[0]=[t(`<h1 id="registry-plugin-system" tabindex="-1">Registry &amp; Plugin System <a class="header-anchor" href="#registry-plugin-system" aria-label="Permalink to “Registry &amp; Plugin System”">​</a></h1><h2 id="overview" tabindex="-1">Overview <a class="header-anchor" href="#overview" aria-label="Permalink to “Overview”">​</a></h2><p>The <strong>Registry</strong> is StaticPHP&#39;s core extension mechanism. Think of it as a &quot;plugin package&quot;: a Registry consists of a declaration file (<code>spc.registry.yml</code>) and the configuration files and PHP classes it points to, describing a set of package definitions (YAML configuration) and their corresponding build logic (PHP classes). The build system loads all registered Registries at startup and merges their package definitions for use throughout the entire build process.</p><p>StaticPHP ships with a built-in core registry (<code>core</code>) that contains all definitions for PHP and related extensions, libraries, build tools, and more. The declaration file for the <code>core</code> registry is <code>spc.registry.yml</code> in the project root, which describes the mapping between the configuration file directory (<code>config/pkg/</code>, <code>config/artifact/</code>) and the build class PSR-4 namespace (<code>src/Package/</code>).</p><p>External Registries can only define new packages that don&#39;t already exist in <code>core</code>; they cannot override or modify existing definitions in the core registry. Depending on your needs, there are three ways to extend or modify StaticPHP&#39;s build capabilities:</p><ul><li><strong>Modify the <code>core</code> registry</strong>: Directly edit files under <code>src/Package</code> and <code>config/pkg/</code>, suitable when you want to contribute changes back to the StaticPHP mainline. Please read the <a href="./../contributing/">Contributing Guide</a> section on contributing new packages before submitting a PR.</li><li><strong>Vendor Mode</strong>: Package your custom packages as a standalone sub-registry distributed as a Composer package, suitable for private packages or scenarios where you want to reuse build logic as a library. See <a href="./extending/">Extending StaticPHP</a> for details.</li><li><strong>External Registry (<code>SPC_REGISTRIES</code>)</strong>: Specify one or more external registry file paths via the <code>SPC_REGISTRIES</code> environment variable, which StaticPHP loads at startup. Suitable for temporary extensions or scenarios where packaging as a Composer package isn&#39;t practical, similar to external source mechanisms in other package managers.</li></ul><h2 id="registry-declaration-file" tabindex="-1">Registry Declaration File <a class="header-anchor" href="#registry-declaration-file" aria-label="Permalink to “Registry Declaration File”">​</a></h2><p>Each Registry has a declaration file, typically named <code>spc.registry.yml</code>, located in the project root or the root of a Composer package. The file format supports YAML (<code>.yml</code> / <code>.yaml</code>) and JSON (<code>.json</code>). All paths within the file are resolved relative to the directory containing the declaration file itself.</p><p>In source mode (direct git clone), StaticPHP loads <code>spc.registry.yml</code> in the project root as the core registry (<code>core</code>) by default. In Vendor mode, it automatically detects whether <code>spc.registry.yml</code> exists in the current Composer package root and loads it as a standalone registry. External registries specified via the <code>SPC_REGISTRIES</code> environment variable must also contain a valid declaration file.</p><p>Below is a complete example with all available fields (based on the <code>core</code> registry):</p><div class="language-yaml"><button title="Copy Code" class="copy"></button><span class="lang">yaml</span><pre class="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><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># [Required] Unique registry name; loading a registry with a duplicate name is automatically skipped</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">name</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">my-registry</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># [Optional] Composer autoload file path, used when an external registry has its own dependencies</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">autoload</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">vendor/autoload.php</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># Package (library / php-extension / target) related configuration</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">package</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">  # YAML configuration file directory or specific file paths for packages, can be an array</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">  config</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    - </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">config/pkg/lib/</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    - </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">config/pkg/target/</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    - </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">config/pkg/ext/</span></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">  # PSR-4 namespace → directory path mapping for package build classes; the loader scans all PHP classes in the directory</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">  psr-4</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">    Package</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">src/Package</span></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">  # You can also load specific classes as needed, supporting array format or {&quot;ClassName&quot;: &quot;file path&quot;} mapping</span></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">  # classes:</span></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">  #   - Package\\Library\\MyLib</span></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">  #   MyLib: src/Package/Library/MyLib.php</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># Artifact (build artifact) related configuration</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">artifact</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">  # YAML configuration file directory or specific file paths for artifacts</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">  config</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    - </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">config/artifact/</span></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">  # PSR-4 namespace → directory path mapping for custom artifact download/extract classes</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">  psr-4</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">    Package\\Artifact</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">src/Package/Artifact</span></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">  # classes: ... (same format as package.classes)</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># Doctor environment check configuration</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">doctor</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">  # PSR-4 namespace → directory path mapping for Doctor check item classes</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">  psr-4</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">    StaticPHP\\Doctor\\Item</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">src/StaticPHP/Doctor/Item</span></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">  # classes: ... (same format as package.classes)</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># Additional CLI command configuration</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">command</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">  # PSR-4 namespace → directory path mapping for custom command classes</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">  psr-4</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">    Package\\Command</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">src/Package\\Command</span></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">  # classes: ... (same format as package.classes)</span></span></code></pre></div><p>Top-level field descriptions:</p><table tabindex="0"><thead><tr><th>Field</th><th>Required</th><th>Description</th></tr></thead><tbody><tr><td><code>name</code></td><td>✅</td><td>Unique registry name; loading a registry with a duplicate name is automatically skipped</td></tr><tr><td><code>autoload</code></td><td></td><td>Composer autoload file path, for external registries that carry their own dependencies</td></tr><tr><td><code>package</code></td><td></td><td>Package definition, including YAML config (<code>config</code>) and build classes (<code>psr-4</code> / <code>classes</code>)</td></tr><tr><td><code>artifact</code></td><td></td><td>Artifact definition, including YAML config (<code>config</code>) and custom classes (<code>psr-4</code> / <code>classes</code>)</td></tr><tr><td><code>doctor</code></td><td></td><td>Doctor check item definition, class loading only (<code>psr-4</code> / <code>classes</code>)</td></tr><tr><td><code>command</code></td><td></td><td>Additional CLI command definition, class loading only (<code>psr-4</code> / <code>classes</code>)</td></tr></tbody></table><p>The difference between <code>psr-4</code> and <code>classes</code>: <code>psr-4</code> scans all PHP classes in the entire directory that match the namespace rules and registers them in bulk; <code>classes</code> is used to precisely specify individual classes, supporting plain array format (<code>[&quot;ClassName&quot;]</code>, must already be available in autoload) or key-value mapping format (<code>{&quot;ClassName&quot;: &quot;path/to/file.php&quot;}</code>, the loader will automatically <code>require</code> the corresponding file).</p>`,14)])])}const g=a(n,[["render",l]]);export{k as __pageData,g as default};