Skip to content

Support local PHP functions with vercel dev - #653

Open
denusklo wants to merge 2 commits into
vercel-community:masterfrom
denusklo:feat/local-dev-server
Open

denusklo wants to merge 2 commits into
vercel-community:masterfrom
denusklo:feat/local-dev-server

Conversation

@denusklo

@denusklo denusklo commented Oct 3, 2026

Copy link
Copy Markdown

Summary

Fixes #607.

Implement the BuildV3 startDevServer hook so vercel dev can serve local PHP functions without downloading or executing the Linux Lambda runtime.

  • Run local PHP from PATH or VERCEL_PHP_EXECUTABLE, with entrypoint routing, loopback ephemeral ports, readiness checks, bounded startup retries, and owned-process shutdown.
  • Pass the CLI's local environment and log callbacks through; handle Windows environment-key casing without mutating the parent environment.
  • Keep host PHP configuration and scan project api/*.ini overrides when api/php.ini exists. Document that Composer dependencies/build scripts are installed/run locally, not per request.
  • Replace the old dev-build process exit with an explanatory rejection for callers that do not use the hook.
  • Add real-PHP hook tests, an optional actual Vercel CLI integration runner, and updated local-development documentation.

Verification

Tested final commit ca43e2a with Node 22 on:

Host PHP Build Dev-hook tests Actual vercel dev
Windows x64 8.2.0 Pass Pass Pass
Ubuntu WSL2 x64 8.4.17 Pass Pass Pass
macOS arm64 8.4.26 Pass Pass Pass

The unmodified Vercel CLI 50.4.5 integration runs both builds and functions configurations and checks direct/nested endpoints, rewrites/query merging, form and binary bodies, concurrent requests, static files, .env, PHP ini overrides and per-response PHP shutdown. It uses a local builder cache, isolated CLI configuration, and a loopback API trap; no deployment or real account access is required. See test/integration/README.md.

Full Jest passes on Linux/macOS. On Windows, all eight dev-hook tests pass; three existing production/path tests still fail because of Windows bundle keys and POSIX-only expectations. Those are addressed independently in #652. This PR does not incorporate or mask those unrelated fixes.

Scope

This enables local development, not deployment emulation. Developers still need local PHP/extensions and Composer dependencies. No production deployment behavior changes are intended.

@denusklo

denusklo commented Oct 3, 2026

Copy link
Copy Markdown
Author

Follow-up from lifecycle stress testing: a client disconnect during startDevServer() exposes a CLI-side race, now reported at vercel/vercel#17672.

The CLI attaches its response-close listener after awaiting the hook, so it can miss an already-emitted close and retain the returned request-scoped server. This reproduces on current CLI62.2.0 with a standalone Node-only builder, without PHP or this PR. I haven't added a speculative PHP timeout/supervisor workaround here. Normal shutdown and client disconnect after readiness passed on Windows, Linux and macOS.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Why isn't vercel dev supported?

1 participant