Exploring the NativePHP Directory and File Structure


Once you've installed NativePHP in your Laravel project, you might notice a few new files and folders appear. But what do they do? Where should you write your code to customize the native behavior of your desktop app?

In this article, we'll take a deep dive into the directory and file structure of a NativePHP project, so you can understand what’s going on and where to go next.

🧱 The Basics

After running:

composer require nativephp/electron
php artisan native:install

NativePHP scaffolds a few things to integrate itself into your Laravel project.

Let’s look at the key components it adds or modifies.

📁 Key Directories and Files

1. /app/NativePHP/

This is the heart of your NativePHP application logic.

🗂️ MainWindow.php

This file defines how your desktop window behaves.

Example:

use Native\Laravel\Facades\Window;

public function boot()
{
    Window::open()
        ->title('My Native App')
        ->width(1024)
        ->height(768);
}

Here, you can:

  • Set window size

  • Set title

  • Control the initial route/view

  • Enable dev tools

  • More advanced behaviors like multi-window support

You can also create multiple window classes if you want to open several independent windows.

2. /config/nativephp.php

This configuration file allows you to customize NativePHP’s behavior at the app level.

Some of the options you’ll find:

'url' => 'http://localhost:8000',
'windows' => [
    App\NativePHP\MainWindow::class,
],

Here, you can:

  • Define which windows to load

  • Modify URL source (local vs. remote)

  • Set options for production builds

3. /resources/js/native/ (Optional, if using JS UI)

If you're using Vue, React, or any frontend JavaScript framework, NativePHP can work with those too. You might choose to organize frontend-specific logic here.

4. NativePHP Artisan Commands

NativePHP brings a few new Artisan commands:

php artisan native:install   // Set up files
php artisan native:serve     // Launch Electron window
php artisan native:build     // Package the app

You can think of native:serve as the "run app" command during development.

🧰 Optional Files

NativePHP doesn’t force you into any directory structure beyond what’s necessary. But for more complex apps, you might create:

  • /app/NativePHP/Tray.php – to control system tray behavior

  • /app/NativePHP/Menu.php – to manage native menus

  • /app/NativePHP/Notifications.php – for system notifications

  • /app/NativePHP/Hotkeys.php – to register global hotkeys

  • /app/NativePHP/FileHandlers.php – for drag/drop or file integrations

These are not mandatory, but organizing them like this keeps your project clean.

🖼 How Laravel & NativePHP Connect

Here's a quick map of how everything ties together:

[ Laravel Routes ]
      ↓
[ Blade / SPA View ]
      ↓
[ NativePHP Window (MainWindow.php) ]
      ↓
[ Electron Shell ]

You can continue using:

  • Controllers

  • Middleware

  • Blade templates

  • Laravel Mix / Vite

  • Eloquent & DB

Just like you would in a regular web app—except now, it runs in a native window!

🧪 Bonus Tip: Debugging the Window

You can enable dev tools like this in MainWindow.php:

Window::open()
    ->devtools(true);

This opens up the familiar Chrome DevTools within your Electron shell.

📦 When You Build for Production

When you run:

php artisan native:build

NativePHP uses Electron Builder to package your app for:

  • macOS (.dmg or .app)

  • Windows (.exe or .msi)

  • Linux (.AppImage or .deb)

The output is placed in a /dist folder, ready for distribution.

🧭 Wrapping Up

The NativePHP structure is surprisingly simple, yet extremely powerful. You don’t need to learn a new way of building software—you just enhance your Laravel apps with native power.