7 Dec 2023 · Software Engineering

    NativePHP: Build Desktop Applications with PHP

    4 min read

    PHP holds a special place in my heart. It was my first job. I remember spending countless hours at home on little side projects. I wanted so bad to be able to create desktop applications with PHP, but I never could.

    Now, thanks to NativePHP, I can. NativePHP, following in the footsteps of popular applications like Slack, Discord, and Trello, wraps your PHP application in Electro. It allows the backend logic to run on PHP, while the UI is built using HTML, CSS and any JavaScript framework.

    Setting the Scene with NativePHP

    I’ve decided to dive into NativePHP by converting a Laravel application into a desktop app. To give you a clearer picture, let’s start with a basic setup. The application I’m working on has a Laravel backend and a React frontend, with a MySQL database as its backbone.

    Installing NativePHP

    To get started, we install NativePHP via Composer:

    $ composer require nativephp/electron

    This extends Laravel’s artisan tool with a new set of NativePHP specific commands. For instance, php artisan native shows a list of commands to build and manage your native application.

    Next, running php artisan native:install sets up the basic structure.

    Of particular interest are two files:

    • config/nativephp.php for application configuration
    • app/Providers/NativeAppServiceProvider.php for the bootup sequence and registering native components.

    Running the Development Build

    With the application set up, we can start our dev build:

    $ php artisan native:serve &
    $ npm run dev &

    We need to start development servers for PHP and the UI. In this case, npm uses [Vite]() to build and serve the UI components to the Electron window.

    NativePHP bundles the app with Electron, embedding a PHP interpreter. During development, it switches the backend to a local SQLite database, so we need to run migrations using php artisan native:migrate to set up the new database.

    Adding Native Features

    To enhance the desktop experience, NativePHP allows integration of native elements like notifications, menu bars, and hotkeys. You can see the complete list of elements in the [docs page]()

    I added a simple notification on app start by editingapp/Providers/NativeAppServiceProvider.php. This helps us give the application that native feel we’re aiming for.

    First, we add the Notification Facade:

    use Native\Laravel\Facades\Notification;

    Then, in the boot function I add the following lines after the window opens:

    Notification::title('Application Started')
        ->message('This message is comming from NativePHP running on Electron')

    Upon saving, the hot reload function should restart the application and show the notification (check that you haven’t enabled notifications from Electron if you don’t see them).

    Building for Release

    For a production build, we fill in the publishing details in config/nativephp.php. Notably, the environment file (.env) gets bundled in the build, so sensitive data must be cleaned up using cleanup_env_keys.

    To build a release for your OS, simply run:

    $ php artisan native:build

    This process generates various bundles, including a DMG, a Zip file, and the binary for the application.

    We can also build Windows and Linux bundles with:

    $ php artisan native:build win
    $ php artisan native:build linux

    We should get a setup.exe, AppImage and, .deb files after the build process completes.

    Caveats of NativePHP

    Before diving into NativePHP, here are some considerations:

    1. Alpha Stage: As of now, NativePHP is in its alpha stage, leaning more towards a beta experience.
    2. Laravel-First Framework: While NativePHP claims compatibility with any PHP framework, its design is heavily tailored for Laravel.
    3. Database Limitations: The database support is confined to local SQLite, replacing your existing database setup upon build.
    4. Cross-Compilation Limits: While it supports building for different OSs, cross-architecture builds are not yet supported. For instance, binaries built on an M1 chip won’t work on most Linux and Windows machines (ARM builds won’t work on Intel chips). A workaround is using a different machine or a CI/CD pipeline for builds.


    NativePHP, even in its alpha stage, is an impressive and user-friendly framework for PHP developers. It opens up a new world of possibilities for PHP-based desktop applications. If you’re into PHP development, NativePHP is definitely a project to keep an eye on.

    That’s all for this exploration. If you found this interesting, feel free to like, share, and subscribe for more updates. Thanks for reading, and happy coding!

    Leave a Reply

    Your email address will not be published. Required fields are marked *

    Writen by:
    I picked up most of my skills during the years I worked at IBM. Was a DBA, developer, and cloud engineer for a time. After that, I went into freelancing, where I found the passion for writing. Now, I'm a full-time writer at Semaphore.