Fix native php blueprint by bcotrim · Pull Request #3491 · Automattic/studio

bcotrim · 2026-05-14T14:06:50Z

Related issues

None.

How AI was used in this PR

Codex was used interactively to debug the native PHP blueprint startup failure, inspect daemon/PHP behavior on Windows, and draft the focused fix. The behavior was manually reproduced before the fix and validated afterward in both CLI and Studio flows.

Proposed Changes

Add a temporary native PHP subprocess php.ini for blueprint PHAR execution.
Load Studio's bundled Windows PHP extensions in that subprocess config, including pdo_sqlite and sqlite3, so the PHAR can detect the SQLite-backed WordPress install correctly.
Generate a temporary CA bundle from Node's trusted root certificates and pass it to PHP via openssl.cafile and curl.cainfo, fixing HTTPS downloads from blueprint steps under native PHP.
Allow native PHP subprocess callers to pass scoped environment variables and extra PHP args.
Clean up the temporary blueprint php.ini directory after the blueprint run.
Add focused tests for the native PHP helper behavior.

Testing Instructions

Confirm automated checks pass:
- npx eslint --fix apps/cli/lib/native-php.ts apps/cli/php-server-child.ts apps/cli/lib/tests/native-php.test.ts
- npm run typecheck
- npm test -- apps/cli/lib/tests/native-php.test.ts apps/cli/lib/tests/wordpress-server-manager.test.ts
Build the CLI before manual testing:
- npm run cli:build
On Windows, create an empty blueprint file containing {} and verify native PHP site creation succeeds:
- $env:STUDIO_RUNTIME = "native-php"
- node apps/cli/dist/cli/main.mjs --path "$env:USERPROFILE\Studio\native-empty-blueprint-test" site create --name "Empty Blueprint" --wp latest --php 8.4 --blueprint "$env:TEMP\empty-blueprint.json" --skip-browser
In the Studio desktop app, create a native PHP site from the Quick Start blueprint and verify the site starts successfully.
Optional: enable Xdebug for the created native PHP site and confirm the running PHP process loads php_xdebug.dll.

Pre-merge Checklist

Have you checked for TypeScript, React or other console errors?

wpmobilebot · 2026-05-14T14:32:01Z

📊 Performance Test Results

Comparing e8a9402 vs trunk

app-size

Metric	trunk	`e8a9402`	Diff	Change
App Size (Mac)	1354.95 MB	1355.45 MB	+0.49 MB	⚪ 0.0%

site-editor

Metric	trunk	`e8a9402`	Diff	Change
load	1515 ms	1470 ms	45 ms	⚪ 0.0%

site-startup

Metric	trunk	`e8a9402`	Diff	Change
siteCreation	8572 ms	8579 ms	+7 ms	⚪ 0.0%
siteStartup	4951 ms	4932 ms	19 ms	⚪ 0.0%

Results are median values from multiple test runs.

Legend: 🟢 Improvement (faster) | 🔴 Regression (slower) | ⚪ No change (<50ms diff)

fredrikekelund

This fixes the problem, which is great! @bcotrim, you mentioned seeing some trouble with images on this branch, but I can upload and view images on the site fine. Let me know what problems you were experiencing.

Really, the only thing I think we should explore here (although it could be a follow-up PR) is using php.ini for all PHP processes on Windows, not just when running blueprints. This would help with simplicity in the implementation and predictability at runtime.

fredrikekelund · 2026-05-18T05:27:57Z

Did you patch this file somehow, @bcotrim? php-toolkit has had a new release, so we shouldn't have to commit this file anymore since #3437

I now know you did patch it with the changes from WordPress/php-toolkit#280. I've since also patched it with the changes from WordPress/php-toolkit#281

fredrikekelund · 2026-05-18T05:29:22Z

I guess it doesn't hurt, but I'm a little bit allergic to unit tests that LLMs generate out of habit. I think E2E tests serve us much better for truly testing this functionality (we already have E2E tests that do that)

I went ahead and removed the test file in e834425

fredrikekelund · 2026-05-18T05:39:06Z

+// blueprints.phar spawns its own PHP subprocesses while applying a blueprint.
+// Those subprocesses inherit PHPRC but not the parent process's `-d` argv, so
+// this php.ini carries the bundled extension and CA settings they need.
+export async function createNativePhpSubprocessIniDirectory(
+	phpVersion: NativePhpSupportedVersion
+): Promise< string > {
+	const tempRoot =
+		process.platform === 'win32' ? fs.realpathSync.native( os.tmpdir() ) : os.tmpdir();
+	const phpIniDirectory = await fs.promises.mkdtemp( path.join( tempRoot, 'studio-native-php-' ) );
+	const caBundlePath = getNativePhpCaBundlePath( phpIniDirectory );
+	await fs.promises.writeFile( caBundlePath, rootCertificates.join( os.EOL ), 'utf8' );
+	await fs.promises.writeFile(
+		path.join( phpIniDirectory, 'php.ini' ),
+		getNativePhpSubprocessIniContents( phpVersion, caBundlePath ),
+		'utf8'
+	);
+	return phpIniDirectory;
+}


The php.ini contents only change with PHP versions. To keep things simple, I think we should explore writing the php.ini file to the PHP executable's directory and using that as the source of truth for the PHP config for all Windows PHP processes. Did you try this already, @bcotrim?

I implemented this in 3f3977c

fredrikekelund · 2026-05-18T18:52:09Z

I implemented my suggestion to always load the php.ini file (that lives next to the binary) and verified that creating a site with a blueprint still works. In fact, I even took it one step further and made it so we create that file on macOS, too. Streamlining the implementation between platforms will make things more predictable.

+// and is fussy about backslashes (which also act as escape characters). Use
+// forward slashes everywhere and escape stray double quotes.
+function toPhpIniPath( filePath: string ): string {
+	return filePath.replace( /\\/g, '/' ).replace( /"/g, '\\"' );


fredrikekelund · 2026-05-19T07:41:03Z

The E2E tests aren't passing on Windows, but that's expected. We need to build and upload the new PHP packages to the CDN before it'll work

fredrikekelund added 30 commits May 12, 2026 09:09

Build PHP binaries with Xdebug

7b6dc2d

WIP

702ea22

New approach

594e5af

Fix

5c15545

Address build log warnings

c0d6ba3

WIP

0513325

WIP

74e219d

WIP

7ec141c

GitHub API token

f610b55

pkg-config

0d48dff

pkg-config

d35d4ac

Fix libcurl issue

a7aa765

WIP

a65dfec

Clean up

beab364

curl fix

8132a23

Embed curl

b2ac2c5

More curl

695279f

Merge branch 'trunk' into rsm-2698-build-php-with-xdebug

241cb89

Normalize directory structure on macOS

34f1d07

Name GitHub action run using inputs

c606c6c

Address review comments

491ec37

WIP

4d8caad

Rely on existing spc tools where possible

477e6b1

Fix extension smoke tests failing

6298024

Fix xdebug extension testing

b9955ac

Cleanup

630cc54

curl smoke test fix

c4582d4

Bring back PHP version resolver

cacc2cd

Dynamically find latest extension versions on Windows

a2c1065

Apply phar patch

b209699

fredrikekelund and others added 8 commits May 13, 2026 14:43

Fix phar issue (again)

bf47f9f

Make xdebug the only shared extension

e60bcae

Docs

28d14f5

[WIP] Load PHP extensions properly on Windows

a447f4a

Update the extension list

b269191

Merge branch 'trunk' into rsm-2698-build-php-with-xdebug

70598be

Merge branch 'rsm-2698-build-php-with-xdebug' into f26d/load-xdebug

b25d8e5

Fix native PHP blueprint subprocess config

5761987

bcotrim self-assigned this May 14, 2026

bcotrim changed the base branch from trunk to f26d/load-xdebug May 14, 2026 14:07

bcotrim requested a review from fredrikekelund May 14, 2026 14:08

bcotrim added 3 commits May 14, 2026 16:00

Load generated PHP ini for blueprints

522e5d4

Clarify native PHP blueprint subprocess config

2c785ea

Patch blueprints PHAR for native PHP imports

2ede5b3

fredrikekelund approved these changes May 18, 2026

View reviewed changes

fredrikekelund added 4 commits May 18, 2026 12:06

Doubly patched blueprints.phar

58856df

Always load php.ini on Windows

3f3977c

php.ini on macOS, too

6b4e5bf

Remove redundant test file

e834425

fredrikekelund mentioned this pull request May 19, 2026

Load native PHP extensions properly on Windows #3471

Merged

1 task

Base automatically changed from f26d/load-xdebug to trunk May 19, 2026 05:38

fredrikekelund added the native-php label May 19, 2026

Merge branch 'trunk' into fix-native-php-blueprint

effc321

github-advanced-security AI found potential problems May 19, 2026

View reviewed changes

Comment thread apps/cli/lib/native-php.ts

// and is fussy about backslashes (which also act as escape characters). Use

// forward slashes everywhere and escape stray double quotes.

function toPhpIniPath( filePath: string ): string {

return filePath.replace( /\\/g, '/' ).replace( /"/g, '\\"' );

Fix .gitignore

e8a9402

fredrikekelund merged commit 53c1153 into trunk May 19, 2026
8 of 10 checks passed

fredrikekelund deleted the fix-native-php-blueprint branch May 19, 2026 07:42

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Fix native php blueprint#3491

Fix native php blueprint#3491
fredrikekelund merged 48 commits into
trunkfrom
fix-native-php-blueprint

bcotrim commented May 14, 2026 •

edited

Loading

Uh oh!

wpmobilebot commented May 14, 2026 •

edited

Loading

Uh oh!

fredrikekelund left a comment

Uh oh!

fredrikekelund May 18, 2026

Uh oh!

fredrikekelund May 18, 2026

Uh oh!

fredrikekelund May 18, 2026

Uh oh!

fredrikekelund May 18, 2026

Uh oh!

fredrikekelund May 18, 2026

Uh oh!

fredrikekelund May 18, 2026

Uh oh!

fredrikekelund commented May 18, 2026

Uh oh!

fredrikekelund commented May 19, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Conversation

bcotrim commented May 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Related issues

How AI was used in this PR

Proposed Changes

Testing Instructions

Pre-merge Checklist

Uh oh!

wpmobilebot commented May 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

📊 Performance Test Results

app-size

site-editor

site-startup

Uh oh!

fredrikekelund left a comment

Choose a reason for hiding this comment

Uh oh!

fredrikekelund May 18, 2026

Choose a reason for hiding this comment

Uh oh!

fredrikekelund May 18, 2026

Choose a reason for hiding this comment

Uh oh!

fredrikekelund May 18, 2026

Choose a reason for hiding this comment

Uh oh!

fredrikekelund May 18, 2026

Choose a reason for hiding this comment

Uh oh!

fredrikekelund May 18, 2026

Choose a reason for hiding this comment

Uh oh!

fredrikekelund May 18, 2026

Choose a reason for hiding this comment

Uh oh!

fredrikekelund commented May 18, 2026

Uh oh!

fredrikekelund commented May 19, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

bcotrim commented May 14, 2026 •

edited

Loading

wpmobilebot commented May 14, 2026 •

edited

Loading