Bifrost

Overview: Why NativePHP Changes the Game for Laravel Developers For years, Laravel developers faced a steep wall when venturing into mobile development. You either had to learn a completely different language like Swift or Kotlin, or embrace the complexity of heavy frameworks like React Native or Flutter. NativePHP shatters this barrier by allowing you to use the PHP and Laravel skills you already possess to build truly native applications. This isn't just about wrapping a website in a container. NativePHP compiles PHP for iOS and Android, effectively treating the mobile device as its own server. It manages a local SQLite database and provides a bridge to native device APIs like biometrics, camera, and secure storage. By leveraging the Laravel ecosystem, you gain the ability to offer mobile solutions to your clients without outsourcing the work or switching your tech stack. It's about empowerment—transforming every web developer into a mobile developer overnight. Prerequisites: Setting Your Foundation Before you dive into building, you need a solid environment. While NativePHP handles much of the heavy lifting, you should have the following tools and concepts ready: * **PHP & Laravel Knowledge:** You should be comfortable with Laravel 10 or 11, including routes, controllers, and Inertia.js (or Livewire). * **Local Development Environment:** Laravel Herd is highly recommended for its speed and ease of use in managing local sites. * **Native Tools:** For Android, you will need Android Studio and an emulator. For iOS development, Xcode is mandatory (requiring a Mac). * **Node.js & NPM:** Essential for managing the JavaScript side of your Inertia or Livewire components. * **Bifrost Account:** To manage builds and deployments efficiently, especially if you want to avoid the headache of manual signing and App Store submissions. Key Libraries & Tools Building with NativePHP involves several specialized tools that work together to create the mobile experience: * **NativePHP Mobile:** The core framework that compiles PHP for mobile OSs and provides the bridge to native functionality. * **Bifrost:** A deployment and build service (similar to Laravel Forge but for mobile) that handles GitHub integration, signing credentials, and App Store/Play Store delivery. * **Edge (Element Description Generation Engine):** A specialized engine that allows you to use Blade to render actual native UI components, like top bars and navigation items, rather than just HTML. * **Secure Storage Facade:** A native PHP utility for storing sensitive data (like API tokens) in the device’s encrypted storage silo. * **Biometric API:** A library that triggers native FaceID or Fingerprint prompts and returns success/failure events to your application. Code Walkthrough: Installation and Biometric Integration Let's look at how to get a project running and implement a secure biometric login. 1. Initial Setup and Installation Start by creating a new Laravel project and installing the NativePHP components. If you are using a starter kit, the process is streamlined. ```bash Install the NativePHP mobile package ./native install Run the Android emulator with a watcher for hot module replacement (HMR) ./native run a -W ``` Using the `run` command with the `-W` flag is critical. It starts the Vite server, allowing you to see UI changes on your physical device or emulator in real-time without recompiling the entire binary. 2. Implementing Secure Storage In a mobile app, you shouldn't rely on standard sessions that expire. Instead, you store an API token securely on the device. NativePHP provides a facade for this. ```python // In your Auth Controller use Native\Laravel\Facades\SecureStorage; public function checkAuth() { // Check for an existing token $token = SecureStorage::get('api_token'); if (!$token) { return redirect()->route('login'); } return Inertia::render('Dashboard'); } ``` 3. Native Biometric Prompt To trigger a native biometric check, you use the JavaScript library provided by the framework. This creates a bridge between your Vue/React/Livewire frontend and the device hardware. ```javascript // Inside your Vue component script import { Biometric, BiometricEvents } from "@nativephp/mobile"; import { onMounted, onUnmounted } from "vue"; const promptForBio = async () => { // This tells the device to show the FaceID/Fingerprint prompt await Biometric.prompt("Verify your identity"); }; onMounted(() => { // Listen for the device to signal that biometrics are complete Biometric.on(BiometricEvents.COMPLETED, (payload) => { if (payload.success) { window.location.href = "/dashboard"; } }); }); onUnmounted(() => { // Always turn off listeners to prevent memory leaks or duplicate triggers Biometric.off(BiometricEvents.COMPLETED); }); ``` Syntax Notes and Conventions One notable pattern in NativePHP is the use of the "God Method": `nativephp_all()`. This is an internal function that handles the communication between the PHP engine and the native C-libraries on the device. While you will mostly interact with clean Facades like `SecureStorage`, knowing that this tunnel exists helps you understand the architecture. Another important convention is the separation of the **Mobile App** and the **API Backend**. In mobile development, your app is a client. You should treat your local development server as a remote entity. Using tools like ngrok to expose your local API to the mobile device is a standard practice that mimics how the app will behave once it is live in the App Store. Practical Examples: Real-World Use Cases NativePHP isn't just for hobby projects; it excels in several professional scenarios: 1. **Field Data Collection:** A Laravel app for utility workers can use the local SQLite database to store data offline in areas with poor connectivity. Once they return to a Wi-Fi zone, the app can sync the local data to the central Laravel server. 2. **Internal Enterprise Tools:** Companies needing secure, internal-only apps can deploy via Bifrost to private enterprise App Stores. The biometric features ensure that only authorized employees can open the app, even if the phone is unlocked. 3. **Real-Time Monitoring:** Apps that need to interact with Bluetooth hardware—such as medical sensors or industrial equipment—can use future NativePHP plugins to read data directly into a Laravel-managed interface. Tips & Gotchas: Avoiding Common Pitfalls * **The Unmount Rule:** In single-page applications (SPAs), always use `Biometric.off()` or equivalent event removal functions. If you don't, event listeners will persist across page navigations, potentially triggering actions like "Delete Account" when you simply meant to log in. * **Security First:** Never store production credentials (like your main database password) in your app's `.env` file. Anything in the mobile binary is technically accessible to a determined attacker. Always use API tokens with limited scopes. * **Asset Management:** Mobile apps can get bloated quickly. Use the `exclusions` array in your `config/nativephp.php` to remove unused vendor packages and large assets from the final build to keep your APK/IPA size small (ideally under 30MB for a standard Laravel app). * **Building for iOS on Windows:** You simply can't do it locally. If you are on a Windows machine, you must use a service like Bifrost to handle the iOS compilation and signing on a remote Mac server.