NativePHP v4: створення нативного UI для iOS та Android у Blade

NativePHP відтепер відображає Blade-компоненти як справжні SwiftUI-представлення на iOS та Jetpack Compose на Android, повністю відмовившись від web view та HTML. Розробники назвали цю технологію SuperNative. Саймон Гемп та Шейн Розенталь презентували її на камерній події The Vibes у Бостоні одразу після завершення Laracon US.

Якщо рік тому ви сприйняли NativePHP лише як Laravel всередині web view, версія v4 змусить вас передумати. Web views все ще підтримуються, але вони більше не є єдиним способом побудови інтерфейсу. SuperNative став стандартом за замовчуванням у v4. Наразі технологія має статус бета-версії (актуальна 4.1), тож розробники попереджають про інтенсивні оновлення.

Головне в оновленні:

• Нативний UI через Blade. Набір компонентів під назвою EDGE (Element Definition and Generation Engine) компілює код у SwiftUI та Jetpack Compose замість HTML.
• Жодних мережевих затримок. PHP та нативний шар взаємодіють через спільну пам'ять. Більше ніяких «кругосвітніх подорожей» запитів чи складних містків між компонентом та екраном.
• Компоненти у стилі Livewire. Публічні властивості, метод mount(), методи дій та атрибути, включно з #[Poll], #[Computed], #[Lazy] та #[Locked].
• Тестування нативних екранів через Pest. Тести монтують компонент всередині процесу та перевіряють результат без потреби у важких симуляторах.
• Плагіни в ядрі. Device, Dialog, File та System тепер постачаються разом із nativephp/mobile. Це єдина зміна, що порушує зворотну сумісність.

# Як працює SuperNative

SuperNative — це не кастомний рушій рендерингу на кшталт Skia чи Impeller, і не додаткова віртуальна машина. Це також не транспайлер і не конвертер HTML у нативний код.

З документації NativePHP щодо архітектури:

Ми створили власний Blade-рушій, який перетворює Blade-компоненти на просте бінарне представлення замість HTML.

Це представлення є масивом байтів фіксованої довжини. Інтерпретатор на нативній стороні зчитує його та будує відповідні SwiftUI або Compose views.

Екрани SuperNative запускаються швидше, ніж web view: не потрібно завантажувати браузерний рушій, парсити бандли чи серіалізувати дані через «місток» при кожному натисканні.

Важливий плюс — доступність (Accessibility). Оскільки це справжні нативні елементи, VoiceOver, TalkBack, динамічні шрифти та допоміжні засоби платформи працюють «з коробки». Для іконок без тексту все ще потрібно вказувати a11y-label.

# Розробка екрана на SuperNative

У v3 екран був звичайним веб-маршрутом. Ви писали Blade, Livewire або Inertia, які рендерилися як HTML, а EDGE огортав це у нативну «обгортку» (меню, таббари). Окремого PHP-класу для екрана не існувало.

У v4 екран — це і є компонент. Це PHP-клас, що розширює NativeComponent, та відповідний Blade-шаблон. Стан зберігається у публічних властивостях, методи класу — це дії, а атрибути на кшталт #[Poll] відповідають за періодичне оновлення. Ось приклад трекера доставки:

<?php
 
namespace App\NativeComponents;
 
use App\Models\Delivery;
use Illuminate\View\View;
use Native\Mobile\Attributes\Locked;
use Native\Mobile\Attributes\Poll;
use Native\Mobile\Edge\NativeComponent;
 
class DeliveryTracker extends NativeComponent
{
    #[Locked]
    public int $deliveryId;
 
    public string $status = 'awaiting_pickup';
 
    public ?string $courier = null;
 
    public function mount(): void
    {
        $this->syncFromDatabase();
    }
 
    #[Poll(5000)]
    public function syncFromDatabase(): void
    {
        $delivery = Delivery::findOrFail($this->deliveryId);
 
        $this->status = $delivery->status;
        $this->courier = $delivery->courier_name;
    }
 
    public function confirmReceipt(): void
    {
        Delivery::findOrFail($this->deliveryId)->markReceived();
 
        $this->syncFromDatabase();
    }
 
    public function render(): View
    {
        return view('native.delivery-tracker');
    }
}

Маршрути реєструються у routes/mobile.php через макрос Route::native. Нативний інтерфейс задається через NativeLayout:

Route::native('/deliveries/{deliveryId}', DeliveryTracker::class)
    ->layout(DeliveryLayout::class)
    ->name('deliveries.show');

Шаблон використовує нативні примітиви замість HTML-тегів, а стилізація відбувається через Tailwind-класи, які парсер зіставляє з параметрами платформи:

<column class="flex-1 p-6 gap-4 bg-theme-background safe-area">
    <text class="text-2xl font-bold text-theme-on-background">
        {{ str($status)->headline() }}
    </text>
 
    @if ($courier)
        <text class="text-sm text-gray-500">Кур'єр: {{ $courier }}</text>
    @endif
 
    <pressable @tap="confirmReceipt" class="px-6 py-4 rounded bg-theme-primary items-center">
        <text class="text-theme-on-primary font-semibold">Підтвердити отримання</text>
    </pressable>
</column>

Тег <column> перетворюється на справжній SwiftUI layout або Compose Column. Для тестування на реальному пристрої не потрібні Xcode чи Android Studio: команда php artisan native:jump генерує QR-код, який можна відсканувати застосунком Jump для миттєвого перегляду змін по Wi-Fi.

# Збереження Web Views

Вам не потрібно переписувати існуючий застосунок на v3. Web view тепер є компонентом, який можна вставити всередину нативного екрана:

<webview php url="/" fullscreen />

Це дозволяє комбінувати підходи: використовувати нативну навігацію навколо веб-контенту. Кожен такий php-mode web view отримує власну ізольовану PHP-середу.

# Тестування в Pest

Оскільки екран — це PHP-об'єкт, його можна тестувати без девайса за допомогою FakeBridge:

use App\NativeComponents\DeliveryTracker;
use Native\Mobile\Testing\Native;
 
it('confirms receipt of a delivery', function () {
    $delivery = Delivery::factory()->create(['status' => 'out_for_delivery']);
 
    Native::visit("/deliveries/{$delivery->id}")
        ->assertSee('Out For Delivery')
        ->tap('Confirm receipt')
        ->assertSet('status', 'received');
});

# Версія 4.1

Оновлення від 7 серпня додало атрибут #[Locked] для захисту властивостей від перезапису через typo у native:model. Також з'явилися TreeObservers для відстеження дерев елементів, що корисно для налагодження та запису сесій.

# Як оновитися з v3

Більшість змін у v4 — це нові можливості, що не ламають старий код. Єдина критична зміна стосується плагінів. Оскільки вони стали частиною ядра, потрібно видалити старі пакети:

php artisan native:plugin:uninstall --core-v4

Далі оновіть залежності у composer.json до ~4.0.0 та перевстановіть нативний проект:

composer update
php artisan native:install --force

NativePHP v4 нарешті відповідає на головну критику: «це просто веб-сайт у нативній оболонці». Тепер ви можете створювати справжні нативні додатки, не виходячи за межі екосистеми Laravel (PHP, Blade, Pest).