Install NativeWatch for NativePHP desktop

The desktop SDK connects Laravel's reporting lifecycle to NativeWatch and adds NativePHP desktop context. Install it in the Laravel application that you package for desktop.

#Check package access

The package requires PHP 8.4 or later within PHP 8 and supports Laravel 11, 12 and 13 through native-core. It does not install the NativePHP desktop runtime for you.

As of 29 October 2026, zinxan/native-desktop is not listed on public Packagist. The following command requires access to the SDK distribution, including its zinxan/native-core dependency. If Composer cannot find it, confirm package availability before proceeding; changing your project's stability setting does not create a missing package.

composer require zinxan/native-desktop

Laravel package discovery registers the service provider. Publish the configuration when you need to adjust privacy, sampling or delivery:

php artisan vendor:publish --tag=nativewatch-config

#Configure the packaged app

Copy the ingest key from the project's setup guide and set the destination explicitly:

NATIVEWATCH_KEY=nw_your_project_key
NATIVEWATCH_URL=https://native.watch
NATIVEWATCH_ENABLED=true
NATIVEWATCH_REQUIRE_CONSENT=true
NATIVEWATCH_ENVIRONMENT=development

Implement the diagnostic choice before testing. Start with sharing off and show success only when the SDK confirms the consent change.

During development, run php artisan config:clear after changing these values. Rebuild and reinstall your desktop package when checking the distributed configuration; changing the source checkout does not update an already installed application.

#Understand capture boundaries

The SDK captures exceptions that Laravel reports. It also captures a throwable passed as the exception value in a Laravel log context, including an exception your application caught. Reporting and logging the same throwable does not create a second SDK capture in that client process.

Add the Blade script to collect uncaught errors and unhandled promise rejections in the web view. That is a separate integration from PHP reporting.

The Composer SDK runs in PHP. It does not install an Electron main-process crash reporter, and its presence does not establish capture of native desktop process crashes. Verify failures in the layer where they occur.

#Send and inspect a diagnostic

After opting in within the development environment, run:

php artisan nativewatch:test

Match the command's UUID to an occurrence in the intended project. An accepted API request can still be waiting for processing. Then exercise a deliberate report() call from a temporary development-only path inside your packaged app:

report(new RuntimeException('Desktop reporting verification'));

Check the new occurrence's message, source frame, runtime and environment. Remove the test trigger before distribution. A successful command in your terminal proves that terminal's configuration; repeat inside the packaged app to check its actual storage and settings.

#Add useful context

Use a breadcrumb to describe the operation that preceded an error, without including customer content or credentials:

use ZXN\NativeWatch\Core\Laravel\NativeWatch;
use ZXN\NativeWatch\Core\Level;

NativeWatch::addBreadcrumb('sync', 'Started inventory sync');
NativeWatch::captureMessage('Inventory sync was deferred', Level::Warning);

Unless explicitly configured, the release comes from nativephp.version. Use exact build IDs when you want PHP source locations linked to release commits.

#Troubleshoot delivery

The default outbox is storage/nativewatch/outbox in the application's storage directory. NativePHP's installed app storage can differ from the checkout. Ensure the app can write there, confirm consent in that installation, and use offline delivery to interpret pending and rejected reports. Capture, serialization and disk access have a cost; an unwritable outbox can cause an immediate send attempt.