Download the PHP package pushinbr/pam-native-nitro without Composer

Why PAM Native Nitro

Query indexed local data, observe incremental changes, and keep large datasets responsive through a typed storage boundary. The public API is strictly typed for PHP 8.5; expensive or frame-sensitive work stays in Rust or the platform SDK instead of crossing the application boundary every frame.

What you can build

• Offline catalogs and field applications
• Large local timelines and searchable datasets
• Reactive caches backed by durable native storage

Quick start

Already have a PAM Native project? Add only this capability:

New to PAM? Follow the five-minute PAM Native setup once, then return here. Your application stays a normal Composer project with a committed lockfile.

Offline-first data at native speed.

PAM Native Nitro is the high-performance local data engine for PAM Native. It keeps application startup independent from database size by querying lazily on a native worker and materializing only the records a screen needs.

Part of the PAM ecosystem

Nitro is an extension of PAM Native, the native Android and iOS runtime that keeps PHP alive in the application process and renders real platform controls without JavaScript or WebViews.

• PAM Native core — runtime, renderer, navigation, native modules and tooling required by Nitro.
• PAM Native documentation — install and understand the native runtime first.
• Nitro documentation — models, schemas, queries, observability and offline-first patterns.
• PAM platform — the persistent PHP server runtime and the wider ecosystem.

Performance claims in this project are backed by reproducible benchmarks. The engineering target is to outperform JSON cache hydration by at least 10× in representative mobile workloads.

Design

• Native SQLite on Android and iOS.
• WAL and prepared-statement optimizations in the PAM runtime.
• Lazy models: no full-database hydration.
• Bounded, indexed, paginated queries.
• Integer-backed enums for coded domain values.
• Additive schema evolution without dropping cached rows.
• Atomic scoped snapshot replacement without stale rows or empty-cache windows.
• Durable idempotent mutation outbox with bounded exponential retry.
• Integer-backed mutation states, operations and conflict policies.
• No reflection in hot query paths; schemas are reflected once and cached.
• No JavaScript, JSI, ORM proxies, or runtime code generation.

WatermelonDB demonstrated the right mobile principle: keep queries native, lazy, asynchronous, and observable. PAM Native Nitro applies that principle to PAM's persistent PHP runtime with fewer transport layers.

Read the architecture and benchmark protocol before evaluating performance claims.

PAM Native Nitro 0.3.3 and newer require PAM Native 0.6.2 or newer within the 0.6 release line.

Models

Relations are declared once and stay lazy:

Use

Durable offline mutations

Queue a local mutation before starting network work. The idempotency key is stored as the outbox primary key, so replaying the same user action updates one durable entry instead of creating duplicate server writes:

Workers request only due pending/retry entries, mark an attempt in flight, and either acknowledge it or schedule a bounded exponential retry. Acknowledged and terminally failed rows stay in the log until application retention policy removes them, preserving diagnostics and exactly-once intent across process death.

Conflict resolution is explicit and deterministic through integer-backed ConflictPolicy cases: server wins, client wins, last write wins (server wins ties), or an application-provided manual resolver.

Incoming server pages use DeltaApplier: row upserts, tombstone deletions and the new opaque cursor commit through one native SQLite transaction. A crash can therefore never advance the cursor without its data, or apply data without the matching cursor. Empty pages still advance the cursor and deletion identifiers are parameterized in bounded chunks.

Model deletion always uses its primary key. deleteWhere() requires an explicit non-empty scope, so an accidental table-wide delete is rejected.

Schema evolution

Nitro::prepare() reconciles newly declared fields with an existing table. Missing columns are added sequentially on the native SQLite worker, preserving all cached rows. Give a new non-nullable property a domain-safe default:

Older rows hydrate with that default immediately. Nullable fields migrate to NULL; integer-backed enums use the first sequential case when no explicit property default exists. Destructive renames and type changes remain explicit application migrations.

Status

PAM Native Nitro is under active development. The initial API is intentionally small while the binary bridge, batch writes, observation, destructive migrations, relations, and benchmarks are hardened.