NativePHP for Desktop Documentation

NativePHP manages a collection of child processes to ensure the PHP environment and its associated services (like the scheduler) are correctly cleaned up when the Electron application exits.

Process Cleanup

When the Electron app receives a before-quit event, NativePHP performs a coordinated shutdown:

1. Kill Framework Processes: It first stops the framework's own processes (like the PHP server) to prevent new requests from spawning fresh child processes during shutdown.
2. Stop App Processes: It sends a SIGTERM to the application's child processes, allowing them to perform their own cleanup (flushing data, persisting state).
3. Graceful Wait: It waits up to 12 seconds for processes to exit naturally before forcing a shutdown.

Scheduler Lifecycle

The scheduler runs tasks at minute intervals. It is sensitive to system power states:

• Suspend: When the system suspends, the scheduler is stopped.
• Resume: When the system resumes, the scheduler is restarted.

Security

To secure communication between the Electron frontend and the PHP backend, NativePHP injects an X-NativePHP-Secret header into all requests sent to the local PHP server (http://127.0.0.1:${state.phpPort}/*).

NativePHP reads configuration from the underlying PHP environment to configure Electron-specific features. The following settings are extracted from the NativePHP configuration:

• app_id: Used to set the Electron appUserModelId.
• deeplink_scheme: If provided, NativePHP registers this protocol (e.g., myapp://) with the operating system. It also handles open-url (macOS) and second-instance (Windows/Linux) events to notify the Laravel application of the incoming URL.
• updater:
  • enabled: Boolean to enable/disable automatic updates.
  • default: The name of the default provider to use.
  • providers: A map of provider configurations. Each provider can have a public_url used to set the autoUpdater feed URL.

When a deep link is triggered, NativePHP notifies Laravel by dispatching the \Native\Desktop\Events\App\OpenedFromURL event with the URL as the payload.

When creating a menubar application, you provide an Options object to define the behavior, appearance, and window properties of the menubar. Key configurations include the window dimensions, the icon used in the system tray, the URL to load, and the positioning of the window relative to the tray.

Window and URL Configuration

• browserWindow: An object containing BrowserWindowConstructorOptions (e.g., width, height).
• dir: The directory containing your application source.
• index: The URL to load. Defaults to file:// + dir + index.html. Set to false to prevent automatic loading.
• loadUrlOptions: Options passed directly to Electron's browserWindow.loadURL().

Appearance and Tray

• icon: A path to a PNG icon or an Electron.NativeImage. For retina support, provide a 2x sized image with @2x appended to the filename (e.g., icon@2x.png).
• tooltip: The text displayed when hovering over the menubar tray icon.
• tray: An optional Electron.Tray instance. If provided, the icon option is ignored.
• showDockIcon: (macOS only) If false, hides the application dock icon.

Behavior and Positioning

• activateWithApp: If true (default), the menubar opens when the app is activated via app.on('activate').
• preloadWindow: If true, creates the BrowserWindow instance before use to speed up loading at the cost of higher initial resource usage.
• showOnAllWorkspaces: (macOS) Makes the window available on all OS X workspaces.
• showOnRightClick: If true, the window shows on a 'right-click' event instead of a regular click.
• windowPosition: Defines where the window appears relative to the tray or screen corners.

const options = { height: 640, width: 480 };

const mb = new Menubar({
  browserWindow: options
});