【v2対応】NativePHP Mobile + React で スマホアプリを作る

はじめに

NativePHP Mobile は、Laravel + PHP でネイティブモバイルアプリを開発できる画期的なフレームワークです。本記事では、NativePHP Mobile と React を使って Android アプリを開発する環境を構築する手順を紹介します。

2026年2月更新: NativePHP Mobile v3 がリリースされ、完全無料・オープンソースになりました！
v2 では有料ライセンスが必要でしたが、v3 からは誰でも無料で利用できます。
最新版は 公式ドキュメント v3 を参照してください。

本記事は NativePHP Mobile v2.6 時点の内容です。基本的な流れは v3 でも同様ですが、一部設定が異なる場合があります。

NativePHP Mobile とは

NativePHP Mobile は以下の特徴を持っています：

• PHP がデバイス上で動作: 静的コンパイルされた PHP ランタイムがアプリに組み込まれる
• Laravel ベース: 既存の Laravel スキルをそのまま活用可能
• サーバー不要: 完全にオフラインで動作
• ネイティブ API アクセス: カメラ、生体認証、プッシュ通知などにアクセス可能

必要な環境

1. 基本ツールのインストール（macOS）

# Homebrew がなければインストール
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Homebrew を最新に
brew update

# PHP 8.2 以上
brew install php

# Composer
brew install composer

# Node.js
brew install node

2. Java のインストール

Android ビルドには Java が必要です。

brew install openjdk

# PATH を通す
echo 'export PATH="/opt/homebrew/opt/openjdk/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

# 確認
java -version

3. Android SDK のインストール

Android Studio を使わずにコマンドラインでセットアップする方法です。

# Android Platform Tools と Command Line Tools をインストール
brew install --cask android-platform-tools
brew install --cask android-commandlinetools

4. Android SDK ツールのセットアップ

# 基本ツールをインストール
sdkmanager "emulator"
sdkmanager "platform-tools"
sdkmanager "platforms;android-34"
sdkmanager "build-tools;34.0.0"

5. エミュレータ用システムイメージのインストール

お使いの Mac の CPU に合わせて選択してください。

# Intel Mac の場合
sdkmanager "system-images;android-34;google_apis;x86_64"

# Apple Silicon (M1/M2/M3) の場合
sdkmanager "system-images;android-34;google_apis;arm64-v8a"

6. 環境変数の設定

~/.zshrc に以下を追加します。

# Android SDK の設定
export ANDROID_HOME="/opt/homebrew/share/android-commandlinetools"
export PATH="$ANDROID_HOME/emulator:$PATH"
export PATH="$ANDROID_HOME/platform-tools:$PATH"
export PATH="$ANDROID_HOME/cmdline-tools/latest/bin:$PATH"

設定を反映：

source ~/.zshrc

7. エミュレータの作成

# Intel Mac の場合
avdmanager create avd -n Pixel_6_Pro -k "system-images;android-34;google_apis;x86_64"

# Apple Silicon の場合
avdmanager create avd -n Pixel_6_Pro -k "system-images;android-34;google_apis;arm64-v8a"

Android Studio を使う場合
Android Studio の Device Manager から GUI でエミュレータを作成することもできます。その場合は ANDROID_HOME を $HOME/Library/Android/sdk に設定してください。

プロジェクトの作成

1. Laravel プロジェクトを作成

composer create-project laravel/laravel my-native-app
cd my-native-app

2. NativePHP Mobile をインストール

NativePHP は公式のプライベートリポジトリからインストールします。

# composer.json にリポジトリを追加
composer config repositories.nativephp composer https://nativephp.composer.sh

# NativePHP Mobile をインストール
composer require nativephp/mobile

v2 の場合（有料）: composer require 実行時に認証情報の入力を求められます。

購入後に届くライセンスメール

公式サイト で購入後、メールでライセンスキーが届きます。
Composer から認証を求められたら、以下のように入力してください：

• Username: 購入時に使用した メールアドレス
• Password: メールに記載された ライセンスキー（XXXX-XXXX-XXXX-XXXX 形式）

v3 の場合（無料）: 完全無料・オープンソースになったため、ライセンスキーは不要です。

3. NativePHP の初期設定

php artisan native:install

このコマンドで以下が行われます：

• config/nativephp.php の作成
• nativephp/ ディレクトリの作成（Android/iOS のネイティブコード）
• .env への設定追加

4. .env の設定

NATIVEPHP_APP_ID=com.example.myapp
NATIVEPHP_APP_VERSION=1.0.0
NATIVEPHP_APP_VERSION_CODE=1

開発時の Tips: NATIVEPHP_APP_VERSION=DEBUG に設定すると、キャッシュを使わず常に最新のコードが反映されます。

# 開発時は DEBUG 推奨
NATIVEPHP_APP_VERSION=DEBUG

React のセットアップ

1. 必要なパッケージをインストール

npm install react react-dom
npm install -D @vitejs/plugin-react

2. vite.config.js を編集

import { defineConfig } from 'vite';
import laravel from 'laravel-vite-plugin';
import react from '@vitejs/plugin-react';

export default defineConfig({
    plugins: [
        laravel({
            input: ['resources/css/app.css', 'resources/js/app.jsx'],
            refresh: true,
        }),
        react(),
    ],
});

3. resources/js/app.jsx を作成

import { createRoot } from 'react-dom/client';
import App from './components/App';

const container = document.getElementById('app');
if (container) {
    const root = createRoot(container);
    root.render(<App />);
}

4. resources/js/components/App.jsx を作成

import { useState } from 'react';

export default function App() {
    const [count, setCount] = useState(0);

    return (
        <div style={{
            display: 'flex',
            flexDirection: 'column',
            alignItems: 'center',
            justifyContent: 'center',
            minHeight: '100vh',
            fontFamily: 'sans-serif'
        }}>
            <h1>NativePHP + React</h1>
            <p>カウント: {count}</p>
            <div>
                <button onClick={() => setCount(count - 1)}>-1</button>
                <button onClick={() => setCount(count + 1)}>+1</button>
            </div>
        </div>
    );
}

5. resources/views/app.blade.php を作成

<!DOCTYPE html>
<html lang="{{ str_replace('_', '-', app()->getLocale()) }}">
<head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1, user-scalable=no">
    <meta name="csrf-token" content="{{ csrf_token() }}">
    <title>{{ config('app.name', 'NativePHP App') }}</title>

    @viteReactRefresh
    @vite(['resources/css/app.css', 'resources/js/app.jsx'])
</head>
<body>
    <div id="app"></div>
</body>
</html>

6. routes/web.php を編集

<?php

use Illuminate\Support\Facades\Route;

Route::get('/', function () {
    return view('app');
});

Bootstrap を追加する場合（オプション）

モバイルアプリらしい UI を作るために Bootstrap を追加できます。

npm install bootstrap react-bootstrap

resources/js/app.jsx で読み込み：

import 'bootstrap/dist/css/bootstrap.min.css';
import { createRoot } from 'react-dom/client';
import App from './components/App';

// ...

Android エミュレータで実行

1. アセットをビルド

npm run build

2. エミュレータの確認・起動

# 作成済みのエミュレータを確認
emulator -list-avds

# エミュレータを起動（バックグラウンドで）
emulator -avd Pixel_6_Pro &

3. NativePHP でアプリを実行

php artisan native:run

対話形式でプラットフォームを選択：

 ┌ Which platform would you like to run? ───────────────────────┐
 │ › ● Android                                                  │
 │   ○ iOS                                                      │
 └──────────────────────────────────────────────────────────────┘

Android を選択すると、エミュレータが起動していない場合は自動で選択画面が表示されます：

  Running NativePHP for Android

 Build log: /Users/noguchi/Desktop/native_php/nativephp/android-build.log

 No devices found. Attempting to launch an emulator...

 ┌ Select an emulator to launch ────────────────────────────────┐
 │ › ● Pixel_6_Pro_arm                                          │
 └──────────────────────────────────────────────────────────────┘

エミュレータを選択するとビルドが始まります：

  Waiting for emulator to boot ................................. 2s DONE
  Updating Android configuration ........................... 4.80ms DONE
  Copying Laravel source ....................................... 2s DONE
  Installing Composer dependencies ............................. 2s DONE
  Optimizing autoloader ........................................ 1s DONE
  Creating bundle archive ...................................... 2s DONE
  Bundle size ................................................ 26.76 MB
  Build type ..................................................... debug
  App version .................................................... DEBUG

Starting a Gradle Daemon (subsequent builds will be faster)

ビルドが完了すると、エミュレータにアプリがインストールされて自動的に起動します。

BUILD SUCCESSFUL in 12s
40 actionable tasks: 5 executed, 35 up-to-date
  App launched!

初回ビルドには時間がかかります（Gradle Daemon の起動含め数分〜10分程度）。2回目以降は差分ビルドで高速になります。

4. 直接指定して実行する場合

# プラットフォームを直接指定
php artisan native:run android

# または iOS
php artisan native:run ios

実機でのデバッグ（USB 接続）

エミュレータだけでなく、USB 接続した実機でもテストできます。

1. Android 端末の設定

1. 開発者向けオプションを有効化

   • 設定 → デバイス情報 → ビルド番号を 7回タップ

2. USB デバッグを有効化

   • 設定 → 開発者向けオプション → USB デバッグを ON

2. USB 接続と確認

# 接続されているデバイスを確認
adb devices

以下のように表示されれば OK：

List of devices attached
XXXXXXXX    device

初回接続時は端末側に「USB デバッグを許可しますか？」というダイアログが表示されます。許可をタップしてください。

3. 実機でアプリを実行

エミュレータと同様に実行：

php artisan native:run android

実機が接続されていれば、エミュレータではなく実機にインストールされます。

プロジェクト構造

my-native-app/
├── app/                    # Laravel アプリケーション
├── config/
│   └── nativephp.php       # NativePHP 設定
├── nativephp/
│   ├── android/            # Android ネイティブコード
│   └── ios/                # iOS ネイティブコード
├── resources/
│   ├── js/
│   │   ├── app.jsx         # React エントリーポイント
│   │   └── components/     # React コンポーネント
│   └── views/
│       └── app.blade.php   # HTML テンプレート
├── routes/
│   └── web.php             # ルーティング
├── composer.json
├── package.json
└── vite.config.js

config/nativephp.php の主要設定

return [
    // アプリバージョン
    'version' => env('NATIVEPHP_APP_VERSION', '1.0.0'),
    'version_code' => env('NATIVEPHP_APP_VERSION_CODE', 1),

    // アプリ ID（com.example.app 形式）
    'app_id' => env('NATIVEPHP_APP_ID'),

    // パーミッション設定
    'permissions' => [
        'camera' => false,
        'location' => false,
        'push_notifications' => false,
        // 必要に応じて true に変更
    ],

    // 画面の向き
    'orientation' => [
        'android' => [
            'portrait' => true,
            'landscape_left' => false,
            'landscape_right' => false,
        ],
    ],
];

ホットリロード（開発時）

開発中は Hot Reload を使って、アプリ全体を再コンパイルせずに変更を反映できます。

セットアップ手順

3つのターミナルを使用します：

# ターミナル 1: アプリを起動
php artisan native:run android

# ターミナル 2: Vite の HMR（Hot Module Replacement）を起動
npm run dev

# ターミナル 3: NativePHP のファイル監視を起動
php artisan native:watch android

vite.config.js の設定

HMR を有効にするため、vite.config.js に以下を追加します：

export default defineConfig({
    plugins: [
        // ...
    ],
    server: {
        hmr: {
            host: '127.0.0.1',
        },
    },
});

native:watch コマンドにより、Blade/Livewire ファイルや CSS/JS の変更が自動的にアプリに反映されます。

トラブルシューティング

エミュレータが見つからない

環境変数が正しく設定されているか確認してください。

# 環境変数を確認
echo $ANDROID_HOME

# Homebrew でインストールした場合
export ANDROID_HOME="/opt/homebrew/share/android-commandlinetools"

# Android Studio を使っている場合
export ANDROID_HOME="$HOME/Library/Android/sdk"

# PATH も設定
export PATH="$ANDROID_HOME/emulator:$PATH"
export PATH="$ANDROID_HOME/platform-tools:$PATH"

ライセンスの同意が必要

# ライセンスに同意
sdkmanager --licenses

すべて y で同意してください。

ビルドエラーが発生する

# Laravel のキャッシュをクリア
php artisan cache:clear
php artisan config:clear
php artisan view:clear

# フロントエンドを再ビルド
npm run build

# NativePHP を再インストール
php artisan native:install --force

Gradle エラー

nativephp/android ディレクトリで直接ビルドしてエラー詳細を確認：

cd nativephp/android
./gradlew clean
./gradlew assembleDebug --stacktrace

NATIVEPHP_APP_ID が設定されていない

.env ファイルに必ず設定してください：

NATIVEPHP_APP_ID=com.yourcompany.yourapp

NATIVEPHP_APP_ID は「ドメインを逆順にしてドット区切り」の形式で設定します。
例：example.com → com.example.myapp

まとめ

NativePHP Mobile を使えば、Laravel と React の知識だけでネイティブ Android アプリを開発できます。PHP がデバイス上で動作するため、サーバーなしでオフライン対応のアプリが作れるのが大きな魅力です。

次回は、ネイティブ API（カメラ、位置情報など）の使い方について解説する予定です。

参考リンク

• NativePHP 公式ドキュメント
• NativePHP を使って Laravel でスマホアプリを作成する - 環境構築の参考
• Laravel 公式ドキュメント
• React 公式ドキュメント