README

PHP Packager 1.0.0

Pack any PHP web application into a single self-contained Windows EXE — no installer required on the end-user machine.

How it works

1. You supply your PHP app source and a Windows PHP runtime (e.g. PHP 8.0 NTS).
2. The packager bundles them into a single EXE using a launcher stub.
3. The end user runs the EXE. It extracts to %LOCALAPPDATA%, starts PHP's built-in server, and opens a browser — no PHP installation needed on the target machine.

Contents of this archive

php-packager-1.0.0\
  bin\
    embed_cli.exe       ??? packaging tool (creates the final EXE)
    launcher_stub.exe   ??? launcher template embedded into every packaged app
    updater.exe         ??? optional: in-place app updater helper
  builder\src\          ??? Pascal source (reference / recompile if needed)
  launcher\src\
  updater\src\
  shared\src\
  installer\
    setup.iss           ??? Inno Setup template for creating an installer
  tools\
    build_release.bat   ??? one-command release build
    build_installer.bat ??? optional Inno Setup installer build
    generate_manifest.ps1
    smoke_test_release.ps1
    (and more)
  examples\
    packager.yml        ??? annotated configuration example
    manifest.json
  docs\
    packager_user_guide.md
  README.md             ??? this file

Prerequisites

Quick start

1. Prepare your staging folder

Create a staging\ folder at the root of this archive:

staging\
  packager.yml         ??? your configuration (copy from examples\packager.yml)
  app\
    your-app\
      public\
        index.php      ??? your PHP entry point
        healthz.php    ??? optional health check (return HTTP 200)
  runtime\
    php80\
      php.exe
      php.ini.base     ??? minimal php.ini (can be empty)
      ext\
        *.dll          ??? PHP extension DLLs

Download a Windows PHP NTS x64 build from windows.php.net/download and extract it into staging\runtime\php80\.

2. Configure packager.yml

Copy examples\packager.yml to staging\packager.yml and edit it:

app_name: MyApp
app_version: 1.0.0
app_dir: app/your-app
document_root: public
entrypoint: public/index.php
healthcheck_path: public/healthz.php
php_runtime: runtime/php80
open_mode: browser        # browser | manual | none
output_dir: dist
work_dir: work
php_extensions_required:
  - mbstring
  - openssl
php_ini:
  memory_limit: 256M
  max_execution_time: 60
  post_max_size: 32M
  upload_max_filesize: 32M
exclude:
  - .git
  - node_modules
  - tests

Key fields:

3. Build

Copy the pre-built binaries from bin\ to dist\ (skip recompiling Pascal source):

mkdir dist
copy bin\launcher_stub.exe dist\
copy bin\embed_cli.exe dist\
copy bin\updater.exe dist\

Then run the embed step:

tools\embed_release.bat dist\launcher_stub.exe staging dist\MyApp.exe 1.0.0

Or run the full one-command build (requires Lazarus/FPC — recompiles everything):

tools\build_release.bat

Output: dist\MyApp.exe

4. Test

dist\MyApp.exe

The app extracts to %LOCALAPPDATA%\MyApp\versions\<version_hash>\ and opens your browser at http://localhost:18080 (or the next available port up to 18120).

Logs: %LOCALAPPDATA%\MyApp\logs\startup.log

5. Build an installer (optional)

Requires Inno Setup 6:

tools\build_installer.bat

Output: a setup EXE in dist\.

Signing (optional)

Set SIGN_CERT_SHA1 to your Authenticode certificate thumbprint before building to sign all output EXEs:

set SIGN_CERT_SHA1=<your certificate thumbprint>
tools\build_release.bat

Set STRICT_RELEASE=1 to enforce signing — the build will fail immediately if SIGN_CERT_SHA1 is not set:

set STRICT_RELEASE=1
set SIGN_CERT_SHA1=<thumbprint>
tools\build_release.bat

Environment variables reference

Runtime behaviour (end user)

When the end user runs the packaged EXE:

1. Verifies embedded payload SHA-256 checksum.
2. Extracts to %LOCALAPPDATA%\<AppName>\versions\<version_hash>\ — only on first run or after an update.
3. Starts PHP built-in server on localhost:18080 (tries ports up to 18120).
4. Waits for the health check endpoint to respond.
5. Opens the default browser to the configured entrypoint.

Updater (optional)

bin\updater.exe supports in-place version switching:

updater.exe <app_exe> <new_version> [wait_pid] [manifest.json] [manifest.sig] [signer_thumbprint]

• Waits for wait_pid to exit, then replaces the app EXE and relaunches.
• Optionally verifies a signed update manifest (SHA-256 + CMS/PKCS#7 signature) before proceeding.

See docs\updater_notes.md for full details.

Recompiling from source

If you need to modify the launcher, builder, or updater:

1. Install Lazarus IDE with FPC 3.2.2.
2. Open the relevant .lpi project file:
   • launcher\launcher.lpi
   • builder\embed_cli.lpi
   • updater\updater.lpi
3. Build from Lazarus, or run tools\build_release.bat — it compiles everything automatically.

Further reading

• docs\packager_user_guide.md — full configuration and build reference
• docs\single_exe_format.md — binary format specification
• docs\updater_notes.md — updater integration guide
• docs\installer_notes.md — Inno Setup customisation guide
• examples\packager.yml — fully annotated configuration example