Skip to main content

​
Before you begin

Make sure you have a Laravel application ready. NativePHP Mobile requires:
  • PHP 8.3 or higher
  • Laravel 10.x, 11.x, or 12.x
  • Composer installed
If you don’t have a Laravel app yet, create one with: composer create-project laravel/laravel my-mobile-app

​
Installation steps

1

Install the package

Install NativePHP Mobile via Composer:
composer require nativephp/mobile
This will add the package to your Laravel application and register the service provider automatically.
2

Run the install command

Run the installation command to set up your mobile platforms:
php artisan native:install
iOS development is only available on macOS due to Xcode requirements.

​
What this command does

The native:install command performs several important tasks:
  1. Prompts for your app bundle ID - Creates a unique identifier like com.yourname.myapp
  2. Publishes configuration files - Adds config/nativephp.php to your project
  3. Creates the nativephp directory - Sets up nativephp/android and/or nativephp/ios with native project files
  4. Downloads PHP binaries - Embeds PHP runtime for your target platforms
  5. Copies CLI wrapper - Installs the native binary for convenient commands
The nativephp directory contains build artifacts and should not be committed to version control. It’s automatically ignored via .gitignore.
3

Configure your app ID

During installation, you’ll be prompted to set your app bundle ID. This uniquely identifies your app on the App Store and Google Play.The installer generates a suggestion like com.username.appname, but you should customize it:
What should your app bundle ID be?
com.yourcompany.myapp
This sets NATIVEPHP_APP_ID in your .env file:
.env
NATIVEPHP_APP_ID=com.yourcompany.myapp
Bundle IDs use reverse domain notation and must be unique. Choose carefully as changing it later requires updating app store listings.
4

Publish configuration (optional)

The config file is published automatically, but you can republish it anytime:
php artisan vendor:publish --tag=nativephp-mobile-config
This creates config/nativephp.php where you can customize:
  • App version and version code
  • Deep link schemes
  • Start URL
  • Development server ports
  • Permissions
  • Device orientation support
  • Platform-specific settings

​
Platform-specific setup

​
iOS development requirements

iOS development requires macOS and Xcode:
1

Install Xcode

Download and install Xcode from the Mac App Store (free).After installation, open Xcode at least once to complete setup and accept the license agreement.
2

Install command line tools

xcode-select --install
3

Set up iOS Simulator

Open Xcode and go to Xcode > Settings > Platforms to download iOS Simulator runtimes for your target iOS versions.
4

Configure development team (optional)

For running on physical devices, you’ll need an Apple Developer account:
  1. Sign up at developer.apple.com
  2. Find your Team ID in Membership section
  3. Add to your .env:
.env
NATIVEPHP_DEVELOPMENT_TEAM=ABC123XYZ
The free Apple Developer tier allows testing on your own devices. Paid membership ($99/year) is required for App Store distribution.

​
Install command options

The native:install command supports several options: 
php artisan native:install [platform] [options]

​
Arguments

  • platform - Specify android, ios, or both (interactive prompt if omitted)

​
Options

  • --force or -F - Overwrite existing native project files
  • --with-icu - Include ICU support for Android (adds ~30MB, enables internationalization)
  • --without-icu - Exclude ICU support (default, smaller app size)
  • --skip-php - Skip downloading PHP binaries (for offline development)

​
Examples

# Install both platforms, overwriting existing files
php artisan native:install both --force

# Install Android with ICU support for internationalization
php artisan native:install android --with-icu

# Install iOS without downloading PHP again
php artisan native:install ios --skip-php

​
Verify installation

Check that everything is installed correctly: 
php artisan native:version
This displays the NativePHP Mobile version and confirms the package is working.

​
Configuration file overview

The config/nativephp.php file contains all mobile app settings: 
return [
    // App version displayed to users (e.g., "1.0.0")
    'version' => env('NATIVEPHP_APP_VERSION', '1.0.0'),
    
    // Internal version code (must increment with each release)
    'version_code' => env('NATIVEPHP_APP_VERSION_CODE', 1),
    
    // Unique app identifier
    'app_id' => env('NATIVEPHP_APP_ID'),
    
    // URL to open when app launches
    'start_url' => env('NATIVEPHP_START_URL', '/'),
    
    // Deep linking configuration
    'deeplink_scheme' => env('NATIVEPHP_DEEPLINK_SCHEME'),
    'deeplink_host' => env('NATIVEPHP_DEEPLINK_HOST'),
    
    // Platform-specific settings
    'android' => [
        'status_bar_style' => 'auto', // 'auto', 'light', or 'dark'
    ],
    
    // Device permissions
    'permissions' => [
        // 'camera' => 'We need camera access to scan QR codes',
        // 'location' => true,
    ],
    
    // iPad support (iOS only)
    'ipad' => false,
    
    // Orientation support
    'orientation' => [
        'iphone' => [
            'portrait' => true,
            'landscape_left' => false,
            'landscape_right' => false,
        ],
        'android' => [
            'portrait' => true,
            'landscape_left' => false,
            'landscape_right' => false,
        ],
    ],
];

​
Troubleshooting

NativePHP Mobile does not support Android development in WSL (Windows Subsystem for Linux).Solution: Run commands from Windows CMD or PowerShell instead of WSL.
iOS development requires macOS hardware due to Xcode and Apple’s licensing restrictions.Solution: Use a Mac or Mac mini for iOS development, or focus on Android only.
If PHP binary downloads fail due to network issues:Solution: Retry the install command. For persistent issues, check your internet connection and firewall settings.
Gradle may fail if JDK is not configured correctly.Solution: Ensure JDK 17+ is installed and set JAVA_HOME environment variable:
export JAVA_HOME=/path/to/jdk-17

​
Next steps

Quickstart tutorial

Build your first mobile app in under 5 minutes

CLI commands

Learn about the available NativePHP commands

Configuration

Explore all configuration options

Native features

Start using device features in your app

Build docs developers (and LLMs) love

Get started for freeTalk to us