Blog

Découverte de NativePHP

Publié le 1 août 2023 par Mathieu De Gracia

Présenté pendant la LaraconUS 2023, NativePHP est un package principalement maintenu par Marcel Pociot et Simon Hamp transformant votre Laravel ... en une application de bureau. 🤯

Voyons rapidement de quoi il en retourne !

Installation

Actuellement, seul Laravel est supporté par NativePHP mais l’équipe derrière le package travaille à le rendre accessible à d'autres frameworks dans le futur.

Dans le cadre de cet article, nous allons utiliser le package sur une installation fraîche de Laravel 10 :

1composer create-project laravel/laravel --prefer-dist native-php-demo

Après s’être déplacé dans le dossier native-php-demo, installons le package nativephp/electron depuis composer :

1cd native-php-demo
2
3composer require nativephp/electron

Le package nécessite au minimum une version 8.1 de PHP.

Désormais, une commande native:install est nécessaire pour installer le package :

1php artisan native:install

Durant cette installation, NativePHP vous proposera d'installer automatiquement toutes ses dépendances NPM et notamment les dépendances électron qui seront nécessaires au bon fonctionnement de l'application desktop :

1Would you like to install the NativePHP NPM dependencies? (yes/no) [yes]:

Pour finir, si tout s'est bien passé, NativePHP proposera de lancer son serveur de rendu :

1Would you like to start the NativePHP development server (yes/no) [no]:

Si toute la procédure s'est correctement effectuée, une fenêtre s'ouvrira sur votre ordinateur affichant la page "welcome" de Laravel, félicitations, votre Laravel est devenue une application Desktop !

Troubleshooting

NativePHP est une solution encore expérimentale qui peut parfois rencontrer des problématiques exotiques, notamment lors de son installation dans votre Laravel.

Si vous voulez vous amuser avec ce package, assurez-vous d'avoir la dernière version de NPM ainsi que Node, une solution comme NVM peut vous aider à mieux maitriser la version de ces packages sur votre environnement de travail.

L'ajout de Yarn sera également nécessaire pour exécuter le serveur de rendu, vous pouvez l'installer en global avec la commande suivante :

1npm install -g yarn

Par la suite, si vous rencontrez d'autres problèmes, vous n'aurez d'autres choix que de vous rendre sur la page issues du projet sur Github pour explorer les anomalies connues.

Nous avons personnellement rencontré l'erreur suivante lors de l'installation de NativePHP sur un Mac avec l'OS Ventura :

1Could not resolve "../../resources/php?asset&asarUnpack" from "src/main/index.js"

Pour régler cette problématique, il fut nécessaire de déplacer un certificat ainsi que plusieurs autres fichiers dans un dossier "ressources" d'électron à l'aide des commandes suivantes :

1cp vendor/nativephp/php-bin/cacert.pem vendor/nativephp/electron/resources/js/resources
2cp vendor/nativephp/php-bin/bin/mac/x86/php vendor/nativephp/electron/resources/js/resources

⚠️ Cette seconde commande dépendra de l'architecture de votre système (x86 ou arm64).

Attention, en cas d’erreur de configuration d'une fonctionnalité de NativPHP il est possible que rien ne réagisse sur votre écran sans pour autant provoquer d’erreur dans votre terminal ... n’hésitez pas à scruter vos fichiers de logs !

Usage

À l'installation du package NativePHP dans votre Laravel, un nouveau provider dénommé NativeAppServiceProvider sera automatiquement ajouté dans votre application, comme tout provider ce dernier vous permettra de communiquer avec le package et contiendra la configuration initiale pour gérer votre premier fenêtre ainsi que le menu.

Voici le contenu par défaut de ce provider :

 1<?php
 2 
 3namespace App\Providers;
 4 
 5use Native\Laravel\Facades\Window;
 6use Native\Laravel\Menu\Menu;
 7 
 8class NativeAppServiceProvider
 9{
10    /**
11     * Executed once the native application has been booted.
12     * Use this method to open windows, register global shortcuts, etc.
13     */
14    public function boot(): void
15    {
16        Menu::new()
17            ->appMenu()
18            ->submenu('About', Menu::new()
19                ->link('https://beyondco.de', 'Beyond Code')
20                ->link('https://simonhamp.me', 'Simon Hamp')
21            )
22            ->submenu('View', Menu::new()
23                ->toggleFullscreen()
24                ->separator()
25                ->link('https://laravel.com', 'Learn More', 'CmdOrCtrl+L')
26            )
27            ->register();
28 
29        Window::open()
30            ->width(1280)
31            ->height(720);
32    }
33}

Ce provider contient deux éléments importants : la configuration du menu et celle de votre première fenêtre.

Le menu correspond à ce que vous voyez apparaitre dans la barre de tâches quand l'une des fenêtres de votre application est sélectionnée :

Cette notion de "menu" est totalement inédite pour une application Web et vous offrira tout un lot de nouvelles possibilités pour imaginer les interactions avec vos utilisateurs !

Il sera par exemple envisageable de configurer des checkboxes dans votre barre de tâches puis d'en récupérer la valeur depuis votre backend ou bien même d'enclencher directement des events Laravel depuis ce menu !

 1Menu::new()
 2    ->appMenu()
 3    ->submenu(
 4        'Checkboxes',
 5        Menu::new()
 6            ->checkbox('foo', true)
 7            ->checkbox('bar', false)
 8    )
 9    ->submenu(
10        'Events',
11        Menu::new()
12            ->event(App\Events\FooEvent::class, 'Trigger FooEvent')
13    )
14    ->register();

Le résultat de cette configuration est la suivante :

Maintenant que notre application Desktop fonctionne, ajoutons une nouvelle route "/hello" dans notre web.php :

1Route::get('hello', function () {
2    echo 'hello 👋';
3})->name('hello');

Toujours depuis le NativeAppServiceProvider, affichons le contenu de cette route dans une nouvelle fenêtre :

1Window::open('second window')
2    ->route('hello')
3    ->position(50, 50)
4    ->width(200)
5    ->height(100);

Si ce n'est pas déjà fait, ou si vous souhaitez lancer manuellement le serveur de rendu, exécutez la commande suivante dans votre terminal :

1php artisan native:server

Une nouvelle fenêtre fera son apparition affichant le contenu de la route "hello" !

De nombreuses options sont disponibles afin de configurer l'affichage de vos fenêtres, vous pourrez modifier son apparence, lui donner une taille maximale, une priorité sur l'écran, etc ...

Vous retrouverez l'ensemble des possibilités offertes par NativePHP pour configurer les fenêtres à cette URL.

Ouvrir une fenêtre de dialogue

Maintenant que nous savons comment afficher une route dans une fenêtre, voyons un peu plus comment communiquer avec notre ordinateur.

Nous allons modifier notre route "/hello" pour afficher une fenêtre de dialogue de NativePHP nous permettant de parcourir les fichiers de notre ordinateur :

 1use Native\Laravel\Dialog; 
 2 
 3Route::get('hello', function () {
 4 
 5    $file = Dialog::new() 
 6        ->title('Select a file') 
 7        ->open(); 
 8 
 9    dd($file); 
10 
11})->name('hello');

En relançant notre serveur de rendu, la fenêtre suivante apparaîtra, nous laissant l'opportunité de naviguer dans les dossiers de notre ordinateur et d'y choisir un fichier :

Après avoir submit, le chemin absolu du fichier sélectionné sera manipulable dans une variable, libre à vous d'en récupérer le contenu par la suite, par exemple, depuis la façade Storage du framework !

Conclusion

Nous n'avons fait ici que brosser succinctement quelques possibilités offertes par NativePHP, énormément de chose reste encore à découvrir.

Attention toutefois, le package est encore une solution immature, toujours dans sa phase d'alpha, il est fortement déconseillé de l'utiliser pour le moment en production.

Il sera également important de se poser des questions de performances, de sécurité et enfin de la pertinence d'une telle solution pour réaliser une application Desktop.

Pour autant, le package nous propose ici une nouvelle façon d'imaginer une application Laravel et ouvrira sans aucun doute des nouvelles perspectives excitantes dans notre approche de ce que peut être une application PHP.