§Overview
SWLGUISIGN is a Laravel application shipped as a native desktop app via NativePHP, with an Electron shell wrapping a self-contained PHP 8.4 runtime. The three install.* scripts at the repo root are the only supported way to produce a shippable build — they install dependencies, obfuscate the PHP source, build the Vite frontend, patch NativePHP's Electron packaging config, and invoke php artisan native:build.
Each script is equivalent for its platform. Pick the one matching where you're building — cross-compiling from macOS to Windows (or vice versa) is not supported.
§Prerequisites
| Tool | Version | Notes |
|---|---|---|
| PHP | 8.3+ (8.4 used in CI) | Auto-detected from PATH, or pass --php / -PhpPath explicitly. |
| Node.js | 22+ | Required for both the Vite build and Electron's own node_modules. |
| Composer | any recent 2.x | Windows: the script looks for composer.phar next to composer on PATH and runs it via the resolved PHP directly. |
| ImageMagick | optional | install.ps1 only — converts public/main.jpg into the Windows .ico. Skipped with a warning if magick isn't found. |
§Quick start
Default behavior on every platform is a full production build with obfuscation. Nothing extra needs to be passed.
$ ./install.sh # build .dmg, obfuscated $ ./install.sh --no-obf # build .dmg, skip obfuscation $ ./install.sh --run # dev server only $ ./install.sh --php /opt/homebrew/opt/php@8.4/bin
> install.bat :: build .exe, obfuscated > install.bat --no-obf :: build .exe, skip obfuscation > install.bat --php C:\php84
PS> .\install.ps1 # build .exe, obfuscated PS> .\install.ps1 -NoObf # build .exe, skip obfuscation PS> .\install.ps1 -Run # dev server only PS> .\install.ps1 -PhpPath C:\php84
Obfuscation is the default, not an opt-in — a plain ./install.sh or install.bat always runs tools/yakpro-po against app/. Read Known issue & fix before packaging a release build.
§Build pipeline
What each script actually does, in order. Steps tagged Windows only or PowerShell only don't run on the other scripts.
Finds PHP 8.3+, Node 22+, and Composer, then prepends the resolved PHP's directory to PATH so every child process — Composer, npm, native:build — resolves the same binary.
composer install --no-dev --optimize-autoloader --no-interaction
Installs root node_modules. install.bat additionally installs vendor/nativephp/desktop/resources/electron/node_modules if missing.
APP_KEYCopies .env.example → .env if absent, then force-generates APP_KEY if it's missing or empty. This check is separate from "does .env exist" — the build bakes .env straight into resources/build/app/.env, so a blank key ships a package that crashes with MissingAppKeyException.
app/ with yakpro-poRuns tools/yakpro-po/yakpro-po.php, replaces app/ with the obfuscated output. Skippable with --no-obf / -NoObf. See known issue →
npm run build — compiles the Vite/Inertia assets.
Unzips the platform PHP 8.4 binary from vendor/nativephp/php-bin into vendor/nativephp/desktop/resources/build/php, so Electron ships a self-contained interpreter.
electron-builder.mjsRuns scripts/patch-electron-builder.mjs — an idempotent no-op beforePack patch. Safe to run on every build.
Adds allowToChangeInstallationDirectory: true and oneClick: false to the NSIS block so the Windows installer lets users pick an install directory.
extras/Creates an empty extras/ folder — electron-builder expects it to exist.
Extracts the winCodeSign cache while excluding darwin/, whose .dylib symlinks need SeCreateSymbolicLinkPrivilege to create. Non-fatal on failure — falls back to letting electron-builder fetch it.
If magick is available, converts public/main.jpg into build/icon.ico at the sizes Windows expects. Skipped with a warning otherwise.
php artisan native:build mac arm64|x64 or native:build win x64, with NATIVEPHP_APP_ID, version, and author set for th.co.spn.guisign.
§Known issue & fix
A production build threw Undefined property errors from controllers that use constructor property promotion (private readonly WorkspaceService $workspace style parameters). The plain source was correct — the bug lives in the obfuscator that Step 5 runs against it.
Symptom
production.ERROR: Undefined property: App\Http\Controllers\ConfigurationController::$workspace
{"exception":"[object] (ErrorException(code: 0): Undefined property: …
at …/app/Http/Controllers/ConfigurationController.php:8)"}
Only shows up in an obfuscated build — never in --no-obf builds or during artisan native:run, which is what made it easy to miss in dev.
Root cause
tools/yakpro-po/include/classes/parser_extensions/my_node_visitor.php renames identifiers through several independent, globally-scoped scramblers — one for variable names, a separate one for property names — that never coordinate with each other:
- The variable scrambler renames every
Paramnode's$var— including a promoted param's nestedExpr\Variablechild, which the traverser visits as its own node. - The property scrambler independently renames every
PropertyFetchnode (any$this->xxxread/write), with no awareness of how — or whether — that property was declared.
A promoted parameter (private readonly Foo $bar in a constructor signature) is both a variable and an implicit property declaration with the same name — PHP creates the property using whatever name the parameter ends up with. Because the two scramblers pick names independently, the declared property and its $this->bar access sites almost never land on the same random name. Whichever one wins, the other is left pointing at a property that no longer exists.
An initial attempt patched only the variable scrambler to skip promoted params. That fixed the declaration side but left the property scrambler free to keep renaming every $this->bar access on its own — so the mismatch persisted, just inverted. Confirmed by actually running the obfuscator (see below) rather than reasoning from source alone.
Fix applied
Rather than patching the vendored obfuscator's traversal logic — fragile, and easy to leave half-fixed the way the first attempt did — the fix uses yakpro-po's own t_ignore_variables / t_ignore_properties config lists in tools/yakpro-po/yakpro-po.cnf. Every constructor-promoted property name in app/ is listed in both, so neither scrambler ever touches them — the declaration and every access site all keep the original literal name, everywhere, regardless of file processing order:
// yakpro-po.cnf
$promoted_property_names = array(
'service', 'workspace', 'profiles',
'name', 'message', 'level', 'profileName',
'generation',
'pipeline', 'gateway', 'signer',
'outboxReader', 'packager', 'mover', 'signing',
'encrypter', 'decrypter',
'rest', 'ftp',
);
$conf->t_ignore_variables = $promoted_property_names;
$conf->t_ignore_properties = $promoted_property_names;
Verified end to end with the real obfuscator (PHP 8.4 in Docker, not just static reading): ran yakpro-po.php against the actual app/ directory, confirmed every promoted name matches between declaration and access in the obfuscated output, php -l linted clean across all obfuscated files, and a minimal reproduction class instantiated and called through its obfuscated form without the "Undefined property" error.
Whenever a new constructor-promoted property is added anywhere in app/, its parameter name has to be added to $promoted_property_names in yakpro-po.cnf too — otherwise this exact bug comes back, silently, and only in obfuscated builds.
Surfaces that were at risk
Promotion is used throughout the app — any of these could have hit the same bug once obfuscated, not just ConfigurationController:
Run a full obfuscated build, open the app, and exercise Configuration → create/edit a profile — the path that originally surfaced this. Also spot-check a full sign cycle, since SendPipeline, SigningService, and GatewayService all use promotion too.
§Troubleshooting
| Symptom | Cause | Fix |
|---|---|---|
PHP 8.3+ not found |
No PHP on PATH, or one below 8.3. |
Pass --php / -PhpPath pointing at a PHP 8.3+ install. |
composer.phar not found |
Windows only — install.bat expects composer.phar next to composer on PATH. |
Reinstall Composer with the official Windows installer, which places both. |
MissingAppKeyException in the packaged app |
.env existed already but had an empty APP_KEY=, so the auto-generate check was skipped. |
Run php artisan key:generate --force before building, or delete .env and let the script recreate it. |
| winCodeSign extract fails: required privilege not held | Creating the darwin/ .dylib symlinks needs admin rights or Developer Mode. |
Non-fatal — the script already excludes darwin/ and falls back to electron-builder's own handling. Only matters if you're also signing macOS builds. |
Undefined property in production only |
See Known issue & fix — obfuscator/constructor-promotion mismatch. | Confirm the promoted-property name is listed in yakpro-po.cnf's $promoted_property_names, then rebuild. |
Allowed memory size of 134217728 bytes exhausted in scrambler.php |
yakpro-po holds a rename map for the whole codebase in memory at once. A stock php.ini's 128M default (134217728 bytes) isn't enough for this app's size. |
All three install scripts now run the obfuscation step with -d memory_limit=1024M. If it still runs out, pass an even higher value or set memory_limit=-1 (unlimited) in the PHP you point --php at. |
§Output
| Platform | Location |
|---|---|
| macOS | nativephp/electron/dist/*.dmg |
| Windows | nativephp\electron\dist\SWLGUISIGN-*.exe |