NativePHP Mobile

https://nativephp.com/docs/mobile/3/
Admin
NativePHP Mobile enables developers to build performant, offline-capable native mobile applications...
Tokens:37,203
Snippets:608
Trust Score:8.5
Update:2 months ago
Show doc for...
Tokens:
Raw
### Install a Premium Plugin

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

Install a premium plugin after configuring the repository and credentials.

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

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

### Start NativePHP application

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

Use this command to compile and boot the application on a selected device.

```shell
php artisan native:run
```

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

### Windows Environment Variables Setup

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

Configures essential environment variables for Android development on Windows, including ANDROID_HOME and PATH. Assumes default installation paths for Android SDK and JDK. Ensure JAVA_HOME is correctly set if not already defined.

```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
```

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

### PHP Usage Example (Markdown)

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

Demonstrates basic PHP usage of a plugin facade and listening for events in Livewire.

```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'];
}
```

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

### Install and Register Plugin (Markdown)

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

Instructions for installing a plugin using Composer and registering it with NativePHP.

```markdown
## Installation

composer require vendor/my-plugin

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

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

### Install AI agents

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

Install AI agents to assist with plugin development.

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

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

### Install Xcode Command Line Tools

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

Installs the Xcode command line tools necessary for iOS development. Verify the installation using `xcode-select -p`.

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

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

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

### List All Installed Plugins

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

View all installed plugins, including those that are not yet registered.

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

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

### Install a Standard Plugin

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

Use Composer to install any standard NativePHP plugin package.

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

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

### Set the application start URL

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

Defines the initial path loaded upon application startup, defaulting to the root if not specified.

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

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

### Install CocoaPods

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

Installs CocoaPods, a dependency manager for Swift and Objective-C Cocoa projects, using Homebrew. Verify the installation with `pod --version`.

```shell
brew install cocoapods
```

```shell
pod --version
```

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

### Vue Component Example (Inertia)

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

Example of a Vue component used with Inertia, showing how to import and use plugin functions for starting a scan and handling scan completion events.

```vue
<script setup>
import { ref } from 'vue';
import { StartScan, OnScanComplete } from 'vendor-my-plugin';

const result = ref(null);

OnScanComplete((data) => {
    result.value = data.value;
});

async function scan() {
    await StartScan();
}
</script>

<template>
    <button @click="scan">Scan</button>
    <p v-if="result">@{{ result }}</p>
</template>
```

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

### Run NativePHP installer

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

Execute this command to set up and configure the Laravel application for iOS and Android.

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

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

### Install Laravel Boost

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

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

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

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

### Download and Copy ML Model - PHP

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

This example demonstrates downloading an ML model if it's not cached and then copying it to the appropriate platform asset or bundle location using provided helper methods.

```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 NativePHP

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

Installs NativePHP into a Laravel application.

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

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

### Start Jump Development Server

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

Run this command in your Laravel project terminal to initiate the development server, WebSocket bridge, and QR code generation for mobile previewing.

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

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

### JavaScript Usage Example (Markdown)

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

Shows how to import and use a plugin's JavaScript functions in SPA frameworks like Vue or React.

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

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

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

### Start Hot Reloading

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

Run this command to start a long-lived process that watches source files and pushes updates to the emulator.

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

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

### Update Version Constraints and Install

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

Update the package version in composer.json and run the installation commands to finalize the upgrade.

```json
"require": {
    "nativephp/mobile": "~2.0.0" // [tl! remove]
    "nativephp/mobile": "~3.0.0" // [tl! add]
}
```

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

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

### Create New Laravel App with NativePHP Starter

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

Use this command to create a new Laravel application pre-configured with the NativePHP mobile starter kit. Navigate into the app directory and run `php artisan native:jump` to initiate the mobile setup.

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

cd my-app

php artisan native:jump
```

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

### List Installed NativePHP Plugins

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

Verify that NativePHP recognizes your installed plugins and view their details.

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

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

### Livewire Component Example

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

Example of a Livewire component demonstrating the use of NativePHP's #[OnNative] attribute for handling native events and calling plugin facades.

```php
use Livewire\Component;
use Native\Mobile\Attributes\OnNative;
use Vendor\MyPlugin\Facades\MyPlugin;
use Vendor\MyPlugin\Events\ScanComplete;

class Scanner extends Component
{
    public ?string $result = null;

    public function scan(): void
    {
        MyPlugin::startScan();
    }

    #[OnNative(ScanComplete::class)]
    public function handleScan($data): void
    {
        $this->result = $data['value'];
    }

    public function render()
    {
        return view('livewire.scanner');
    }
}
```

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

### Run update and installation commands

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

Execute these commands in the terminal to update dependencies and refresh native project files.

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

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

### Example Plugin Registration in Service Provider

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

This is how a plugin's service provider is typically added to the `plugins()` array within `app/Providers/NativeServiceProvider.php`.

```php
public function plugins(): array
{
    return [
        \Vendor\PluginName\PluginNameServiceProvider::class,
    ];
}
```

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

### Placeholder Substitution in Text Assets

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

Example of an XML configuration file demonstrating placeholder substitution for environment variables. These placeholders are replaced during the build process.

```xml
<!-- resources/config/api.xml -->
<config>
    <api-key>${MY_PLUGIN_API_KEY}</api-key>
</config>
```

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

### Example Background Job

Source: https://nativephp.com/docs/mobile/3/concepts/queues

This job performs an API call and shows a toast notification upon completion. It requires the `Http` facade and the `Dialog` plugin.

```php
namespace App\Jobs;

use Illuminate\Bus\Queueable;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Foundation\Bus\Dispatchable;
use Illuminate\Queue\InteractsWithQueue;
use Illuminate\Queue\SerializesModels;
use Illuminate\Support\Facades\Http;
use NativePHP\Plugins\Dialog\Dialog;

class SyncData implements ShouldQueue
{
    use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;

    public function __construct(public array $payload) {}

    public function handle()
    {
        Http::post('https://api.example.com/sync', $this->payload);

        Dialog::toast('Sync complete!');
    }
}
```

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

### Use NativePHP `native` Script Wrapper

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

Once `native:install` is run, a `native` script helper is created. This allows you to use `./native run` or `php native run` as a shorthand for `php artisan native:run`.

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

# Do
php native run

# Or
./native run
```

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

### Install NativePHP Composer package

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

Run this command in your Laravel project root to install the necessary NativePHP libraries.

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

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

### Force Native Project Reinstall

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

Use this command to force a fresh install of native projects, useful when testing significant native code or manifest changes.

```shell
php artisan native:install --force
```

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

### Import NativePHP JavaScript Library

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

Add this section to your package.json to enable the NativePHP JavaScript library import. Run 'npm install' after adding.

```json
{
    "dependencies": {
        ...
    },
    "imports": { 
        "#nativephp": "./vendor/nativephp/mobile/resources/dist/native.js"
    }
}
```

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

### Common NativePHP Facades

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

These are examples of common NativePHP Facades available for direct use in your PHP code, providing access to platform-specific features.

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

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

### Run NativePHP Mobile App

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

After installing NativePHP and preparing your app, use this command to run your application on a mobile device. Ensure your environment is set up for mobile builds.

```bash
php artisan native:run
```

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

### macOS Environment Variables Setup

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

Configures essential environment variables for Android development on macOS, including JAVA_HOME, ANDROID_HOME, and PATH. Ensure JAVA_HOME is correctly set if not already defined.

```shell
# This isn't required if JAVA_HOME is already set in your environment variables (check using `printenv | grep JAVA_HOME`)
export JAVA_HOME=$(/usr/libexec/java_home -v 17) 

export ANDROID_HOME=$HOME/Library/Android/sdk
export PATH=$PATH:$JAVA_HOME/bin:$ANDROID_HOME/emulator:$ANDROID_HOME/tools:$ANDROID_HOME/tools/bin:$ANDROID_HOME/platform-tools
```

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

### Create Seed Migration

Source: https://nativephp.com/docs/mobile/3/concepts/databases

Use the Artisan command to create a new migration file specifically for seeding data. This ensures data is inserted once per installation.

```shell
php artisan make:migration seed_app_settings
```

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

### Complete Firebase ML Kit Plugin Manifest Example

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

A comprehensive manifest for a NativePHP plugin integrating Firebase ML Kit. It includes bridge functions, events, platform-specific configurations for Android and iOS (permissions, dependencies, activities, info.plist), assets, secrets, and compile hooks.

```json
{
    "namespace": "FirebaseML",
    "bridge_functions": [
        {
            "name": "FirebaseML.Analyze",
            "android": "com.nativephp.plugins.firebaseml.AnalyzeFunctions.Analyze",
            "ios": "FirebaseMLFunctions.Analyze"
        }
    ],
    "events": [
        "Vendor\FirebaseML\Events\AnalysisComplete"
    ],
    "android": {
        "permissions": [
            "android.permission.CAMERA",
            "android.permission.INTERNET"
        ],
        "features": [
            {"name": "android.hardware.camera", "required": true}
        ],
        "dependencies": {
            "implementation": [
                "com.google.firebase:firebase-ml-vision:24.1.0",
                "com.google.firebase:firebase-core:21.1.1"
            ]
        },
        "activities": [
            {
                "name": ".CameraPreviewActivity",
                "theme": "@style/Theme.AppCompat.Light.NoActionBar",
                "exported": false,
                "configChanges": "orientation|screenSize|keyboardHidden"
            }
        ],
        "meta_data": [
            {
                "name": "com.google.firebase.ml.vision.DEPENDENCIES",
                "value": "ocr"
            }
        ]
    },
    "ios": {
        "info_plist": {
            "NSCameraUsageDescription": "Camera is used for ML analysis"
        },
        "dependencies": {
            "pods": [
                {"name": "Firebase/MLVision", "version": "~> 10.0"},
                {"name": "Firebase/Core", "version": "~> 10.0"}
            ]
        },
        "background_modes": ["processing"],
        "entitlements": {
            "com.apple.developer.associated-domains": ["applinks:example.com"]
        }
    },
    "assets": {
        "android": {
            "google-services.json": "google-services.json"
        },
        "ios": {
            "GoogleService-Info.plist": "Resources/GoogleService-Info.plist"
        }
    },
    "secrets": {
        "FIREBASE_API_KEY": {
            "description": "Firebase API key from Firebase Console",
            "required": true
        }
    },
    "hooks": {
        "pre_compile": "nativephp:firebase-ml:setup"
    }
}
```

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

### Build for Development

Source: https://nativephp.com/docs/mobile/3/getting-started/deployment

Command to package an application for testing on a local 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
```

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

### Install Homebrew Package Manager

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

Installs Homebrew, a package manager for macOS, used for installing other development tools. This script should be run directly in your terminal.

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

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

### Using Plugin Facades and Events in PHP

Source: https://nativephp.com/docs/mobile/3/plugins/introduction

Demonstrates how to interact with a plugin's native functionality through PHP facades and listen for events dispatched from native code. Ensure the plugin is registered and its facade is imported.

```php
use Vendor\MyPlugin\Facades\MyPlugin;

// Call native functions
MyPlugin::doSomething();

// Listen for events
#[OnNative(MyPlugin\Events\SomethingHappened::class)]
public function handleResult($data)
{
    // Handle it
}
```

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

### Clone the repository

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

Initializes a local copy of the project repository.

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

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

### Create Boost AI guidelines

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

Generate Boost AI guidelines for a specific plugin.

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

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

### Fixed Header Example

Source: https://nativephp.com/docs/mobile/3/the-basics/web-view

Example of a fixed header element using Tailwind CSS classes.

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

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

### Register NativeServiceProvider and Plugins

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

Publish the NativeServiceProvider to register third-party plugins, then use the registration command to add specific plugins.

```shell
php artisan vendor:publish --tag=nativephp-plugins-provider
```

```shell
php artisan native:plugin:register vendor/some-plugin
```

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

### Run a release build

Source: https://nativephp.com/docs/mobile/3/getting-started/deployment

Generates an optimized production build of the application for store submission.

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

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

### Install NativePHP for Mobile Development

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

Install NativePHP into a new Laravel app using Composer. This command sets up the necessary components for building mobile applications. It's a prerequisite for running your app on a mobile device.

```bash
composer require nativephp/mobile

php artisan native:install
```

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

### Run native:jump with an external server

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

Use --no-serve to bypass the default artisan serve command and connect to an existing server instance.

```shell
php artisan native:jump --no-serve --laravel-port=8000
```

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

### Uninstall a plugin

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

Completely remove an installed plugin.

```shell
php artisan native:plugin:uninstall {plugin}
```

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

### Build for App Store

Source: https://nativephp.com/docs/mobile/3/getting-started/deployment

Command to package an application for App Store distribution using required signing credentials.

```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
```

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

### Install Axios for Inertia 3

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

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

```shell
npm install axios
```

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

### Build frontend for specific platforms

Source: https://nativephp.com/docs/mobile/3/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
```

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

### Upload to App Store Connect

Source: https://nativephp.com/docs/mobile/3/getting-started/deployment

Command to build and automatically upload the application to App Store Connect.

```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 \
  --upload-to-app-store
```

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

### Handling Missing Prop Validation Errors

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

Example of the error message displayed when a required prop like 'label' is omitted from a component.

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

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

### Export bridge port for external server

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

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

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

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

### Register a Plugin

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

Register a plugin to ensure it is compiled into your native builds. This command automatically adds the plugin's service provider to your `plugins()` array.

```shell
php artisan native:plugin:register vendor/plugin-name
```

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

### Build with Environment Variables

Source: https://nativephp.com/docs/mobile/3/getting-started/deployment

Build command that utilizes credentials stored in the environment.

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

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

### iOS CocoaPods Dependencies

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

Configure CocoaPods dependencies using the `pods` array within `ios.dependencies`. NativePHP generates a `Podfile` and runs `pod install`.

```json
{
    "ios": {
        "dependencies": {
            "pods": [
                {"name": "GoogleMLKit/FaceDetection", "version": "~> 4.0"},
                {"name": "TensorFlowLiteSwift", "version": "~> 2.13"}
            ]
        }
    }
}
```

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

### Register a plugin

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

Register a plugin in the NativeServiceProvider or discover unregistered plugins.

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

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

### Test App Store Uploads

Source: https://nativephp.com/docs/mobile/3/getting-started/deployment

Command to test the upload process for an existing IPA file without performing a full build.

```bash
php artisan native:package ios \
  --test-upload \
  --api-key-path=/path/to/api-key.p8 \
  --api-key-id=ABC123DEF \
  --api-issuer-id=01234567-89ab-cdef-0123-456789abcdef
```

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

### Verify keystore contents

Source: https://nativephp.com/docs/mobile/3/getting-started/deployment

Use the keytool utility to confirm that a specific key alias exists within your keystore.

```bash
keytool -list -v -keystore /path/to/keystore
```

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

### JavaScript Bridge Call Example

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

Provides a JavaScript function to call native methods. Ensure the `baseUrl` matches your API endpoint. This function is intended to be imported and used in your frontend application.

```javascript
// resources/js/myPlugin.js
const baseUrl = '/_native/api/call';

async function bridgeCall(method, params = {}) {
    const response = await fetch(baseUrl, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ method, params })
    });
    return response.json();
}

export async function doSomething(options = {}) {
    return bridgeCall('MyPlugin.DoSomething', options);
}
```

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

### Android Kotlin Bridge Function

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

Define bridge functions in Kotlin for Android. Ensure the package declaration matches the path where the file will be compiled. This example shows a simple success response.

```kotlin
// resources/android/src/MyPluginFunctions.kt
package com.myvendor.plugins.myplugin

import com.nativephp.mobile.bridge.BridgeFunction
import com.nativephp.mobile.bridge.BridgeResponse

object MyPluginFunctions {
    class DoSomething : BridgeFunction {
        override fun execute(parameters: Map<String, Any>): Map<String, Any> {
            return BridgeResponse.success(mapOf("status" to "done"))
        }
    }
}
```

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

### Open Project in IDE

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

Opens the native project in the appropriate IDE, such as Xcode or Android Studio.

```shell
php artisan native:open {os?}
```

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

### Register Android Manifest Components

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

Define Android activities, services, receivers, and providers to be merged into the app's AndroidManifest.xml. Component names starting with '.' are relative to the plugin's package.

```json
{
    "android": {
        "activities": [
            {
                "name": ".MyPluginActivity",
                "theme": "@style/Theme.AppCompat.Light.NoActionBar",
                "exported": false,
                "configChanges": "orientation|screenSize"
            }
        ],
        "services": [
            {
                "name": ".BackgroundSyncService",
                "exported": false,
                "foregroundServiceType": "dataSync"
            }
        ],
        "receivers": [
            {
                "name": ".BootReceiver",
                "exported": true,
                "intent-filters": [
                    {
                        "action": "android.intent.action.BOOT_COMPLETED",
                        "category": "android.intent.category.DEFAULT"
                    }
                ]
            }
        ],
        "providers": [
            {
                "name": ".MyContentProvider",
                "authorities": "${applicationId}.myplugin.provider",
                "exported": false,
                "grantUriPermissions": true
            }
        ]
    }
}
```

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

### Configure Android Credentials via Environment Variables

Source: https://nativephp.com/docs/mobile/3/getting-started/deployment

Store signing credentials in the .env file to simplify command-line arguments.

```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 for Ad-Hoc Distribution

Source: https://nativephp.com/docs/mobile/3/getting-started/deployment

Command to package an application for distribution to specific registered devices.

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

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

### Specify Initialization Functions for Android and iOS

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

Configure native functions to be called once during app initialization for both Android and iOS platforms. This is useful for SDKs requiring early setup before bridge functions are available.

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

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

### Configure Composer Credentials for Premium Plugins

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

Set up your email and license key for accessing the private Composer repository of premium plugins.

```shell
composer config http-basic.plugins.nativephp.com your-email@example.com your-license-key
```

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

### Listen for Native Events on the Backend

Source: https://nativephp.com/docs/mobile/3/the-basics/events

Register a listener in your Laravel application to handle native events on the PHP side. This example shows how to process a `PhotoTaken` event and update an avatar via an API service.

```php
use App

class UpdateAvatar
{
    public function __construct(private APIService $api) {}
    
    public function handle(PhotoTaken $event): void
    {
        $imageData = base64_encode(
            file_get_contents($event->path)
        );
        
        $this->api->updateAvatar($imageData);
    }
}
```

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

### Configure Environment Variables

Source: https://nativephp.com/docs/mobile/3/getting-started/deployment

Store iOS credentials in a .env file to simplify build commands.

```env
APP_STORE_API_KEY_PATH=/path/to/api-key.p8
APP_STORE_API_KEY_ID=ABC123DEF
APP_STORE_API_ISSUER_ID=01234567-89ab-cdef-0123-456789abcdef
IOS_DISTRIBUTION_CERTIFICATE_PATH=/path/to/distribution.p12
IOS_DISTRIBUTION_CERTIFICATE_PASSWORD=certificatepassword
IOS_DISTRIBUTION_PROVISIONING_PROFILE_PATH=/path/to/profile.mobileprovision
IOS_TEAM_ID=ABC1234567
```

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

### Declare Android Features

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

Specify required hardware or software features for your plugin. These are added as <uses-feature> elements in AndroidManifest.xml. Setting 'required: false' allows installation on devices lacking the feature, but requires runtime checks.

```json
{
    "android": {
        "features": [
            {"name": "android.hardware.camera", "required": true},
            {"name": "android.hardware.camera.autofocus", "required": false},
            {"name": "android.hardware.bluetooth_le", "required": true}
        ]
    }
}
```

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

### Add NativePHP to Existing Laravel App

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

Integrate NativePHP into an existing Laravel application by requiring the package via Composer. After installation, run `php artisan native:jump` to prepare the app for mobile deployment.

```bash
composer require nativephp/mobile

php artisan native:jump
```

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

### Generate Boost Guidelines

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

Command to generate Boost guidelines for your NativePHP plugin, creating a blade view for documentation.

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

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

### Handle Token Generated Event

Source: https://nativephp.com/docs/mobile/3/concepts/push-notifications

Listen for the `TokenGenerated` event to capture the push notification token. This example demonstrates storing the token using an `APIService` within a Livewire component. Tokens can change, so it's common practice to request them during app bootup.

```php
use App\Services\APIService;
use Native\Mobile\Attributes\OnNative;
use Native\Mobile\Facades\PushNotifications;
use Native\Mobile\Events\PushNotification\TokenGenerated;

class PushNotifications extends Component
{
    #[OnNative(TokenGenerated::class)]
    public function storePushToken(APIService $api, string $token)
    {
        $api->storePushToken($token);
    }
}
```

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

### Configure Android build settings

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

Define build-time optimizations and settings within the android.build configuration array.

```php
'android' => [
    'build' => [
        'minify_enabled' => env('NATIVEPHP_ANDROID_MINIFY_ENABLED', false),
        'shrink_resources' => env('NATIVEPHP_ANDROID_SHRINK_RESOURCES', false),
        'obfuscate' => env('NATIVEPHP_ANDROID_OBFUSCATE', false),
        'debug_symbols' => env('NATIVEPHP_ANDROID_DEBUG_SYMBOLS', 'FULL'),
        'parallel_builds' => env('NATIVEPHP_ANDROID_PARALLEL_BUILDS', true),
        'incremental_builds' => env('NATIVEPHP_ANDROID_INCREMENTAL_BUILDS', true),
    ],
],
```

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

### View command help

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

Displays available arguments and options for a specific command to bypass interactive prompts.

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

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

### Generate Android Signing Credentials

Source: https://nativephp.com/docs/mobile/3/getting-started/deployment

Creates a JKS keystore and signing keys, automatically updating the .env file and .gitignore.

```bash
php artisan native:credentials android
```

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

### Skip Build Preparation

Source: https://nativephp.com/docs/mobile/3/getting-started/deployment

Performs an incremental build by skipping the preparation phase when native code has not changed.

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

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

### Rebuild Native Application

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

Rebuild the native application after upgrading to ensure all v3 project files are correctly generated.

```shell
php artisan native:install --force
php artisan native:run
```

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

### iOS Info.plist Configuration

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

Provide iOS permission usage descriptions, API keys, or configuration tokens as key-value pairs under `ios.info_plist`. These are merged into the app's `Info.plist`.

```json
{
    "ios": {
        "info_plist": {
            "NSCameraUsageDescription": "This app uses the camera for scanning",
            "NSMicrophoneUsageDescription": "This app records audio for transcription",
            "NSLocationWhenInUseUsageDescription": "This app needs your location",
            "MBXAccessToken": "${MAPBOX_ACCESS_TOKEN}"
        }
    }
}
```

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

### Initiate OAuth Flow with Browser Auth

Source: https://nativephp.com/docs/mobile/3/concepts/authentication

Use the `Native\Mobile\Facades\Browser::auth()` API to initiate the OAuth authentication flow. Ensure the redirect URL matches your scheme and the callback route in your app.

```php
Browser::auth('https://workos.com/my-company/auth?redirect=myapp://auth/handle')
```

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

### Configure App Store Connect API

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

Set API credentials in config/nativephp.php to enable direct IPA uploads via the native:package command.

```php
'app_store_connect' => [
    'api_key' => env('APP_STORE_API_KEY'),
    'api_key_id' => env('APP_STORE_API_KEY_ID'),
    'api_issuer_id' => env('APP_STORE_API_ISSUER_ID'),
    'app_name' => env('APP_STORE_APP_NAME'),
],
```

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

### Validate Provisioning Profiles

Source: https://nativephp.com/docs/mobile/3/getting-started/deployment

Command to check provisioning profile details such as entitlements and push notification support.

```bash
php artisan native:package ios \
  --validate-profile \
  --provisioning-profile-path=/path/to/profile.mobileprovision
```

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

### Using a NativePHP Plugin

Source: https://nativephp.com/docs/mobile/3/plugins

Demonstrates invoking native functionality via a facade and handling events dispatched from native code using the OnNative attribute.

```php
use Vendor\MyPlugin\Facades\MyPlugin;
 
// Call native functions
MyPlugin::doSomething();
 
// Listen for events
#[OnNative(MyPlugin\Events\SomethingHappened::class)]
public function handleResult($data)
{
    // Handle it
}
```

```php
use Vendor\MyPlugin\Facades\MyPlugin;

// Call native functions
MyPlugin::doSomething();

// Listen for events
#[OnNative(MyPlugin\Events\SomethingHappened::class)]
public function handleResult($data)
{
    // Handle it
}
```

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

### native:package

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

Packages your application for distribution with signing for either Android or iOS platforms.

```APIDOC
## native:package

### Description
Package your app for distribution with signing.

### Usage
`php artisan native:package {platform}`

### Arguments
- **platform** (string) - Required - Target platform: `android/a` or `ios/i`

### Options
- **--build-type** (string) - Optional - Build type: `release` or `bundle`
- **--output** (string) - Optional - Output directory for signed artifacts
- **--jump-by** (string) - Optional - Skip ahead in version numbering
- **--no-tty** (boolean) - Optional - Disable TTY mode for non-interactive environments

### Android Specific Options
- **--keystore** (string) - Path to Android keystore file
- **--keystore-password** (string) - Keystore password
- **--key-alias** (string) - Key alias for signing
- **--key-password** (string) - Key password
- **--fcm-key** (string) - FCM Server Key for push notifications
- **--google-service-key** (string) - Google Service Account Key file path
- **--upload-to-play-store** (boolean) - Upload to Play Store after packaging
- **--play-store-track** (string) - Play Store track: `internal`, `alpha`, `beta`, `production`
- **--test-push** (string) - Test Play Store upload with existing AAB file
- **--skip-prepare** (boolean) - Skip prepareAndroidBuild() to preserve existing project files

### iOS Specific Options
- **--export-method** (string) - Export method: `app-store`, `ad-hoc`, `enterprise`, `development`
- **--upload-to-app-store** (boolean) - Upload to App Store Connect after packaging
- **--test-upload** (boolean) - Test upload existing IPA
- **--validate-only** (boolean) - Only validate the archive without exporting
- **--validate-profile** (boolean) - Validate provisioning profile entitlements
- **--rebuild** (boolean) - Force rebuild by removing existing archive
- **--clean-caches** (boolean) - Clear Xcode and SPM caches before building
- **--api-key** (string) - Path to App Store Connect API key file (.p8)
- **--api-key-id** (string) - App Store Connect API key ID
- **--api-issuer-id** (string) - App Store Connect API issuer ID
- **--certificate-path** (string) - Path to distribution certificate (.p12/.cer)
- **--certificate-password** (string) - Certificate password
- **--provisioning-profile-path** (string) - Path to provisioning profile (.mobileprovision)
- **--team-id** (string) - Apple Developer Team ID
```

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

### Build Android App Bundle (AAB)

Source: https://nativephp.com/docs/mobile/3/getting-started/deployment

Creates a signed Android App Bundle required for Play Store distribution.

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

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

### Package Application for Distribution

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

Packages the application for the specified platform with signing. Requires platform argument (android/a or ios/i).

```shell
php artisan native:package {platform}
```

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

### Specify custom output directory

Source: https://nativephp.com/docs/mobile/3/getting-started/deployment

Directs the build artifact to a specific file system path instead of the default location.

```bash
php artisan native:package android \
  --build-type=bundle \
  --keystore=/path/to/my-app.keystore \
  --keystore-password=mykeystorepassword \
  --key-alias=my-app-key \
  --key-password=mykeypassword \
  --output=/path/to/custom/directory
```

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

### Dispatch Job with Helper Function

Source: https://nativephp.com/docs/mobile/3/concepts/queues

Alternatively, use the `dispatch()` helper function to dispatch a new instance of your job class.

```php
dispatch(new App\Jobs\ProcessUpload($file));
```
Tokens:
Raw