NativePHP Mobile 4.7: rotation fixes and an upgrade checklist

NativePHP Mobile 4.7.0 shipped on 29 October 2026. Its release notes cover a lot of ground, but three fixes deserve particular attention if your app supports landscape: an Android startup crash, Android backgrounds that stopped short of the screen edges, and stale safe-area values in the iOS root webview. This article is pinned to the 4.7.0 release, the latest stable release when checked on that date.

There is an important distinction: 4.7.0 did not introduce the PHP orientation API. OrientationChanged, System::orientation(), System::isPortrait(), and System::isLandscape() shipped in 4.6.0 on 2 October 2026. The latest release makes several surrounding behaviors more reliable.

Beyond rotation, the 4.7.0 changelog includes removing Composer's auth.json from bundled apps, checking PHP binary downloads against signed manifest checksums, enabling Gradle caches, and skipping build steps whose inputs have not changed. Review the complete release against your build pipeline and plugin set. Those changes are useful reasons to evaluate the upgrade even for portrait-only apps.

#What changed when the screen rotates

On Android, a rotation or appearance change could arrive before the embedded PHP runtime had loaded. Dispatching that event then reached a native function that was not available yet. PR 525 guards that early dispatch. PHP can read the current orientation when it starts, instead of the app crashing while trying to notify it too soon.

The Android background fix addresses a different problem. In landscape, the areas beside the camera cutout and navigation controls could retain the app theme's color even when the screen had its own bg-* color. PR 528 extends that screen background behind those areas, including the relevant dark-mode color. Check both ordinary screens and tabbed layouts when upgrading.

On iOS, the root webview could keep the --inset-* values calculated when the page loaded. Rotating the phone changed the actual safe area, but those inline CSS values stayed stale until navigation. PR 624 re-injects the insets when the view geometry changes. Its title still says “WIP,” but the change is merged and present in the 4.7.0 tagged implementation. That is evidence of inclusion, not a promise that every layout or external-display configuration is covered.

#Use the window orientation API deliberately

NativePHP reports the app window's orientation, with two values: portrait and landscape. It does not expose a four-direction physical orientation reading through this API. That matters on tablets and in multi-window modes, where the window shape and the position of the device can differ. The tagged System implementation documents that distinction.

For a direct read in PHP:

use Native\Mobile\Facades\System;

$orientation = System::orientation();
$showSidePanel = System::isLandscape();

For an existing native component, import the event and attribute, then add a typed state property and handler:

use Native\Mobile\Attributes\On;
use Native\Mobile\Events\System\OrientationChanged;

// Inside your NativeComponent class:
public string $orientation = 'portrait';

#[On(OrientationChanged::class)]
public function rotated(string $orientation): void
{
    $this->orientation = $orientation;
}

Initialize that property from System::orientation() in the component's existing mount() method, so an app opened in landscape starts correctly. This adapts the pattern in the official event source. The event also supports app-wide Laravel listeners.

Use responsive width rules for ordinary layout changes. Reserve PHP orientation state for behavior that needs the distinction, such as showing a different set of controls. A narrow landscape window can still be too small for a wide side panel.

#Enable the orientations you actually support

The event documentation specifies that orientation changes require the app to allow more than one orientation. In config/nativephp.php, merge the appropriate settings into the existing configuration:

'orientation' => [
    'iphone' => [
        'portrait' => true,
        'upside_down' => false,
        'landscape_left' => true,
        'landscape_right' => true,
    ],
    'android' => [
        'portrait' => true,
        'upside_down' => false,
        'landscape_left' => true,
        'landscape_right' => true,
    ],
],

These settings feed the native build's platform configuration. Changing a PHP file without rebuilding is insufficient. The 4.7.0 configuration also treats iPad support separately; review it before assuming the iPhone settings describe your tablet build.

#Verify the upgrade in the packaged app

Begin by recording the installed version:

composer show nativephp/mobile

Review the dependency changes and follow NativePHP's upgrade process in a working branch. Rebuild the native shell, then install a build with a new build number. The tagged configuration explains why: outside the DEBUG app version, extraction depends on the app version and build number. Reusing both can leave an installed app running an older PHP bundle.

Use the same small acceptance matrix on iOS and Android:

1. Cold-launch in portrait and landscape. On Android, also rotate immediately after launch several times to exercise the timing window.
2. Rotate on the first screen, navigate, then rotate again. Check controls, scroll position, entered text, and any open keyboard.
3. Use a screen with a conspicuous background color. Inspect the camera and navigation edges in both themes.
4. On an iOS webview screen, inspect content near each safe-area edge before and after rotation, without navigating to force a refresh.
5. Where supported, resize a tablet window. Record screenshots, OS version, device model, app build, and NativePHP version.

A browser preview can help with layout work, but the off-device orientation query returns portrait when no native bridge is available. It cannot establish that native rotation handling works.

#Connect verification to error reporting

Rotation bugs illustrate why NativePHP error tracking needs more than one test. A PHP exception, a webview JavaScript error, and a native startup crash follow different capture paths. Verify each relevant path in the packaged build and match the resulting event to its release and reproduction.

With NativeWatch, start with the mobile installation guide, then review errors and issues. Keep the screenshots as evidence of layout behavior and the actual reports as evidence of capture. Together, they make an upgrade easier to assess and a regression easier to investigate.