README

Read and write NDEF tags through one lifecycle-safe API.
Run bounded NFC sessions, parse typed records and handle platform capability differences without leaking native session objects.

Install · Quick example · Platforms · Permissions · API · Issues

Install

Inside a PAM Native project, add only this capability:

pam composer require pushinbr/pam-native-nfc
pam doctor --fix

New to PAM? Follow the five-minute PAM Native setup once (pam init my-app --template native), then come back here. Your application stays a normal Composer project with a committed lockfile; pam doctor --fix refreshes the generated native integration. Use pam packages to inspect availability.

Quick example

use Pam\Native\Nfc\{NdefRecord, Nfc, NfcAvailability, NfcEvent, NfcEventKind};

$nfc = new Nfc();

$nfc->availability(function (NfcAvailability $availability) use ($nfc): void {
    if ($availability === NfcAvailability::Available) {
        $nfc->beginRead(fn (bool $ok, ?string $error) => null);
    }
});

$nfc->write(NdefRecord::uri('https://pam.dev'), fn (bool $ok, ?string $error) => null);

$nfc->poll(function (array $events): void {
    foreach ($events as $event) { /** @var NfcEvent $event */
        if ($event->kind === NfcEventKind::TagDiscovered) {
            handleRecords($event->records); // list<NdefRecord>
        }
    }
});

Only one NFC session may be active at a time. iOS presents the system NFC sheet and requires the NFC capability in the signing profile. Android uses reader mode and requires a foreground Activity. The queue is bounded to 128 events. NDEF payloads are limited to 1 MiB in PHP before reaching native code; the physical tag's capacity is checked at write time.

Platform support

Permissions and requirements

The iOS signing profile must include the NFC Tag Reading capability, and scanning needs a compatible physical device.

What you can build

• Asset and inventory tagging
• Contactless onboarding and pairing
• Smart posters, tickets and physical experiences

API guide

All coded states, kinds and variants are sequential integer-backed enums. Use enum cases in application code; do not depend on raw wire numbers.

Production checklist

• End sessions when the owning screen leaves the foreground.
• Validate every record type, length and payload before use.
• Treat tag data as untrusted external input.
• Run pam doctor, pam test and a signed release build on every supported platform.
• Exercise denial, cancellation, backgrounding, process restart and offline behavior before release.

Platform SDKs, credentials, entitlements, physical hardware and store configuration remain application responsibilities.

Troubleshooting

• Session will not start: only one session may be active.
• iOS cannot scan: verify the NFC entitlement and a compatible signed device.
• Write fails: compare the encoded payload with the physical tag capacity.
• Native integration is stale: run pam doctor --fix, rebuild the native host and inspect the first reported diagnostic.

Docs

• PAM Native overview
• Plugin and native capability model
• PAM documentation
• Changelog
• Report an issue: security vulnerabilities go through the repository security policy or GitHub private vulnerability reporting, not a public issue

Part of the PAM ecosystem

PAM runs PHP natively on servers, desktops and phones. This repository is one piece of it.

_{Docs: push-in.github.io/pam-docs · Issues}

_{Apache License 2.0 · Made in Brazil by Pushin}