Download the PHP package sghimire/mobile-browser without Composer

Mobile Browser

Native in-app browsing for NativePHP Mobile apps, powered by android.webkit.WebView on Android and WKWebView on iOS — with a one-line escape hatch to hand a URL off to the device's external default browser instead, and a proper native OAuth flow for signing in with a third-party provider.

This package is a free, self-contained plugin. It ships its own Laravel facade, fluent builders, Laravel events, JS/TypeScript bindings, and the native Kotlin/Swift implementation — no paid plugin dependency.

Features

• Two modes per call: webview (full-screen in-app browser with a compact, modern header — smart back button, page title, and an overflow menu with Open in Chrome/Safari, Refresh, Copy Link, and Share — that follows the device's light/dark theme automatically) or external (hands the URL to the device's default browser app and leaves yours).
• OAuth sign-in via a dedicated auth() builder — presents the authorize URL in a secure, isolated system browser context (ASWebAuthenticationSession on iOS, Chrome Custom Tabs on Android) and captures the redirect for you, with no embedded-WebView login screen (which most providers, including Google, reject).
• Fluent, chainable builders in both PHP and JavaScript.
• Programmatically close an open in-app browser session or cancel an in-progress sign-in.
• Opened, Closed, and AuthCompleted Laravel events, or bind straight to Livewire with #[OnNative].
• Works from PHP (Blade/Livewire) and from JavaScript (Vue, React, Inertia, or plain JS).

Example App

Authenticator is a full example app built using this plugin

Requirements

• PHP ^8.2
• nativephp/mobile ^3.0
• livewire/livewire — only needed if you use the #[OnNative] attribute

Installation

Laravel's package auto-discovery registers BrowserServiceProvider for you. Then register the plugin with NativePHP:

This wires up the plugin's nativephp.json manifest (bridge functions, Android INTERNET permission) into your native build. Rebuild/reinstall the native shell afterwards (php artisan native:install or native:run) so it's picked up.

How It Works (Under the Hood)

Same two-phase pattern as every async call in this plugin family — a synchronous "start" acknowledgement, then the real result delivered later through two parallel channels.

1. Request out. Browser::open($url)->open() (PHP) and Browser.open(url) (JS) both reach the same bridge — JS via fetch('/_native/api/call', { method: 'MobileBrowser.Open', params }), PHP via nativephp_call('MobileBrowser.Open', json_encode($params)). The bridge router matches "MobileBrowser.Open" to BrowserFunctions.Open.
2. Immediate ack. The call returns right away confirming the request was accepted — not that the page has loaded (webview mode) or that the external browser actually opened.
3. Result comes back later, twice. In webview mode, once the page finishes its first load, the native side injects a native-event CustomEvent on document (what the JS On()/Off() helpers listen for) and makes a call back into Laravel that dispatches the real Opened event (what Event::listen() / #[OnNative] pick up). Closing the browser delivers Closed the same way. In external mode, Opened fires as soon as the OS confirms the hand-off succeeded; a failed hand-off (no browser available, bad URL) is returned as a synchronous bridge error instead.
4. Because results are asynchronous and delivered to PHP and JS independently, always drive your UI from the Opened / Closed events — never from the return value of open().
5. Browser::auth($authorizeUrl, $redirectUri)->auth() follows the identical two-phase pattern over MobileBrowser.Auth / BrowserFunctions.Auth: an immediate ack that the sign-in was presented, followed later by AuthCompleted (the callback URL arrived) or Closed (cancelled or failed).

In-app browser UI

The webview mode overlay uses a compact, modern header — the same shape as Instagram's or Chrome Custom Tabs' in-app browser, not a full custom chrome — and it's the same on both platforms:

• Back button — always smart: walks back through the page's own navigation history if there is any, otherwise closes the overlay. This matches the OS hardware-back/swipe-back gesture, which behaves the same way regardless of any setting below.
• Two-line title — the page's own <title> on top, updating live as the user navigates, with your ->title() override underneath as a smaller subtitle (hidden if you never set one).
• Overflow menu (⋮) — Open in Chrome (Android) / Open in Safari (iOS), Refresh, Copy Link, and Share — Share only appears if shareButton(true) (the default).
• System theme aware — header colors, text, icon tint, status bar contrast (Android), and the webview background all switch with the OS light/dark setting automatically. Nothing to configure.

showToolbar(false) hides this header entirely, leaving a bare webview (e.g. a kiosk-style page). showNavigationButtons(false) changes what a tap on the header's back button does — it stops walking page history and just closes the overlay instead; it has no effect on the hardware/gesture back, which always tries page history first either way.

There's no separate back/forward/reload bar anymore — reload moved into the overflow menu, and forward navigation was dropped in favor of this simpler, single-header layout.

PHP Usage

The Browser facade

open() on the builder returns bool — true once the request reached the native bridge, false if it couldn't be started (e.g. running outside the native shell, or the builder was already opened once).

If you never call ->open() explicitly, it fires automatically when the builder object is destructed. Calling ->open() yourself is recommended so you can check the return value.

Builder methods

Supported modes

webview, external (also available as PendingOpen::MODES). Defaults to webview if mode() / external() is never called.

Closing an in-app browser

Useful for dismissing an open webview session programmatically (e.g. from elsewhere in the UI once a task completes):

This fires Closed with reason: 'closed_by_app'. It has no effect on a URL opened with external(), since that leaves your app entirely. Browser::close() also cancels an in-progress auth() sign-in — see below.

OAuth sign-in with auth()

open() is deliberately not meant for logging a user into a third-party provider — most providers (Google included) detect and reject sign-in attempts from an embedded WebView ("Error 403: disallowed_useragent"), and even where it's not blocked outright, an app-controlled WebView can read the password field, which is exactly what OAuth exists to avoid. auth() runs the authorization-code flow in a proper isolated system browser context instead:

• iOS: ASWebAuthenticationSession — the platform API built for this, with optional Safari cookie sharing for SSO.
• Android: Chrome Custom Tabs launched from a dedicated redirect-handling activity — the same pattern used by AppAuth-Android.

The two arguments are Browser::auth(string $authorizeUrl, string $redirectUri):

• $authorizeUrl — the full provider authorize URL, built however you like (query string assembled by hand, a package like league/oauth2-client, etc.). It must itself already contain a redirect_uri parameter matching $redirectUri — that's what tells the provider where to send the browser back to; the second argument is what tells this plugin which incoming URL to treat as that callback and intercept.
• $redirectUri — must use the nativephp:// scheme, e.g. nativephp://127.0.0.1/auth/callback. Host and path are yours to choose freely (useful if you run more than one OAuth flow), but the scheme itself is fixed on both platforms: Android can only route a callback back into the app through a scheme registered in the compiled AndroidManifest at build time (there's no way to register one dynamically per PHP call), so every app using this plugin shares the one nativephp:// scheme rather than something derived per-app. Register exactly this redirect URI with your OAuth provider.

Builder methods

If you never call ->auth() explicitly, it fires automatically when the builder object is destructed, same as open().

Handling the result

$event->params already has both grant types covered: authorization-code flows return code/state as query parameters, implicit-grant flows return access_token/token_type/etc. in the URL fragment — both are parsed into the same flat array.

Cancel a sign-in in progress the same way you'd close a browser session:

Listening for results

Livewire: #[OnNative]

JavaScript Usage

Importing

This package doesn't publish a #nativephp import alias (that's reserved for NativePHP's first-party plugins). Import the file directly — either from the vendor path, or copy it into your own resources/js/ and import it from there:

Full TypeScript types (including the BrowserMode union) are included in browser.d.ts alongside it.

Basic open

Browser.open(url) returns a thenable builder — await it directly, or chain builder methods first:

Closing an in-app browser

OAuth sign-in

Browser.auth(authorizeUrl, redirectUri) runs the same native OAuth flow as the PHP auth() builder (see the PHP section above for the full explanation of why this exists instead of just using open(), and why redirectUri must use the nativephp:// scheme):

Listening for events

React example

JS API reference

await-ing (or .then-ing) a PendingOpen/PendingAuth sends the request to the native bridge exactly once — awaiting it twice is a no-op the second time.

Events reference

Opened

Dispatched once the page has loaded (webview mode) or the OS confirms the hand-off succeeded (external mode).

Closed

Dispatched when the in-app browser is dismissed, when an external hand-off fails, or when an auth() sign-in ends without completing.

AuthCompleted

Dispatched once the OAuth provider redirects back to redirectUri after auth().

• PHP classes: Sandip\Browser\Native\Events\Browser\Opened, Sandip\Browser\Native\Events\Browser\Closed, Sandip\Browser\Native\Events\Browser\AuthCompleted
• JS event name constants: Events.Browser.Opened, Events.Browser.Closed, Events.Browser.AuthCompleted

Platform notes

Both are configured automatically by nativephp.json — you don't need to edit native project files by hand.

OAuth implementation notes and known limitations

• Why not just use open() for sign-in? Providers routinely detect and block embedded WebView user agents for OAuth (Google returns Error 403: disallowed_useragent), and it defeats one of OAuth's own purposes — the app hosting the WebView could otherwise read the password field. auth() presents the login in a context the app can't inspect.
• ephemeral() on Android clears the app's shared CookieManager cookie jar before presenting the Custom Tab. Android's CookieManager is process-wide rather than scoped to one WebView/tab, so this is an app-wide clear, not a perfectly isolated private session the way iOS's prefersEphemeralWebBrowserSession is. Avoid triggering auth() while another unrelated webview-mode open() session needs to keep its cookies.
• Cancellation detection on Android has no direct signal from Custom Tabs (unlike iOS, which gets an explicit cancellation callback). This plugin detects it by noticing the redirect-handling activity was resumed again without a matching callback ever arriving — reliable for the normal case (user backs out of the tab), but calling Browser::close() cannot force the Custom Tab itself to visually disappear if it's already in the foreground; it only dismisses this plugin's own state and fires Closed.
• Process death mid-flow (Android killing the app while the Custom Tab is open, e.g. under memory pressure) drops the in-memory session state, so a redirect arriving after that point can't be correlated back to a Closed/AuthCompleted dispatch. Uncommon, but a known limitation shared with most Custom-Tabs-based implementations that don't persist flow state to disk.
• The nativephp:// scheme is shared plugin-wide, not per-app-generated, because Android intent-filters are compiled into the AndroidManifest at build time and can't be registered dynamically from a PHP call. Host and path in redirectUri are still yours to pick freely.

Testing

Outside of a compiled native shell, Browser::open($url)->open() and Browser::close() return false (there's no bridge to call) — this is expected and is exactly what the test suite asserts.

License

MIT