NativePHP for Mobile

https://nativephp.com/docs/mobile/4
Admin
NativePHP for Mobile is a library that enables developers to build and run full, performant,...
Tokens:106,448
Snippets:1,440
Trust Score:8.5
Update:2 months ago
Show doc for...
Tokens:
Raw
### Define Installation Instructions

Source: https://nativephp.com/docs/mobile/4/plugins/best-practices

Include these commands in your README to guide users through the installation process via Composer and the NativePHP CLI.

```markdown
## Installation

composer require vendor/my-plugin

php artisan native:plugin:register vendor/my-plugin
```

--------------------------------

### Install a premium plugin

Source: https://nativephp.com/docs/mobile/4/plugins/using-plugins

Install a premium plugin after configuring the repository and credentials.

```shell
composer require vendor/nativephp-premium-plugin
```

--------------------------------

### Full Plugin Manifest Example

Source: https://nativephp.com/docs/mobile/4/plugins/permissions-dependencies

A complete manifest example demonstrating Android permissions, dependencies, repository configuration, and iOS Pods with required secrets.

```json
{
    "name": "vendor/ml-maps-plugin",
    "namespace": "MLMaps",
    "android": {
        "permissions": [
            "android.permission.CAMERA",
            "android.permission.ACCESS_FINE_LOCATION"
        ],
        "dependencies": {
            "implementation": [
                "com.google.mlkit:object-detection:17.0.0",
                "com.mapbox.maps:android:11.0.0"
            ]
        },
        "repositories": [
            {
                "url": "https://api.mapbox.com/downloads/v2/releases/maven",
                "credentials": {
                    "username": "mapbox",
                    "password": "${MAPBOX_DOWNLOADS_TOKEN}"
                }
            }
        ]
    },
    "ios": {
        "info_plist": {
            "NSCameraUsageDescription": "Camera is used for real-time object detection",
            "NSLocationWhenInUseUsageDescription": "Location is used to display your position on the map",
            "MBXAccessToken": "${MAPBOX_PUBLIC_TOKEN}"
        },
        "dependencies": {
            "pods": [
                {"name": "MapboxMaps", "version": "~> 11.0"}
            ]
        }
    },
    "secrets": {
        "MAPBOX_DOWNLOADS_TOKEN": {
            "description": "Mapbox SDK download token from mapbox.com/account/access-tokens",
            "required": true
        },
        "MAPBOX_PUBLIC_TOKEN": {
            "description": "Mapbox public access token for runtime API calls",
            "required": true
        }
    }
}
```

--------------------------------

### Start Development Server

Source: https://nativephp.com/docs/mobile/4/getting-started/commands

Starts the NativePHP development server for testing mobile apps without building.

```shell
php artisan native:jump
```

--------------------------------

### Install AI agents

Source: https://nativephp.com/docs/mobile/4/getting-started/commands

Install AI agents for plugin development with options to force overwrite or install all.

```shell
php artisan native:plugin:install-agent
```

--------------------------------

### Install and Verify Xcode Command Line Tools

Source: https://nativephp.com/docs/mobile/4/getting-started/environment-setup

Commands to install the Xcode command line tools and verify the installation path.

```shell
xcode-select --install
```

```shell
xcode-select -p
```

--------------------------------

### Download ML Model Hook Example

Source: https://nativephp.com/docs/mobile/4/plugins/lifecycle-hooks

Example implementation of a handle method that downloads a file and copies it to platform-specific directories.

```php
public function handle(): int
{
    $modelPath = $this->pluginPath() . '/resources/models/model.tflite';

    // Download if not cached locally
    $this->downloadIfMissing(
        'https://example.com/models/v2/model.tflite',
        $modelPath
    );

    // Copy to the appropriate platform location
    if ($this->isAndroid()) {
        $this->copyToAndroidAssets('models/model.tflite', 'models/model.tflite');
        $this->info('Model copied to Android assets');
    }

    if ($this->isIos()) {
        $this->copyToIosBundle('models/model.tflite', 'models/model.tflite');
        $this->info('Model copied to iOS bundle');
    }

    return self::SUCCESS;
}
```

--------------------------------

### Install a standard plugin

Source: https://nativephp.com/docs/mobile/4/plugins/using-plugins

Install a standard NativePHP plugin using Composer.

```shell
composer require vendor/nativephp-plugin-name
```

--------------------------------

### Install Vibe Plugin

Source: https://nativephp.com/docs/mobile/4/digging-deeper/websockets

Install the required Composer package and register the plugin in your project.

```shell
composer require nativephp/mobile-vibe
php artisan native:plugin:register nativephp/mobile-vibe
```

--------------------------------

### Configure Start URL

Source: https://nativephp.com/docs/mobile/4/getting-started/configuration

Sets the initial path for the application upon startup, defaulting to the root if not specified.

```php
'start_url' => env('NATIVEPHP_START_URL', '/'),
```

--------------------------------

### Install and Verify CocoaPods

Source: https://nativephp.com/docs/mobile/4/getting-started/environment-setup

Commands to install CocoaPods via Homebrew and verify the installed version.

```shell
brew install cocoapods
```

```shell
pod --version
```

--------------------------------

### Initialize and run the SuperNative demo application

Source: https://nativephp.com/docs/mobile/4/architecture/super-native

Commands to clone the repository, install dependencies, and launch the application on a simulator or device.

```shell
git clone https://github.com/nativephp/super-native
cd super-native
composer install
php artisan native:install
php artisan native:run
```

--------------------------------

### List installed plugins

Source: https://nativephp.com/docs/mobile/4/plugins/using-plugins

Verify that NativePHP recognizes your installed plugins.

```shell
php artisan native:plugin:list
```

--------------------------------

### Deep Link Examples

Source: https://nativephp.com/docs/mobile/4/digging-deeper/deep-links

Examples of the two supported deep link formats.

```text
myapp://some/path
```

```text
https://example.net/some/path
```

--------------------------------

### Install Homebrew

Source: https://nativephp.com/docs/mobile/4/getting-started/environment-setup

Command to install the Homebrew package manager on macOS.

```shell
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
```

--------------------------------

### Install local plugin

Source: https://nativephp.com/docs/mobile/4/plugins/creating-plugins

Use composer to require the local plugin package.

```shell
composer require vendor/my-plugin
```

--------------------------------

### Install NativePHP dependencies

Source: https://nativephp.com/docs/mobile/4/architecture/embedded-php

Downloads the prebuilt PHP bundles and places them into the platform projects.

```shell
php artisan native:install
```

--------------------------------

### Initialize Text Input Element

Source: https://nativephp.com/docs/mobile/4/edge-components/text-input

Example of initializing an OutlinedTextInput with common configuration methods.

```php
use Nativephp\NativeUi\Elements\OutlinedTextInput;
use Nativephp\NativeUi\Elements\FilledTextInput;
use Nativephp\NativeUi\Elements\BareTextInput;

OutlinedTextInput::make()
    ->label('Email')
    ->placeholder('you@example.com')
    ->value($email)
    ->keyboard('email')
    ->leadingIcon('email')
    ->onChange('updateEmail');
```

--------------------------------

### Install and run NativePHP locally

Source: https://nativephp.com/docs/mobile/4/getting-started/quick-start

Configure a local environment for mobile builds using Xcode or Android Studio.

```bash
# Install NativePHP for Mobile into a new Laravel app
composer require nativephp/mobile

# Ready your app to go native
php artisan native:install

# Run your app on a mobile device
php artisan native:run
```

--------------------------------

### Install Laravel Boost for NativePHP

Source: https://nativephp.com/docs/mobile/4/getting-started/development

Run this command after installing the necessary packages to configure NativePHP for Laravel Boost.

```bash
php artisan boost:install
```

--------------------------------

### Settings List Example

Source: https://nativephp.com/docs/mobile/4/edge-components/toggle

A collection of toggles within a layout, demonstrating both native:model binding and manual event handling with disabled states.

```blade
@php $darkMode = false; $notifications = true; $locationEnabled = true; @endphp

<native:column class="w-full gap-0">
    <native:row class="w-full px-4 py-3 justify-between items-center">
        <native:text class="text-base text-theme-on-surface-variant">Dark Mode</native:text>
        <native:toggle native:model="darkMode" />
    </native:row>
    <native:divider />
    <native:row class="w-full px-4 py-3 justify-between items-center">
        <native:text class="text-base text-theme-on-surface-variant">Notifications</native:text>
        <native:toggle native:model="notifications" />
    </native:row>
    <native:divider />
    <native:row class="w-full px-4 py-3 justify-between items-center">
        <native:text class="text-base text-theme-on-surface-variant">Location</native:text>
        <native:toggle :value="$locationEnabled" @change="toggleLocation" disabled />
    </native:row>
</native:column>
```

--------------------------------

### Specify Initialization Functions

Source: https://nativephp.com/docs/mobile/4/plugins/advanced-configuration

Define native functions to execute during app startup for early SDK setup.

```json
{
    "android": {
        "init_function": "com.myvendor.plugins.myplugin.MyPluginInit.initialize"
    },
    "ios": {
        "init_function": "MyPluginInit.initialize"
    }
}
```

--------------------------------

### Move File Example

Source: https://nativephp.com/docs/mobile/4/the-basics/file

Move a temporary file to a permanent storage location.

```php
use Native\Mobile\Facades\File;

$temp = sys_get_temp_dir().'/recording.m4a';
$permanent = storage_path('recordings/recording.m4a');

if (File::move($temp, $permanent)) {
    // saved
}
```

--------------------------------

### Install v4 dependencies

Source: https://nativephp.com/docs/mobile/4/getting-started/upgrade-guide

Update dependencies and force a rebuild of native project files.

```sh
composer update
php artisan native:install --force
```

--------------------------------

### Use the native command helper

Source: https://nativephp.com/docs/mobile/4/getting-started/quick-start

Utilize the native script helper as a shorthand for Artisan commands after installation.

```shell
# Instead of...
php artisan native:run

# Do
php native run

# Or
./native run
```

--------------------------------

### Accessing Native Facades in PHP

Source: https://nativephp.com/docs/mobile/4/the-basics/native-functions

Examples of common NativePHP facades available for platform-specific features.

```php
Native\Mobile\Facades\Biometrics
Native\Mobile\Facades\Browser
Native\Mobile\Facades\Camera
```

--------------------------------

### Document JavaScript Usage

Source: https://nativephp.com/docs/mobile/4/plugins/best-practices

Provide examples for integrating the plugin into SPA frameworks like Vue or React.

```markdown
## Usage (JavaScript)

import { DoSomething } from 'vendor-my-plugin';

// In Vue/React components
const result = await DoSomething({ option: 'value' });
```

--------------------------------

### List registered plugins

Source: https://nativephp.com/docs/mobile/4/plugins/creating-plugins

View currently registered or all installed plugins.

```shell
# Show registered plugins
php artisan native:plugin:list

# Show all installed plugins (including unregistered)
php artisan native:plugin:list --all
```

--------------------------------

### Basic Image Example

Source: https://nativephp.com/docs/mobile/4/edge-components/image

A simple implementation of an image with full width and rounded corners.

```blade
<native:image src="https://picsum.photos/seed/hero/800/400" class="w-full rounded-xl" :height="200" :fit="2" />
```

--------------------------------

### Document PHP Usage

Source: https://nativephp.com/docs/mobile/4/plugins/best-practices

Provide clear examples of facade usage and event handling within Livewire components.

```markdown
## Usage (PHP)

use Vendor\MyPlugin\Facades\MyPlugin;

// Basic usage
$result = MyPlugin::doSomething(['option' => 'value']);

// Listening for events in Livewire
#[OnNative(SomethingCompleted::class)]
public function handleResult($data)
{
    $this->result = $data['result'];
}
```

--------------------------------

### Basic Stack Usage

Source: https://nativephp.com/docs/mobile/4/edge-components/stack

A simple stack example layering a background column and a text overlay.

```blade
<native:stack class="w-[200] h-[200] rounded-2xl">
    <native:column class="w-full h-full bg-theme-primary rounded-2xl" />
    <native:column class="w-full h-full items-center justify-center">
        <native:text class="text-xl font-bold text-theme-on-primary">Overlay Text</native:text>
    </native:column>
</native:stack>
```

--------------------------------

### Using plugin-defined assertions

Source: https://nativephp.com/docs/mobile/4/testing/advanced

Illustrates calling custom assertions provided by installed plugins directly on the harness.

```php
it('copies the link in domain terms', function () {
    Native::test(ShareSheet::class)
        ->tap('copy')
        ->assertCopied('https://nativephp.com');
});
```

--------------------------------

### Configure Android environment variables on Windows

Source: https://nativephp.com/docs/mobile/4/getting-started/environment-setup

Set ANDROID_HOME, PATH, and JAVA_HOME using Windows command syntax. Paths assume default installation locations.

```shell
set ANDROID_HOME=C:\Users\yourname\AppData\Local\Android\Sdk
set PATH=%PATH%;%JAVA_HOME%\bin;%ANDROID_HOME%\platform-tools

# This isn't required if JAVA_HOME is already set in the Windows Env Variables
set JAVA_HOME=C:\Program Files\Microsoft\jdk-17.0.8.7-hotspot
```

--------------------------------

### Inline loading example

Source: https://nativephp.com/docs/mobile/4/edge-components/activity-indicator

Displays a small activity indicator alongside text for inline loading states.

```blade
<native:row class="gap-2 items-center">
    <native:activity-indicator size="sm" />
    <native:text class="text-sm text-theme-on-surface-variant">Refreshing</native:text>
</native:row>
```

--------------------------------

### Plan picker example

Source: https://nativephp.com/docs/mobile/4/edge-components/radio-group

A radio group with multiple options, including a disabled state for one of the choices.

```blade
@php $selectedPlan = 'free'; @endphp

<native:radio-group native:model="selectedPlan" label="Choose a plan">
    <native:radio value="free"     label="Free — $0/mo" />
    <native:radio value="pro"      label="Pro — $9/mo" />
    <native:radio value="team"     label="Team — $29/mo" />
    <native:radio value="custom"   label="Enterprise (contact sales)" disabled />
</native:radio-group>

<native:text class="text-sm text-theme-on-surface-variant">Current plan: {{ $selectedPlan }}</native:text>
```

--------------------------------

### Start Hot Reloading

Source: https://nativephp.com/docs/mobile/4/getting-started/development

Initiates a long-lived process to watch source files and push updates to the emulator.

```shell
php artisan native:watch
```

--------------------------------

### Full-screen and Container Layouts

Source: https://nativephp.com/docs/mobile/4/edge-components/column

Examples of using columns for fixed-height containers and full-screen layouts with safe area insets.

```blade
<native:column class="w-full h-[220] p-4 bg-theme-background rounded-xl border border-theme-outline">
    <native:text class="text-2xl font-bold text-theme-on-surface-variant">My App</native:text>
    <native:spacer />
    <native:button label="Get Started" @press="start" />
</native:column>
```

```blade
<native:column class="w-full h-full safe-area bg-theme-background">
    <native:text class="text-2xl font-bold">My App</native:text>
    <native:spacer />
    <native:button label="Get Started" @press="start" />
</native:column>
```

--------------------------------

### Install NativePHP

Source: https://nativephp.com/docs/mobile/4/getting-started/commands

Installs NativePHP into a Laravel application.

```shell
php artisan native:install {platform?}
```

--------------------------------

### Initialize component data with mount()

Source: https://nativephp.com/docs/mobile/4/digging-deeper/lifecycle-hooks

Runs once when a screen is pushed onto the stack. Use this to load initial data and read route parameters.

```php
class ProductScreen extends NativeComponent
{
    public array $product = [];

    public function mount(): void
    {
        $this->product = Product::findOrFail($this->param('id'))->toArray();
    }
}
```

--------------------------------

### Start Vite HMR with Watcher

Source: https://nativephp.com/docs/mobile/4/getting-started/development

Enables Vite HMR during development. Use the run command to build, deploy, and watch simultaneously.

```shell
php artisan native:watch --vite

# or build, deploy, and start watching in one go:
php artisan native:run --watch --vite
```

--------------------------------

### Create a new NativePHP Laravel app

Source: https://nativephp.com/docs/mobile/4/getting-started/quick-start

Use the starter kit to scaffold a new Laravel application pre-configured for NativePHP.

```bash
laravel new my-app --using=nativephp/mobile-starter

cd my-app

php artisan native:jump
```

--------------------------------

### Publish UI layouts

Source: https://nativephp.com/docs/mobile/4/the-basics/layouts

Use the artisan command to scaffold starter Blade components for layouts.

```bash
php artisan vendor:publish --tag=native-ui-layouts
```

--------------------------------

### Create and configure an Icon element

Source: https://nativephp.com/docs/mobile/4/edge-components/icon

Demonstrates initializing an icon with shared or platform-specific symbols and applying styling properties.

```php
use App\Icons\Android;
use App\Icons\Ios;
use Native\Mobile\Edge\Elements\Icon;

Icon::make('home')->size(24)->color('#1E293B');

// Per-platform symbols — a shared name, enum overrides, or both:
Icon::make(ios: Ios::Gearshape, android: Android::Settings);
Icon::make('share', ios: Ios::SquareAndArrowUp);
```

--------------------------------

### Import Device Facade

Source: https://nativephp.com/docs/mobile/4/the-basics/device

Include the Device facade to access hardware-related methods.

```php
use Native\Mobile\Facades\Device;
```

--------------------------------

### Volume Slider Example

Source: https://nativephp.com/docs/mobile/4/edge-components/slider

A practical example of a volume slider with a label that updates based on the slider value.

```blade
@php $volume = 40; @endphp

<native:column class="w-full gap-2 p-4">
    <native:row class="w-full justify-between">
        <native:text class="text-sm text-theme-on-surface">Volume</native:text>
        <native:text class="text-sm text-theme-on-surface-variant">{{ $volume }}%</native:text>
    </native:row>
    <native:slider :min="0" :max="100" :step="1" native:model.debounce.150ms="volume" />
</native:column>
```

--------------------------------

### Generate Boost Guidelines

Source: https://nativephp.com/docs/mobile/4/plugins/best-practices

Use this command to create the initial guidelines file for Laravel Boost integration.

```shell
php artisan native:plugin:boost
```

--------------------------------

### Clone the repository

Source: https://nativephp.com/docs/mobile/4/getting-started/contributing

Initial step to set up the local development environment by cloning the fork.

```bash
git clone git@github.com:your-username/mobile-air.git
cd mobile-air
```

--------------------------------

### Import the Native facade

Source: https://nativephp.com/docs/mobile/4/testing/introduction

Include the Native facade to access testing entry points.

```php
use Native\Mobile\Testing\Native;
```

--------------------------------

### Install axios for Inertia 3

Source: https://nativephp.com/docs/mobile/4/getting-started/development

Required dependency installation for Inertia 3 projects to ensure NativePHP can intercept HTTP requests.

```shell
npm install axios
```

--------------------------------

### Scripting plugin responses

Source: https://nativephp.com/docs/mobile/4/testing/advanced

Demonstrates using plugin-provided macros to stage device responses before mounting the component.

```php
it('reads the scripted location', function () {
    Native::fakeBridge()->withLocation(48.85, 2.35);

    Native::test(GeolocationDemo::class)
        ->call('locate')
        ->assertSet('latitude', 48.85);
});
```

--------------------------------

### Manage Emulators

Source: https://nativephp.com/docs/mobile/4/getting-started/commands

Lists and launches available emulators or simulators for the specified platform.

```shell
php artisan native:emulator {os}
```

--------------------------------

### Retrieve Device Identifier

Source: https://nativephp.com/docs/mobile/4/the-basics/device

Get a stable per-install identifier for the device.

```php
$id = Device::getId(); // ?string
```

--------------------------------

### System::appSettings()

Source: https://nativephp.com/docs/mobile/4/the-basics/system

Opens the device's system settings page for the application.

```APIDOC
## System::appSettings()

### Description
Opens the app's page in the device Settings app. This is useful for directing users to re-grant permissions that were previously denied.
```

--------------------------------

### Publish the theme configuration

Source: https://nativephp.com/docs/mobile/4/digging-deeper/theming

Run this command to generate the config/native-ui.php file for customizing app tokens and settings.

```shell
php artisan vendor:publish --tag=native-ui-config
```

--------------------------------

### Create a decorative separator

Source: https://nativephp.com/docs/mobile/4/edge-components/shapes

Examples of using lines or dividers for visual separation.

```blade
<native:line class="border border-theme-outline" />
```

```blade
<native:divider class="border-theme-outline" />
```

--------------------------------

### Photo Grid Example

Source: https://nativephp.com/docs/mobile/4/edge-components/lazy-grid

A grid layout displaying images with fixed heights.

```blade
<native:lazy-grid :columns="3" :gap="2" class="w-full">
    @foreach (range(1, 9) as $i)
        <native:column :height="120">
            <native:image src="https://picsum.photos/seed/grid{{ $i }}/300" class="w-full h-full" :fit="2" />
        </native:column>
    @endforeach
</native:lazy-grid>
```

--------------------------------

### Using scripting macros in a test

Source: https://nativephp.com/docs/mobile/4/plugins/validation-testing

Stage a device response before mounting the component to simulate specific hardware states.

```php
Native::fakeBridge()->withLocation(48.85, 2.35);

Native::test(GeolocationDemo::class)
    ->call('locate')
    ->assertSet('latitude', 48.85);
```

--------------------------------

### Basic Badge Usage

Source: https://nativephp.com/docs/mobile/4/edge-components/badge

A simple example of a badge displaying a numeric count.

```blade
<native:badge :count="3" />
```

--------------------------------

### Build iOS App for App Store

Source: https://nativephp.com/docs/mobile/4/publishing/ios

Use this command to package a production-ready app for App Store submission.

```bash
php artisan native:package ios \
  --export-method=app-store \
  --api-key-path=/path/to/api-key.p8 \
  --api-key-id=ABC123DEF \
  --api-issuer-id=01234567-89ab-cdef-0123-456789abcdef \
  --certificate-path=/path/to/distribution.p12 \
  --certificate-password=certificatepassword \
  --provisioning-profile-path=/path/to/profile.mobileprovision \
  --team-id=ABC1234567
```

--------------------------------

### Import System Facade

Source: https://nativephp.com/docs/mobile/4/the-basics/system

Import the System facade to access system-level functionality.

```php
use Native\Mobile\Facades\System;
```

--------------------------------

### Create a release build

Source: https://nativephp.com/docs/mobile/4/publishing/introduction

Generates an optimized production build of the application for distribution.

```shell
php artisan native:run --build=release
```

--------------------------------

### Badge on an Icon

Source: https://nativephp.com/docs/mobile/4/edge-components/stack

Example of using a stack to overlay a notification count badge on an icon.

```blade
<native:stack class="w-[40] h-[40]">
    <native:icon name="notifications" :size="32" />
    <native:column class="w-[18] h-[18] bg-red-500 rounded-full items-center justify-center">
        <native:text class="text-[10] font-bold text-white">3</native:text>
    </native:column>
</native:stack>
```

--------------------------------

### Country Picker Example

Source: https://nativephp.com/docs/mobile/4/edge-components/select

A standard implementation of the select component populated with a list of countries.

```blade
@php $destination = 'Japan'; @endphp

<native:select
    label="Country"
    placeholder="Select country"
    :options="['Australia', 'Brazil', 'Canada', 'Germany', 'Japan', 'United Kingdom', 'United States']"
    native:model="destination"
/>
```

--------------------------------

### Initialize and configure a ScrollView

Source: https://nativephp.com/docs/mobile/4/edge-components/scroll-view

Create a scrollable container and apply layout and behavior modifiers.

```php
use Native\Mobile\Edge\Elements\ScrollView;

ScrollView::make()
    ->horizontal()
    ->both()
    ->showsIndicators(false)
    ->autoScrollTo(0);
```

--------------------------------

### Create Boost AI guidelines

Source: https://nativephp.com/docs/mobile/4/getting-started/commands

Generate Boost AI guidelines for a specific plugin or path.

```shell
php artisan native:plugin:boost {plugin?}
```

--------------------------------

### Rounded Avatar Example

Source: https://nativephp.com/docs/mobile/4/edge-components/image

Displays a circular image by applying a full border radius.

```blade
<native:image
    src="https://i.pravatar.cc/128?img=12"
    :width="64"
    :height="64"
    :fit="2"
    class="rounded-full"
/>
```

--------------------------------

### Configure NativePHP environment variables

Source: https://nativephp.com/docs/mobile/4/getting-started/installation

Set these variables in your .env file before running the installation command.

```dotenv
NATIVEPHP_APP_ID=com.yourcompany.yourapp
```

```dotenv
NATIVEPHP_DEVELOPMENT_TEAM={your team ID}
```

--------------------------------

### Image with Bottom-Aligned Overlay

Source: https://nativephp.com/docs/mobile/4/edge-components/stack

Example of using a stack to overlay text content on top of an image.

```blade
<native:stack class="w-full h-[250] rounded-2xl">
    <native:image src="https://picsum.photos/seed/banner/800/500" class="w-full h-full" :fit="2" />
    <native:column class="w-full h-full justify-end p-4 bg-black/40">
        <native:text class="text-2xl font-bold text-white">Featured Article</native:text>
        <native:text class="text-base text-white">Read more about this topic</native:text>
    </native:column>
</native:stack>
```

--------------------------------

### Avatar with Centered Badge

Source: https://nativephp.com/docs/mobile/4/edge-components/stack

Example of using a stack to place a status badge over an avatar container.

```blade
<native:stack class="w-[56] h-[56]">
    <native:column class="w-[56] h-[56] rounded-full bg-theme-surface-variant" />
    <native:column class="w-[20] h-[20] bg-green-500 rounded-full border-2 border-white" />
</native:stack>
```

--------------------------------

### Enable lazy loading with #[Lazy]

Source: https://nativephp.com/docs/mobile/4/digging-deeper/lifecycle-hooks

Marks a component to show a placeholder while mount() performs slow operations in the background. Override placeholder() to customize the loading UI.

```php
use Native\Mobile\Attributes\Lazy;

#[Lazy]
class Dashboard extends NativeComponent
{
    public function mount(): void
    {
        $this->stats = $this->crunchExpensiveStats(); // slow
    }

    protected function placeholder(): Element|View
    {
        return view('native.dashboard-skeleton');
    }
}
```

--------------------------------

### Import File Facade

Source: https://nativephp.com/docs/mobile/4/the-basics/file

Include the File facade to access native file system operations.

```php
use Native\Mobile\Facades\File;
```

--------------------------------

### Install NativePHP Composer package

Source: https://nativephp.com/docs/mobile/4/getting-started/installation

Run this command to add the NativePHP mobile library to your Laravel project.

```shell
composer require nativephp/mobile
```

--------------------------------

### Define a List Item

Source: https://nativephp.com/docs/mobile/4/edge-components/list

A basic example of a list item with a headline, supporting text, and leading/trailing icons.

```blade
<native:list-item
    headline="Inbox"
    supporting="42 unread"
    leadingIcon="email"
    trailingIcon="forward"
    @press="openInbox"
/>
```

--------------------------------

### Define Row Template

Source: https://nativephp.com/docs/mobile/4/edge-components/virtual-list

Example of a row view that renders a single item based on the provided index.

```blade
{{-- resources/views/native/rows/contact.blade.php --}}
@php $contact = \App\Models\Contact::skip($index)->first(); @endphp

<native:list-item headline="{{ $contact->name }}" supporting="{{ $contact->email }}" />
```

--------------------------------

### Build iOS App for Development

Source: https://nativephp.com/docs/mobile/4/publishing/ios

Use this command to package an app for testing on your own device.

```bash
php artisan native:package ios \
  --export-method=development \
  --certificate-path=/path/to/development.p12 \
  --certificate-password=certificatepassword \
  --provisioning-profile-path=/path/to/development-profile.mobileprovision
```

--------------------------------

### Basic Toggle Implementation

Source: https://nativephp.com/docs/mobile/4/edge-components/toggle

A simple toggle example using a boolean property and an @change event handler.

```blade
@php $darkMode = false; @endphp

<native:toggle label="Dark Mode" :value="$darkMode" @change="toggleDarkMode" />
```

--------------------------------

### BottomSheet::make()

Source: https://nativephp.com/docs/mobile/4/edge-components/bottom-sheet

Initializes a new BottomSheet instance.

```APIDOC
## BottomSheet::make()

### Description
Creates a new instance of a bottom sheet component.

### Method
Static Method

### Parameters
None
```

--------------------------------

### Configure Development Server

Source: https://nativephp.com/docs/mobile/4/getting-started/configuration

Defines ports and service discovery settings for the local development server.

```php
'server' => [
    'http_port' => env('NATIVEPHP_HTTP_PORT', 3000),
    'ws_port' => env('NATIVEPHP_WS_PORT', 8081),
    'service_name' => env('NATIVEPHP_SERVICE_NAME', 'NativePHP Server'),
    'open_browser' => env('NATIVEPHP_OPEN_BROWSER', true),
],
```

--------------------------------

### View command help

Source: https://nativephp.com/docs/mobile/4/getting-started/development

Displays available arguments and options for a specific Artisan command.

```shell
php artisan native:run --help
```

--------------------------------

### Determinate Progress Bar Example

Source: https://nativephp.com/docs/mobile/4/edge-components/progress-bar

A progress bar integrated with a percentage label, tracking a component property.

```blade
@php $progress = 0.65; @endphp

<native:column class="w-full gap-2 p-4">
    <native:row class="w-full justify-between">
        <native:text class="text-sm text-theme-on-surface">Uploading</native:text>
        <native:text class="text-sm text-theme-on-surface-variant">{{ round($progress * 100) }}%</native:text>
    </native:row>
    <native:progress-bar :value="$progress" />
</native:column>
```

--------------------------------

### Create a NativeList

Source: https://nativephp.com/docs/mobile/4/edge-components/list

Initializes a list with items, separators, and event handlers for refresh and end-reached actions.

```php
use Nativephp\NativeUi\Elements\NativeList;
use Nativephp\NativeUi\Elements\ListItem;

NativeList::make(
    ListItem::make('Profile')->leadingIcon('person')->trailingIcon('forward'),
    ListItem::make('Settings')->leadingIcon('settings')->trailingIcon('forward'),
)
    ->separator()
    ->onRefresh('refresh')
    ->onEndReached('loadMore');
```

--------------------------------

### Centered loading screen example

Source: https://nativephp.com/docs/mobile/4/edge-components/activity-indicator

Displays a large activity indicator centered within a column container.

```blade
<native:column class="w-full h-[200] items-center justify-center">
    <native:activity-indicator size="lg" />
    <native:text class="text-base text-theme-on-surface-variant mt-4">Loading...</native:text>
</native:column>
```

--------------------------------

### Use plugin facade

Source: https://nativephp.com/docs/mobile/4/plugins/using-plugins

Interact with native functionality using the plugin's facade.

```php
use Vendor\PluginName\Facades\PluginName;

// Call a native function
$result = PluginName::doSomething(['option' => 'value']);
```

--------------------------------

### Build frontend for specific platforms

Source: https://nativephp.com/docs/mobile/4/getting-started/development

Run these commands to build assets for iOS or Android before compiling the native application.

```shell
npm run build -- --mode=ios

npm run build -- --mode=android
```

--------------------------------

### follow()

Source: https://nativephp.com/docs/mobile/4/testing/navigation

Resolves pending navigation and returns a new harness mounted on the destination.

```APIDOC
## follow()

### Description
Resolves the pending navigation through the route registry and returns a new harness mounted on the destination, carrying the intent's data, params, and layout. It mirrors the router precisely, maintaining state for forward navigations or unmounting for replacements.
```

--------------------------------

### Add NativePHP to an existing Laravel app

Source: https://nativephp.com/docs/mobile/4/getting-started/quick-start

Install the package via Composer and initiate the jump process for mobile deployment.

```bash
composer require nativephp/mobile

php artisan native:jump
```

--------------------------------

### Configure Keystore via Environment Variables

Source: https://nativephp.com/docs/mobile/4/publishing/android

Store sensitive keystore credentials in the .env file to simplify the packaging command.

```env
ANDROID_KEYSTORE_FILE=/path/to/my-app.keystore
ANDROID_KEYSTORE_PASSWORD=mykeystorepassword
ANDROID_KEY_ALIAS=my-app-key
ANDROID_KEY_PASSWORD=mykeypassword
```

```bash
php artisan native:package android --build-type=bundle
```

--------------------------------

### Build a Release APK

Source: https://nativephp.com/docs/mobile/4/publishing/android

Compiles and signs the Android application using the provided keystore and key credentials.

```bash
php artisan native:package android \
  --keystore=/path/to/my-app.keystore \
  --keystore-password=mykeystorepassword \
  --key-alias=my-app-key \
  --key-password=mykeypassword
```

--------------------------------

### Importing and Using Native JavaScript Functions

Source: https://nativephp.com/docs/mobile/4/the-basics/native-functions

Example of importing native modules and using them within a Vue component lifecycle.

```javascript
import { On, Off, Microphone, Events } from '#nativephp';
import { onMounted, onUnmounted } from 'vue';

const buttonClicked = () => {
    Microphone.record();
};

const handleRecordingFinished = () => {
    // Update the UI
};

onMounted(() => {
    On(Events.Microphone.MicrophoneRecorded, handleRecordingFinished);
});

onUnmounted(() => {
    Off(Events.Microphone.MicrophoneRecorded, handleRecordingFinished);
});
```

--------------------------------

### Apply Fixed Header without Safe Areas

Source: https://nativephp.com/docs/mobile/4/edge-components/web-view

Example of a fixed header implementation that does not account for device display cutouts.

```html
<div class="fixed top-0 left-0 w-full bg-red-500">
    ...
</div>
```

--------------------------------

### View missing prop error message

Source: https://nativephp.com/docs/mobile/4/edge-components/introduction

Example of the error message displayed when a required property is omitted from an EDGE component.

```text
EDGE Component <native:bottom-nav-item> is missing required properties: 'label'.
Add these attributes to your component: label="..."
```

--------------------------------

### Declare plugin secrets in manifest

Source: https://nativephp.com/docs/mobile/4/plugins/advanced-configuration

Define required or optional environment variables with descriptions to guide users during the build process.

```json
{
    "secrets": {
        "MAPBOX_DOWNLOADS_TOKEN": {
            "description": "Mapbox SDK download token from mapbox.com/account/access-tokens",
            "required": true
        },
        "FIREBASE_API_KEY": {
            "description": "Firebase project API key",
            "required": false
        }
    }
}
```

--------------------------------

### Tinted Icon Image Example

Source: https://nativephp.com/docs/mobile/4/edge-components/image

Applies a hex color tint to an image, best used with assets containing an alpha channel.

```blade
<native:image
    src="https://www.php.net/images/logos/new-php-logo.png"
    :width="80"
    :height="42"
    :fit="1"
    tint-color="#7C3AED"
/>
```

--------------------------------

### Build iOS App with Environment Variables

Source: https://nativephp.com/docs/mobile/4/publishing/ios

Execute the build command after configuring credentials in the .env file.

```bash
php artisan native:package ios --export-method=app-store
```

--------------------------------

### Export Bridge Port for Custom Server

Source: https://nativephp.com/docs/mobile/4/the-basics/jump

Set the JUMP_BRIDGE_PORT environment variable when starting a custom server to ensure correct communication.

```shell
JUMP_BRIDGE_PORT=3002 php artisan serve --port=8000
```

--------------------------------

### Initialize shape elements in PHP

Source: https://nativephp.com/docs/mobile/4/edge-components/shapes

Use the make() method to instantiate shape elements within PHP code.

```php
use Native\Mobile\Edge\Elements\Rect;
use Native\Mobile\Edge\Elements\Circle;
use Native\Mobile\Edge\Elements\Line;

Rect::make();
Circle::make();
Line::make();
```

--------------------------------

### Basic Tab Row implementation

Source: https://nativephp.com/docs/mobile/4/edge-components/tab-row

A standard tab row setup using native:model to track the active tab index.

```blade
@php $activeTab = 0; @endphp

<native:tab-row native:model="activeTab">
    <native:tab label="Recent" icon="history" />
    <native:tab label="Starred" icon="star" />
    <native:tab label="Archived" icon="archive-box" />
</native:tab-row>
```

--------------------------------

### Generate a test file

Source: https://nativephp.com/docs/mobile/4/testing/introduction

Use the artisan command to scaffold a new test file for a component.

```bash
php artisan native:make-test Counter
```

--------------------------------

### Set a custom height for the bottom sheet

Source: https://nativephp.com/docs/mobile/4/edge-components/bottom-sheet

Defines a specific height using a numeric detent value. This example displays an image within the sheet.

```blade
@php
    $showPreview = false;
    $previewUrl = 'https://picsum.photos/600/400';
@endphp

<native:column class="w-full gap-3 items-start">
    <native:button label="Preview" @press="$showPreview = true" />

    <native:bottom-sheet :visible="$showPreview" @dismiss="$showPreview = false" detents="0.4">
        <native:image src="{{ $previewUrl }}" class="w-full h-full" :fit="2" />
    </native:bottom-sheet>
</native:column>
```
Tokens:
Raw