PARQORE Accessibility Plugin for NativePHP Mobile#
Screen-reader announcements, OS accessibility settings, focus tools and a development-time audit for the Blade, Livewire and Inertia content inside a NativePHP WebView.
Overview#
partek/accessibility connects the web content of your app to the phone's assistive technology. It has three parts:
- A native bridge (iOS and Android) that speaks announcements through VoiceOver and TalkBack, reads the OS accessibility settings (screen reader, reduce motion, bold text, contrast, text size and more), dispatches an event when they change, and moves screen-reader focus to the WebView.
- A JavaScript module for your WebView pages:
announce()with an ARIA live-region fallback, focus management after Livewire / Inertia / SPA navigation, a focus trap for modals, CSS custom properties written from the OS settings, an Alpine plugin, and an in-page accessibility audit with a development overlay. - PHP: the
Accessibilityfacade, Blade components, a typedAccessibilitySettingsDTO, anAccessibilitySettingsChangedevent, andAccessibility::fake()with assertions.
use PARTek\Accessibility\Facades\Accessibility; Accessibility::announce('Order placed'); // polite, spoken by VoiceOver / TalkBackAccessibility::announce('Payment failed', 'assertive'); // may interrupt $settings = Accessibility::settings(); // typed DTOif ($settings->prefersReducedMotion()) { // true only when the OS positively says so // skip the animation}
import { init, announce, routeChanged, trapFocus, audit } from '../../vendor/partek/accessibility/resources/js/index.js'; init(); // live regions, settings -> CSS, focus after navigation, dev overlayawait announce('Draft saved'); // { delivered: 'native' | 'dom' | 'none' }, never throwsconsole.table(audit().findings); // development audit, runs entirely in the page
What this is not#
- Not a replacement for testing with a screen reader. The audit is automated, dependency-free, and finds only a subset of accessibility problems. A report with no findings does not mean your app is accessible, and the plugin never claims WCAG or legal compliance. See "The audit" below.
- Not a label or dark-mode tool for native UI. See the next section.
- Not a way to focus a specific element from PHP. Native code can move screen-reader focus to the WebView as a whole. Focusing a particular heading or input is done in JavaScript with
focus(), and this plugin's JavaScript does that for you.
What this plugin does, and what nativephp/mobile-ui already does#
nativephp/mobile-ui renders native SwiftUI and Jetpack Compose elements. Those elements accept a11y-label and a11y-hint, and VoiceOver and TalkBack work on them by default. That is a different layer from this plugin.
| You want to | Use |
|---|---|
Label or hint a native button, list, or input from mobile-ui |
The element's own a11y-label / a11y-hint (nativephp/mobile-ui) |
| Make Blade, Livewire or Inertia content in the WebView work well with VoiceOver and TalkBack | This plugin |
| Speak a message after a Livewire action, an Inertia visit, or an AJAX call | This plugin: announce() |
| Move focus to the new page's heading after client-side navigation | This plugin: routeChanged() |
| Trap focus inside a modal or bottom sheet in the WebView | This plugin: trapFocus() |
| Know whether a screen reader is on, or whether the user asked for reduced motion or larger text, and react when it changes | This plugin: settings(), AccessibilitySettingsChanged |
| Find missing labels, tiny touch targets, low contrast in your web pages while developing | This plugin: audit() and the dev overlay |
| Switch between light and dark appearance | A color-scheme plugin. This plugin does not touch appearance. |
Support matrix#
| iOS | Android | |
|---|---|---|
| Minimum OS | 18.0 (the NativePHP host's own minimum) | API 26 (Android 8.0) |
| NativePHP Mobile | ^4.6.1 |
^4.6.1 |
| PHP | ^8.2 |
^8.2 |
| Screen-reader announcements | VoiceOver, with polite/assertive priority and language | TalkBack, priority and language ignored |
| Screen reader detection | UIAccessibility.isVoiceOverRunning (documented) |
Touch exploration state (documented; what TalkBack turns on) |
| Switch control / switch access | Documented | Best-effort (matched by enabled service) |
| Reduce motion | Documented | Best-effort ("Remove animations" sets the animator scale to 0) |
| Bold text | Documented | Android 12 (API 31) and up |
| Increase contrast | Documented (Darker System Colors) | Best-effort (high text contrast setting, Android 14 contrast level) |
| Reduce transparency | Documented | Not available. Reported as unsupported. |
| Invert colors | Documented | Best-effort |
| Text scale | Multiplier relative to the default size, plus the category name | fontScale multiplier. No category name. |
| Change events | Yes | Yes |
| Focus the WebView / screen changed | Yes | Yes |
Every value the OS cannot report comes back null with unsupported in the capabilities map. Android values marked best-effort come from heuristics or unpublished setting keys and say best_effort in the capabilities map. Treat them as hints.
Installation#
composer require partek/accessibilityphp artisan native:plugin:register partek/accessibility
native:plugin:register is NativePHP's explicit step that adds the plugin's provider to your app. Then rebuild the native app so the Swift and Kotlin code is compiled in:
php artisan native:run
The plugin needs no Android permissions, no Gradle dependencies, no Info.plist keys, no entitlements and no Apple developer portal changes. See "iOS setup, step by step" below.
Optionally publish the config and the front-end files:
php artisan vendor:publish --tag=accessibility-config # config/accessibility.phpphp artisan vendor:publish --tag=accessibility-assets # resources/js/vendor/accessibility and resources/css/vendor/accessibilityphp artisan vendor:publish --tag=accessibility-views # override the Blade components
You can also import straight from vendor/partek/accessibility/resources/js/index.js.
Set up your layout#
<body> <x-accessibility::skip-link /> @persist('accessibility-announcer') {{-- Livewire only: keeps the live regions across wire:navigate --}} <x-accessibility::announcer /> @endpersist <x-accessibility::audit-overlay /> {{-- renders nothing unless APP_DEBUG=true --}} <main id="main-content">{{ $slot }}</main></body>
// resources/js/app.jsimport { init } from '../../vendor/partek/accessibility/resources/js/index.js'; init();
init() creates the live regions if the Blade component is absent, reads the OS settings and writes them to CSS custom properties, starts watching Livewire, Inertia and history navigation for focus management, and mounts the audit overlay when it is enabled. Each part can be switched off: init({ settings: false, navigation: false, overlay: false }).
See examples/layout.blade.php and examples/app.js for complete files.
iOS setup, step by step#
There is nothing to configure in Xcode or the Apple developer portal for this plugin. This section explains why, how to build, and how to tell it worked.
Most iOS plugins need something from Apple: a capability, an entitlement, an Info.plist usage string (the "this app wants to use your camera" text), or a setting on your App ID. This plugin uses only UIAccessibility (the system API that VoiceOver and the accessibility settings are built on) and UIKit. Apple gates none of that behind permissions, entitlements or provisioning. The plugin's nativephp.json therefore declares an empty info_plist and no entitlements or capabilities.
- Install and register as shown in "Installation".
- Build for a device or the Simulator:
php artisan native:runand pick a target. The first build of a new plugin recompiles the app. If you use Bifrost (NativePHP's cloud builder), push and build as usual: nothing extra is needed. - Signing. If you already run your app on your iPhone, signing is already set up and this plugin changes nothing. You do not need a new provisioning profile.
- Try it on a physical iPhone. The iOS Simulator has no VoiceOver. It does have the display accessibility settings (Larger Text, Bold Text, Reduce Motion, Increase Contrast and others under Settings > Accessibility), which is enough to test
settings()and the change events. Announcements and focus behavior must be verified on a real iPhone with VoiceOver on. - How to tell it worked.
Accessibility::settings()returnsavailable: trueandplatform: ios. If it returnsbridge_unavailable, the native plugin is not compiled in: runphp artisan native:runagain afternative:plugin:register.- With VoiceOver on,
Accessibility::announce('Test')is spoken. - Turn on Reduce Motion in Settings while the app is open and
AccessibilitySettingsChangedfires withchangedKeyreduce_motion(afterAccessibility::observe(), or withinit()on a WebView page).
- Common problems and what they mean.
| What you see | What it means | What to do |
|---|---|---|
settings()->reason is bridge_unavailable |
The app is running without the native plugin (a desktop browser, an old build, or the plugin was not registered) | Run native:plugin:register partek/accessibility, then rebuild with native:run |
| Announcements are silent | VoiceOver is off (iOS drops announcements silently) | Turn VoiceOver on: Settings > Accessibility > VoiceOver |
| Announcement is cut off when you also move focus | VoiceOver interrupts speech when focus moves | Announce after the focus change, or let the focused heading say it. routeChanged() already avoids doubling. |
Xcode says a Swift file cannot find BridgeFunction or LaravelBridge |
You are compiling the plugin's Swift files on their own | They compile inside the NativePHP host project, which native:run generates. Do not add the files to your own target. |
Quick start#
1. Announce#
Accessibility::announce('Draft saved');Accessibility::announce('Payment failed', 'assertive');Accessibility::announce('Guardado', language: 'es'); // BCP 47 tag, iOS only
await announce('Draft saved');await announce('Payment failed', { priority: 'assertive' });
2. React to the user's settings#
$settings = Accessibility::settings(); $settings->prefersReducedMotion(); // true only when the OS positively says so$settings->screenReaderActive(); // same: unknown counts as false$settings->fontScale; // 1.0 = default, 1.5 = 150 percent, null = unknown$settings->capability(SettingKey::HighContrast); // Capability::BestEffort on Android
const unsubscribe = watchSettings((settings, changedKey) => { // changedKey is null on the first call, then 'reduceMotion', 'fontScale', ...});
3. Focus after navigation#
init() already does this for Livewire wire:navigate, Inertia visits and history navigation. For other routers, call it from their navigated hook:
router.afterEach(() => routeChanged()); // Vue Router
4. Audit while you develop#
Run the app with APP_DEBUG=true, tap the A11y button in the corner, read the findings. Tap a finding to highlight the element. Or in a debugger console: parqoreAccessibility.audit().
PHP API#
All methods are on PARTek\Accessibility\Facades\Accessibility.
| Method | Returns | Notes |
|---|---|---|
announce(string $message, AnnouncementPriority|string $priority = 'polite', ?string $language = null) |
bool |
true: handed to the OS. false: no native bridge or not accepted. Throws InvalidAnnouncementException for an empty or over-long message, a bad priority, or a malformed language, before anything crosses the bridge. |
notifyScreenChanged(?string $announcement = null, ?string $title = null) |
bool |
iOS: screen-changed notification targeting the WebView. Android: sets the WebView's pane title (API 28+) and moves accessibility focus. title is ignored on iOS. |
notifyLayoutChanged(?string $announcement = null) |
bool |
Lighter: part of the layout changed. |
focusWebView() |
bool |
Moves screen-reader focus to the WebView container. |
settings() |
AccessibilitySettings |
Never throws. Unavailable results carry a reason. |
observe() |
bool |
Start delivering AccessibilitySettingsChanged. Idempotent. false when reporting is disabled. |
stopObserving() |
bool |
Release all native listeners. Idempotent. |
settingsReportingEnabled() |
bool |
The privacy opt-out, as configured. |
clientConfig() |
array |
What the JavaScript module reads. Contains no device state. |
true/false from these methods is not an error signal. There is no bridge in a desktop browser or in tests, and the OS may decline a request. Only invalid arguments throw.
Message rules: at most announcements.max_length characters (default 500), valid UTF-8, control characters stripped and whitespace collapsed, zero-width joiners kept so emoji sequences survive.
Result shapes#
AccessibilitySettings#
| Property | Type | Meaning |
|---|---|---|
available |
bool |
true when a native snapshot was read |
reason |
?string |
When not available: disabled_by_config, bridge_unavailable, malformed_response |
platform |
string |
ios, android, or unknown |
screenReader |
?bool |
VoiceOver / TalkBack running |
switchControl |
?bool |
Switch Control (iOS) / Switch Access (Android, best-effort) |
reduceMotion |
?bool |
|
boldText |
?bool |
|
highContrast |
?bool |
|
reduceTransparency |
?bool |
iOS only |
invertColors |
?bool |
|
fontScale |
?float |
Multiplier. 1.0 is the default text size. |
textSizeCategory |
?string |
iOS: large, accessibilityExtraLarge, ... Android: null |
capabilities |
array<string, string> |
Per setting: supported, best_effort, unsupported, disabled |
A null value is unknown, not off. Use prefersReducedMotion() and screenReaderActive() when you want unknown to count as false, and read capabilities when the difference matters. AccessibilitySettings::fromArray() validates an untrusted payload: wrong types become null, a value the capabilities map calls unsupported is forced to null, a font scale outside 0.1 to 10 is dropped, and a non-array payload becomes unavailable('malformed_response').
The PHP enums are SettingKey (the keys used everywhere), Capability, and AnnouncementPriority.
Events#
| Event | Constructor (flat scalars) | When |
|---|---|---|
PARTek\Accessibility\Events\AccessibilitySettingsChanged |
changedKey, platform, screenReader, switchControl, reduceMotion, boldText, highContrast, reduceTransparency, invertColors, fontScale, textSizeCategory |
An OS setting changed while observing. One event per changed key. |
The event only fires after Accessibility::observe() (or after the JavaScript module starts watching), and never when settings reporting is disabled.
A NativeComponent #[On] handler receives the payload by parameter name, not as an event object: declare the keys you need, named as in the table above. Type-hinting AccessibilitySettingsChanged $event throws a BindingResolutionException. Give the nullable values a null default, because Android leaves out values it cannot read. SettingKey::tryFrom($changedKey) gives the enum (null for a key a future version adds).
use Native\Mobile\Attributes\On;use PARTek\Accessibility\Enums\SettingKey;use PARTek\Accessibility\Events\AccessibilitySettingsChanged; #[On(AccessibilitySettingsChanged::class)]public function onSettingsChanged(string $changedKey, ?float $fontScale = null): void{ if (SettingKey::tryFrom($changedKey) === SettingKey::FontScale) { $this->fontScale = $fontScale ?? 1.0; }}
When you hold an AccessibilitySettingsChanged object yourself (built with named arguments, for example), key() returns the SettingKey and toSettings() builds an AccessibilitySettings from it.
examples/native/SettingsScreen.php shows a full NativeComponent screen.
Configuration#
config/accessibility.php (publish with --tag=accessibility-config):
| Key | Env | Default | Purpose |
|---|---|---|---|
settings_reporting |
ACCESSIBILITY_SETTINGS_REPORTING |
true |
The privacy opt-out. false disables all reading and observing of OS settings. |
expose_assistive_tech_state |
ACCESSIBILITY_EXPOSE_ASSISTIVE_TECH |
false |
Also write "screen reader on" / "switch control on" to <html> data attributes |
announcements.max_length |
ACCESSIBILITY_ANNOUNCE_MAX_LENGTH |
500 |
Reject longer announcements in PHP |
announcements.default_priority |
ACCESSIBILITY_ANNOUNCE_PRIORITY |
polite |
|
announcements.mode |
ACCESSIBILITY_ANNOUNCE_MODE |
auto |
JavaScript: auto (native, then live region), native, or dom (live region only) |
navigation.enabled |
ACCESSIBILITY_NAVIGATION |
true |
Focus management after navigation |
navigation.focus_selector |
[data-a11y-focus], main h1, h1, [role="main"], main |
First match wins, in selector order | |
navigation.title_template |
:title |
Template for the announced title | |
navigation.announce_title |
true |
Announce the title when the heading would not already say it | |
audit.overlay |
ACCESSIBILITY_AUDIT_OVERLAY |
APP_DEBUG |
Show the dev overlay |
audit.min_contrast_normal / min_contrast_large |
4.5 / 3.0 |
WCAG AA ratios | |
audit.target_size.ios / .android |
44 / 48 |
Touch target guidance, CSS pixels | |
register_components |
ACCESSIBILITY_REGISTER_COMPONENTS |
true |
Register <x-accessibility::*> |
Blade components#
| Component | Purpose |
|---|---|
<x-accessibility::announcer /> |
The polite and assertive live regions plus the JSON config the JavaScript reads. Once per layout. |
<x-accessibility::skip-link target="main-content">Skip to main content</x-accessibility::skip-link> |
First focusable element. Hidden until focused. |
<x-accessibility::live-region politeness="polite|assertive" :atomic="true"> |
A region whose text changes are spoken. Livewire re-renders work. |
<x-accessibility::visually-hidden> |
Text for screen readers only |
<x-accessibility::audit-overlay /> |
Mount point for the dev overlay. Renders nothing unless enabled. |
JavaScript API#
All exports come from resources/js/index.js and are typed in index.d.ts. Everything degrades gracefully with no native bridge: nothing throws because the bridge is missing.
Announcements#
announce(message, { priority, language, mode }) resolves { delivered: 'native' | 'dom' | 'none' } and never throws.
auto(default): tries the native announcement. If the bridge reports it was handed to the OS, that is used and the live region is left alone. Otherwise the message is written to a polite or assertive ARIA live region. It never does both, so nothing is spoken twice.native: native only.dom: live region only.- Repeating the same text is re-announced (the live region alternates a trailing non-breaking space and empties itself first).
- Messages are cleaned and cut to
announcements.max_length.
Settings and CSS#
getSettings(), watchSettings(callback), applySettings(settings).
With no native bridge, or with settings reporting off, settings come from CSS media queries (prefers-reduced-motion, prefers-contrast, forced-colors, prefers-reduced-transparency, inverted-colors) and the capabilities map says web. A web page cannot know whether a screen reader is running, so that stays null.
init() writes these on <html>:
| Property | Value |
|---|---|
--a11y-font-scale |
1.35. 1 when unknown. |
--a11y-motion-scale |
0 when reduce motion is on, else 1. Use calc(250ms * var(--a11y-motion-scale, 1)). |
data-a11y-reduce-motion |
"true" or "false". Absent when unknown. |
data-a11y-bold-text, -high-contrast, -reduce-transparency, -invert-colors |
Same |
data-a11y-screen-reader, -switch-control |
Only when expose_assistive_tech_state is true (see Privacy) |
resources/css/accessibility.css is an optional stylesheet using them (reduce-motion rules, .a11y-sr-only, reduce-transparency and high-contrast helpers). examples/reduce-motion.css shows the patterns.
Focus management#
routeChanged({ title, focusSelector, announce, native, delay }): waits for the framework to render, focuses the first match of the focus selector (making it programmatically focusable withtabindex="-1", removed again on blur), and announces the page title. Withannounce: 'auto'(default) the title is announced only if focus did not move or the focused heading does not already say it, because focusing a heading makes the screen reader read it and announcing the same words would be spoken twice.watchNavigation(options): callsrouteChanged()after Livewirelivewire:navigated, Inertiainertia:navigate,popstate(and optionallyturbo:load), only when the URL actually changed.init()calls it for you.focusElement(el),findFocusTarget(selectors).- Native helpers, each resolving
true/false:focusWebView(),notifyScreenChanged({ message, title }),notifyLayoutChanged({ message }).
What native can and cannot do. Native code can move screen-reader focus to the WebView as a whole (focusWebView(), notifyScreenChanged()). It cannot reach into the page and focus a particular heading. That is JavaScript: element.focus() on an element with tabindex="-1", plus correct ARIA. routeChanged() does that. Whether a given screen reader then moves its cursor to the focused element depends on the screen reader and OS version, so verify it on a device.
Focus trap#
const trap = trapFocus(dialogElement, { initialFocus: '#name', // element, selector, or function. Default: first focusable returnFocus: true, // restore focus to the opener on release inertOthers: true, // make the rest of the page inert onEscape: closeDialog,});// latertrap.release();
While active: Tab and Shift+Tab cycle inside the container, focus that escapes is pulled back, and every sibling of the container and its ancestors becomes inert. The inert part matters on a phone: VoiceOver and TalkBack navigate by swiping, which does not use Tab, so a Tab-only trap does not stop a screen-reader user from reaching content behind the dialog. Give the container role="dialog", aria-modal="true" and an accessible name. This helper handles focus, not semantics.
Alpine#
import accessibilityAlpine from '../../vendor/partek/accessibility/resources/js/alpine.js'; document.addEventListener('alpine:init', () => window.Alpine.plugin(accessibilityAlpine));
$announce('Saved'), $a11y.announce / focus / routeChanged / audit, $store.a11y.settings (reactive), x-a11y-trap="open" (.noinert, .noreturn), x-a11y-announce="message" (.assertive). See examples/modal-alpine.blade.php.
The audit#
audit(options) runs 16 dependency-free rules over the page and returns a typed report. It runs entirely in the page and sends nothing anywhere.
Automated checks find only a subset of accessibility problems. A clean report does not mean your app is accessible or compliant with WCAG or any law, and this plugin never claims it does. Every report carries that disclaimer. Use the audit to catch obvious defects early, then test with VoiceOver and TalkBack.
| Rule | Looks for | Related WCAG criteria (informational) |
|---|---|---|
image-alt |
img without alt, filename-looking alt text, unnamed role="img" / svg / image inputs |
1.1.1 |
button-name |
Buttons with no accessible name | 4.1.2 |
link-name |
Links with no name, and generic text ("click here", "read more") | 2.4.4, 4.1.2 |
form-label |
Controls with no label, placeholder-only labels, label for pointing nowhere, email/tel/password without autocomplete |
1.3.1, 3.3.2, 4.1.2, 1.3.5 |
heading-order |
No headings, empty headings, skipped levels, first heading not h1, several h1 | 1.3.1, 2.4.6 |
landmarks |
No main, several main, several nav without distinct names |
1.3.1, 2.4.1 |
target-size |
Touch targets under 44 pt (iOS) / 48 dp (Android) as a warning, under 24 px as an error. Links inside a sentence are exempt. | 2.5.8, 2.5.5 |
color-contrast |
Text contrast below 4.5:1 (3:1 for large text) where a solid background can be resolved. Backgrounds with images or gradients are reported as needs-review, not guessed. |
1.4.3 |
duplicate-id |
The same id used more than once | 4.1.1 |
aria-usage |
Unknown roles and aria-* names, bad values, ids that do not exist, missing required attributes, aria-hidden on focusable content, role="button" on something that cannot be focused, aria-label that omits the visible text |
4.1.2, 1.3.1, 2.5.3 |
nested-interactive |
Controls nested inside links or buttons | 4.1.2 |
tabindex-positive |
tabindex above 0 |
2.4.3 |
html-lang |
Missing or invalid lang |
3.1.1 |
document-title |
Missing <title> |
2.4.2 |
viewport-zoom |
user-scalable=no or maximum-scale below 2, which blocks pinch zoom |
1.4.4, 1.4.10 |
media-alternatives |
Video without captions and audio without a transcript (needs-review), autoplay with sound |
1.2.x, 1.4.2 |
Severities: error (a defect the rule is sure of), warning (likely problem or best-practice miss), needs-review (the audit could not decide).
Honest limits. The accessible name is a simplified calculation, not the full accname algorithm. Contrast is not computed for text over images or gradients. Nothing checks reading order, meaningful alt text, keyboard traps, focus visibility, screen-reader output, gestures, or timing. Findings can be false positives.
Privacy of the report. A finding's html is the element's opening tag only, with any value attribute replaced by .... No page text is included. The report stays in the page unless you copy it.
const report = audit({ platform: 'android', skip: ['media-alternatives'] });// report.schema 'parqore.accessibility.audit/1'// report.summary { errors, warnings, needsReview, total, elementsScanned, rulesRun, rulesSkipped }// report.findings [{ ruleId, severity, message, help, wcag, selector, html, details? }]// report.disclaimer always present
Ways to run it without Artisan or any tooling:
- The overlay. With
APP_DEBUG=true(orACCESSIBILITY_AUDIT_OVERLAY=true), an A11y button appears. It lists findings, highlights an element when tapped, copies the report as JSON, and is itself keyboard and screen-reader operable. It is hidden in a release build unless you opt in. - A JavaScript call:
audit()from your own code, orparqoreAccessibility.audit()in a console while the overlay is enabled. - Chrome DevTools remote debugging for Android WebViews (
chrome://inspect), if your build enables WebView debugging.
Livewire and Inertia#
Livewire. Put <x-accessibility::announcer /> inside @persist('accessibility-announcer') so wire:navigate does not recreate the live regions. Render status text inside <x-accessibility::live-region> so a re-render is announced, or call Accessibility::announce() from the component. init() handles focus after wire:navigate. See examples/livewire/.
Inertia (Vue, React). There is no server-rendered announcer, so init() creates the live regions. Announce flash messages and the first validation error from your layout. See examples/inertia-vue/ and examples/inertia-react/.
NativeComponent (SuperNative). Facade and event work from #[On(...)] listeners. See examples/native/SettingsScreen.php.
Testing#
There are two ways to test code that uses this plugin. Accessibility::fake() replaces the facade, which suits service classes, controllers and Livewire. The test helpers work with NativePHP's component test harness (Native::test()), which suits NativeComponent screens: the screen calls the real facade, the helpers answer the bridge the way the device does, and they deliver the native settings-change event.
Testing with the fake#
use PARTek\Accessibility\Facades\Accessibility; it('announces when the order is placed', function () { $fake = Accessibility::fake(); $this->post('/orders', $payload); $fake->assertAnnounced('Order placed'); $fake->assertAnnounced(fn (string $message, string $priority, ?string $language) => $priority === 'polite'); $fake->assertNotAnnounced('Something else'); $fake->assertAnnouncedTimes(1);}); it('adapts to reduce motion', function () { $fake = Accessibility::fake()->simulateSettings(['reduce_motion' => true, 'font_scale' => 1.5]); expect(Accessibility::settings()->prefersReducedMotion())->toBeTrue();}); it('reacts to a settings change', function () { Event::fake([AccessibilitySettingsChanged::class]); $fake = Accessibility::fake(); Accessibility::observe(); $fake->simulateChange('reduce_motion', true); Event::assertDispatched(AccessibilitySettingsChanged::class, fn ($e) => $e->reduceMotion === true);});
Fake assertions: assertAnnounced($message = null, $priority = null), assertNotAnnounced(), assertAnnouncedTimes(), assertNothingAnnounced(), assertScreenChanged(), assertLayoutChanged(), assertWebViewFocused(), assertObserving(), assertNotObserving(), assertNothingCalled(). Helpers: simulateSettings(array|AccessibilitySettings), simulateChange($key, $value) (dispatches the event, only while observing), withoutBridge() (a device with no native bridge), announcements(), calls(). Input validation still runs in the fake, so a test that announces an empty string fails exactly like production. The fake honors settings_reporting = false.
Test helpers#
On NativePHP Mobile 4.0 or later, the plugin registers these helpers on Native::fakeBridge() and on the Native::test() harness whenever the app runs under a test runner (APP_ENV=testing). Production boots never register them, and there is nothing extra to install.
use App\NativeComponents\SettingsScreen;use Native\Mobile\Testing\Native; it('saves and adapts to reduce motion', function () { Native::fakeBridge()->withAccessibility(['reduce_motion' => false]); Native::test(SettingsScreen::class) ->tap('Save') ->assertAnnounced('Draft saved', 'polite') ->assertAccessibilityObserving() ->changeAccessibilitySetting('reduce_motion', true) ->assertSee('Animations off');});
Script the bridge first. With nothing scripted, the fake bridge answers null and the facade treats that as a missing bridge: announce(), the focus helpers and observe() return false, and settings() is unavailable with reason bridge_unavailable. The bridge assertions would still pass while your screen runs its fallback branch.
| Helper | Called on | What it does |
|---|---|---|
withAccessibility(array $settings = []) |
bridge | Every Accessibility.* call answers {delivered: true}, as the device does. settings() returns an iPhone with everything off, font_scale 1.0 and text size large, with $settings (snake_case payload keys, and capabilities merged key by key) on top. Pass 'platform' => 'android' for an Android device: best-effort capabilities, no reduce_transparency or text_size_category. |
withoutAccessibilitySupport() |
bridge | A device without the plugin's native code: nativephp_can() is false for all 7 functions and every call answers null. |
assertAnnounced(?string $message = null, AnnouncementPriority|string|null $priority = null) |
bridge | announce() reached the bridge: any message, or exactly $message and/or $priority. The message is compared after the facade trims it and collapses whitespace. |
assertNothingAnnounced() |
bridge | announce() never reached the bridge. |
assertAccessibilityScreenChanged(?string $announcement = null, ?string $title = null) |
bridge | notifyScreenChanged() reached the bridge, optionally with that announcement and title. |
assertAccessibilityLayoutChanged(?string $announcement = null) |
bridge | notifyLayoutChanged() reached the bridge, optionally with that announcement. |
assertAccessibilityObserving() |
bridge | observe() reached the bridge and no stopObserving() came after it. |
changeAccessibilitySetting(SettingKey|string $key, mixed $value, array $extra = []) |
harness | Delivers AccessibilitySettingsChanged for $key, as when the user flips a setting. The other values come from what withAccessibility() scripted (or its defaults), with $extra (camelCase event keys, e.g. ['textSizeCategory' => 'extraLarge']) on top. If you scripted settings, settings() returns the changed values from then on. |
Bridge helpers work on Native::fakeBridge() or straight off the harness. Called off the harness, they return the harness, so the chain continues.
- What the device sends.
changeAccessibilitySetting()fails for a key the device never sends: iOS reports a text size change asfont_scale(pass the category in$extra), and neither platform sendstext_size_category. It also fails for a setting the scripted capabilities mark as unsupported, afterwithoutAccessibilitySupport(), and for a value of the wrong type (in$extratoo). Like Android, it leaves out values the device can't report, so your handler's parameter defaults apply. - Handler parameters. A screen's
#[On(AccessibilitySettingsChanged::class)]method gets the payload by parameter name (string $changedKey, ?bool $reduceMotion = null, ...). Give the nullable values anulldefault: a value that is left out with no default throws aBindingResolutionException. - Observing. The helper doesn't require a prior
observe(), because the JavaScript module can start observing too. UseassertAccessibilityObserving()when your screen is meant to call it. - With
Accessibility::fake(). The fake replaces the facade, so nothing reaches the bridge while it is active and the bridge helpers see no calls.changeAccessibilitySetting()still reaches the screen. The fake's ownsimulateChange()goes through Laravel's event dispatcher, so it never reaches a screen's#[On]handler; usechangeAccessibilitySetting()for that.
Testing with VoiceOver and TalkBack, step by step#
You do not need to be an iOS or Android accessibility specialist. Ten minutes with a real screen reader teaches more than any tool. Do this on a physical phone.
iPhone: VoiceOver#
- Turn it on. Settings > Accessibility > VoiceOver. Or set a shortcut: Settings > Accessibility > Accessibility Shortcut > VoiceOver, then triple-click the side button to toggle it. Turn the shortcut on before you need it: once VoiceOver is on, everything needs an extra gesture.
- The gestures you need.
- Touch anywhere: VoiceOver reads what is under your finger.
- Swipe right / left with one finger: next / previous item.
- Double-tap anywhere: activate the selected item.
- Two-finger scrub (a quick Z shape): go back / dismiss.
- Three-finger swipe up / down: scroll.
- Rotor: turn two fingers on the screen like a dial. Choose Headings, then swipe up or down to jump between headings. This is how many users skim a page, and how you check your heading structure.
- What to check.
- Swipe through the whole screen. Is every control announced with a useful name and role ("Place order, button")? Is anything read twice or skipped?
- After a Livewire action, is the status message spoken?
- Navigate to another page. Does VoiceOver land on the new page's heading?
- Open a modal. Can you swipe out of it? (You should not be able to.) Close it. Does focus return to the button?
- Display settings (test
settings()and events): Settings > Accessibility > Motion > Reduce Motion; Settings > Accessibility > Display & Text Size > Bold Text, Larger Text, Increase Contrast, Reduce Transparency, Smart Invert. Change one while your app is open and watchAccessibilitySettingsChanged(or your CSS) update. - Xcode Accessibility Inspector (on your Mac): Xcode > Open Developer Tool > Accessibility Inspector. Choose your connected iPhone or the Simulator from the target menu. Hover to see the element's label and role, or use the Audit tab to run Apple's checks on the native screen. It is most useful for native views, and it does not replace listening to VoiceOver on the WebView.
- The Simulator has no VoiceOver. It has the display settings above (Settings > Accessibility inside the Simulator) and the Accessibility Inspector, so use it for
settings()and change events, and use an iPhone for everything else.
Android: TalkBack#
- Turn it on. Settings > Accessibility > TalkBack (the path varies by manufacturer and Android version; searching Settings for "TalkBack" always works). Enable the shortcut too: hold both volume keys for three seconds toggles it.
- The gestures you need.
- Touch: TalkBack reads what is under your finger.
- Swipe right / left: next / previous item.
- Double-tap: activate.
- Two-finger swipe: scroll.
- Swipe down then left: Back. Swipe up then left: Home.
- Swipe up or down changes the reading granularity (the exact gesture depends on your TalkBack version and settings). Set it to Headings and swipe to jump between headings.
- What to check. The same list as VoiceOver above.
- Display settings (paths vary by device): Settings > Display > Font size and Display size; Settings > Accessibility > Bold text, High contrast text, Color inversion, and "Remove animations" (under Color and motion on recent Pixels). Switch Access lives at Settings > Accessibility > Switch Access.
- Emulator. Google Play system images include TalkBack, so you can try it without a phone, but a real device is more reliable.
- Debugging the WebView. Where your build enables WebView debugging,
chrome://inspecton your computer opens DevTools for the app's WebView, where you can runparqoreAccessibility.audit().
A short checklist to fill in per release is in DEVICE_TEST_MATRIX.md.
Pitfalls in WebViews#
- A live region must exist before its text changes. A region created at the same moment as its first message is often missed. Render
<x-accessibility::announcer />in the layout. With Livewirewire:navigate, wrap it in@persist. - Do not announce what focus will already say. Focusing a heading makes the screen reader read it.
routeChanged()avoids the double. - Announcements cross a bridge. A native announcement is an HTTP call to the local NativePHP server, then a call into native code. It is fast, but not instant. Do not use announcements for things that must be spoken in a fixed order with other speech.
- iOS moves focus on its own sometimes. VoiceOver may interrupt an announcement when focus changes at the same moment. Announce after the focus change. Confirmed on a real device (2026-09-24): calling
announce()synchronously from a new screen'smount()/initial load consistently loses this race - a human twice heard VoiceOver's own automatic screen-change narration (the screen title, or a focused element's label) instead of the announcement, even with the native call correctly accepted every time. A blocking sleep before the announcement does not fix this: it delays the screen's own appearance (and therefore VoiceOver's transition narration) by the same amount, so the two events never actually separate. What worked: let the screen render immediately, and fire the realannounce()call from an async delay (this project's own test harness uses NativePHP's#[Poll(300)]to check elapsed wall-clock time - seeAccessibilityTest.phpin the plugin sandbox) roughly 1.5s later, well after VoiceOver's own screen-change narration has had time to finish. - Text size does not follow the OS on its own. Neither iOS Dynamic Type nor Android font scale automatically resizes text in a WebView. Size type in
rem, and let--a11y-font-scalescale the root (examples/reduce-motion.css), or usefont: -apple-system-bodyon iOS. user-scalable=noandmaximum-scale=1break zoom. The audit flags it.aria-hidden="true"on something focusable hides it from screen readers but keeps it in the tab order.- A
divwith a click handler is not a button. It gets no role, no keyboard activation and no switch-control support. Use<button>and<a href>. - Small touch targets. Aim for 44 pt on iOS and 48 dp on Android. In a WebView one CSS pixel is one point / dp at 100 percent zoom.
- Android 16 deprecates
announceForAccessibility(). It still works. For text in the page, an ARIA live region is the recommended mechanism, andannounce(msg, { mode: 'dom' })uses only that. See "Platform behavior". - Placeholder text is not a label. It disappears while typing and is often low contrast.
- Custom modals need more than
role="dialog". They need focus moved in, contained, and returned, and the page behind made inert.trapFocus()does all of it. - Do not read the screen reader state to decide what a user can do. Never hide features from someone because a screen reader is on. Use it, if at all, to choose a plainer presentation.
Platform behavior#
| iOS | Android | |
|---|---|---|
| Announcement API | UIAccessibility.post(.announcement) with an attributed string |
View.announceForAccessibility() on the WebView (or the window root if there is no WebView yet) |
| Polite vs assertive | Polite queues behind current speech (accessibilitySpeechQueueAnnouncement). Assertive uses high priority (accessibilitySpeechAnnouncementPriority, iOS 17+). |
No priority in the API: both behave the same |
| Language | Sets the speech language for that announcement | Ignored |
| Android 16 (API 36) | announceForAccessibility() and TYPE_ANNOUNCEMENT are deprecated. They still function. Google's recommended replacements are live regions, pane titles and stateDescription. The native result reports deprecated: true. |
|
| Screen changed | .screenChanged with the WKWebView as the target |
Sets the WebView's accessibility pane title (API 28+), sends a window-content-changed event, and requests accessibility focus on the WebView |
| Layout changed | .layoutChanged targeting the WKWebView |
Subtree-changed content event on the WebView |
| Message with a screen or layout change | Spoken about half a second later (posting it at the same instant is usually cut off) | Announced about 400 ms later |
| Silent when the screen reader is off | Yes: the OS drops it | Yes: the OS drops it |
| Change detection | UIAccessibility notifications, plus a re-check when the app becomes active |
AccessibilityManager listeners, settings observers, configuration changes, and a re-check on resume |
| Threading | Work is dispatched to the main thread | Work is posted to the main thread |
| WebView not created yet | Focus helpers return delivered: false |
Focus helpers return delivered: false |
The plugin finds the iOS WKWebView by searching the key window's view tree, and the Android WebView through the host activity's WebView provider without forcing one to be created.
Privacy#
Both iOS and Android treat "a screen reader is running" as sensitive information, because it can reveal that someone has a disability. This plugin is built accordingly:
- It never transmits any accessibility setting, announcement, or audit report. Nothing leaves the device: values are returned to your own PHP or JavaScript code and stay there. The native code contains no networking code (a test in the repository checks that).
- It never logs a setting value. Native code logs nothing that includes a value, and PHP does not log.
- Turn reading off entirely with
ACCESSIBILITY_SETTINGS_REPORTING=false. The plugin then does not read or observe any OS setting:settings()returnsunavailable('disabled_by_config')without touching the bridge,observe()returnsfalse, and the JavaScript uses CSS media queries only. Announcements and focus helpers keep working because they send output to the screen reader and never read whether one is running. This opt-out is enforced in the PHP facade and the JavaScript module. Your own JavaScript can still call the native bridge directly, so it is a switch for your app's behavior, not a security boundary against your own code. - The page never learns about a screen reader by default. The JavaScript module writes the visual preferences (reduce motion, bold text, contrast, transparency, inverted colors, text scale) to
<html>. It does not write "screen reader on" or "switch control on" unless you setexpose_assistive_tech_statetotrue, because any script on the page, including third-party scripts, could read it. - Do not send the values elsewhere. Do not put them in analytics, error reports or server requests. Do not gate features on them.
- App Store and Play Store privacy forms. Because nothing is collected or transmitted by this plugin, it adds nothing to your data-collection disclosures. If your own code sends these values anywhere, that changes and is yours to declare.
Troubleshooting#
| Symptom | Cause and fix |
|---|---|
settings() says bridge_unavailable |
No native plugin: register it (native:plugin:register partek/accessibility) and rebuild. Also expected in a desktop browser and in tests. |
settings() says disabled_by_config |
ACCESSIBILITY_SETTINGS_REPORTING=false |
announce() returns false |
No native bridge. The JavaScript module falls back to a live region. |
announce() returns true but nothing is spoken |
No screen reader is running (the OS drops it), or, on iOS, focus moved at the same moment |
| Live-region text is not read | The region did not exist before its text changed. Use <x-accessibility::announcer />, and @persist with Livewire. |
| The overlay does not appear | APP_DEBUG is false. Set it, or ACCESSIBILITY_AUDIT_OVERLAY=true, and make sure init() runs and <x-accessibility::audit-overlay /> is in the layout. |
| Change events never arrive | Call Accessibility::observe(), or run init() on a WebView page. Not delivered when reporting is disabled. |
reduceTransparency is null on Android |
Android has no such setting. capabilities.reduce_transparency says unsupported. |
boldText is null on Android |
Requires Android 12 (API 31) or later |
InvalidAnnouncementException |
Empty message, longer than announcements.max_length, unknown priority, or a language that is not a BCP 47 tag |
| Focus does not move to the heading on a route change | No element matched navigation.focus_selector, or your router does not fire Livewire / Inertia / popstate events. Call routeChanged() yourself. |
Manual test matrix#
A ready-to-fill list of what must be verified on a physical iPhone and a physical Android device is in DEVICE_TEST_MATRIX.md. Automated tests cover the PHP layer, the JavaScript, and that the native sources type-check. None of them run VoiceOver or TalkBack.
Upgrade notes#
This is the first release line; there is nothing to upgrade from. Changes are recorded in CHANGELOG.md. Native code changes require rebuilding the app (php artisan native:run). A manifest change may need php artisan native:install --force.
Support policy#
Supports NativePHP Mobile ^4.6.1, PHP ^8.2, Laravel 10 to 13, iOS 18.0 and later, Android 8.0 (API 26) and later. Semantic versioning: breaking changes only in a major version. Native-behavior notes in this README describe what was implemented and type-checked. Behavior that depends on a screen reader is marked as needing device verification.
Security#
Report a vulnerability privately to [email protected]. Please do not open a public issue for it. Details are in SECURITY.md.
License#
Proprietary commercial software. Copyright (c) 2026 PARTek. All rights reserved. See LICENSE.