How to Set Up and Run NativePHP Desktop V1.0 – A Step‑by‑Step Guide

Overview

NativePHP compiles PHP code into native binaries, enabling desktop applications that run directly on the OS without a web server or PHP interpreter.

Startup Process

Step 1 – Install dependencies and start services

In vendor/nativephp/resources/js install the electron npm package (e.g., npm install electron --save-dev). If the npm registry is slow, use a proxy or mirror.

Run npm run dev. According to package.json this executes node php.js and electron-vite dev --watch, which starts the Node helper and watches the Electron source.

Step 2 – Inject environment variables and unpack PHP binary

Before launching, set an ENV object (or real environment variables) that contains the path to the compressed PHP binary package and the target PHP version, e.g. PHP_ZIP=/path/to/php.zip and PHP_VERSION=8.2.0. php.js reads these variables, extracts the zip file, and copies the resulting files to vendor/nativephp/resources/js/resources/php.

Step 3 – Electron client initialization

The command electron-vite dev launches the Electron client via the plugin located at vendor/nativephp/resources/js/electron-plugin.

The plugin builds the Electron bundle, starts a local webserve server, and exposes low‑level APIs. Core logic resides in vendor/nativephp/resources/js/electron-plugin/src/index.ts.

After Electron finishes initializing, execute php artisan native:config to generate a PHP‑ini configuration file (memory limit, extensions, etc.) based on the bundled binary.

Step 4 – Bridge API service and PHP service startup

Start the Node API bridge (e.g., node api-server.js) which provides endpoints for window management, file dialogs, and other native functions.

Start the Laravel‑based PHP service with php artisan serve while passing the environment variable NATIVEPHP_RUNNING=1. The service detects the Electron context and registers additional routes.

Step 5 – Route registration and event handling

The PHP service registers three core routes defined in vendor/nativephp/larave/routes/api.php. These routes allow the Node bridge to invoke PHP code and retrieve configuration.

JavaScript side registers event listeners (e.g., open-window, open-file) that forward user actions to the PHP routes.

Step 6 – Electron ↔ PHP interaction

When Electron emits its first activate event, it sends an HTTP GET request to /_native/api/booted. This notifies the PHP backend that the UI is ready.

The request triggers App\Providers\NativeAppServiceProvider, which calls Window::open() exactly once. Window::open() performs an HTTP call to the Node API bridge; the Node side then creates the requested window.

Workflow diagram