Contacts for NativePHP Mobile#

Read, create & sync the device address book — straight from Laravel.#

Contacts plugin on iOS Contacts plugin on Android

A complete contacts API for your NativePHP mobile app. Query contacts with a fluent builder, create and update entries, manage groups, and handle iOS 18's new limited-access contact picker — all without writing a line of Swift or Kotlin.

Why this plugin?#

🔎 Fluent contact search — MobileContacts::contacts()->search('John')->withPhoneNumber()->limit(50)->get().
✍️ Full CRUD — create, update and delete contacts and groups with typed data objects.
🆕 iOS 18 contact access picker — first-class support for Apple's new limited-access flow.
📡 Live events — ContactCreated, ContactUpdated, ContactAccessUpdated dispatched straight into your Livewire components.
📱 One API, both platforms — iOS Contacts framework and Android ContactsContract, unified.

Features at a glance#

Feature	Android	iOS
Read / search contacts	✅	✅
Create / update / delete contacts	✅	✅
Groups	✅	✅
Limited-access contact picker	—	iOS 18+
Real-time events	✅	✅

Perfect for#

CRMs · Sales & outreach tools · Messaging & social apps · Dialer / VoIP · Event & conference apps · Field-service & delivery

Installation#

Copied!

composer require srwiez/nativephp-mobile-contacts
php artisan vendor:publish --tag=nativephp-plugins-provider
php artisan native:plugin:register srwiez/nativephp-mobile-contacts

composer require srwiez/nativephp-mobile-contacts
php artisan vendor:publish --tag=nativephp-plugins-provider
php artisan native:plugin:register srwiez/nativephp-mobile-contacts

Usage#

Copied!

use SRWieZ\NativePHP\Mobile\Contacts\Facades\MobileContacts;
use SRWieZ\NativePHP\Mobile\Contacts\Data\ContactData;
use SRWieZ\NativePHP\Mobile\Contacts\Data\PhoneNumber;
use SRWieZ\NativePHP\Mobile\Contacts\Data\EmailAddress;
 
// Request permission
$result = MobileContacts::requestAccess();
 
// Query contacts
$contacts = MobileContacts::contacts()
    ->search('John')
    ->withPhoneNumber()
    ->limit(50)
    ->get();
 
// Create a contact
$contact = MobileContacts::createContact(
    ContactData::make()
        ->name('John', 'Doe')
        ->organization('Acme Inc')
        ->addPhone(PhoneNumber::mobile('+1234567890'))
        ->addEmail(EmailAddress::work('[email protected]'))
);
 
// Update a contact
$contact->update(
    ContactData::make()->jobTitle('Senior Developer')
);
 
// Delete a contact
$contact->delete();

use SRWieZ\NativePHP\Mobile\Contacts\Facades\MobileContacts;
use SRWieZ\NativePHP\Mobile\Contacts\Data\ContactData;
use SRWieZ\NativePHP\Mobile\Contacts\Data\PhoneNumber;
use SRWieZ\NativePHP\Mobile\Contacts\Data\EmailAddress;

// Request permission
$result = MobileContacts::requestAccess();

// Query contacts
$contacts = MobileContacts::contacts()
    ->search('John')
    ->withPhoneNumber()
    ->limit(50)
    ->get();

// Create a contact
$contact = MobileContacts::createContact(
    ContactData::make()
        ->name('John', 'Doe')
        ->organization('Acme Inc')
        ->addPhone(PhoneNumber::mobile('+1234567890'))
        ->addEmail(EmailAddress::work('[email protected]'))
);

// Update a contact
$contact->update(
    ContactData::make()->jobTitle('Senior Developer')
);

// Delete a contact
$contact->delete();

Manage Contact Access#

Open the iOS 18+ contact access picker to let users manage which contacts your app can access in limited-access mode. The call is asynchronous — it returns immediately and dispatches a ContactAccessUpdated event when the user finishes.

Copied!

use SRWieZ\NativePHP\Mobile\Contacts\Facades\MobileContacts;
 
$success = MobileContacts::manageContactAccess(); // true if picker was presented

use SRWieZ\NativePHP\Mobile\Contacts\Facades\MobileContacts;

$success = MobileContacts::manageContactAccess(); // true if picker was presented

Platform behavior:

iOS 18+ — Opens contactAccessPicker, allowing the user to select multiple contacts in limited-access mode.
iOS < 18 — Returns false with an error (Contact access picker requires iOS 18.0 or later).
Android — Not available (iOS-only feature).

JavaScript:

Copied!

import { mobileContacts } from '@srwiez/nativephp-mobile-contacts';
 
await mobileContacts.manageContactAccess();

import { mobileContacts } from '@srwiez/nativephp-mobile-contacts';

await mobileContacts.manageContactAccess();

Listening for Events#

Copied!

use Native\Mobile\Attributes\OnNative;
use SRWieZ\NativePHP\Mobile\Contacts\Events\ContactCreated;
use SRWieZ\NativePHP\Mobile\Contacts\Events\ContactAccessUpdated;
 
#[OnNative(ContactCreated::class)]
public function handleContactCreated($contactId, $displayName)
{
    // Contact was created
}
 
#[OnNative(ContactAccessUpdated::class)]
public function handleContactAccessUpdated($identifiers, $contacts, $count, $timestamp)
{
    // $identifiers — array of native contact IDs the user selected
    // $contacts    — array of full contact data for each selected contact
    // $count       — number of contacts updated
    // $timestamp   — Unix timestamp of the selection
}

use Native\Mobile\Attributes\OnNative;
use SRWieZ\NativePHP\Mobile\Contacts\Events\ContactCreated;
use SRWieZ\NativePHP\Mobile\Contacts\Events\ContactAccessUpdated;

#[OnNative(ContactCreated::class)]
public function handleContactCreated($contactId, $displayName)
{
    // Contact was created
}

#[OnNative(ContactAccessUpdated::class)]
public function handleContactAccessUpdated($identifiers, $contacts, $count, $timestamp)
{
    // $identifiers — array of native contact IDs the user selected
    // $contacts    — array of full contact data for each selected contact
    // $count       — number of contacts updated
    // $timestamp   — Unix timestamp of the selection
}

Available Events#

Event	Parameters
`ContactAccessGranted`	—
`ContactAccessDenied`	—
`ContactCreated`	`$contactId`, `$displayName`
`ContactUpdated`	`$contactId`, `$displayName`
`ContactDeleted`	`$contactId`
`ContactAccessUpdated`	`$identifiers`, `$contacts`, `$count`, `$timestamp`
`GroupCreated`	`$groupId`, `$name`
`GroupDeleted`	`$groupId`

All events live in the SRWieZ\NativePHP\Mobile\Contacts\Events namespace.

Version Support#

Platform	Minimum Version
Android	5.0 (API 21)
iOS	18.0

Features requiring higher versions:

iOS 18+: manageContactAccess() contact access picker for limited-access mode

Support#

Bugs, questions, and feature requests should be reported at github.com/SRWieZ/nativephp-mobile-packages.