From da47eea9bb5a469cc605d71132ddb2f228b05553 Mon Sep 17 00:00:00 2001
From: Jonathan Danse <j.danse@prestaedit.com>
Date: Tue, 6 Oct 2026 08:19:34 +0200
Subject: [PATCH] Document Android image_format (WebP) for Mobile 4.6

---
 .../docs/mobile/4/the-basics/app-icon.md      |  3 ++
 .../mobile/4/the-basics/splash-screens.md     | 42 ++++++++++++++++++-
 2 files changed, 44 insertions(+), 1 deletion(-)

diff --git a/resources/views/docs/mobile/4/the-basics/app-icon.md b/resources/views/docs/mobile/4/the-basics/app-icon.md
index 5b1bfdbbb..b15a4c3f2 100644
--- a/resources/views/docs/mobile/4/the-basics/app-icon.md
+++ b/resources/views/docs/mobile/4/the-basics/app-icon.md
@@ -18,6 +18,9 @@ Place a single high-resolution icon file at: `public/icon.png`.
 This image will be automatically resized for all Android densities and used as the base iOS app icon.
 You must have the GD extension installed in your development machine's PHP environment for this to work.
 
+On Android, the resized icons can be written as WebP instead of PNG to reduce your app's size. See
+[Android Image Format](splash-screens#android-image-format).
+
 <aside>
 
 If you do not provide a custom app icon, a default one will be used.
diff --git a/resources/views/docs/mobile/4/the-basics/splash-screens.md b/resources/views/docs/mobile/4/the-basics/splash-screens.md
index 1c803e4e4..d45554ef2 100644
--- a/resources/views/docs/mobile/4/the-basics/splash-screens.md
+++ b/resources/views/docs/mobile/4/the-basics/splash-screens.md
@@ -13,6 +13,46 @@ Place the relevant files in the locations specified:
 - `public/splash-dark.png` - for the Dark Mode splash screen
 
 ### Requirements
-- Format: PNG
+- Format: PNG (WebP is also accepted on Android, see below)
 - Minimum Size/Ratio: 1080 × 1920 pixels
 - GD PHP extension must be enabled, ensure it has enough memory (~2GB should be enough) 
+
+## Android Image Format
+
+<x-docs.version-badge since="4.6" />
+
+When building for Android, NativePHP resizes your splash screens (and [app icon](app-icon)) into a bitmap for every
+screen density. By default these are written as PNG files.
+
+Full-screen splash images are large, and multiplied across five densities and two themes they can add tens of
+megabytes to your app bundle. Google Play Console flags this under "Optimize your app's images".
+
+To ship smaller files, set the `image_format` option under the `android` key in `config/nativephp.php` to `webp`:
+
+```php
+'android' => [
+    'image_format' => env('NATIVEPHP_ANDROID_IMAGE_FORMAT', 'png'),
+],
+```
+
+```dotenv
+NATIVEPHP_ANDROID_IMAGE_FORMAT=webp
+```
+
+- `png` - Default. Compressed PNG files.
+- `webp` - Lossless WebP files. Same visual output, usually 80-90% smaller than PNG.
+
+When switching formats, the files from the previous format are removed on the next build, so you won't get
+duplicate resource errors.
+
+You may also supply `public/splash.webp` and `public/splash-dark.webp` as sources for Android. When both a `.webp`
+and a `.png` exist, the `.webp` is used.
+
+<aside>
+
+WebP output requires your PHP GD extension to be compiled with WebP support. If it isn't, NativePHP falls back to
+PNG output instead of failing the build. You can check with `php -r "var_dump(function_exists('imagewebp'));"`.
+
+iOS always uses the PNG files, so keep `public/splash.png` and `public/splash-dark.png` if you build for iOS.
+
+</aside>