@wp-playground/blueprints 3.1.43 → 3.1.44

package/lib/compile.d.ts

@@ -0,0 +1,29 @@
+import type { UniversalPHP } from '@php-wasm/universal';
+import type { Blueprint, BlueprintBundle, BlueprintDeclaration } from './types';
+import { type CompileBlueprintV1Options, type CompiledBlueprintV1 } from './v1/compile';
+import type { BlueprintV1Declaration } from './v1/types';
+import type { BlueprintV2Declaration } from './v2/blueprint-v2-declaration';
+import { type CompiledBlueprintV2 } from './v2/compile';
+export type BlueprintExecutionPath = 'v1' | 'v2';
+export type CompiledBlueprintForExecution = {
+    version: 1;
+    declaration: BlueprintV1Declaration;
+    compiled: CompiledBlueprintV1;
+    run: (playground: UniversalPHP) => Promise<void>;
+} | {
+    version: 2;
+    declaration: BlueprintV2Declaration;
+    compiled: CompiledBlueprintV2;
+    run: (playground: UniversalPHP) => Promise<void>;
+};
+export interface CompileBlueprintForExecutionOptions extends Omit<CompileBlueprintV1Options, 'onBlueprintValidated' | 'streamBundledFile'> {
+    onBlueprintValidated?: (blueprint: BlueprintDeclaration) => void;
+}
+/**
+ * Compiles a Blueprint into the shape consumers need before execution.
+ *
+ * The legacy `compileBlueprint()` export intentionally remains v1-only for
+ * backwards compatibility. This helper is the version-aware entrypoint that
+ * newer callers can migrate to as Blueprint v2 support grows.
+ */
+export declare function compileBlueprintForExecution(input: Blueprint | BlueprintBundle, options?: CompileBlueprintForExecutionOptions): Promise<CompiledBlueprintForExecution>;

package/lib/is-git-repo-url.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Heuristically indicates whether a URL looks like a Git repository.
+ *
+ * Blueprint compilers use this to distinguish plugin/theme repository URLs
+ * from downloadable ZIP URLs. This is intentionally a small allowlist of URL
+ * shapes Playground can clone, not a general Git remote detector.
+ */
+export declare function seemsLikeGitRepoUrl(url: string): boolean;

package/lib/steps/import-wxr.d.ts

@@ -17,6 +17,30 @@ export interface ImportWxrStep<ResourceType> {
     step: 'importWxr';
     /** The file to import */
     file: ResourceType;
+    /**
+     * Whether to fetch and import attachment files referenced by the WXR file.
+     *
+     * @default true
+     */
+    fetchAttachments?: boolean;
+    /**
+     * Whether to rewrite imported URLs to the current site URL.
+     *
+     * @default true
+     */
+    rewriteUrls?: boolean;
+    /**
+     * Whether to import comments from the WXR file.
+     *
+     * @default true
+     */
+    importComments?: boolean;
+    /**
+     * The fallback local user for imported authors that cannot be mapped.
+     *
+     * @default "admin"
+     */
+    defaultAuthorUsername?: string;
     /**
      * The importer to use. Possible values:
      *

package/lib/steps/install-plugin.d.ts

@@ -62,10 +62,22 @@ export interface InstallPluginOptions {
      * Whether to activate the plugin after installing it.
      */
     activate?: boolean;
+    /**
+     * Parameters to expose to the plugin during its activation hook.
+     */
+    activationOptions?: Record<string, unknown>;
+    /**
+     * Whether installation/activation failures should abort the Blueprint.
+     */
+    onError?: 'skip-plugin' | 'throw';
     /**
      * The name of the folder to install the plugin to. Defaults to guessing from pluginData
      */
     targetFolderName?: string;
+    /**
+     * Human-readable plugin name for progress captions and skip warnings.
+     */
+    humanReadableName?: string;
 }
 /**
  * Installs a WordPress plugin in the Playground.

package/lib/steps/install-theme.d.ts

@@ -49,10 +49,19 @@ export interface InstallThemeOptions {
      * Whether to import the theme's starter content after installing it.
      */
     importStarterContent?: boolean;
+    /**
+     * Whether installation, activation, or starter-content failures should
+     * abort the Blueprint.
+     */
+    onError?: 'skip-theme' | 'throw';
     /**
      * The name of the folder to install the theme to. Defaults to guessing from themeData
      */
     targetFolderName?: string;
+    /**
+     * Human-readable theme name for the progress caption and skip warning.
+     */
+    humanReadableName?: string;
 }
 /**
  * Installs a WordPress theme in the Playground.

package/lib/v1/compile.d.ts

@@ -75,7 +75,7 @@ export interface CompileBlueprintV1Options {
      */
     additionalSteps?: any[];
 }
-export declare function compileBlueprintV1(input: BlueprintV1Declaration | BlueprintBundle, options?: Omit<CompileBlueprintV1Options, 'streamBundledFile'>): Promise<CompiledBlueprintV1>;
+export declare function compileBlueprintV1(input: BlueprintV1Declaration | BlueprintBundle, options?: CompileBlueprintV1Options): Promise<CompiledBlueprintV1>;
 export declare function isBlueprintBundle(input: any): input is BlueprintBundle;
 export declare function getBlueprintDeclaration(blueprint: BlueprintV1 | BlueprintBundle): Promise<BlueprintV1Declaration>;
 export type BlueprintValidationResult = {

package/lib/v2/compile.d.ts

@@ -0,0 +1,117 @@
+import type { UniversalPHP } from '@php-wasm/universal';
+import type { RuntimeConfiguration } from '../types';
+import { type CompileBlueprintV1Options } from '../v1/compile';
+import type { StepDefinition } from '../steps';
+import type { BlueprintV2Declaration } from './blueprint-v2-declaration';
+export declare class UnsupportedBlueprintV2FeatureError extends Error {
+    readonly featurePath: string;
+    constructor(featurePath: string, message?: string);
+}
+type BlueprintV2ApplicationOptions = BlueprintV2Declaration['applicationOptions'];
+type BlueprintV2Constants = NonNullable<BlueprintV2Declaration['constants']>;
+type BlueprintV2SiteOptions = NonNullable<BlueprintV2Declaration['siteOptions']>;
+type BlueprintV2MuPlugin = NonNullable<BlueprintV2Declaration['muPlugins']>[number];
+type BlueprintV2Theme = NonNullable<BlueprintV2Declaration['themes']>[number];
+type BlueprintV2ActiveTheme = NonNullable<BlueprintV2Declaration['activeTheme']>;
+type BlueprintV2Plugin = NonNullable<BlueprintV2Declaration['plugins']>[number];
+type BlueprintV2Fonts = NonNullable<BlueprintV2Declaration['fonts']>;
+type BlueprintV2Media = NonNullable<BlueprintV2Declaration['media']>[number];
+type BlueprintV2Role = NonNullable<BlueprintV2Declaration['roles']>[number];
+type BlueprintV2User = NonNullable<BlueprintV2Declaration['users']>[number];
+type BlueprintV2PostTypes = NonNullable<BlueprintV2Declaration['postTypes']>;
+type BlueprintV2Content = NonNullable<BlueprintV2Declaration['content']>[number];
+type BlueprintV2Step = NonNullable<BlueprintV2Declaration['additionalStepsAfterExecution']>[number];
+export type BlueprintV2ExecutionPlan = BlueprintV2ExecutionPlanItem[];
+export type BlueprintV2StepPlan = StepDefinition[];
+export type BlueprintV2StepPlanLoweringResult = {
+    steps: BlueprintV2StepPlan;
+    unsupportedPlan: BlueprintV2ExecutionPlan;
+};
+export type BlueprintV2ExecutionPlanItem = {
+    type: 'defineWpConfigConsts';
+    consts: BlueprintV2Constants;
+} | {
+    type: 'setSiteOptions';
+    options: BlueprintV2SiteOptions;
+} | {
+    type: 'installMuPlugin';
+    muPlugin: BlueprintV2MuPlugin;
+    sourcePath: string;
+} | {
+    type: 'installTheme';
+    theme: BlueprintV2Theme;
+    active: false;
+    sourcePath: string;
+} | {
+    type: 'installTheme';
+    theme: BlueprintV2ActiveTheme;
+    active: true;
+    sourcePath: string;
+} | {
+    type: 'installPlugin';
+    plugin: BlueprintV2Plugin;
+    sourcePath: string;
+} | {
+    type: 'installFonts';
+    fonts: BlueprintV2Fonts;
+} | {
+    type: 'importMedia';
+    media: BlueprintV2Media;
+    sourcePath: string;
+} | {
+    type: 'setSiteLanguage';
+    language: string;
+} | {
+    type: 'defineRoles';
+    roles: BlueprintV2Role[];
+} | {
+    type: 'defineUsers';
+    users: BlueprintV2User[];
+} | {
+    type: 'definePostTypes';
+    postTypes: BlueprintV2PostTypes;
+} | {
+    type: 'importContent';
+    content: BlueprintV2Content;
+    sourcePath: string;
+} | {
+    type: 'runStep';
+    step: BlueprintV2Step;
+    sourcePath: string;
+};
+export type CompiledBlueprintV2 = {
+    runtime: RuntimeConfiguration;
+    applicationOptions?: BlueprintV2ApplicationOptions;
+    plan: BlueprintV2ExecutionPlan;
+    steps: BlueprintV2StepPlan;
+    unsupportedPlan: BlueprintV2ExecutionPlan;
+    run: (playground: UniversalPHP) => Promise<void>;
+};
+export type CompileBlueprintV2Options = Pick<CompileBlueprintV1Options, 'streamBundledFile'>;
+/**
+ * Compiles a Blueprint v2 declaration into the pieces the TypeScript runner can
+ * understand today.
+ *
+ * It resolves runtime options, creates an ordered v2 execution plan, and lowers
+ * supported plan items into v1 step records. Fully lowered plans run through the
+ * existing v1 runner; unsupported items stay visible and block execution before
+ * any partial work is applied.
+ */
+export declare function compileBlueprintV2(declaration: BlueprintV2Declaration, options?: CompileBlueprintV2Options): Promise<CompiledBlueprintV2>;
+/**
+ * Converts the top-level Blueprint v2 fields into a simple ordered plan.
+ *
+ * The plan keeps the original v2 data intact. It only decides execution order
+ * and records where each item came from, which makes unsupported items visible
+ * instead of silently dropping them during lowering.
+ */
+export declare function createBlueprintV2ExecutionPlan(declaration: BlueprintV2Declaration): BlueprintV2ExecutionPlan;
+/**
+ * Converts the supported v2 plan items into v1-compatible step records.
+ *
+ * The v1 step runner already knows how to install plugins, install themes, set
+ * options, and run several imperative steps. This function reuses those shapes
+ * while keeping unsupported v2-only work in `unsupportedPlan` for future PRs.
+ */
+export declare function lowerBlueprintV2ExecutionPlan(plan: BlueprintV2ExecutionPlan): BlueprintV2StepPlanLoweringResult;
+export {};

package/lib/v2/wep-1-blueprint-v2-schema/appendix-A-blueprint-v2-schema.d.ts

@@ -159,12 +159,12 @@ export declare namespace V2Schema {
          * @default "latest".
          */
         wordpressVersion?: DataSources.WordPressVersion | DataSources.DataReference | {
-            min: DataSources.WordPressVersion;
-            max?: DataSources.WordPressVersion;
+            min: DataSources.WordPressVersionConstraintVersion;
+            max?: DataSources.WordPressVersionConstraintVersion;
             /**
              * @default "latest"
              */
-            preferred?: DataSources.WordPressVersion;
+            preferred?: DataSources.WordPressVersionPreferredVersion;
         };
         /**
          * The PHP version required for this Blueprint to work.
@@ -180,9 +180,9 @@ export declare namespace V2Schema {
          * @see https://github.com/WordPress/blueprints-library/issues/47
          */
         phpVersion?: DataSources.PHPVersion | {
-            min?: DataSources.PHPVersion;
-            recommended?: DataSources.PHPVersion;
-            max?: DataSources.PHPVersion;
+            min?: DataSources.PHPVersionConstraintVersion;
+            recommended?: DataSources.PHPVersionConstraintVersion;
+            max?: DataSources.PHPVersionConstraintVersion;
         };
         /**
          * The theme to install and also activate.
@@ -196,9 +196,13 @@ export declare namespace V2Schema {
          * @example `"activeTheme": "adventurer@4.6.0"`
          * @example
          * ```json
-         * "activeTheme": {
-         *     "source": "https://github.com/richtabor/kanso/archive/refs/heads/main.zip",
-         *     "id": "kanso"
+         * {
+         *     "version": 2,
+         *     "activeTheme": {
+         *         "source": "https://github.com/richtabor/kanso/archive/refs/heads/main.zip",
+         *         "targetDirectoryName": "kanso",
+         *         "importStarterContent": true
+         *     }
          * }
          * ```
          */
@@ -209,14 +213,17 @@ export declare namespace V2Schema {
          * Example:
          *
          * ```json
-         * themes: [
-         *     "stylish-press-theme",
-         *     "adventurer@4.6.0",
-         *     {
-         *         "source": "https://github.com/richtabor/kanso/archive/refs/heads/main.zip",
-         *         "id": "kanso"
-         *     }
-         * ]
+         * {
+         *     "version": 2,
+         *     "themes": [
+         *         "stylish-press-theme",
+         *         "adventurer@4.6.0",
+         *         {
+         *             "source": "https://github.com/richtabor/kanso/archive/refs/heads/main.zip",
+         *             "targetDirectoryName": "kanso"
+         *         }
+         *     ]
+         * }
          * ```
          */
         themes?: ThemeDefinition[];
@@ -226,16 +233,20 @@ export declare namespace V2Schema {
          * Example:
          *
          * ```json
-         * plugins: [
-         *     "jetpack",
-         *     "akismet@6.4.3",
-         *     "./query-monitor.php",
-         *     "./code-block.zip",
-         *     {
-         *         "source": "https://github.com/woocommerce/woocommerce/archive/refs/heads/6.4.3.zip",
-         *         "active": false
-         *     }
-         * ]
+         * {
+         *     "version": 2,
+         *     "plugins": [
+         *         "jetpack",
+         *         "akismet@6.4.3",
+         *         "./query-monitor.php",
+         *         "./code-block.zip",
+         *         {
+         *             "source": "https://github.com/woocommerce/woocommerce/archive/refs/heads/6.4.3.zip",
+         *             "active": false
+         *         }
+         *     ]
+         * }
+         * ```
          */
         plugins?: PluginDefinition[];
         /**
@@ -244,14 +255,15 @@ export declare namespace V2Schema {
          * Example:
          *
          * ```json
-         * muPlugins: [
-         *     {
-         *         "file": {
+         * {
+         *     "version": 2,
+         *     "muPlugins": [
+         *         {
          *             "filename": "addFilter-0.php",
          *             "content": "<?php add_action( 'requests-requests.before_request', function( &$url ) {\n$url = 'https://playground.wordpress.net/cors-proxy.php?' . $url;\n} );"
          *         }
-         *     }
-         * ]
+         *     ]
+         * }
          * ```
          */
         muPlugins?: Array<DataSources.DataReference>;
@@ -366,10 +378,10 @@ export declare namespace V2Schema {
     };
     type ContentDefinition = ({
         type: 'mysql-dump';
-        source: DataSources.DataReference | DataSources.DataReference[];
+        source: DataSources.FileDataReference | DataSources.FileDataReference[];
     } & URLMappingConfig) | ({
         type: 'posts';
-        source: DataSources.DataReference | DataSources.DataReference[] | WordPressPost | WordPressPost[];
+        source: DataSources.FileDataReference | DataSources.FileDataReference[] | WordPressPost | WordPressPost[];
     } & URLMappingConfig)
     /**
      * WXR files to import.
@@ -377,36 +389,33 @@ export declare namespace V2Schema {
      * Example:
      *
      * ```json
-     * content: [
-     *     {
-     *         "type": "wxr",
-     *         "https://raw.githubusercontent.com/wordpress/blueprints/trunk/blueprints/stylish-press/woo-products.wxr"
-     *     },
-     *     {
-     *         "type": "wxr",
-     *         "url": "https://raw.githubusercontent.com/wordpress/blueprints/trunk/blueprints/stylish-press/site-content.wxr",
-     *         "rewriteUrls": true,
-     *         "fetchStaticAssets": false,
-     *         "users": false,
-     *         "comments": false,
-     *     }
-     * ]
+     * {
+     *     "version": 2,
+     *     "content": [
+     *         {
+     *             "type": "wxr",
+     *             "source": "https://raw.githubusercontent.com/wordpress/blueprints/trunk/blueprints/stylish-press/woo-products.wxr"
+     *         },
+     *         {
+     *             "type": "wxr",
+     *             "source": "https://raw.githubusercontent.com/wordpress/blueprints/trunk/blueprints/stylish-press/site-content.wxr",
+     *             "urlsMode": "rewrite",
+     *             "staticAssets": "hotlink",
+     *             "importUsers": false,
+     *             "importComments": false
+     *         }
+     *     ]
+     * }
      * ```
      */
-     | ({
-        type: 'wxr';
-        source: DataSources.DataReference;
+     | WXRContentDefinition;
+    type WXRContentDefinition = WXRContentBase & ({
         /**
-         * Static assets handling.
-         *
-         * Possible values:
-         *
-         * * "fetch" – Fetch the static assets and save them to the local filesystem.
-         * * "hotlink" – Hotlink the static assets from the remote site.
-         *
-         * @default "fetch".
+         * Map remote authors to existing local authors.
          */
-        staticAssets?: 'fetch' | 'hotlink';
+        authorsMode: 'map';
+        authorsMap: Record<RemoteUsername, LocalUsername>;
+    } | {
         /**
          * How to handle authors that don't exist on the current site.
          *
@@ -414,28 +423,32 @@ export declare namespace V2Schema {
          *
          * * "create" – Create a new author.
          * * "default-author" – Use the default author.
-         * * "map" – Map the author to an existing author on the current site.
          *
          * @default "create".
          */
-        authorsMode?: 'create' | 'default-author' | 'map';
+        authorsMode?: 'create' | 'default-author';
+        authorsMap?: Record<RemoteUsername, LocalUsername>;
+    });
+    type WXRContentBase = {
+        type: 'wxr';
+        source: DataSources.FileDataReference | DataSources.FileDataReference[];
         /**
-         * The default author to use when `mode` is "default-author".
+         * Static assets handling.
          *
-         * @default "admin".
-         */
-        defaultAuthorUsername?: string;
-        /**
-         * Map post authors from the remote site to the current site.
+         * Possible values:
          *
-         * When not provided, the importer will attempt to match the authors by
-         * username, email, or name.
+         * * "fetch" – Fetch the static assets and save them to the local filesystem.
+         * * "hotlink" – Hotlink the static assets from the remote site.
          *
-         * Required when `authorsMode` is "map".
+         * @default "fetch".
+         */
+        staticAssets?: 'fetch' | 'hotlink';
+        /**
+         * The default author to use when `mode` is "default-author".
          *
-         * @default undefined.
+         * @default "admin".
          */
-        authorsMap?: Record<RemoteUsername, LocalUsername>;
+        defaultAuthorUsername?: string;
         /**
          * Whether to import users from the remote site.
          *
@@ -448,15 +461,9 @@ export declare namespace V2Schema {
          * @default false.
          */
         importComments?: boolean;
-        /**
-         * Whether to import site settings from the remote site.
-         *
-         * @default false.
-         */
-        importSiteOptions?: boolean;
-    } & URLMappingConfig);
-    type MediaDefinition = DataSources.DataReference | {
-        source: DataSources.DataReference;
+    } & URLMappingConfig;
+    type MediaDefinition = DataSources.FileDataReference | {
+        source: DataSources.FileDataReference;
         title?: string;
         description?: string;
         alt?: string;
@@ -540,6 +547,12 @@ export declare namespace V2Schema {
          * @default "throw"
          */
         onError?: 'skip-plugin' | 'throw';
+        /**
+         * How to handle a plugin that is already installed.
+         *
+         * @default "overwrite"
+         */
+        ifAlreadyInstalled?: 'overwrite' | 'skip' | 'error';
         /**
          * Human-readable name of the plugin for the progress bar.
          *
@@ -573,6 +586,18 @@ export declare namespace V2Schema {
          * If not provided, it will be inferred from the theme source.
          */
         targetDirectoryName?: string;
+        /**
+         * Sometimes it's fine when a theme fails to install.
+         *
+         * @default "throw"
+         */
+        onError?: 'skip-theme' | 'throw';
+        /**
+         * How to handle a theme that is already installed.
+         *
+         * @default "overwrite"
+         */
+        ifAlreadyInstalled?: 'overwrite' | 'skip' | 'error';
         /**
          * Human-readable name of the theme for the progress bar.
          *
@@ -594,8 +619,8 @@ export declare namespace V2Schema {
          */
         humanReadableName?: string;
     };
-    type RemoteUsername = 'string';
-    type LocalUsername = 'string';
+    type RemoteUsername = string;
+    type LocalUsername = string;
     /**
      * WordPress register_post_type() arguments representation. {{{
      *
@@ -1327,7 +1352,7 @@ export declare namespace V2Schema {
         /**
          * The PHP file to execute.
          */
-        code: DataSources.DataReference;
+        code: DataSources.FileDataReference;
         /**
          * Environment variables to set for this run.
          */
@@ -1335,7 +1360,7 @@ export declare namespace V2Schema {
     };
     type RunSQLStep = {
         step: 'runSQL';
-        source: DataSources.DataReference;
+        source: DataSources.FileDataReference;
     };
     /**
      * Sets the site language and download translations for WordPress core
@@ -1364,7 +1389,7 @@ export declare namespace V2Schema {
         /**
          * The zip file resource to extract.
          */
-        zipFile: DataSources.DataReference;
+        zipFile: DataSources.FileDataReference;
         /**
          * The path to extract the zip file to inside the virtual filesystem.
          */

package/lib/v2/wep-1-blueprint-v2-schema/appendix-B-data-sources.d.ts

@@ -67,7 +67,15 @@ export declare namespace DataSources {
      */
     export type InlineDirectory = {
         directoryName: string;
-        files: Record<string, InlineFileContent | InlineDirectory>;
+        files: Record<string, InlineFileContent | NestedInlineDirectory>;
+    };
+    /**
+     * A child directory inside an inline directory.
+     *
+     * Its directory name comes from the parent `files` record key.
+     */
+    export type NestedInlineDirectory = {
+        files: Record<string, InlineFileContent | NestedInlineDirectory>;
     };
     /**
      * A reference to a remote git repository.
@@ -94,6 +102,10 @@ export declare namespace DataSources {
      * A union of all general data reference types.
      */
     export type DataReference = URLReference | ExecutionContextPath | InlineFile | InlineDirectory | GitPath;
+    /**
+     * A data reference that must resolve to a single file.
+     */
+    export type FileDataReference = URLReference | ExecutionContextPath | InlineFile;
     /**
      * }}}
      */
@@ -118,7 +130,12 @@ export declare namespace DataSources {
      */
     export type Slug = string;
     export type SimpleVersionExpression = 'latest' | `${number}.${number}` | `${number}.${number}.${number}`;
-    export type WordPressVersionSuffix = `beta${number}` | `rc${number}`;
+    export type VersionNumberComponent = `${bigint}`;
+    export type ComparableVersionExpression = `${VersionNumberComponent}.${VersionNumberComponent}` | `${VersionNumberComponent}.${VersionNumberComponent}.${VersionNumberComponent}`;
+    export type WordPressVersionSuffix = `beta${VersionNumberComponent}` | `rc${VersionNumberComponent}`;
+    export type WordPressVersionConstraintVersion = ComparableVersionExpression | `${ComparableVersionExpression}-${WordPressVersionSuffix}`;
+    export type WordPressVersionPreferredVersion = 'latest' | WordPressVersionConstraintVersion;
+    export type PHPVersionConstraintVersion = SimpleVersionExpression;
     /** }}} Helper types */
     /**
      * Plugin directory reference, e.g. "jetpack", "jetpack@6.4", or "akismet@6.4.3".
@@ -149,7 +166,8 @@ export declare namespace DataSources {
      */
     export type ThemeDirectoryReference = Slug | `${Slug}@${SimpleVersionExpression}`;
     /**
-     * WordPress version, e.g. "6.4", "6.4.3", "6.8-RC1", or "6.7-beta2".
+     * WordPress version, e.g. "latest", "beta", "trunk", "6.4",
+     * "6.4.3", "6.8-RC1", or "6.7-beta2".
      *
      * These refer to slugs of specific WordPress releases as listed in
      * the first table column on https://wordpress.org/download/releases/.
@@ -157,16 +175,18 @@ export declare namespace DataSources {
      * The WordPressVersion type is only meaningful in the top-level
      * `wordpressVersion` property.
      */
-    export type WordPressVersion = SimpleVersionExpression | `${SimpleVersionExpression}-${WordPressVersionSuffix}`;
+    export type WordPressVersion = 'beta' | 'trunk' | 'nightly' | SimpleVersionExpression | `${SimpleVersionExpression}-${WordPressVersionSuffix}`;
     /**
-     * PHP version, e.g. "8.1" or "8.1.3".
+     * PHP version, e.g. "8.1", "8.1.3", or "next".
      *
      * These refer to PHP versions as listed in https://www.php.net/releases/.
+     * `next` previews the php-src development branch and is currently
+     * supported by the web runtime only.
      *
      * The PHPVersion type is only meaningful in the top-level
      * `phpVersion` property.
      */
-    export type PHPVersion = SimpleVersionExpression;
+    export type PHPVersion = SimpleVersionExpression | 'next';
     /**
      * A path within the built WordPress site, relative to the WordPress root
      * directory. For example, site:wp-content/uploads/2024/01/image.jpg.