NativePHP for Desktop

https://github.com/nativephp/desktop
Admin
NativePHP for Desktop allows developers to write native desktop applications using PHP.
Tokens:88,092
Snippets:792
Trust Score:9.7
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### Direct GET request example

Source: https://github.com/nativephp/desktop/blob/main/_autodocs/api-reference/Client.md

Direct usage example: creates a Client instance, performs a GET request to 'power-monitor/get-system-idle-time', and reads the 'result' field from the JSON response.

```php
use Native\Desktop\Client\Client;

$client = new Client;

$response = $client->get('power-monitor/get-system-idle-time');
$seconds = $response->json('result');
```

--------------------------------

### Usage example for AutoUpdater facade

Source: https://github.com/nativephp/desktop/blob/main/_autodocs/api-reference/AutoUpdater.md

Shows how to use the AutoUpdater facade to check for updates, download, and quit and install.

```php
use Native\Desktop\Facades\AutoUpdater;

AutoUpdater::checkForUpdates();

// after UpdateAvailable -> user confirms:
AutoUpdater::downloadUpdate();

// after UpdateDownloaded:
AutoUpdater::quitAndInstall();
```

--------------------------------

### start()

Source: https://github.com/nativephp/desktop/blob/main/_autodocs/api-reference/Process.md

Starts a new child process with the given command and alias.

```APIDOC
## start()

### Description
Starts a new child process with the given command and alias. The command can be a string or an array of arguments.

### Method
POST

### Endpoint
child-process/start

### Parameters
#### Request Body
- **cmd** (string|array) - Required - Command string or argv array.
- **alias** (string) - Required - Unique runtime alias.
- **cwd** (?string) - Optional - Working directory. Defaults to base_path().
- **env** (?array) - Optional - Extra environment variables.
- **persistent** (bool) - Optional - Keep alive / auto-restart. Defaults to false.
- **handlesOwnShutdown** (bool) - Optional - Process manages its own shutdown. Defaults to false.

### Request Example

{
  "cmd": "php artisan serve",
  "alias": "my-server",
  "cwd": "/path/to/project",
  "env": {"APP_ENV": "local"},
  "persistent": true,
  "handlesOwnShutdown": false
}


### Response
#### Success Response (200)
- **ChildProcess** - The hydrated ChildProcess instance.

#### Response Example
json
{
  "pid": 1234,
  "alias": "my-server",
  "cmd": ["php", "artisan", "serve"],
  "cwd": "/path/to/project",
  "env": {"APP_ENV": "local"},
  "persistent": true,
  "handlesOwnShutdown": false,
  "iniSettings": null
}

```

--------------------------------

### Usage Example

Source: https://github.com/nativephp/desktop/blob/main/_autodocs/api-reference/PowerMonitor.md

Shows how to use PowerMonitor facade to get idle state, idle time, thermal state, and battery status, with switch cases for handling different states.

```php
use Native\Desktop\Facades\PowerMonitor;
use Native\Desktop\Enums\SystemIdleStatesEnum;
use Native\Desktop\Enums\ThermalStatesEnum;

$state = PowerMonitor::getSystemIdleState(300);   // SystemIdleStatesEnum
$seconds = PowerMonitor::getSystemIdleTime();
$thermal = PowerMonitor::getCurrentThermalState();

if (PowerMonitor::isOnBatteryPower()) {
    // reduce background work
}

switch ($state) {
    case SystemIdleStatesEnum::IDLE:
        // pause animations
        break;
    case SystemIdleStatesEnum::LOCKED:
        // clear sensitive state
        break;
}
```

--------------------------------

### start() method

Source: https://github.com/nativephp/desktop/blob/main/_autodocs/api-reference/Process.md

Starts a child process with the given command and alias. Posts to child-process/start and hydrates the instance from the response. $cmd can be a string (parsed via parseCommand) or an argv array.

```php
/**
 * @param  string|string[]  $cmd
 * @return $this
 */
public function start(
    string|array $cmd,
    string $alias,
    ?string $cwd = null,
    ?array $env = null,
    bool $persistent = false,
    bool $handlesOwnShutdown = false
): self
```

--------------------------------

### Usage example: builder options and environment variables

Source: https://github.com/nativephp/desktop/blob/main/_autodocs/api-reference/AutoUpdater.md

Shows how to use the Updater facade to get builder options and environment variables, and how to switch providers. The comment notes that builderOptions() returns an array for electron-builder publish config and environmentVariables() returns an array of secrets to export.

```php
use Native\Desktop\Drivers\Electron\Facades\Updater;

$options = Updater::builderOptions();        // array for electron-builder publish config
$env = Updater::environmentVariables();      // array of secrets to export

// provider switching:
Updater::setDefaultDriver('github');
$github = Updater::provider('github');
```

--------------------------------

### Theme handling example

Source: https://github.com/nativephp/desktop/blob/main/_autodocs/api-reference/System.md

Example of reading the current theme and forcing a light theme. It compares the current theme to SystemThemesEnum::DARK to load dark assets, and sets the theme to LIGHT.

```php
use Native\Desktop\Facades\System;
use Native\Desktop\Enums\SystemThemesEnum;

$current = System::theme();

if ($current === SystemThemesEnum::DARK) {
    // load dark assets
}

System::theme(SystemThemesEnum::LIGHT); // force light
```

--------------------------------

### php()

Source: https://github.com/nativephp/desktop/blob/main/_autodocs/api-reference/Process.md

Starts a PHP process using the bundled runtime.

```APIDOC
## php()

### Description
Starts a PHP process using the bundled runtime. Posts to child-process/start-php with optional ini settings.

### Method
POST

### Endpoint
child-process/start-php

### Parameters
#### Request Body
- **cmd** (string|array) - Required - Command string or argv array.
- **alias** (string) - Required - Unique runtime alias.
- **env** (?array) - Optional - Extra environment variables.
- **persistent** (?bool) - Optional - Keep alive / auto-restart. Defaults to false.
- **iniSettings** (?array) - Optional - PHP ini settings, e.g. ['memory_limit' => '512M'].
- **handlesOwnShutdown** (bool) - Optional - Process manages its own shutdown. Defaults to false.

### Request Example

{
  "cmd": "artisan serve",
  "alias": "my-php",
  "env": null,
  "persistent": false,
  "iniSettings": {"memory_limit": "512M"},
  "handlesOwnShutdown": false
}


### Response
#### Success Response (200)
- **ChildProcess** - The hydrated ChildProcess instance.

#### Response Example

{
  "pid": 1234,
  "alias": "my-php",
  "cmd": ["php", "artisan", "serve"],
  "cwd": "/path/to/project",
  "env": null,
  "persistent": false,
  "handlesOwnShutdown": false,
  "iniSettings": {"memory_limit": "512M"}
}

```

--------------------------------

### Registering a shortcut in NativeAppServiceProvider::boot()

Source: https://github.com/nativephp/desktop/blob/main/_autodocs/api-reference/GlobalShortcut.md

Example of registering a global shortcut with key and event.

```php
use Native\Desktop\Facades\GlobalShortcut;

GlobalShortcut::key('CommandOrControl+Shift+P')
    ->event(\App\Events\TogglePalette::class)
    ->register();
```

--------------------------------

### Basic settings read/write

Source: https://github.com/nativephp/desktop/blob/main/_autodocs/api-reference/Settings.md

Basic read/write example: sets a theme and retrieves it with a default.

```php
use Native\Desktop\Facades\Settings;

Settings::set('theme', 'dark');

$theme = Settings::get('theme', 'light');
// $theme === 'dark'
```

--------------------------------

### POST child-process/start

Source: https://github.com/nativephp/desktop/blob/main/_autodocs/endpoints.md

Starts a child process. Used by ChildProcess::start().

```APIDOC
## POST child-process/start

### Description
Starts a child process.

### Method
POST

### Endpoint
`child-process/start`

### Parameters
#### Request Body
- `alias` (string) - Required - The alias for the process.
- `cmd` (string) - Required - The command to run.
- `cwd` (string) - Optional - The working directory.
- `env` (object) - Optional - Environment variables.
- `persistent` (boolean) - Optional - Whether the process persists.
- `handlesOwnShutdown` (boolean) - Optional - Whether the process handles its own shutdown.

### Request Example
{
  "alias": "my-process",
  "cmd": "node server.js",
  "cwd": "/path",
  "env": {},
  "persistent": true,
  "handlesOwnShutdown": false
}

### Response
#### Success Response
- `pid` (number) - The process ID.
- `settings` (object) - The settings map as described.
```

--------------------------------

### Printing examples

Source: https://github.com/nativephp/desktop/blob/main/_autodocs/api-reference/System.md

Examples of printing HTML, printing an existing PDF file, and converting HTML to a PDF on disk. The printToPDF method returns the path of the generated PDF.

```php
use Native\Desktop\Facades\System;

$printers = System::printers();
$first = $printers[0] ?? null;

System::print('<h1>Invoice</h1>', $first, ['copies' => 2]);

// Print a PDF that already exists on disk
$ok = System::printFile(storage_path('app/invoice.pdf'));

// Convert HTML to a PDF on disk; returns the path
$pdfPath = System::printToPDF('<h1>Report</h1>', ['printBackground' => true]);
```

--------------------------------

### Starting long-running processes with ChildProcess

Source: https://github.com/nativephp/desktop/blob/main/_autodocs/api-reference/Process.md

Shows how to start persistent PHP, Node, artisan, and generic processes using the ChildProcess facade.

```php
use Native\Desktop\Facades\ChildProcess;

ChildProcess::php(['worker.php'], 'php-worker', env: ['APP_ENV' => 'desktop'], persistent: true);
ChildProcess::node(['server.js'], 'node-server');
ChildProcess::artisan(['queue:work', '--tries=3'], 'queue-main', persistent: true);
ChildProcess::start(['ping', '8.8.8.8'], 'ping', cwd: base_path());
```

--------------------------------

### get() method

Source: https://github.com/nativephp/desktop/blob/main/_autodocs/api-reference/Window.md

Returns a single hydrated Window for the given id, from GET window/get/{id}.

```php
public function get(string $id): Window
```

--------------------------------

### node() method

Source: https://github.com/nativephp/desktop/blob/main/_autodocs/api-reference/Process.md

Starts a Node.js process. Posts to child-process/start-node.

```php
public function node(string|array $cmd, string $alias, ?array $env = null, ?bool $persistent = false, bool $handlesOwnShutdown = false): self
```

--------------------------------

### Error handling for pruneVendorDirectory

Source: https://github.com/nativephp/desktop/blob/main/_autodocs/api-reference/Builder.md

Error handling example for pruneVendorDirectory. Catches RuntimeException when composer install --no-dev fails inside the built app and reports the exception.

```php
use Native\Desktop\Builder\Builder;
use RuntimeException;

try {
    Builder::make()->pruneVendorDirectory();
} catch (RuntimeException $e) {
    // composer install --no-dev failed inside the built app
    report($e);
}
```

--------------------------------

### php() method

Source: https://github.com/nativephp/desktop/blob/main/_autodocs/api-reference/Process.md

Starts a PHP process using the bundled runtime. Posts to child-process/start-php with iniSettings (e.g., ['memory_limit' => '512M']).

```php
/**
 * @param  string|string[]  $cmd
 * @return $this
 */
public function php(
    string|array $cmd,
    string $alias,
    ?array $env = null,
    ?bool $persistent = false,
    ?array $iniSettings = null,
    bool $handlesOwnShutdown = false
): self
```

--------------------------------

### node()

Source: https://github.com/nativephp/desktop/blob/main/_autodocs/api-reference/Process.md

Starts a Node.js process.

```APIDOC
## node()

### Description
Starts a Node.js process. Posts to child-process/start-node.

### Method
POST

### Endpoint
child-process/start-node

### Parameters
#### Request Body
- **cmd** (string|array) - Required - Command string or argv array.
- **alias** (string) - Required - Unique runtime alias.
- **env** (?array) - Optional - Extra environment variables.
- **persistent** (?bool) - Optional - Keep alive / auto-restart. Defaults to false.
- **handlesOwnShutdown** (bool) - Optional - Process manages its own shutdown. Defaults to false.

### Request Example

{
  "cmd": "server.js",
  "alias": "my-node",
  "env": null,
  "persistent": false,
  "handlesOwnShutdown": false
}


### Response
#### Success Response (200)
- **ChildProcess** - The hydrated ChildProcess instance.

#### Response Example

{
  "pid": 1234,
  "alias": "my-node",
  "cmd": ["node", "server.js"],
  "cwd": "/path/to/project",
  "env": null,
  "persistent": false,
  "handlesOwnShutdown": false,
  "iniSettings": null
}

```

--------------------------------

### Touch ID gate example

Source: https://github.com/nativephp/desktop/blob/main/_autodocs/api-reference/System.md

Example of using System::canPromptTouchID() and System::promptTouchID() to gate access with Touch ID. If the user cancels or authentication fails, the promptTouchID call returns false.

```php
use Native\Desktop\Facades\System;

if (System::canPromptTouchID()) {
    if (! System::promptTouchID('Authenticate to unlock')) {
        // user cancelled or auth failed
    }
}
```

--------------------------------

### POST child-process/start-php

Source: https://github.com/nativephp/desktop/blob/main/_autodocs/endpoints.md

Starts a PHP child process. Used by ChildProcess::php().

```APIDOC
## POST child-process/start-php

### Description
Starts a PHP child process.

### Method
POST

### Endpoint
`child-process/start-php`

### Parameters
#### Request Body
- `alias` (string) - Required - The alias for the process.
- `cmd` (string) - Required - The command to run.
- `cwd` (string) - Optional - The working directory.
- `env` (object) - Optional - Environment variables.
- `persistent` (boolean) - Optional - Whether the process persists.
- `iniSettings` (object) - Optional - PHP ini settings.
- `handlesOwnShutdown` (boolean) - Optional - Whether the process handles its own shutdown.

### Request Example
{
  "alias": "php-worker",
  "cmd": "php worker.php",
  "cwd": "/path",
  "env": {},
  "persistent": true,
  "iniSettings": {},
  "handlesOwnShutdown": false
}

### Response
#### Success Response
- `pid` (number) - The process ID.
- `settings` (object) - The settings map including `iniSettings`.
```

--------------------------------

### GET screen/displays

Source: https://github.com/nativephp/desktop/blob/main/_autodocs/endpoints.md

Gets all displays. Used by Screen::displays().

```APIDOC
## GET screen/displays

### Description
Gets all displays.

### Method
GET

### Endpoint
`screen/displays`

### Response
#### Success Response
- `displays` (array) - List of display objects.
```

--------------------------------

### Error handling example

Source: https://github.com/nativephp/desktop/blob/main/_autodocs/api-reference/System.md

Example of handling ConnectionException when prompting for Touch ID. It catches the exception and sets $ok to false to degrade gracefully.

```php
use Native\Desktop\Facades\System;
use Illuminate\Http\Client\ConnectionException;

try {
    $ok = System::promptTouchID('Confirm payment');
} catch (ConnectionException $e) {
    $ok = false; // degrade gracefully
}
```

--------------------------------

### artisan()

Source: https://github.com/nativephp/desktop/blob/main/_autodocs/api-reference/Process.md

Starts an artisan command by prepending 'artisan' to the command and delegating to php().

```APIDOC
## artisan()

### Description
Starts an artisan command by prepending 'artisan' to the command and delegating to php(). Posts to child-process/start-php.

### Method
POST

### Endpoint
child-process/start-php

### Parameters
#### Request Body
- **cmd** (string|array) - Required - Command string or argv array (without 'artisan').
- **alias** (string) - Required - Unique runtime alias.
- **env** (?array) - Optional - Extra environment variables.
- **persistent** (?bool) - Optional - Keep alive / auto-restart. Defaults to false.
- **iniSettings** (?array) - Optional - PHP ini settings.
- **handlesOwnShutdown** (bool) - Optional - Process manages its own shutdown. Defaults to false.

### Request Example

{
  "cmd": "serve",
  "alias": "my-artisan",
  "env": null,
  "persistent": false,
  "iniSettings": null,
  "handlesOwnShutdown": false
}


### Response
#### Success Response (200)
- **ChildProcess** - The hydrated ChildProcess instance.

#### Response Example

{
  "pid": 1234,
  "alias": "my-artisan",
  "cmd": ["php", "artisan", "serve"],
  "cwd": "/path/to/project",
  "env": null,
  "persistent": false,
  "handlesOwnShutdown": false,
  "iniSettings": null
}

```

--------------------------------

### Usage example: reveal and open files

Source: https://github.com/nativephp/desktop/blob/main/_autodocs/api-reference/Shell.md

Shows how to use the Shell facade to reveal a file in the file manager and open it with the default application.

```php
use Native\Desktop\Facades\Shell;

Shell::showInFolder(storage_path('app/report.pdf'));
Shell::openFile(storage_path('app/report.pdf'));
```

--------------------------------

### Usage example: trash and external links

Source: https://github.com/nativephp/desktop/blob/main/_autodocs/api-reference/Shell.md

Shows how to use the Shell facade to move a file to the trash and open an external URL.

```php
use Native\Desktop\Facades\Shell;

Shell::trashFile(storage_path('app/tmp.txt'));
Shell::openExternal('https://nativephp.com');
```

--------------------------------

### Error Handling Example

Source: https://github.com/nativephp/desktop/blob/main/_autodocs/api-reference/PowerMonitor.md

Shows how to handle unknown thermal state values gracefully by checking against ThermalStatesEnum::UNKNOWN.

```php
use Native\Desktop\Facades\PowerMonitor;
use Native\Desktop\Enums\ThermalStatesEnum;

$thermal = PowerMonitor::getCurrentThermalState();

if ($thermal === ThermalStatesEnum::UNKNOWN) {
    // the runtime returned an unrecognized value
}
```

--------------------------------

### GET process

Source: https://github.com/nativephp/desktop/blob/main/_autodocs/endpoints.md

Gets the current process information. Used by Process::fresh().

```APIDOC
## GET process

### Description
Gets the current process information.

### Method
GET

### Endpoint
`process`

### Response
#### Success Response
- Raw response containing process information (e.g., pid, memory, cpu).
```

--------------------------------

### artisan() method

Source: https://github.com/nativephp/desktop/blob/main/_autodocs/api-reference/Process.md

Prepends 'artisan' to the command and delegates to php(). Starts an artisan command as a PHP process.

```php
/**
 * @param  string|array  $cmd
 * @return $this
 */
public function artisan(string|array $cmd, string $alias, ?array $env = null, ?bool $persistent = false, ?array $iniSettings = null, bool $handlesOwnShutdown = false): self
```

--------------------------------

### ProgressBar start() method

Source: https://github.com/nativephp/desktop/blob/main/_autodocs/api-reference/ProgressBar.md

Stamps lastWriteTime and calls setProgress(0) to draw 0%.

```php
public function start()
```

--------------------------------

### get() method

Source: https://github.com/nativephp/desktop/blob/main/_autodocs/api-reference/Process.md

Returns a hydrated ChildProcess instance for the given alias, or null if not found. Defaults to the current instance's alias. Corresponds to GET child-process/get/{alias}.

```php
public function get(?string $alias = null): ?self
```

--------------------------------

### POST child-process/start-node

Source: https://github.com/nativephp/desktop/blob/main/_autodocs/endpoints.md

Starts a Node.js child process. Used by ChildProcess::node().

```APIDOC
## POST child-process/start-node

### Description
Starts a Node.js child process.

### Method
POST

### Endpoint
`child-process/start-node`

### Parameters
#### Request Body
- `alias` (string) - Required - The alias for the process.
- `cmd` (string) - Required - The command to run.
- `cwd` (string) - Optional - The working directory.
- `env` (object) - Optional - Environment variables.
- `persistent` (boolean) - Optional - Whether the process persists.
- `handlesOwnShutdown` (boolean) - Optional - Whether the process handles its own shutdown.

### Request Example
{
  "alias": "node-worker",
  "cmd": "node server.js",
  "cwd": "/path",
  "env": {},
  "persistent": true,
  "handlesOwnShutdown": false
}

### Response
#### Success Response
- `pid` (number) - The process ID.
- `settings` (object) - The settings map.
```

--------------------------------

### Reading and writing text with Clipboard

Source: https://github.com/nativephp/desktop/blob/main/_autodocs/api-reference/Clipboard.md

Example of writing and reading text using the Clipboard facade.

```php
use Native\Desktop\Facades\Clipboard;

Clipboard::text('Copied by NativePHP');

$current = Clipboard::text(); // 'Copied by NativePHP'
```

--------------------------------

### Keychain round-trip example

Source: https://github.com/nativephp/desktop/blob/main/_autodocs/api-reference/System.md

Example of encrypting and decrypting a secret using the system keychain. It checks System::canEncrypt() first, then encrypts a string and decrypts the cipher, handling null if encryption fails.

```php
use Native\Desktop\Facades\System;

if (System::canEncrypt()) {
    $cipher = System::encrypt('sup3r-secret');
    $plain = $cipher !== null ? System::decrypt($cipher) : null;
}
```

--------------------------------

### POST request with payload example

Source: https://github.com/nativephp/desktop/blob/main/_autodocs/api-reference/Client.md

Usage example for posting a payload: sends a POST request to 'dialog/open' with properties and buttonLabel, then reads the nested 'result.0' field from the response.

```php
use Native\Desktop\Client\Client;

$client = new Client;

$response = $client->post('dialog/open', [
    'properties' => ['openFile'],
    'buttonLabel' => 'Pick',
]);

$chosenPath = $response->json('result.0');
```

--------------------------------

### Error handling when runtime is unreachable

Source: https://github.com/nativephp/desktop/blob/main/_autodocs/api-reference/GlobalShortcut.md

Example of catching ConnectionException when registering a shortcut.

```php
use Native\Desktop\Facades\GlobalShortcut;
use Illuminate\Http\Client\ConnectionException;

try {
    GlobalShortcut::key('F12')->event(\App\Events\HotkeyPressed::class)->register();
} catch (ConnectionException $e) {
    logger()->warning('Could not register shortcut: '.$e->getMessage());
}
```

--------------------------------

### all() method

Source: https://github.com/nativephp/desktop/blob/main/_autodocs/api-reference/Process.md

Returns an array of ChildProcess instances keyed by alias for all tracked processes. Corresponds to GET child-process/.

```php
public function all(): array
```

--------------------------------

### Copying an image from disk with Clipboard

Source: https://github.com/nativephp/desktop/blob/main/_autodocs/api-reference/Clipboard.md

Example of copying an image from a file path and reading it back as a data URI.

```php
use Native\Desktop\Facades\Clipboard;

Clipboard::image('/abs/path/screenshot.png');

$dataUri = Clipboard::image(); // "data:image/png;base64,..."
```

--------------------------------

### Basic usage loop with ProgressBar

Source: https://github.com/nativephp/desktop/blob/main/_autodocs/api-reference/ProgressBar.md

Creates a progress bar with 100 steps, starts it, advances through a loop, and finishes to clear the native progress bar.

```php
use Native\Desktop\ProgressBar;

$bar = ProgressBar::create(100);
$bar->start();

foreach (range(1, 100) as $i) {
    // … do work …
    $bar->advance();
}

$bar->finish(); // clears the native progress bar
```

--------------------------------

### POST auto-updater/quit-and-install

Source: https://github.com/nativephp/desktop/blob/main/_autodocs/endpoints.md

Quits and installs the update. Used by AutoUpdater::quitAndInstall().

```APIDOC
## POST auto-updater/quit-and-install

### Description
Quits and installs the update.

### Method
POST

### Endpoint
`auto-updater/quit-and-install`

### Response
No response body documented.
```

--------------------------------

### GET/POST system/theme

Source: https://github.com/nativephp/desktop/blob/main/_autodocs/endpoints.md

Gets or sets the system theme. Used by System::theme().

```APIDOC
## GET/POST system/theme

### Description
Gets or sets the system theme.

### Method
GET or POST

### Endpoint
`system/theme`

### Parameters
#### Request Body (POST only)
- `theme` (string) - Required - The theme to set (e.g., 'light', 'dark', 'system').

### Request Example (POST)
{
  "theme": "dark"
}

### Response
#### Success Response
- `result` (string) - The current theme.
```

--------------------------------

### Usage example: position window at center

Source: https://github.com/nativephp/desktop/blob/main/_autodocs/api-reference/Screen.md

Positions a window at the center of the active display using Screen::getCenterOfActiveScreen() and Window::open().

```php
use Native\Desktop\Facades\Screen;
use Native\Desktop\Facades\Window;

$center = Screen::getCenterOfActiveScreen();

Window::open('centered')
    ->width(480)
    ->height(320)
    ->position($center['x'] - 240, $center['y'] - 160);
```

--------------------------------

### Interacting with a process using ChildProcess

Source: https://github.com/nativephp/desktop/blob/main/_autodocs/api-reference/Process.md

Shows how to retrieve a process, check if it exists, and then get its PID, send a message, restart, or stop it.

```php
use Native\Desktop\Facades\ChildProcess;

$proc = ChildProcess::get('queue-main');

if ($proc !== null) {
    echo $proc->pid;
    ChildProcess::message('ping', 'queue-main');
    ChildProcess::restart('queue-main');
}

ChildProcess::stop('queue-main');
```

--------------------------------

### ChildProcess class definition

Source: https://github.com/nativephp/desktop/blob/main/_autodocs/api-reference/Process.md

Defines the ChildProcess class with readonly properties and a constructor that takes a Client instance. Properties are hydrated on start(), get(), all(), or restart() via fromRuntimeProcess().

```php
class ChildProcess implements ChildProcessContract
{
    use Conditionable;

    public readonly int $pid;
    public readonly string $alias;
    public readonly array $cmd;
    public readonly ?string $cwd;
    public readonly ?array $env;
    public readonly bool $persistent;
    public readonly bool $handlesOwnShutdown;
    public readonly ?array $iniSettings;

    final public function __construct(protected Client $client) {}
}
```

--------------------------------

### Error handling with Clipboard and ConnectionException

Source: https://github.com/nativephp/desktop/blob/main/_autodocs/api-reference/Clipboard.md

Example of error handling when the clipboard is unavailable, catching ConnectionException and logging a warning.

```php
use Native\Desktop\Facades\Clipboard;
use Illuminate\Http\Client\ConnectionException;

try {
    Clipboard::clear();
    Clipboard::html('<b>Formatted</b>');
} catch (ConnectionException $e) {
    logger()->warning('Clipboard unavailable: '.$e->getMessage());
}
```

--------------------------------

### Settings::get() implementation

Source: https://github.com/nativephp/desktop/blob/main/_autodocs/api-reference/Settings.md

Implementation of the get() method: fetches the value from the runtime and returns the default (or invokes a closure) when the key is missing.

```php
$response = $this->client->get('settings/'.$key)->json('value');

if ($response === null) {
    return $default instanceof \Closure ? $default() : $default;
}
```

--------------------------------

### current() method

Source: https://github.com/nativephp/desktop/blob/main/_autodocs/api-reference/Window.md

Fetches the focused window via GET window/current and hydrates a Window object.

```php
public function current(): Window
```

--------------------------------

### Native\Desktop\AutoUpdater::quitAndInstall

Source: https://github.com/nativephp/desktop/blob/main/_autodocs/api-reference/AutoUpdater.md

Sends a one-shot command to the Electron runtime to quit and install a downloaded update. Results arrive as events.

```APIDOC
## POST auto-updater/quit-and-install

### Description
Sends a command to the Electron runtime to quit and install a downloaded update. Results arrive as events.

### Method
POST

### Endpoint
auto-updater/quit-and-install

### Parameters
None

### Request Example
No request body required.

### Response
#### Success Response (200)
No response body; results arrive as events.

#### Response Example
No response body.
```

--------------------------------

### Usage example: Error handling

Source: https://github.com/nativephp/desktop/blob/main/_autodocs/api-reference/Alert.md

Wraps the show() call in a try-catch to handle ConnectionException when the runtime is unavailable.

```php
use Native\Desktop\Facades\Alert;
use Illuminate\Http\Client\ConnectionException;

try {
    Alert::new()->show('Update complete!');
} catch (ConnectionException $e) {
    // runtime unavailable — the alert cannot be shown
}
```

--------------------------------

### Managing queue workers with QueueWorker

Source: https://github.com/nativephp/desktop/blob/main/_autodocs/api-reference/Process.md

Shows how to start queue workers using a config alias or a QueueConfig instance, and how to stop them.

```php
use Native\Desktop\DataObjects\QueueConfig;
use Native\Desktop\Facades\QueueWorker;

QueueWorker::up('default');                       // config alias under nativephp.queue_workers
QueueWorker::up(new QueueConfig('reports', ['reports', 'emails'], 256, 120, 5));

QueueWorker::down('default');
```

--------------------------------

### Usage example: error handling

Source: https://github.com/nativephp/desktop/blob/main/_autodocs/api-reference/Screen.md

Handles ConnectionException when calling Screen::primary(), falling back to an empty array.

```php
use Native\Desktop\Facades\Screen;
use Illuminate\Http\Client\ConnectionException;

try {
    $primary = Screen::primary();
} catch (ConnectionException $e) {
    $primary = [];
}
```

--------------------------------

### GET api/v1/projects/{projectId}/builds/latest-desktop-bundle

Source: https://github.com/nativephp/desktop/blob/main/_autodocs/endpoints.md

Fetches the latest desktop bundle for a project, including download and signature URLs.

```APIDOC
## GET api/v1/projects/{projectId}/builds/latest-desktop-bundle

### Description
Fetches the latest desktop bundle for a project, including download and signature URLs.

### Method
GET

### Endpoint
api/v1/projects/{projectId}/builds/latest-desktop-bundle

### Parameters
#### Path Parameters
- **projectId** (string) - Required - The ID of the project

#### Authentication
- **Authorization** (string) - Required - Bearer token (e.g., `Bearer <BIFROST_TOKEN>`)

### Response
#### Success Response (200)
- **data** (object) - Bundle information
  - **download_url** (string) - URL to download the bundle
  - **signature_url** (string) - URL to download the GPG signature
```

--------------------------------

### GET system/printers

Source: https://github.com/nativephp/desktop/blob/main/_autodocs/endpoints.md

Gets the list of printers. Used by System::printers().

```APIDOC
## GET system/printers

### Description
Gets the list of printers.

### Method
GET

### Endpoint
`system/printers`

### Response
#### Success Response
- `printers` (array) - List of printer objects.
```

--------------------------------

### GET screen/active

Source: https://github.com/nativephp/desktop/blob/main/_autodocs/endpoints.md

Gets the active display. Used by Screen::active().

```APIDOC
## GET screen/active

### Description
Gets the active display.

### Method
GET

### Endpoint
`screen/active`

### Response
#### Success Response
- Raw response including `bounds` (object) - The display bounds.
```

--------------------------------

### GET screen/primary-display

Source: https://github.com/nativephp/desktop/blob/main/_autodocs/endpoints.md

Gets the primary display. Used by Screen::primary().

```APIDOC
## GET screen/primary-display

### Description
Gets the primary display.

### Method
GET

### Endpoint
`screen/primary-display`

### Response
#### Success Response
- `primaryDisplay` (object) - The primary display object.
```

--------------------------------

### GET screen/cursor-position

Source: https://github.com/nativephp/desktop/blob/main/_autodocs/endpoints.md

Gets the cursor position. Used by Screen::cursorPosition().

```APIDOC
## GET screen/cursor-position

### Description
Gets the cursor position.

### Method
GET

### Endpoint
`screen/cursor-position`

### Response
#### Success Response
- Raw response containing cursor coordinates (e.g., `{x: number, y: number}`).
```

--------------------------------

### Error handling with ConnectionException

Source: https://github.com/nativephp/desktop/blob/main/_autodocs/api-reference/ProgressBar.md

Wraps ProgressBar creation and start in a try/catch for ConnectionException, allowing the app to continue without the progress bar if unavailable.

```php
use Native\Desktop\ProgressBar;
use Illuminate\Http\Client\ConnectionException;

try {
    $bar = ProgressBar::create(5);
    $bar->start();
} catch (ConnectionException $e) {
    // progress bar unavailable — continue without it
}
```

--------------------------------

### GET power-monitor/get-current-thermal-state

Source: https://github.com/nativephp/desktop/blob/main/_autodocs/endpoints.md

Gets the current thermal state. Used by PowerMonitor::getCurrentThermalState().

```APIDOC
## GET power-monitor/get-current-thermal-state

### Description
Gets the current thermal state.

### Method
GET

### Endpoint
`power-monitor/get-current-thermal-state`

### Response
#### Success Response
- `result` (string) - The thermal state (e.g., 'nominal', 'fair', 'serious', 'critical').
```

--------------------------------

### show()

Source: https://github.com/nativephp/desktop/blob/main/_autodocs/api-reference/Dock.md

Shows the Dock icon by posting to the runtime.

```APIDOC
## POST dock/show

### Description
Shows the Dock icon by posting to the runtime.

### Method
POST

### Endpoint
`dock/show`

### Parameters
None.

### Request Example
No request body.

### Response
No response body is documented.
```

--------------------------------

### GET power-monitor/get-system-idle-time

Source: https://github.com/nativephp/desktop/blob/main/_autodocs/endpoints.md

Gets the system idle time. Used by PowerMonitor::getSystemIdleTime().

```APIDOC
## GET power-monitor/get-system-idle-time

### Description
Gets the system idle time.

### Method
GET

### Endpoint
`power-monitor/get-system-idle-time`

### Response
#### Success Response
- `result` (number) - The idle time in seconds.
```

--------------------------------

### focus() method

Source: https://github.com/nativephp/desktop/blob/main/_autodocs/api-reference/App.md

Brings the application and its windows to the foreground by posting to app/focus.

```php
public function focus(): void
```

--------------------------------

### GET power-monitor/get-system-idle-state

Source: https://github.com/nativephp/desktop/blob/main/_autodocs/endpoints.md

Gets the system idle state. Used by PowerMonitor::getSystemIdleState() with a query parameter `threshold`.

```APIDOC
## GET power-monitor/get-system-idle-state

### Description
Gets the system idle state.

### Method
GET

### Endpoint
`power-monitor/get-system-idle-state`

### Parameters
#### Query Parameters
- `threshold` (number) - Optional - The idle threshold in seconds.

### Response
#### Success Response
- `result` (string) - The idle state (e.g., 'active', 'idle', 'locked').
```

--------------------------------

### MenuBuilder create() method

Source: https://github.com/nativephp/desktop/blob/main/_autodocs/api-reference/Menu.md

Builds and registers the menu in one step by calling make(...)->register(). Accepts a variadic list of MenuItem instances.

```php
public function create(MenuItem ...$items): void
```

--------------------------------

### get() method signature

Source: https://github.com/nativephp/desktop/blob/main/_autodocs/api-reference/Client.md

Signature for the get() method. Accepts an endpoint string and optional query parameters (array, string, or null). Returns an Illuminate\Http\Client\Response.

```php
public function get(string $endpoint, array|string|null $query = null): Response
```

--------------------------------

### Open a configured window

Source: https://github.com/nativephp/desktop/blob/main/_autodocs/api-reference/Window.md

Opens a configured window using the pending pattern. The window opens when the PendingOpenWindow object is destroyed.

```php
use Native\Desktop\Facades\Window;

Window::open()
    ->title('My Window')
    ->width(800)
    ->height(600)
    ->minWidth(400)
    ->route('dashboard')
    ->rememberState()
    ->afterOpen(function ($window) {
        // runs once the window is created
        logger('window '.$window->getId().' opened');
    });
// The window opens when the PendingOpenWindow object is destroyed
```

--------------------------------

### get(string $endpoint, array|string|null $query = null): Response

Source: https://github.com/nativephp/desktop/blob/main/_autodocs/api-reference/Client.md

Sends a GET request to the specified endpoint with optional query parameters and returns the Laravel HTTP response.

```APIDOC
## GET Method

### Description
Sends a GET request to the specified endpoint with optional query parameters and returns the Laravel HTTP response.

### Method
GET

### Endpoint
`{base_url}/{endpoint}`

### Parameters

#### Query Parameters
- **$endpoint** (string) - Required - API path relative to the base URL (e.g., `app/is-hidden`).
- **$query** (array|string|null) - Optional - Query-string parameters. Default: `null`.

### Request Example
No explicit request body; query parameters are sent in the URL.

### Response
Returns `Illuminate\Http\Client\Response` for the GET request.

```

--------------------------------

### Error handling for Dock::show()

Source: https://github.com/nativephp/desktop/blob/main/_autodocs/api-reference/Dock.md

Shows the Dock and catches ConnectionException when no runtime is available.

```php
use Native\Desktop\Facades\Dock;
use Illuminate\Http\Client\ConnectionException;

try {
    Dock::show();
} catch (ConnectionException $e) {
    // no runtime; non-fatal
}
```

--------------------------------

### show() method

Source: https://github.com/nativephp/desktop/blob/main/_autodocs/api-reference/Notification.md

The `show()` method sends a POST notification with the payload shown. After a successful post, it stores the runtime-generated `reference` on the instance.

```php
public function show(): self
```

```json
{
  "reference": null,
  "title": "...",
  "body": "...",
  "event": "...",
  "sound": "...",
  "silent": false,
  "hasReply": false,
  "replyPlaceholder": "",
  "actions": [{"type": "button", "text": "..."}]
}
```

--------------------------------

### Window configuration methods

Source: https://github.com/nativephp/desktop/blob/main/_autodocs/api-reference/Window.md

All fluent configuration methods on the Window class. These methods return self or static and configure various window properties.

```php
public function id(string $id = 'main'): self
public function getId(): string
public function title(string $title): self
public function url(string $url)                 // posts window/url when not pending
public function titleBarStyle($style): self
public function titleBarHidden(): self           // titleBarStyle('hidden')
public function titleBarHiddenInset(): self      // titleBarStyle('hiddenInset')
public function trafficLightPosition(int $x, int $y): self
public function trafficLightsHidden(): self      // windowButtonVisibility(false)
public function windowButtonVisibility($visible = true): self
public function rememberState(): self            // persist window state across launches
public function frameless(): self                // frame = false
public function focusable($value = true): self
public function skipTaskbar($value = true): self
public function hiddenInMissionControl($value = true): self
public function hasShadow($value = true): self
public function titleBarButtonsOnHover(): self   // titleBarStyle('customButtonsOnHover')
public function alwaysOnTop(bool $alwaysOnTop = true): self
public function showDevTools(bool $showDevTools = true): self
public function hideDevTools(): self
public function devToolsOpen(): bool
public function resizable(bool $resizable = true): static
public function movable($movable = true): static
public function minimizable($minimizable = true): static
public function maximizable($maximizable = true): static
public function closable(bool $closable = true): static
public function invisibleFrameless(): self       // frameless + transparent + unfocusable + no shadow
public function hideMenu($autoHideMenuBar = true): static
public function fullscreen($fullscreen = true): static
public function fullscreenable($fullscreenable = true): static
public function kiosk($kiosk = true): static
public function webPreferences(array $preferences): static
public function zoomFactor(float $zoomFactor = 1.0): self
public function preventLeaveDomain(bool $preventLeaveDomain = true): self
public function preventLeavePage(bool $preventLeavePage = true): self
public function suppressNewWindows(): self
```

--------------------------------

### Error handling with try-catch example

Source: https://github.com/nativephp/desktop/blob/main/_autodocs/api-reference/Client.md

Error handling example: wraps a POST request in a try-catch. Calls $response->throw() to throw RequestException on 4xx/5xx, catches ConnectionException for runtime/network failures, and RequestException for runtime rejection.

```php
use Native\Desktop\Client\Client;
use Illuminate\Http\Client\ConnectionException;
use Illuminate\Http\Client\RequestException;

$client = new Client;

try {
    $response = $client->post('app/quit');
    $response->throw(); // throws RequestException on 4xx/5xx
} catch (ConnectionException $e) {
    // Runtime not running / network failure
} catch (RequestException $e) {
    // Runtime rejected the request
}
```

--------------------------------

### resize() and position() methods

Source: https://github.com/nativephp/desktop/blob/main/_autodocs/api-reference/Window.md

resize posts window/resize with width and height. position posts window/position with x, y, and animate.

```php
public function resize($width, $height, $id = null)

public function position($x, $y, $animated = false, $id = null)
```

--------------------------------

### GET api/v1/auth/user

Source: https://github.com/nativephp/desktop/blob/main/_autodocs/endpoints.md

Retrieves the authenticated user's information.

```APIDOC
## GET api/v1/auth/user

### Description
Retrieves the authenticated user's information.

### Method
GET

### Endpoint
api/v1/auth/user

### Parameters
#### Authentication
- **Authorization** (string) - Required - Bearer token (e.g., `Bearer <BIFROST_TOKEN>`)

### Response
#### Success Response (200)
- **id** (number) - User ID
- **email** (string) - User email
- **name** (string) - User name
```

--------------------------------

### maximize(), unmaximize(), minimize(), reload() methods

Source: https://github.com/nativephp/desktop/blob/main/_autodocs/api-reference/Window.md

Post to window/maximize, window/unmaximize, window/minimize, and window/reload respectively.

```php
public function maximize($id = null): void

public function unmaximize($id = null): void

public function minimize($id = null): void

public function reload($id = null): void
```

--------------------------------

### Dialog::defaultPath()

Source: https://github.com/nativephp/desktop/blob/main/_autodocs/api-reference/Dialog.md

Sets the starting directory or path for the dialog.

```APIDOC
## Dialog::defaultPath()

### Description
Sets the default path (directory or file) that the dialog opens to.

### Method
defaultPath

### Endpoint
N/A (PHP fluent method)

### Parameters
#### Path Parameters
- **$defaultPath** (string) - Required - The starting path for the dialog.

### Request Example
```php
$dialog->defaultPath('/home/user/documents');
```

### Response
#### Success Response
- **$this** (Dialog) - Returns the Dialog instance for chaining.

#### Response Example
```php
// Returns $this
```
```

--------------------------------

### Class: System (constructor with Client)

Source: https://github.com/nativephp/desktop/blob/main/_autodocs/api-reference/System.md

Defines the System class with a constructor that accepts a Client instance for making HTTP client calls to the runtime.

```php
class System
{
    public function __construct(protected Client $client) {}
}
```

--------------------------------

### Unregistering a shortcut

Source: https://github.com/nativephp/desktop/blob/main/_autodocs/api-reference/GlobalShortcut.md

Example of unregistering a previously registered shortcut.

```php
use Native\Desktop\Facades\GlobalShortcut;

GlobalShortcut::key('CommandOrControl+Shift+P')->unregister();
```

--------------------------------

### GET system/can-encrypt

Source: https://github.com/nativephp/desktop/blob/main/_autodocs/endpoints.md

Checks if encryption is available. Used by System::canEncrypt().

```APIDOC
## GET system/can-encrypt

### Description
Checks if encryption is available.

### Method
GET

### Endpoint
`system/can-encrypt`

### Response
#### Success Response
- `result` (boolean) - True if encryption is available.
```

--------------------------------

### GET child-process/

Source: https://github.com/nativephp/desktop/blob/main/_autodocs/endpoints.md

Retrieves all child processes. Used by ChildProcess::all().

```APIDOC
## GET child-process/

### Description
Retrieves all child processes.

### Method
GET

### Endpoint
`child-process/`

### Response
#### Success Response
- An array of child process objects, each containing `pid` and `settings` as described in the child-process/get endpoint.
```

--------------------------------

### ProgressBar create() method

Source: https://github.com/nativephp/desktop/blob/main/_autodocs/api-reference/ProgressBar.md

Static factory method that returns a new instance with a fresh Client.

```php
public static function create(int $maxSteps): static
```

--------------------------------

### App::badgeCount()

Source: https://github.com/nativephp/desktop/blob/main/_autodocs/api-reference/App.md

Gets or sets the badge count on the application icon.

```APIDOC
## badgeCount

### Description
Gets or sets the badge count on the application icon. When called with an integer argument, it sets the badge count. When called without arguments, it returns the current badge count.

### Method
badgeCount

### Endpoint
App::badgeCount(?int $count = null)

### Parameters
#### Optional Parameters
- **$count** (int) - Optional - The badge count to set. If omitted, the current badge count is returned.

### Request Example
```php
// Set badge count
App::badgeCount(5);

// Get badge count
$count = App::badgeCount();
```

### Response
When setting, no return value. When getting, returns the current badge count as an integer.
```

--------------------------------

### Error handling for MenuBar::show()

Source: https://github.com/nativephp/desktop/blob/main/_autodocs/api-reference/MenuBar.md

Wraps MenuBar::show() in a try-catch for ConnectionException. If the Electron runtime is unreachable, tray commands are no-ops and the exception is reported.

```php
use Native\Desktop\Facades\MenuBar;
use Illuminate\Http\Client\ConnectionException;

try {
    MenuBar::show();
} catch (ConnectionException $e) {
    // the Electron runtime is not reachable — tray commands are no-ops
    report($e);
}
```

--------------------------------

### Registering a context menu with facade

Source: https://github.com/nativephp/desktop/blob/main/_autodocs/api-reference/ContextMenu.md

Builds a menu with copy, paste, separator, fullscreen, and dev tools items, then registers it as the context menu. The menu is built once and registered once.

```php
use Native\Desktop\Facades\ContextMenu;
use Native\Desktop\Facades\Menu;

ContextMenu::register(
    Menu::make(
        Menu::label('Copy')->hotkey('CmdOrCtrl+C')->event('menu-copy'),
        Menu::label('Paste')->event('menu-paste'),
        Menu::separator(),
        Menu::fullscreen(),
        Menu::devTools(),
    )
);
```

--------------------------------

### Basic usage of App facade

Source: https://github.com/nativephp/desktop/blob/main/_autodocs/api-reference/App.md

Shows basic operations: focus, show if hidden, set and read badge count. Uses the Native\Desktop\Facades\App facade.

```php
use Native\Desktop\Facades\App;

App::focus();

if (App::isHidden()) {
    App::show();
}

App::badgeCount(5);
// or read it back:
$count = App::badgeCount();
```

--------------------------------

### GET system/can-prompt-touch-id

Source: https://github.com/nativephp/desktop/blob/main/_autodocs/endpoints.md

Checks if Touch ID can be prompted. Used by System::canPromptTouchID().

```APIDOC
## GET system/can-prompt-touch-id

### Description
Checks if Touch ID can be prompted.

### Method
GET

### Endpoint
`system/can-prompt-touch-id`

### Response
#### Success Response
- `result` (boolean) - True if Touch ID can be prompted.
```

--------------------------------

### GET power-monitor/is-on-battery-power

Source: https://github.com/nativephp/desktop/blob/main/_autodocs/endpoints.md

Checks if the system is on battery power. Used by PowerMonitor::isOnBatteryPower().

```APIDOC
## GET power-monitor/is-on-battery-power

### Description
Checks if the system is on battery power.

### Method
GET

### Endpoint
`power-monitor/is-on-battery-power`

### Response
#### Success Response
- `result` (boolean) - True if on battery power.
```

--------------------------------

### GlobalShortcut::key() method

Source: https://github.com/nativephp/desktop/blob/main/_autodocs/api-reference/GlobalShortcut.md

Sets the accelerator string, e.g., 'CommandOrControl+Shift+P'.

```php
public function key(string $key): self
```
Tokens:
Raw