unloc/nativephp-enhanced-splash

Jump-free Android system splash and vector splash support on iOS

1.0.0 2026-08-11 12:22 UTC

Requires

• php: ^8.2
• nativephp/mobile: ^4.0

Requires (Dev)

• pestphp/pest: ^5.0

MIT

• David Beentjes

Published on Packagist.org on 2026-08-11 12:23 UTC

README

Take control of your app's launch screen: no visible jump on Android, and a polished iOS launch screen generated from your app icon — no design work required.

Why "enhanced"

Android shows two splashes, and you only control one of them. Since Android 12 the system draws its own splash on every cold start — your launcher icon on a flat background — and it cannot be turned off. Only after that does NativePHP's own overlay fade in your splash.png. The system half is hardcoded white or black, so unless your splash art happens to be black too, users see a cut in the middle of your app opening.

This plugin fixes it two ways, and you pick:

• Give the system splash the same background as your splash image, so the two phases read as one continuous screen.
• Or drop the second phase entirely with android.mode = 'icon': the system splash is held on screen until your app is ready to draw, so there is one splash instead of two.

iOS launch screens usually mean commissioning artwork. Every device size, light and dark. With ios.mode = 'icon' you don't design anything: the plugin takes the app icon you already have, masks it to the iOS squircle, centers it on the background color you choose, and uses that for both of iOS's launch phases. It looks deliberate, and it takes one config line.

And if you do have artwork, public/splash.svg is used as a true vector launch image on iOS — one file, sharp on every device, instead of a folder of PNG variants.

Installation

composer require unloc/nativephp-enhanced-splash

# Only needed once per app, before its first plugin registration.
php artisan vendor:publish --tag=nativephp-plugins-provider

php artisan native:plugin:register unloc/nativephp-enhanced-splash
php artisan native:plugin:list

Then rebuild — native code only compiles in at build time:

php artisan native:run ios      # or: android

Alongside other splash plugins

Only run one. This plugin edits MainActivity.kt by exact-string match, as every splash plugin for NativePHP does — including s2br/nativephp-mobile-splashscreen, which anchors on the same two lines. Hook order between plugins is undefined, so with both registered the second to run finds source the first has already rewritten. This plugin then reports MainActivity.kt does not match the expected source and leaves the splash untouched rather than applying half of it — but the other plugin makes no such promise.

Configuration

Set the .env keys, or publish the config to edit it directly:

php artisan vendor:publish --tag=enhanced-splash-config

Key	.env	Values
ios.mode	ENHANCED_SPLASH_IOS_MODE	image (default), icon
ios.background	ENHANCED_SPLASH_IOS_BACKGROUND	#RRGGBB / #RRGGBBAA (default #FFFFFF)
ios.background_dark	ENHANCED_SPLASH_IOS_BACKGROUND_DARK	#RRGGBB / #RRGGBBAA (default #000000)
ios.icon_size	ENHANCED_SPLASH_IOS_ICON_SIZE	points (default 160)
ios.icon_rounded	ENHANCED_SPLASH_IOS_ICON_ROUNDED	bool (default true)
ios.icon_shadow	ENHANCED_SPLASH_IOS_ICON_SHADOW	bool (default false)
android.mode	ENHANCED_SPLASH_ANDROID_MODE	image (default), icon
android.background	ENHANCED_SPLASH_ANDROID_BACKGROUND	#RRGGBB / #RRGGBBAA (default #000000)
android.background_dark	ENHANCED_SPLASH_ANDROID_BACKGROUND_DARK	#RRGGBB / #RRGGBBAA (default #000000)

Colors are authored in CSS channel order throughout; the alpha byte is converted to each platform's own ordering at build time.

# starts a comment in .env, so quote hex values there:

ENHANCED_SPLASH_ANDROID_MODE=icon
ENHANCED_SPLASH_ANDROID_BACKGROUND="#0F172A"
ENHANCED_SPLASH_ANDROID_BACKGROUND_DARK="#020617"

Defaults match NativePHP's own behavior, so installing the plugin changes nothing until you configure it.

Android modes

icon: just one native splash instead of two

The system splash is held on screen until your app is ready, and the overlay never draws. Your launcher icon on background, then straight into your app. No second phase, nothing to time.

This mode ignores splash.png — the system splash draws your launcher icon, not your artwork. Pick it when your splash is a logo on a flat color anyway, and image when the artwork matters.

image: keep the default splash image, but influence the default splash color

Your splash.png still fills the screen. background and background_dark repaint everything around and before it — the system splash, the app window, and the overlay your image fades into. This will make the transitions less jarring if your app and splash.png use different background colors.

One thing to know: this color is also the app window's background afterwards, so it shows through any frame your UI hasn't painted yet. Keep it in the same family as your app's own surface color.

iOS modes

icon: a launch screen without a designer

Set ios.mode = 'icon' and the plugin builds the launch screen from AppIcon.appiconset: your icon, masked to the iOS squircle so it matches the home screen, centered on background / background_dark. Both of iOS's launch phases get the same image, so there is no flicker between them.

Tuning:

• icon_size — how large the icon is drawn, in points. The default 160 matches what Android shows.
• icon_rounded — turn off for artwork that is already shaped, or a logo that shouldn't be clipped.
• icon_shadow — a soft shadow to lift the icon off the background. Off by default.

If no app icon is present, the launch screen is NativePHP's own.

image: added SVG (vector) support

Drop public/splash.svg (and optionally public/splash-dark.svg) in place and it becomes the launch image, kept as a vector so it's sharp at every size. Without an SVG, the PNG variants are used as usual.

Note that splash.svg applies to image mode only — icon mode always draws the app icon.

Uninstall

composer remove unloc/nativephp-enhanced-splash

php artisan native:install

native:install regenerates the native project from NativePHP's own sources, clearing everything the plugin changed.

You don't need this to change settings — edit the config and rebuild. Every build starts by undoing the previous one, so switching modes or colors is just another native:run.

License

MIT. See LICENSE.