From cf223d5319a485c93688a690c66c1c533a244d64 Mon Sep 17 00:00:00 2001 From: Shane Rosenthal Date: Mon, 28 Apr 2025 22:25:20 -0400 Subject: [PATCH 1/7] First pass at docs --- resources/views/docs/index.blade.php | 2 - .../mobile/1/getting-started/configuration.md | 47 +++++++++- .../mobile/1/getting-started/development.md | 33 ++++++- .../mobile/1/getting-started/installation.md | 93 +++++++++++-------- .../mobile/1/getting-started/introduction.md | 2 +- .../docs/mobile/1/getting-started/status.md | 49 ++++++++-- .../views/docs/mobile/1/the-basics/dialogs.md | 18 ++-- .../views/docs/mobile/1/the-basics/system.md | 41 ++++---- 8 files changed, 206 insertions(+), 79 deletions(-) diff --git a/resources/views/docs/index.blade.php b/resources/views/docs/index.blade.php index d72c4ad5..7419f464 100644 --- a/resources/views/docs/index.blade.php +++ b/resources/views/docs/index.blade.php @@ -13,8 +13,6 @@ - - {{-- Table of contents --}}

diff --git a/resources/views/docs/mobile/1/getting-started/configuration.md b/resources/views/docs/mobile/1/getting-started/configuration.md index 71574c49..3741f999 100644 --- a/resources/views/docs/mobile/1/getting-started/configuration.md +++ b/resources/views/docs/mobile/1/getting-started/configuration.md @@ -3,4 +3,49 @@ title: Configuration order: 200 --- -# COMING SOON +## Overview + +NativePHP for Mobile is designed so that most configuration happens **inside your Laravel application**, without requiring you to manually open Xcode or Android Studio. + +After installation, NativePHP sets up the necessary native scaffolding, but your primary interaction remains inside Laravel itself. + +This page explains the key configuration points you can control directly through Laravel. + +## The `nativephp.php` Config File + +The nativephp.php config file is where you can configure the native project for your application. + +NativePHP uses sensible defaults and makes several assumptions based on default installations for tools required to build and run apps from your computer. + +You can override these defaults by editing the `nativephp.php` config file in your Laravel project or changing environment variables. + +```dotenv +NATIVEPHP_APP_VERSION +NATIVEPHP_APP_VERSION_CODE +NATIVEPHP_APP_ID +NATIVEPHP_DEEPLINK_SCHEME +NATIVEPHP_DEEPLINK_HOST +NATIVEPHP_APP_AUTHOR +NATIVEPHP_GRADLE_PATH +NATIVEPHP_ANDROID_SDK_LOCATION +``` + +## Cleanup `env` keys + +The `cleanup_env_keys` array in the config file allows you to specify keys that should be removed from the `.env` file before bundling. +This is useful for removing sensitive information like API keys or other secrets. + +## Cleanup `exclude_files` + +The `cleanup_exclude_files` array in the config file allows you to specify files and folders that should be removed before bundling. +This is useful for removing files like logs or other temporary files. + +## Permissions +In general, the app stores don't want apps to request permissions that they don't need. +To enable some permissions your app needs you simply need to change their values in the permissions section. + +```dotenv +push_notifications +biometric +nfc +``` diff --git a/resources/views/docs/mobile/1/getting-started/development.md b/resources/views/docs/mobile/1/getting-started/development.md index 5e20dba2..6cf3ef30 100644 --- a/resources/views/docs/mobile/1/getting-started/development.md +++ b/resources/views/docs/mobile/1/getting-started/development.md @@ -3,5 +3,36 @@ title: Development order: 300 --- -# COMING SOON + +## The `nativephp` Directory + +After running: + +```bash +php artisan native:install +``` + +you’ll see a new `nativephp` directory at the root of your Laravel project as well as a nativephp.php config file in your config folder in the Laravel root. + +This folder contains all the native project files that NativePHP generates for you. + +You should not need to manually open or edit any native project files under normal circumstances. +NativePHP handles the heavy lifting for you. + +## NATIVEPHP_APP_VERSION + +The NATIVEPHP_APP_VERSION environment variable controls your app's versioning behavior. + +When building for Android, NativePHP first copies the relevant Laravel files into a temporary directory, zips them, and embeds the archive into the Android project. When the app boots, it checks the embedded version against the previously installed version. + +If the versions match, the app uses the existing files without re-extracting the archive. + +If the versions differ — or if the version is set to ***DEBUG*** — the app updates itself by re-extracting the new bundle. + +This mechanism ensures developers can iterate quickly during development, while providing a faster, more stable experience for end users once an app is published. + +> Rule of Thumb: +> During development, keep NATIVEPHP_APP_VERSION set to DEBUG to always refresh the app. +> When preparing a new release, update it to a semantic version (e.g., 1.2.3) to enable versioned updates for your users. + diff --git a/resources/views/docs/mobile/1/getting-started/installation.md b/resources/views/docs/mobile/1/getting-started/installation.md index 919b3853..1014be9f 100644 --- a/resources/views/docs/mobile/1/getting-started/installation.md +++ b/resources/views/docs/mobile/1/getting-started/installation.md @@ -5,35 +5,51 @@ order: 100 ## Requirements -Right now, NativePHP for mobile only supports building iOS applications. Android is in the works already and coming soon! - -Apple's tooling for building iOS apps requires that you compile your applications using macOS. - 1. PHP 8.3+ 2. Laravel 10 or higher -3. An Apple Silicon Mac running macOS 12+ with Xcode 16+ -4. An active [Apple Developer account](https://developer.apple.com/) -5. [A NativePHP for iOS license](https://checkout.anystack.sh/nativephp-ios) -6. _Optional_ iOS device +3. [A NativePHP for mobile license](https://checkout.anystack.sh/nativephp-ios) +6. _Optional_ iOS/Android device -You don't _need_ a physical iOS device to compile your application and test it for iOS, as NativePHP for mobile supports -the iOS Simulator. However, we highly recommend that you test your application on a real device before submitting to the -App Store. +#### For iOS +1. An Apple Mac (ideally Silicon) running macOS 12+ with Xcode 16+ +2. An active [Apple Developer account](https://developer.apple.com/) +3. You can download Xcode from the Mac App Store. -You can download Xcode from the Mac App Store. +#### For Android +1. [Android Studio Giraffe (or later)](https://developer.android.com/studio) +2. The following environment variables set. +3. You should be able to successfully run `java -v` and `adb devices` from the terminal. -The most painless way to get PHP and Node up and running on your system is with -[Laravel Herd](https://herd.laravel.com). It's fast and free! +#### For macOS +```shell +export JAVA_HOME=$(/usr/libexec/java_home -v 17) +export ANDROID_SDK_ROOT=$HOME/Library/Android/sdk +export PATH=$PATH:$JAVA_HOME/bin:$ANDROID_HOME/emulator:$ANDROID_HOME/tools:$ANDROID_HOME/tools/bin:$ANDROID_HOME/platform-tools +``` -### Laravel +#### For Windows +```shell +set JAVA_HOME=C:\Program Files\Microsoft\jdk-17.0.8.7-hotspot +set ANDROID_SDK_ROOT=C:\Users\yourname\AppData\Local\Android\Sdk +set PATH=%PATH%;%JAVA_HOME%\bin;%ANDROID_SDK_ROOT%\platform-tools +``` + +> **Note** You cannot build iOS apps on Windows or Linux -NativePHP for mobile is built to work best with Laravel. You can install it into an existing Laravel application, or -[start a new one](https://laravel.com/docs/installation). +You don't _need_ a physical iOS/Android device to compile your application and test it for your app, as NativePHP for mobile supports +the iOS Simulator and Android emulators. However, we highly recommend that you test your application on a real device before submitting to the +App/Google Play Store. + +## Laravel + +NativePHP for mobile is built to work with Laravel. You can install it into an existing Laravel application, or +[start a new one](https://laravel.com/docs/installation). The most painless way to get PHP and Node up and running on your system is with +[Laravel Herd](https://herd.laravel.com). It's fast and free! ## Private package To make NativePHP for mobile a reality has taken a lot of work and will continue to require even more. For this reason, -it's not open source and you are not free to distribute or modify its source code. +it's not open source, and you are not free to distribute or modify its source code. Before you begin, you will need to purchase a license. Licenses can be obtained via [Anystack](https://checkout.anystack.sh/nativephp-ios). @@ -44,24 +60,29 @@ Once you have your license, you will need to add the following to your `composer "repositories": [ { "type": "composer", - "url": "https://nativephp-ios.composer.sh" + "url": "https://nativephp.composer.sh" } ], ``` -## Install NativePHP for iOS +## Install NativePHP for mobile ```shell -composer require nativephp/ios +composer require nativephp/mobile ``` -This package contains all the libraries, classes, commands, and interfaces that your application will need to work with -iOS. -If this is the first time you're installing the package, you will be prompted to authenticate. +If this is the first time you're installing the package, you will be prompted to authenticate. Your username is the email address you registered with Anystack. Your password is your license key. -Your username is the email address you registered with Anystack. +This package contains all the libraries, classes, commands, and interfaces that your application will need to work with +iOS and Android. -Your password is your license key. +Before running the `install` command it is important to set the following variables in your `.env`: + +```shell +NATIVEPHP_APP_ID=com.nativephp.yourapp +NATIVEPHP_APP_VERSION="DEBUG" +NATIVEPHP_APP_VERSION_CODE="1" +``` ## Run the NativePHP installer @@ -70,11 +91,7 @@ php artisan native:install ``` The NativePHP installer works similarly to NativePHP for desktop, taking care of setting up and configuring your Laravel -application to work with iOS. - -After you've run this command, you'll see a new `ios` folder in the root of your Laravel project. - -We'll come back to this later. +application to work with iOS and/or Android. ## Start your app @@ -87,16 +104,15 @@ Once you're ready: php artisan native:run ``` -This will start compiling your application and boot it in the iOS Simulator by default. +This will start compiling your application and boot it in whichever device you select. ### Running on a real device -If you want to run your app on a real iOS device, you need to make sure the device is in -[Developer Mode](https://developer.apple.com/documentation/xcode/enabling-developer-mode-on-a-device) and that it's -been added to your Apple Developer account as -[a registered device](https://developer.apple.com/account/resources/devices/list). +#### For iOS +If you want to run your app on a real mobile device, you need to make sure the device is in +[Developer Mode](https://developer.apple.com/documentation/xcode/enabling-developer-mode-on-a-device) and that it's been added to your Apple Developer account as [a registered device](https://developer.apple.com/account/resources/devices/list). -You will need to get the device's UDID. You can find this by connecting the device to your Mac and opening it in the +For iOS: You will need to get the device's UDID. You can find this by connecting the device to your Mac and opening it in the Finder. Click on model name at the top until the UDID appears, then right-click on it to copy it. Then you can simply run, replacing `{UDID}` with your device's UDID: @@ -107,4 +123,7 @@ php artisan native:run {UDID} Alternatively, you may open the `ios/NativePHP.xcodeproj` file in Xcode and run builds using Xcode's UI. +#### For Android +On Android you need [enable developer options](https://developer.android.com/studio/debug/dev-options#enable) and have USB debugging (ADB) enabled. + And that's it! You should now see your Laravel application running as a native app! 🎉 diff --git a/resources/views/docs/mobile/1/getting-started/introduction.md b/resources/views/docs/mobile/1/getting-started/introduction.md index 125a064d..8217636c 100644 --- a/resources/views/docs/mobile/1/getting-started/introduction.md +++ b/resources/views/docs/mobile/1/getting-started/introduction.md @@ -12,7 +12,7 @@ We've combined the statically compiling PHP as an embeddable C library with the native APIs of each support platform, unlocking the power and convenience of Laravel for building performant, native _mobile_ applications using PHP. -**It's never been this easy to build beautiful, local-first apps for iOS and Android (coming soon).** +**It's never been this easy to build beautiful, local-first apps for iOS and Android.** ## Old tools, new tricks diff --git a/resources/views/docs/mobile/1/getting-started/status.md b/resources/views/docs/mobile/1/getting-started/status.md index f0b5b520..04ed6b12 100644 --- a/resources/views/docs/mobile/1/getting-started/status.md +++ b/resources/views/docs/mobile/1/getting-started/status.md @@ -5,11 +5,48 @@ order: 099 ## Current Status -NativePHP for mobile is `beta` software. We believe it's already robust enough to build useful applications that can be -distributed to users, so we've made it available via an [Early Access Program](/ios). +NativePHP for mobile v1 is here. While we're still in the process of adding more and more +native API's and other features we believe it's robust enough to build useful applications that can be +distributed to users. -The `beta` phase gives us the opportunity to work with the community to build more features and iron out issues. +Presently, NativePHP for mobile offers the following "native" functionality: + +- Vibrate +- Show Toasts +- Show Alerts +- Share +- Camera +- Flashlight +- Biometric ID +- Push Notifications +- Deep Links +- NFC + +We're working on adding more and more features, including: + - Secure Storage + - Microphone access + - Location + - Bluetooth + - SMS (Android only) + - File picker + - Video camera access + - Background tasks + - Geofencing + - Native image picker + - Calendar access + - Local notifications, scheduled notifications + - Clipboard API + - Contacts access + - App badges + - OTA Updates + - App review prompt + - Proximity sensor + - Gyroscope + - Accelerometer + - Screen brightness + - Haptic feedback + - Network info access + - Battery status + - CPU information + - Ads -If you're in the Early Access Program, please be sure to share your findings by -[raising issues](https://github.com/nativephp/ios/issues/new/choose)/reporting bugs, and on the `#early-access` -[Discord](https://discord.gg/X62tWNStZK) channel. diff --git a/resources/views/docs/mobile/1/the-basics/dialogs.md b/resources/views/docs/mobile/1/the-basics/dialogs.md index 74de7725..db68e7c3 100644 --- a/resources/views/docs/mobile/1/the-basics/dialogs.md +++ b/resources/views/docs/mobile/1/the-basics/dialogs.md @@ -26,12 +26,14 @@ Dialog::share('Title', 'Description', 'URL'); You may open a native alert dialog by using the `Dialog::alert()` method. ```php -$buttons = [ - 'Ok', - 'Cancel' -]; - -Dialog::alert('Title', 'Message', $buttons, fn ($selected) => { - echo "You selected {$buttons[$selected]}"; -}); +Dialog::alert('Title', 'Message'); +``` + +### The Toast Dialog + +You may open a native toast dialog by using the `Dialog::toast()` method. There is not a toast dialog on iOS, +on iOS we will simply show an Alert Dialog with just an `OK` button. + +```php +Dialog::toast('Message'); ``` diff --git a/resources/views/docs/mobile/1/the-basics/system.md b/resources/views/docs/mobile/1/the-basics/system.md index 8dcef6bc..ac4eecc8 100644 --- a/resources/views/docs/mobile/1/the-basics/system.md +++ b/resources/views/docs/mobile/1/the-basics/system.md @@ -21,11 +21,22 @@ about whether a particular feature is specific to iOS or Android. Most of the system-related features are available through the `System` facade. +## Synchronous vs. Asynchronous Methods + +It is important to understand the difference between synchronous and asynchronous methods. Some methods +like `flashlight` and `vibrate` are synchronous, meaning that they will block the current thread until the +operation is complete. Other methods like `camera` and `biometric` are asynchronous, meaning that they +will return immediately and the operation will be performed in the background. When the operation is +complete, the method will `broadcast an event` to your frontend via an injected javascript event. + +In order to receive these events, you must register a listener for the event. + ```php use Native\Ios\Facades\System; ``` -## Camera +## Camera (Async) +Event: `native:\Native\Events\Camera` You may request the native camera interface to take a photograph by calling the `camera` method: @@ -33,23 +44,12 @@ You may request the native camera interface to take a photograph by calling the $imageData = System::camera() ``` -If the user takes a photograph, the function will return a Base64-encoded string of JPEG data. - -If they cancel or there was a problem, it will return an empty string. - -If your app hasn't been granted permission to use the camera, this function will return `false`. +When the user takes a photograph the event is fired with a payload array that contains one item: `photoPath` +which is a string containing the path to the photo. **Note: The first time your application asks to use the camera, the user will be prompted to grant permission. If they decline, triggering the camera API will silently fail.** -### Video - -**COMING SOON** - -## Microphone - -**COMING SOON** - ## Vibration You may vibrate the user's device by calling the `vibrate` method: @@ -58,11 +58,13 @@ You may vibrate the user's device by calling the `vibrate` method: System::vibrate() ``` +_Coming Soon_ Options: `duration` and `intensity` + ## Push Notifications -NativePHP makes it dead simple to enrol your user's device in push notifications from your app. +Currently, NativePHP uses [Firebase Cloud Messaging](https://firebase.google.com/docs/cloud-messaging) to send push notifications to your users. -Simply use the `enrolForPushNotifications` method to trigger enrolment. If this is the first time that your app tries +Simply use the `enrollForPushNotifications` method to trigger enrolment. If this is the first time that your app tries to enrol this device for push notifications, the user will be presented with a native alert, allowing them to opt-in. Then use the `getPushNotificationsToken` method to retrieve the token. If enrolment was unsuccessful for some reason, @@ -81,9 +83,6 @@ if ($token = System::getPushNotificationsToken()) { Once you have the token, you may use it from your server-based applications to trigger Push Notifications directly to your user's device. -Find out more about what's required to use Push Notifications in -[Apple's Developer docs](https://developer.apple.com/notifications/). - ## Accelerometer **COMING SOON** @@ -92,10 +91,6 @@ Find out more about what's required to use Push Notifications in **COMING SOON** -## NFC scanner - -**COMING SOON** - ## Wallet **COMING SOON** From cda319e78a45e8a8fc8802a6a3cb7c164bbfe0de Mon Sep 17 00:00:00 2001 From: Shane Rosenthal Date: Mon, 28 Apr 2025 22:29:55 -0400 Subject: [PATCH 2/7] Update v1 alert --- resources/views/components/alert-v1-announcement.blade.php | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/resources/views/components/alert-v1-announcement.blade.php b/resources/views/components/alert-v1-announcement.blade.php index 529bff35..9217478f 100644 --- a/resources/views/components/alert-v1-announcement.blade.php +++ b/resources/views/components/alert-v1-announcement.blade.php @@ -33,7 +33,7 @@ class="hidden size-5 shrink-0 dark:block"

{{-- Title --}} -

NativePHP for desktop has finally reached v1!

+

NativePHP for desktop and mobile have reached v1!

{{-- Dot 1 --}}
Date: Mon, 28 Apr 2025 23:12:06 -0400 Subject: [PATCH 3/7] cleanup and nfc/deeplink docs --- .../mobile/1/getting-started/configuration.md | 3 +- .../mobile/1/getting-started/installation.md | 1 + .../docs/mobile/1/the-basics/deep-links.md | 109 ++++++++++++++++++ 3 files changed, 112 insertions(+), 1 deletion(-) create mode 100644 resources/views/docs/mobile/1/the-basics/deep-links.md diff --git a/resources/views/docs/mobile/1/getting-started/configuration.md b/resources/views/docs/mobile/1/getting-started/configuration.md index 3741f999..c6cf39b2 100644 --- a/resources/views/docs/mobile/1/getting-started/configuration.md +++ b/resources/views/docs/mobile/1/getting-started/configuration.md @@ -45,7 +45,8 @@ In general, the app stores don't want apps to request permissions that they don' To enable some permissions your app needs you simply need to change their values in the permissions section. ```dotenv -push_notifications biometric +camera nfc +push_notifications ``` diff --git a/resources/views/docs/mobile/1/getting-started/installation.md b/resources/views/docs/mobile/1/getting-started/installation.md index 1014be9f..238e8e13 100644 --- a/resources/views/docs/mobile/1/getting-started/installation.md +++ b/resources/views/docs/mobile/1/getting-started/installation.md @@ -19,6 +19,7 @@ order: 100 1. [Android Studio Giraffe (or later)](https://developer.android.com/studio) 2. The following environment variables set. 3. You should be able to successfully run `java -v` and `adb devices` from the terminal. +4. **Windows only**: You must have [7zip](https://www.7-zip.org/) installed. #### For macOS ```shell diff --git a/resources/views/docs/mobile/1/the-basics/deep-links.md b/resources/views/docs/mobile/1/the-basics/deep-links.md new file mode 100644 index 00000000..17ad1814 --- /dev/null +++ b/resources/views/docs/mobile/1/the-basics/deep-links.md @@ -0,0 +1,109 @@ +--- +title: Deep, Universal, App Links and NFC +order: 900 +--- + +## Overview + +NativePHP for Mobile supports both **deep linking** and **web-based linking** into your mobile apps. + +There are two types of link integrations you can configure: + +- **Deep Links** (myapp://some/path) +- **Universal Links (iOS)** and **App Links (Android)** (https://yourdomain.com/some/path) + +Each method has its use case, and NativePHP allows you to configure and handle both easily. + +--- + +## Deep Links + +Deep links use a **custom URL scheme** to open your app. + +For example: + +``` +myapp://profile/123 +``` + + +When a user taps a deep link, the mobile operating system detects the custom scheme and opens your app directly. + +### Configuration + +To enable deep linking, you must define: + +- **Scheme**: The protocol (e.g., myapp) +- **Host**: An optional domain-like segment (e.g., open) + +These are configured in your .env: + +```dotenv +NATIVEPHP_DEEPLINK_SCHEME=myapp +NATIVEPHP_DEEPLINK_HOST=open +``` + +## Universal Links (iOS) and App Links (Android) + +Universal Links and App Links allow real HTTPS URLs to open your app instead of a web browser, if the app is installed. + +For example: +```dotenv +https://bifrost.tech/property/456 +``` + +When a user taps this link: + + - If your app is installed, it opens directly into the app. + - If not, it opens normally in the browser. + +This provides a seamless user experience without needing a custom scheme. + +### How It Works +1. You must prove to iOS and Android that you own the domain by hosting a special file: + - .well-known/apple-app-site-association (for iOS) + - .well-known/assetlinks.json (for Android) +2. The mobile OS reads these files to verify the link association. +3. Once verified, tapping a real URL will open your app instead of Safari or Chrome. + +NativePHP for Mobile handles all of this for you. + +### Configuration + +To enable Universal Links and App Links, you must define: + +- **Host**: The domain name (e.g., bifrost-tech.com) + +These are configured in your .env: + +```dotenv +NATIVEPHP_DEEPLINK_HOST=bifrost-tech.com +``` + +## Handling Universal/App Links + +Once you've configured your deep link settings, you can handle the link in your app. + +Simply setup a route in your web.php file and the deeplink will redirect to your route. + +```dotenv +https://bifrost-tech.com/profile/123 +``` + +```php +Route::get('/profile/{id}', function ($id) { + // Handle the deep link +}); +``` + +## NFC +NFC is a technology that allows you to read and write NFC tags. + +NativePHP handles NFC tag "bumping" just like a Universal/App Link. +You can use a tool like [NFC Tools](https://www.wakdev.com/en/) to test write NFC tags. + +Set the url to a Universal/App Link and the tag will be written to the NFC tag. +"Bumping" the tag will open the app. + + + From b820ceb01e31280e64f787146d0d01f6e879ca32 Mon Sep 17 00:00:00 2001 From: Shane Rosenthal Date: Mon, 28 Apr 2025 23:25:09 -0400 Subject: [PATCH 4/7] remove coming soon items --- .../views/docs/mobile/1/the-basics/system.md | 16 ---------------- 1 file changed, 16 deletions(-) diff --git a/resources/views/docs/mobile/1/the-basics/system.md b/resources/views/docs/mobile/1/the-basics/system.md index ac4eecc8..a4942ff1 100644 --- a/resources/views/docs/mobile/1/the-basics/system.md +++ b/resources/views/docs/mobile/1/the-basics/system.md @@ -83,22 +83,6 @@ if ($token = System::getPushNotificationsToken()) { Once you have the token, you may use it from your server-based applications to trigger Push Notifications directly to your user's device. -## Accelerometer - -**COMING SOON** - -## GPS - -**COMING SOON** - -## Wallet - -**COMING SOON** - -## Encryption / Decryption - -**COMING SOON** - Almost every non-trivial application will require some concept of secure data storage and retrieval. For example, if you want to generate and store an API key to access a third-party service on behalf of your user. From 543cf6774eecb7e798afac498419c37ae3016569 Mon Sep 17 00:00:00 2001 From: Shane Rosenthal Date: Wed, 30 Apr 2025 08:53:01 -0400 Subject: [PATCH 5/7] updates docs for v1 --- .../1/digging-deeper/push-notifications.md | 96 +++++++++++ .../mobile/1/getting-started/debugging.md | 6 - .../mobile/1/getting-started/development.md | 8 +- .../mobile/1/getting-started/env-files.md | 6 - .../mobile/1/getting-started/installation.md | 16 +- .../getting-started/{status.md => roadmap.md} | 2 +- .../docs/mobile/1/the-basics/app-lifecycle.md | 6 - .../docs/mobile/1/the-basics/deep-links.md | 12 +- .../views/docs/mobile/1/the-basics/dialogs.md | 2 +- .../mobile/1/the-basics/native-functions.md | 70 ++++++++ .../docs/mobile/1/the-basics/notifications.md | 30 ---- .../views/docs/mobile/1/the-basics/system.md | 156 ++++++++---------- 12 files changed, 252 insertions(+), 158 deletions(-) create mode 100644 resources/views/docs/mobile/1/digging-deeper/push-notifications.md delete mode 100644 resources/views/docs/mobile/1/getting-started/debugging.md delete mode 100644 resources/views/docs/mobile/1/getting-started/env-files.md rename resources/views/docs/mobile/1/getting-started/{status.md => roadmap.md} (92%) delete mode 100644 resources/views/docs/mobile/1/the-basics/app-lifecycle.md create mode 100644 resources/views/docs/mobile/1/the-basics/native-functions.md delete mode 100644 resources/views/docs/mobile/1/the-basics/notifications.md diff --git a/resources/views/docs/mobile/1/digging-deeper/push-notifications.md b/resources/views/docs/mobile/1/digging-deeper/push-notifications.md new file mode 100644 index 00000000..a1b47a3a --- /dev/null +++ b/resources/views/docs/mobile/1/digging-deeper/push-notifications.md @@ -0,0 +1,96 @@ +--- +title: Push Notifications +order: 400 +--- + + +## Overview + +NativePHP for Mobile uses [Firebase Cloud Messaging](https://firebase.google.com/docs/cloud-messaging) to send push notifications to your users. + +## Setting up your app + +Once you create a Firebase account and create a project you will be offered to download a `google-services.json` file. + +This file contains the configuration for your app and is used by the Firebase SDK to retrieve tokens for each device using your app. + +Simply drag this file into the root of your Laravel project, enable `push_notifications` in the [config](/docs/mobile/1/getting-started/configuration) it will be used automatically. + +You will see more instructions on how to configure your app in the Firebase documentation, you can ignore all of those, NativePHP handles all of that for you. + +## Receiving Push Tokens + +To receive push notifications, you must register a listener for the event. For example, +take a look at how easy it is to listen for a `TokenGenerated` event in Livewire: + +```php +use Livewire\Attributes\On; +use Livewire\Component; +use Native\Mobile\Facades\System; +use Native\Mobile\Events\PushNotification\TokenGenerated; + +class PushNotifications extends Component +{ + public function render() + { + return view('livewire.system.push-notifications'); + } + + #[On('native:' . TokenGenerated::class)] + public function handlePushNotifications(string $token) + { + // Do something with the token... + } +} +``` + +Because of the nature of mobile applications you need an api server to handle these tokens. You can use Laravel's built-in `Http` facade to +`POST` the token to your server, on the server side you need to associate the token with the "user" that owns the device. + +We **strongly** recommend using [Sanctum](https://laravel.com/docs/12.x/sanctum#main-content) to handle this for you. + +## The flow + +Your app authenticates users against your own api server, when users create an account or login the server validates and authenticates the user and passes back a Sanctum token. + +The token is stored in your apps `session` and is used on subsequent requests to the api server. + +When a push notification is received, the token is sent to your api server and the server stores it for the user who sent it. + +> Optionally, you can have a `HasMany` relationship between your users and devices, +> this allows you to associate a device with a user and then use the device's token +> to send push notifications to that users devices. + +## Sending Push Notifications + +Once you have the token, you may use it from your server-based applications to trigger Push Notifications directly to +your user's device. We use a package like [google/apiclient](https://github.com/googleapis/google-api-php-client) to send the notifications. + +This is the exact code used by the NativePHP Kitchen Sink App (available soon on all app stores and GitHub): + +```php +Route::group(['middleware' => 'auth:sanctum'], function () { + Route::post('send-push-notification', PushNotificationController::class)->name('send-push-notification'); +}); +``` + +```php +namespace App\Http\Controllers; + +use App\Jobs\SendPushNotification; +use Illuminate\Http\Request; + +class PushNotificationController extends Controller +{ + public function __invoke(Request $request) + { + $token = $request->get('token'); + + $request->user()->update([ + 'push_token' => $token + ]); + + SendPushNotification::dispatch($token)->delay(now()->addMinutes(1)); + } +} +``` diff --git a/resources/views/docs/mobile/1/getting-started/debugging.md b/resources/views/docs/mobile/1/getting-started/debugging.md deleted file mode 100644 index 3ba44b7f..00000000 --- a/resources/views/docs/mobile/1/getting-started/debugging.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -title: Debugging -order: 350 ---- - -# COMING SOON diff --git a/resources/views/docs/mobile/1/getting-started/development.md b/resources/views/docs/mobile/1/getting-started/development.md index 6cf3ef30..0097512c 100644 --- a/resources/views/docs/mobile/1/getting-started/development.md +++ b/resources/views/docs/mobile/1/getting-started/development.md @@ -6,13 +6,7 @@ order: 300 ## The `nativephp` Directory -After running: - -```bash -php artisan native:install -``` - -you’ll see a new `nativephp` directory at the root of your Laravel project as well as a nativephp.php config file in your config folder in the Laravel root. +After running: `php artisan native:install` you’ll see a new `nativephp` directory at the root of your Laravel project as well as a `nativephp.php` config file in your config folder in the Laravel root. This folder contains all the native project files that NativePHP generates for you. diff --git a/resources/views/docs/mobile/1/getting-started/env-files.md b/resources/views/docs/mobile/1/getting-started/env-files.md deleted file mode 100644 index 6c80ac8a..00000000 --- a/resources/views/docs/mobile/1/getting-started/env-files.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -title: Environment Files -order: 400 ---- - -# COMING SOON diff --git a/resources/views/docs/mobile/1/getting-started/installation.md b/resources/views/docs/mobile/1/getting-started/installation.md index 238e8e13..81cb6578 100644 --- a/resources/views/docs/mobile/1/getting-started/installation.md +++ b/resources/views/docs/mobile/1/getting-started/installation.md @@ -23,16 +23,18 @@ order: 100 #### For macOS ```shell -export JAVA_HOME=$(/usr/libexec/java_home -v 17) +export JAVA_HOME=$(/usr/libexec/java_home -v 17) // This isn't required if JAVA_HOME is already set in the Windows Env Variables export ANDROID_SDK_ROOT=$HOME/Library/Android/sdk export PATH=$PATH:$JAVA_HOME/bin:$ANDROID_HOME/emulator:$ANDROID_HOME/tools:$ANDROID_HOME/tools/bin:$ANDROID_HOME/platform-tools ``` #### For Windows ```shell -set JAVA_HOME=C:\Program Files\Microsoft\jdk-17.0.8.7-hotspot set ANDROID_SDK_ROOT=C:\Users\yourname\AppData\Local\Android\Sdk set PATH=%PATH%;%JAVA_HOME%\bin;%ANDROID_SDK_ROOT%\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 ``` > **Note** You cannot build iOS apps on Windows or Linux @@ -47,13 +49,14 @@ NativePHP for mobile is built to work with Laravel. You can install it into an e [start a new one](https://laravel.com/docs/installation). The most painless way to get PHP and Node up and running on your system is with [Laravel Herd](https://herd.laravel.com). It's fast and free! -## Private package + +## Install NativePHP for mobile To make NativePHP for mobile a reality has taken a lot of work and will continue to require even more. For this reason, it's not open source, and you are not free to distribute or modify its source code. Before you begin, you will need to purchase a license. -Licenses can be obtained via [Anystack](https://checkout.anystack.sh/nativephp-ios). +Licenses can be obtained via [Anystack](https://checkout.anystack.sh/nativephp). Once you have your license, you will need to add the following to your `composer.json`: @@ -66,8 +69,7 @@ Once you have your license, you will need to add the following to your `composer ], ``` -## Install NativePHP for mobile - +Then run: ```shell composer require nativephp/mobile ``` @@ -77,7 +79,7 @@ If this is the first time you're installing the package, you will be prompted to This package contains all the libraries, classes, commands, and interfaces that your application will need to work with iOS and Android. -Before running the `install` command it is important to set the following variables in your `.env`: +**Before** running the `install` command it is important to set the following variables in your `.env`: ```shell NATIVEPHP_APP_ID=com.nativephp.yourapp diff --git a/resources/views/docs/mobile/1/getting-started/status.md b/resources/views/docs/mobile/1/getting-started/roadmap.md similarity index 92% rename from resources/views/docs/mobile/1/getting-started/status.md rename to resources/views/docs/mobile/1/getting-started/roadmap.md index 04ed6b12..b3c00f6f 100644 --- a/resources/views/docs/mobile/1/getting-started/status.md +++ b/resources/views/docs/mobile/1/getting-started/roadmap.md @@ -22,7 +22,7 @@ Presently, NativePHP for mobile offers the following "native" functionality: - Deep Links - NFC -We're working on adding more and more features, including: +We're working on adding more and more features, including (in no particular order): - Secure Storage - Microphone access - Location diff --git a/resources/views/docs/mobile/1/the-basics/app-lifecycle.md b/resources/views/docs/mobile/1/the-basics/app-lifecycle.md deleted file mode 100644 index 84c20847..00000000 --- a/resources/views/docs/mobile/1/the-basics/app-lifecycle.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -title: Application Lifecycle -order: 1 ---- - -# COMING SOON diff --git a/resources/views/docs/mobile/1/the-basics/deep-links.md b/resources/views/docs/mobile/1/the-basics/deep-links.md index 17ad1814..7be701b6 100644 --- a/resources/views/docs/mobile/1/the-basics/deep-links.md +++ b/resources/views/docs/mobile/1/the-basics/deep-links.md @@ -10,7 +10,7 @@ NativePHP for Mobile supports both **deep linking** and **web-based linking** in There are two types of link integrations you can configure: - **Deep Links** (myapp://some/path) -- **Universal Links (iOS)** and **App Links (Android)** (https://yourdomain.com/some/path) +- **Universal Links (iOS)** and **App Links (Android)** (https://example.net/some/path) Each method has its use case, and NativePHP allows you to configure and handle both easily. @@ -49,7 +49,7 @@ Universal Links and App Links allow real HTTPS URLs to open your app instead of For example: ```dotenv -https://bifrost.tech/property/456 +https://example.net/property/456 ``` When a user taps this link: @@ -72,22 +72,22 @@ NativePHP for Mobile handles all of this for you. To enable Universal Links and App Links, you must define: -- **Host**: The domain name (e.g., bifrost-tech.com) +- **Host**: The domain name (e.g., example.net) These are configured in your .env: ```dotenv -NATIVEPHP_DEEPLINK_HOST=bifrost-tech.com +NATIVEPHP_DEEPLINK_HOST=example.net ``` ## Handling Universal/App Links Once you've configured your deep link settings, you can handle the link in your app. -Simply setup a route in your web.php file and the deeplink will redirect to your route. +Simply set up a route in your web.php file and the deeplink will redirect to your route. ```dotenv -https://bifrost-tech.com/profile/123 +https://example.net/profile/123 ``` ```php diff --git a/resources/views/docs/mobile/1/the-basics/dialogs.md b/resources/views/docs/mobile/1/the-basics/dialogs.md index db68e7c3..a7e35836 100644 --- a/resources/views/docs/mobile/1/the-basics/dialogs.md +++ b/resources/views/docs/mobile/1/the-basics/dialogs.md @@ -10,7 +10,7 @@ NativePHP allows you to trigger many native dialogs. Dialogs are created using the `Dialog` facade. ```php -use Native\Ios\Facades\Dialog; +use Native\Mobile\Facades\Dialog; ``` ### The Share Dialog diff --git a/resources/views/docs/mobile/1/the-basics/native-functions.md b/resources/views/docs/mobile/1/the-basics/native-functions.md new file mode 100644 index 00000000..00326253 --- /dev/null +++ b/resources/views/docs/mobile/1/the-basics/native-functions.md @@ -0,0 +1,70 @@ +--- +title: Native Functions +order: 1 +--- + +Nearly any basic Laravel app will work as a mobile app with NativePHP for mobile. However, what makes NativePHP +unique is that it allows you to call native functions from your PHP code. + +These functions are called from your PHP code using one of an ever-growing list of facades. + +Currently, there are two facades available: + +- `Native\Mobile\Facades\System` +- `Native\Mobile\Facades\Dialog` + +## System + +The `System` facade is used to call native functions that access system resources. + +For example, you may use the `System::camera()` method to request access to the device's camera. + + +## Synchronous vs. Asynchronous Methods + +It is important to understand the difference between synchronous and asynchronous methods. Some methods +like `flashlight` and `vibrate` are synchronous, meaning that they will block the current thread until the +operation is complete. + +Other methods like `camera` and `biometric` are asynchronous, meaning that they +will return immediately and the operation will be performed in the background. When the operation is +complete, the method will `broadcast an event` to your frontend via an injected javascript event as well +as a traditional [Laravel Event](https://laravel.com/docs/12.x/events#main-content) that you can listen for within your app. + +In order to receive these events, you must register a listener for the event. For example, +take a look at how easy it is to listen for a `PhotoTaken` event in Livewire: + +```php +use Livewire\Attributes\On; +use Livewire\Component; +use Native\Mobile\Facades\System; +use Native\Mobile\Events\Camera\PhotoTaken; + +class Camera extends Component +{ + public string $photoDataUrl = ''; + + public function camera() + { + System::camera(); + } + + #[On('native:' . PhotoTaken::class)] + public function handleCamera($path) + { + $data = base64_encode(file_get_contents($path)); + $mime = mime_content_type($path); + + $this->photoDataUrl = "data:$mime;base64,$data"; + } + + public function render() + { + return view('livewire.system.camera'); + } +} +``` + +All Livewire/front end events are prefixed with `native:` to avoid collisions with other events. +In the following pages we will highlight the available native functions, whether they are asynchronous or not +and which events they fire. diff --git a/resources/views/docs/mobile/1/the-basics/notifications.md b/resources/views/docs/mobile/1/the-basics/notifications.md deleted file mode 100644 index 57943da9..00000000 --- a/resources/views/docs/mobile/1/the-basics/notifications.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -title: Notifications -order: 500 ---- - -## Notifications - -NativePHP allows you to send system notifications using an elegant PHP API. These notifications are, unlike Laravel's -built-in notifications, actual device notifications displayed by the device's native notification UI. - -When used sparingly, notifications can be a great way to inform the user about events that are occurring in your -application and to bring their attention back to it, especially if further input from them is required. - -Notifications are sent using the `Notification` facade. - -```php -use Native\Ios\Facades\Notification; -``` - -### Sending Notifications - -**COMING SOON** - -You may send a notification using the `Notification` facade. - -```php -Notification::title('Hello from NativePHP') - ->message('This is a detail message coming from your Laravel app.') - ->send(); -``` diff --git a/resources/views/docs/mobile/1/the-basics/system.md b/resources/views/docs/mobile/1/the-basics/system.md index a4942ff1..cc3236d3 100644 --- a/resources/views/docs/mobile/1/the-basics/system.md +++ b/resources/views/docs/mobile/1/the-basics/system.md @@ -3,65 +3,77 @@ title: System order: 800 --- -## The System +## Native System -One of the main advantages of building a native application is having more direct access to system resources, such as -device sensors and APIs that aren't typically accessible inside a browser's sandbox. +NativePHP allows you to trigger many native system functions. -NativePHP makes it trivial to access these resources and APIs. +System functions are called using the `System` facade. -One of the main challenges - particularly when writing cross-platform apps - is that each operating system has -its own set of available APIs, along with their own idiosyncrasies. - -NativePHP smooths over as much of this as possible, to offer a simple and consistent set of interfaces regardless of -the platform on which your app is running. +```php +use Native\Mobile\Facades\System; +``` +--- -While some features are platform-specific, NativePHP gracefully handles this for you so that you don't have to think -about whether a particular feature is specific to iOS or Android. +# Synchronous Functions +--- -Most of the system-related features are available through the `System` facade. +### Vibration -## Synchronous vs. Asynchronous Methods +You may vibrate the user's device by calling the `vibrate` method: -It is important to understand the difference between synchronous and asynchronous methods. Some methods -like `flashlight` and `vibrate` are synchronous, meaning that they will block the current thread until the -operation is complete. Other methods like `camera` and `biometric` are asynchronous, meaning that they -will return immediately and the operation will be performed in the background. When the operation is -complete, the method will `broadcast an event` to your frontend via an injected javascript event. +```php +System::vibrate() +``` +--- +### Flashlight -In order to receive these events, you must register a listener for the event. +You may toggle the device flashlight (on/off) by calling the `flashlight` method: ```php -use Native\Ios\Facades\System; +System::flashlight() ``` +--- -## Camera (Async) -Event: `native:\Native\Events\Camera` - -You may request the native camera interface to take a photograph by calling the `camera` method: +# Asynchronous Functions +--- +### Camera ```php -$imageData = System::camera() +Front End Event: `native:Native\Mobile\Events\Camera\PhotoTaken` +Back End Event: `Native\Mobile\Events\Camera\PhotoTaken` ``` -When the user takes a photograph the event is fired with a payload array that contains one item: `photoPath` +You may request the native camera interface to take a photograph by calling the `System::camera()` method: + +When the user takes a photograph the event is fired with a payload array that contains one item: `path` which is a string containing the path to the photo. -**Note: The first time your application asks to use the camera, the user will be prompted to grant permission. If they -decline, triggering the camera API will silently fail.** +```php +use Native\Mobile\Events\Camera\PhotoTaken; -## Vibration +System::camera(); -You may vibrate the user's device by calling the `vibrate` method: +// Later... +#[On('native:' . PhotoTaken::class)] +public function handlePhotoTaken($path) +{ + $data = base64_encode(file_get_contents($path)); + $mime = mime_content_type($path); -```php -System::vibrate() + $this->photoDataUrl = "data:$mime;base64,$data"; +} ``` -_Coming Soon_ Options: `duration` and `intensity` +**Note: The first time your application asks to use the camera, the user will be prompted to grant permission. If they +decline, triggering the camera API will silently fail.** -## Push Notifications +--- +### Push Notifications +```php +Front End Event: `native:Native\Mobile\Events\PushNotification\TokenGenerated` +Back End Event: `Native\Mobile\Events\PushNotification\TokenGenerated` +``` Currently, NativePHP uses [Firebase Cloud Messaging](https://firebase.google.com/docs/cloud-messaging) to send push notifications to your users. Simply use the `enrollForPushNotifications` method to trigger enrolment. If this is the first time that your app tries @@ -71,65 +83,45 @@ Then use the `getPushNotificationsToken` method to retrieve the token. If enrolm this method will return `null`. ```php -System::enrolForPushNotifications(); +use Native\Mobile\Events\PushNotification\TokenGenerated; -// Later... +System::enrollForPushNotifications(); -if ($token = System::getPushNotificationsToken()) { +// Later... +#[On('native:' . TokenGenerated::class)] +public function handlePushNotifications(string $token) +{ // Do something with the token... } ``` - Once you have the token, you may use it from your server-based applications to trigger Push Notifications directly to your user's device. -Almost every non-trivial application will require some concept of secure data storage and retrieval. For example, if -you want to generate and store an API key to access a third-party service on behalf of your user. - -You shouldn't ship these sorts of secrets _with_ your app, but rather generate them or ask your user for them at -runtime. - -But when your app is running on a user's device, you have -[far less control and fewer guarantees](/docs/digging-deeper/security) over the safety of any secrets stored. - -On a traditional server-rendered application, this is a relatively simple problem to solve using server-side encryption -with keys which are hidden from end users. - -For this to work on the user's device, you need to be able to generate and store an encryption key securely. - -NativePHP takes care of the key generation and storage for you, all that's left for you to do is encrypt, store and -decrypt the secrets that you need to store on behalf of your user. - -NativePHP allows you to encrypt and decrypt data in your application easily: - -```php -if (System::canEncrypt()) { - $encrypted = System::encrypt('secret_key_a79hiunfw86...'); - - // $encrypted => 'djEwJo+Huv+aeBgUoav5nIJWRQ==' -} -``` - -You can then safely store the encrypted string in a database or the filesystem. +> Learn more about [what to do with push tokens here](/docs/mobile/1/digging-deeper/push-notifications). -When you need to get the original value, you can decrypt it: +--- +### Biometric ID ```php -if (System::canEncrypt()) { - $decrypted = System::decrypt('djEwJo+Huv+aeBgUoav5nIJWRQ=='); - - // $decrypted = 'secret_key_a79hiunfw86...' -} +Front End Event: `native:Native\Mobile\Events\Biometric\Completed` +Back End Event: `Native\Mobile\Events\Biometric\Completed` ``` -## Biometric ID - For devices that support some form of biometric identification, you can use this to protect and unlock various parts of your application. ```php -if (System::promptForBiometricID()) { - // Do your super secret activity here +use Native\Mobile\Events\Biometric\Completed; + +System::promptForBiometricID() + +// Later... +#[On('native:' . Completed::class)] +public function handleBiometricAuth(boolean $success) +{ + if ($success) { + // Do your super secret activity here + } } ``` @@ -140,15 +132,3 @@ data. is *someone* who has the capacity to unlock the device your app is installed on. It does not allow you to *identify* that user or prove that they are willingly taking this action.** -## Time Zones - -**COMING SOON** - -PHP and your Laravel application are configured to work with the time zone that the device reports it is currently -operating in. - -This means that, for the most part, any dates and times your show will already be in the appropriate time zone for the -user without having to ask your users to manually select their current time zone. - -Your app will also be responsive to changes in the system's time zone settings, e.g. in case the user moves between -time zones. From d9b550bd252d9bc5fef15f6c6a2a3ddf28d8782b Mon Sep 17 00:00:00 2001 From: Shane Rosenthal Date: Wed, 30 Apr 2025 14:59:41 -0400 Subject: [PATCH 6/7] Updates --- .../views/docs/mobile/1/digging-deeper/broadcasting.md | 6 ------ resources/views/docs/mobile/1/digging-deeper/databases.md | 4 ++-- resources/views/docs/mobile/1/digging-deeper/files.md | 6 ------ 3 files changed, 2 insertions(+), 14 deletions(-) delete mode 100644 resources/views/docs/mobile/1/digging-deeper/broadcasting.md delete mode 100644 resources/views/docs/mobile/1/digging-deeper/files.md diff --git a/resources/views/docs/mobile/1/digging-deeper/broadcasting.md b/resources/views/docs/mobile/1/digging-deeper/broadcasting.md deleted file mode 100644 index ef31c48f..00000000 --- a/resources/views/docs/mobile/1/digging-deeper/broadcasting.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -title: Broadcasting -order: 100 ---- - -# COMING SOON diff --git a/resources/views/docs/mobile/1/digging-deeper/databases.md b/resources/views/docs/mobile/1/digging-deeper/databases.md index 4ab55f7b..fdccaf8f 100644 --- a/resources/views/docs/mobile/1/digging-deeper/databases.md +++ b/resources/views/docs/mobile/1/digging-deeper/databases.md @@ -3,14 +3,14 @@ title: Databases order: 200 --- -# Working with Databases +## Working with Databases You'll almost certainly want your application to persist structured data. For this, NativePHP supports [SQLite](https://sqlite.org/), which works on both iOS and Android devices. You can interact with SQLite from PHP in whichever way you're used to. -### Configuration +## Configuration You do not need to do anything special to configure your application to use SQLite. NativePHP will automatically: - Switch to using SQLite when building your application. diff --git a/resources/views/docs/mobile/1/digging-deeper/files.md b/resources/views/docs/mobile/1/digging-deeper/files.md deleted file mode 100644 index 27e513a4..00000000 --- a/resources/views/docs/mobile/1/digging-deeper/files.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -title: Files -order: 300 ---- - -## COMING SOON From 1c0518ad56416b604aabadf64f2e5b9fc6057e0e Mon Sep 17 00:00:00 2001 From: Simon Hamp Date: Wed, 30 Apr 2025 20:42:15 +0100 Subject: [PATCH 7/7] Cleanup --- .../mobile/1/getting-started/installation.md | 27 +++++++------------ 1 file changed, 10 insertions(+), 17 deletions(-) diff --git a/resources/views/docs/mobile/1/getting-started/installation.md b/resources/views/docs/mobile/1/getting-started/installation.md index 7bacf96a..0ea3c11c 100644 --- a/resources/views/docs/mobile/1/getting-started/installation.md +++ b/resources/views/docs/mobile/1/getting-started/installation.md @@ -9,14 +9,14 @@ order: 100 2. Laravel 10 or higher 3. An Apple Silicon Mac running macOS 12+ with Xcode 16+ 4. An active [Apple Developer account](https://developer.apple.com/) -5. [A NativePHP for mobile license](https://checkout.anystack.sh/nativephp) +5. [A NativePHP for mobile license](https://checkout.anystack.sh/nativephp) 6. _Optional_ iOS device #### For iOS 1. An Apple Mac (ideally Silicon) running macOS 12+ with Xcode 16+ 2. An active [Apple Developer account](https://developer.apple.com/) -3. You can download Xcode from the Mac App Store. +3. You can download Xcode from the Mac App Store #### For Android 1. [Android Studio Giraffe (or later)](https://developer.android.com/studio) @@ -77,7 +77,8 @@ Then run: composer require nativephp/mobile ``` -If this is the first time you're installing the package, you will be prompted to authenticate. Your username is the email address you registered with Anystack. Your password is your license key. +If this is the first time you're installing the package, you will be prompted to authenticate. Your username is the +email address you registered with Anystack. Your password is your license key. This package contains all the libraries, classes, commands, and interfaces that your application will need to work with iOS and Android. @@ -110,26 +111,18 @@ Once you're ready: php artisan native:run ``` -This will start compiling your application and boot it in whichever device you select. +This will start compiling your application and boot it on whichever device you select. ### Running on a real device #### For iOS If you want to run your app on a real mobile device, you need to make sure the device is in -[Developer Mode](https://developer.apple.com/documentation/xcode/enabling-developer-mode-on-a-device) and that it's been added to your Apple Developer account as [a registered device](https://developer.apple.com/account/resources/devices/list). - -For iOS: You will need to get the device's UDID. You can find this by connecting the device to your Mac and opening it in the -Finder. Click on model name at the top until the UDID appears, then right-click on it to copy it. - -Then you can simply run, replacing `{UDID}` with your device's UDID: - -```shell -php artisan native:run -``` - -Alternatively, you may open the `ios/NativePHP.xcodeproj` file in Xcode and run builds using Xcode's UI. +[Developer Mode](https://developer.apple.com/documentation/xcode/enabling-developer-mode-on-a-device) +and that it's been added to your Apple Developer account as +[a registered device](https://developer.apple.com/account/resources/devices/list). #### For Android -On Android you need [enable developer options](https://developer.android.com/studio/debug/dev-options#enable) and have USB debugging (ADB) enabled. +On Android you need to [enable developer options](https://developer.android.com/studio/debug/dev-options#enable) +and have USB debugging (ADB) enabled. And that's it! You should now see your Laravel application running as a native app! 🎉