examples

Examples

Shipped demos live under examples/00x-*/ with an example.php entry script. Use the unified phpc CLI from the repo root (wrapper around bin/vm.php, bin/compile.php, bin/lint.php, and bin/serve.php).

Quick start (all examples)

./phpc lint examples/000-HelloWorld/example.php
./phpc run examples/000-HelloWorld/example.php

./phpc lint examples/001-SimpleWeb/example.php
./phpc run -q 'name=World' examples/001-SimpleWeb/example.php
./phpc serve 127.0.0.1:8080 examples/001-SimpleWeb

./phpc lint examples/002-StaticWeb/example.php
./phpc run examples/002-StaticWeb/example.php

./phpc lint examples/004-ApiJson/example.php
./phpc run examples/004-ApiJson/example.php

AOT (needs LLVM 9 — see script/install-llvm9.sh or the php-compiler:22.04-dev Docker image):

./phpc build -o /tmp/hello examples/000-HelloWorld/example.php && /tmp/hello
cd examples/001-SimpleWeb && ../../phpc build --project .
# or: ../../phpc build -o .phpc/bin/app example.php
../../phpc serve --aot 127.0.0.1:8080 .

Legacy entrypoints still work: php bin/vm.php, php bin/jit.php, php bin/compile.php -l.

Run matrix

Example	VM	JIT	AOT build	AOT runtime notes
000-HelloWorld	✅ ./phpc run	✅ bin/jit.php	optional	no superglobals
001-SimpleWeb	✅ -q / -p / env / phpc serve	✅ bin/jit.php	✅ phpc build	runtime QUERY_STRING / POST (#201, #257, #259)
002-StaticWeb	✅ ./phpc run	✅ bin/jit.php	✅ recommended	no superglobals — #247 execute smoke
004-ApiJson	✅ ./phpc run	✅ bin/jit.php	✅ phpc build	JSON + http_response_code — #270, #61
003-MiniWebApp	✅ phpc serve	partial	✅ phpc build --project	PATH_INFO — #489, runtime #539; AOT link ✅ (#752); native execute 📋 (#764)

000-HelloWorld

Plain echo; no CGI superglobals.

./phpc lint examples/000-HelloWorld/example.php
./phpc run examples/000-HelloWorld/example.php
php bin/jit.php examples/000-HelloWorld/example.php
./phpc build -o /tmp/hello examples/000-HelloWorld/example.php && /tmp/hello   # optional

001-SimpleWeb

Reads name from $_REQUEST (GET query or POST form body); serves HTML, a POST form, and /style.css.

./phpc lint examples/001-SimpleWeb/example.php
./phpc run -q 'name=World' examples/001-SimpleWeb/example.php
./phpc run -p 'name=Posted' examples/001-SimpleWeb/example.php
./phpc serve 127.0.0.1:8080 examples/001-SimpleWeb
curl -s 'http://127.0.0.1:8080/example.php?name=Dev'
curl -s -X POST -d 'name=PostDev' 'http://127.0.0.1:8080/example.php'
cd examples/001-SimpleWeb
../../phpc build -o .phpc/bin/app example.php
../../phpc serve --aot 127.0.0.1:8080 .

AOT binaries refresh $_GET / $_POST / $_REQUEST from CGI env on each request unless you bake values at compile time with -q on phpc build.

003-MiniWebApp

Reference front controller with PATH_INFO routes (#489). VM serve and examples-web-smoke.sh curls are green. phpc build --project links when LLVM is available (#752); native execute still returns empty stdout until #764 (ExamplesCompileTest documents the gap).

./phpc lint --all examples/003-MiniWebApp
./phpc serve 127.0.0.1:8080 examples/003-MiniWebApp
curl -s 'http://127.0.0.1:8080/index.php/hello?name=Dev'
./script/examples-web-smoke.sh
make web-smoke

See 003-MiniWebApp/README.md for routes and gate ladder (make miniwebapp-gates). AOT deploy quickstart: docs/deploy-web-aot.md.

002-StaticWeb

Static page (no superglobals); good default for first AOT compile.

./phpc lint examples/002-StaticWeb/example.php
./phpc run examples/002-StaticWeb/example.php
php bin/jit.php examples/002-StaticWeb/example.php
cd examples/002-StaticWeb
../../phpc build -o .phpc/bin/app example.php && ./.phpc/bin/app
../../phpc serve --aot 127.0.0.1:8080 .

phpc.json (web examples)

Full field reference: docs/phpc-json.md (#727).

001-SimpleWeb, 002-StaticWeb, and 004-ApiJson ship a minimal manifest beside example.php (#274):

{
    "entry": "example.php",
    "binary": ".phpc/bin/app"
}

entry is the script to compile; binary is the default AOT output path for phpc serve --aot (see lib/Web/ProjectManifest.php).

CI and local verification

PHPUnit gate: test/unit/ExamplesCompileTest.php — every examples/*/example.php is linted (phpc lint), smoke-run under bin/vm.php (GET and POST for 001-SimpleWeb), and (when LLVM is available) checked with bin/compile.php -l / phpc build (#203, #243, #247, #282, #259).

Before a PR that touches examples or bin/serve.php:

make web-smoke              # lint examples/*/example.php + 003 lint --all + VM ?name= smoke
make examples-web-smoke     # phpc serve + curl GET/POST (001-SimpleWeb, 002-StaticWeb, 004-ApiJson)
make examples-aot-smoke     # phpc build + CLI execute (000–004; skips when LLVM missing; 003 execute #764)

Full CI (./script/ci-local.sh) runs examples-aot-smoke.sh after PHPUnit @group aot-link when LLVM is available (EXAMPLES_AOT_SMOKE_GATE=1 default in script/ci-defaults.env; set EXAMPLES_AOT_SMOKE_GATE=0 to skip during iteration — #674). Not run in ci-fast.sh.

Full suite on the host (after composer install):

./script/ci-local.sh
EXAMPLES_AOT_SMOKE_GATE=0 ./script/ci-local.sh   # skip 000–004 CLI AOT execute smoke (#674)

In Docker (preferred on harness hosts without host PHP/LLVM):

make test-docker            # or: ./script/docker-ci-local.sh
docker run --rm -v "$(pwd):/compiler" -w /compiler php-compiler:22.04-dev ./script/ci-local.sh

Root README quick start and local CI matrix: #48, #245.

Benchmark results

Each example includes a benchmark that compares VM, JIT, and (when LLVM is present) AOT against native php. Regenerate this table with script/rebuild-examples.php (#60).

MINIWEBAPP_LINT_GATE=1 ./script/rebuild-examples.php
# or: BENCH_MINIWEBAPP=1 ./script/rebuild-examples.php

For 001-SimpleWeb, bin/compile.php is timed without compile-time -q; the ./compiled column runs the binary with runtime QUERY_STRING (and related CGI env), matching production AOT web binaries.

For 003-MiniWebApp, VM/JIT/native columns run public/index.php with PATH_INFO=/home (and related CGI env) from the example public/ directory (#491, runtime #539). AOT execute columns stay n/a until native run is green (#764; link #568 closed, #624). The row is omitted when phpc lint --all examples/003-MiniWebApp fails unless BENCH_MINIWEBAPP=1.

Example Name	Native PHP	bin/vm.php	bin/jit.php	bin/compile.php	./compiled
000-HelloWorld	0.00778	0.04055	0.16935	0.55685	0.00092
001-SimpleWeb	0.01024	0.04413	0.16994	0.53688	0.00092
002-StaticWeb	0.01098	0.04485	0.16732	0.55200	0.00118
003-MiniWebApp	0.00878	0.09707	0.11338	n/a	n/a
004-ApiJson	0.00752	0.04128	0.16942	0.55373	0.00104