Configuration Reference

NativePHP Mobile is configured through the config/nativephp.php file. This page documents all available configuration options.

Publishing Configuration

The configuration file is published during installation, but you can republish it anytime:

php artisan vendor:publish --tag=nativephp-config

App Settings

Version

version

string

default:"1.0.0"

The human-readable version of your app (e.g., “1.0.0”, “2.1.3”). This is used as the versionName in Android builds and may be displayed in the app or console.Environment Variable: NATIVEPHP_APP_VERSION

'version' => env('NATIVEPHP_APP_VERSION', '1.0.0'),

Version Code

version_code

int

default:"1"

The internal numeric version code used for Play Store builds. This must increase with every release. Used as versionCode in Android builds and required for publishing updates.Environment Variable: NATIVEPHP_APP_VERSION_CODE

'version_code' => env('NATIVEPHP_APP_VERSION_CODE', 1),

Always increment version_code when releasing updates to the Play Store, even if the version string stays the same.

App ID

app_id

string

required

The unique identifier for your application. Written in reverse domain format (e.g., com.nativephp.app). This is used by both Android and iOS to uniquely identify your app.Environment Variable: NATIVEPHP_APP_ID

'app_id' => env('NATIVEPHP_APP_ID'),

Choose your app ID carefully - it cannot be changed after publishing to app stores.

Deep Linking

deeplink_scheme

string

Custom URL scheme for opening your app (e.g., myapp://some/path). This allows other apps and websites to deep link into your app.Environment Variable: NATIVEPHP_DEEPLINK_SCHEME

'deeplink_scheme' => env('NATIVEPHP_DEEPLINK_SCHEME'),

deeplink_host

string

Domain name for verified HTTPS links and NFC tags (e.g., example.com). This allows URLs like https://example.com/path to open your app when tapped from NFC tags or browsers.Environment Variable: NATIVEPHP_DEEPLINK_HOST

'deeplink_host' => env('NATIVEPHP_DEEPLINK_HOST'),

Start URL

start_url

string

default:"/"

The initial path to load when the app starts. Should be a path relative to your app root (e.g., /dashboard, /onboarding).Environment Variable: NATIVEPHP_START_URL

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

iOS Settings

Development Team

development_team

string

Your Apple Developer Team ID for code signing iOS apps. This is automatically detected from your installed certificates, but can be overridden here. Find your Team ID in your Apple Developer account under Membership details.Environment Variable: NATIVEPHP_DEVELOPMENT_TEAM

'development_team' => env('NATIVEPHP_DEVELOPMENT_TEAM'),

iPad Support

ipad

bool

default:"false"

Enable or disable iPad support for your iOS app. When enabled, your app will support iPad devices and all iPad orientations as required by Apple’s App Store guidelines. When disabled, your app will be iPhone-only.

'ipad' => false,

Once an app is deployed to the App Store with iPad support, you cannot revoke this action.

Android Settings

android.gradle_jdk_path

string

Path to the JDK installation to use for Gradle builds.Environment Variable: NATIVEPHP_GRADLE_PATH

android.android_sdk_path

string

Path to your Android SDK installation.Environment Variable: NATIVEPHP_ANDROID_SDK_LOCATION

android.emulator_path

string

Path to the Android emulator binary.Environment Variable: ANDROID_EMULATOR

android.7zip-location

string

default:"C:\\\\Program Files\\\\7-Zip\\\\7z.exe"

Path to 7-Zip executable (Windows only).Environment Variable: NATIVEPHP_7ZIP_LOCATION

Status Bar Style

android.status_bar_style

string

default:"auto"

Controls the color of status bar and navigation bar icons.Options:

auto - Auto-detect from system theme (recommended)
light - Light/white icons
dark - Dark icons

Environment Variable: NATIVEPHP_ANDROID_STATUS_BAR_STYLE

'android' => [
    'status_bar_style' => env('NATIVEPHP_ANDROID_STATUS_BAR_STYLE', 'auto'),
],

Build Configuration

Android build optimization settings:

android.build.minify_enabled

bool

default:"false"

Enable R8/ProGuard minification to reduce APK size.Environment Variable: NATIVEPHP_ANDROID_MINIFY_ENABLED

android.build.shrink_resources

bool

default:"false"

Remove unused resources from the APK.Environment Variable: NATIVEPHP_ANDROID_SHRINK_RESOURCES

android.build.obfuscate

bool

default:"false"

Obfuscate code to make reverse engineering harder.Environment Variable: NATIVEPHP_ANDROID_OBFUSCATE

android.build.debug_symbols

string

default:"FULL"

Debug symbol configuration. Options: FULL, LINE_TABLES_ONLY, NONE.Environment Variable: NATIVEPHP_ANDROID_DEBUG_SYMBOLS

android.build.generate_mapping_files

bool

default:"false"

Generate ProGuard mapping files for crash report deobfuscation.Environment Variable: NATIVEPHP_ANDROID_MAPPING_FILES

android.build.parallel_builds

bool

default:"true"

Enable parallel Gradle builds for faster compilation.Environment Variable: NATIVEPHP_ANDROID_PARALLEL_BUILDS

android.build.incremental_builds

bool

default:"true"

Enable incremental builds to speed up subsequent builds.Environment Variable: NATIVEPHP_ANDROID_INCREMENTAL_BUILDS

Device Orientation

Configure which orientations your app supports on different devices:

iPhone Orientation

'orientation' => [
    'iphone' => [
        'portrait' => true,
        'upside_down' => false,
        'landscape_left' => false,
        'landscape_right' => false,
    ],
],

orientation.iphone.portrait

bool

default:"true"

Support portrait mode (home button at bottom)

orientation.iphone.upside_down

bool

default:"false"

Support upside-down portrait (home button at top)

orientation.iphone.landscape_left

bool

default:"false"

Support landscape with home button on left

orientation.iphone.landscape_right

bool

default:"false"

Support landscape with home button on right

Android Orientation

'orientation' => [
    'android' => [
        'portrait' => true,
        'upside_down' => false,
        'landscape_left' => false,
        'landscape_right' => false,
    ],
],

For iPad, all orientations are automatically supported when ipad is enabled, as required by Apple’s guidelines.

At least one orientation must be enabled, or the build will fail.

Security

Environment Key Cleanup

cleanup_env_keys

array

Environment variable keys to remove from .env during app bundling. This prevents secrets or development credentials from being leaked in the bundled app. Wildcards are supported.

'cleanup_env_keys' => [
    'AWS_*',
    'GITHUB_*',
    'DO_SPACES_*',
    '*_SECRET',
    'DB_PASSWORD',
    'DB_USERNAME',
],

File Exclusion

cleanup_exclude_files

array

Files and folders to remove before the final bundle is built. Use glob/wildcard patterns to skip unnecessary assets like logs, sessions, or temp data.

'cleanup_exclude_files' => [
    'storage/framework/sessions',
    'storage/framework/cache',
    'storage/framework/testing',
    'storage/logs/laravel.log',
],

Development Server

Configuration for the NativePHP development server that enables hot reloading:

server.http_port

int

default:"3000"

HTTP server port for serving the app.Environment Variable: NATIVEPHP_HTTP_PORT

server.ws_port

int

default:"8081"

WebSocket server port for hot reload communication.Environment Variable: NATIVEPHP_WS_PORT

server.service_name

string

default:"NativePHP Server"

Service name advertised on the network via mDNS.Environment Variable: NATIVEPHP_SERVICE_NAME

server.service_type

string

default:"_http._tcp"

Service type for mDNS advertisement.

server.public_path

string

default:"public"

Public directory to serve (relative to Laravel root).Environment Variable: NATIVEPHP_PUBLIC_PATH

server.build_path

string

default:"storage/app/native-build"

Build output directory where the ZIP will be created.Environment Variable: NATIVEPHP_BUILD_PATH

server.open_browser

bool

default:"true"

Automatically open browser with QR code when server starts.Environment Variable: NATIVEPHP_OPEN_BROWSER

server.watch_paths

array

Directories to watch for changes during development.

'server' => [
    'watch_paths' => [
        'app',
        'resources',
        'routes',
        'public/build',
    ],
],

server.watch_extensions

array

File extensions to watch for changes.

'server' => [
    'watch_extensions' => ['php', 'blade.php', 'js', 'css', 'ts', 'vue', 'json'],
],

Hot Reload

Configuration for hot reload functionality:

hot_reload.watch_paths

array

Directories to monitor for file changes.

'hot_reload' => [
    'watch_paths' => [
        'app',
        'resources',
        'routes',
        'config',
        'public',
    ],
],

hot_reload.exclude_patterns

array

Regex patterns for paths to exclude from watching.

'hot_reload' => [
    'exclude_patterns' => [
        '\.git',
        'storage',
        'tests',
        'nativephp',
        'credentials',
        'node_modules',
        '\.swp',
        '\.tmp',
        '~',
        '\.log',
    ],
],

App Store Connect

Configuration for uploading apps to App Store Connect:

app_store_connect.api_key

string

App Store Connect API key (store in .env).Environment Variable: APP_STORE_API_KEY

app_store_connect.api_key_id

string

App Store Connect API Key ID.Environment Variable: APP_STORE_API_KEY_ID

app_store_connect.api_issuer_id

string

App Store Connect API Issuer ID.Environment Variable: APP_STORE_API_ISSUER_ID

app_store_connect.app_name

string

Your app name in App Store Connect.Environment Variable: APP_STORE_APP_NAME

'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'),
],

Store all App Store Connect credentials in your .env file, not in the config file.

Permissions

Enable or disable specific native features and define permission request messages:

permissions

array

Array of permission keys mapped to boolean or string values.

true - Enable permission with default message
false - Disable permission
string - Enable with custom iOS permission message

'permissions' => [
    'camera' => 'We need camera access to scan QR codes for login.',
    'location' => 'We use your location to show nearby stores.',
    'microphone' => true,  // Uses default message
    'notifications' => true,
],

On iOS, custom permission messages are shown when requesting access. Android interprets any string value as true but doesn’t display custom messages.

Available permission keys:

camera
location
microphone
notifications
photo_library
contacts
calendar
reminders
bluetooth
motion
speech_recognition
face_id
nfc

Run php artisan native:install --force after changing permissions to update the native project files.

Example Configuration

Here’s a complete example configuration for a production app:

return [
    'version' => '2.1.0',
    'version_code' => 21,
    'app_id' => 'com.mycompany.myapp',
    
    'deeplink_scheme' => 'myapp',
    'deeplink_host' => 'myapp.com',
    'start_url' => '/dashboard',
    
    'development_team' => 'ABC123XYZ',
    'ipad' => true,
    
    'android' => [
        'status_bar_style' => 'auto',
        'build' => [
            'minify_enabled' => true,
            'shrink_resources' => true,
            'obfuscate' => false,
            'debug_symbols' => 'LINE_TABLES_ONLY',
        ],
    ],
    
    'orientation' => [
        'iphone' => [
            'portrait' => true,
            'upside_down' => false,
            'landscape_left' => true,
            'landscape_right' => true,
        ],
        'android' => [
            'portrait' => true,
            'upside_down' => false,
            'landscape_left' => true,
            'landscape_right' => true,
        ],
    ],
    
    'permissions' => [
        'camera' => 'Required for scanning QR codes and taking photos',
        'location' => 'Used to show nearby locations',
        'notifications' => 'Get notified about important updates',
    ],
    
    'cleanup_env_keys' => [
        'AWS_*',
        '*_SECRET',
        'DB_PASSWORD',
    ],
];

Next Steps

Architecture

Understand how NativePHP Mobile works

Native APIs

Explore available native APIs

Permissions

Learn about requesting permissions

Building Apps

Build your app for production

Getting Started

Core Concepts

Native Features

UI Components

Building & Deployment

Advanced

Publishing Configuration

App Settings

Version

Version Code

App ID

Deep Linking

Start URL

iOS Settings

Development Team

iPad Support

Android Settings

Status Bar Style

Build Configuration

Device Orientation

iPhone Orientation

Android Orientation

Security

Environment Key Cleanup

File Exclusion

Development Server

Hot Reload

App Store Connect

Permissions

Example Configuration

Next Steps

Architecture

Native APIs

Permissions

Building Apps

Build docs developers (and LLMs) love

Getting Started

Core Concepts

Native Features

UI Components

Building & Deployment

Advanced

​Publishing Configuration

​App Settings

​Version

​Version Code

​App ID

​Deep Linking

​Start URL

​iOS Settings

​Development Team

​iPad Support

​Android Settings

​Status Bar Style

​Build Configuration

​Device Orientation

​iPhone Orientation

​Android Orientation

​Security

​Environment Key Cleanup

​File Exclusion

​Development Server

​Hot Reload

​App Store Connect

​Permissions

​Example Configuration

​Next Steps

Architecture

Native APIs

Permissions

Building Apps

Build docs developers (and LLMs) love

Publishing Configuration

App Settings

Version

Version Code

App ID

Deep Linking

Start URL

iOS Settings

Development Team

iPad Support

Android Settings

Status Bar Style

Build Configuration

Device Orientation

iPhone Orientation

Android Orientation

Security

Environment Key Cleanup

File Exclusion

Development Server

Hot Reload

App Store Connect

Permissions

Example Configuration

Next Steps