masterix21/laravel-contacts

Add contacts book abilities to any Laravel project

1.0.0 2026-04-29 17:24 UTC

Requires

• php: ^8.2
• illuminate/contracts: ^11.0||^12.0||^13.0
• spatie/laravel-package-tools: ^1.16

Requires (Dev)

• larastan/larastan: ^2.9||^3.0
• laravel/pint: ^1.14
• nunomaduro/collision: ^8.1.1
• orchestra/testbench: ^9.0||^10.0||^11.0
• pestphp/pest: ^3.0||^4.0
• pestphp/pest-plugin-arch: ^3.0||^4.0
• pestphp/pest-plugin-laravel: ^3.0||^4.0
• phpstan/extension-installer: ^1.3
• phpstan/phpstan-deprecation-rules: ^1.1||^2.0
• phpstan/phpstan-phpunit: ^1.3||^2.0
• spatie/laravel-ray: ^1.35

MIT

• Luca Longo

• laravel
• LucaLongo
• laravel-contacts

README

Attach a contact book to any Eloquent model. Users, companies, venues, projects — anything that needs phone numbers, emails, websites, or social handles can grow them through a single polymorphic relation, without you spinning up a dedicated table for every model.

Why

Most apps end up scattering contact fields across half a dozen tables: a phone column on users, an email on companies, a separate addresses table that nobody trusts. This package centralises all of that into one contacts table and lets any model attach as many entries as it needs.

A single contact row can hold a label (e.g. Office, Personal), a phone, a mobile, an email, a website, a few social handles, a push token, and a freeform meta JSON payload for anything else.

Requirements

• PHP 8.2+
• Laravel 11, 12, or 13

Installation

Install via Composer:

composer require masterix21/laravel-contacts

Publish and run the migration:

php artisan vendor:publish --tag="laravel-contacts-migrations"
php artisan migrate

If you need to swap the Contact model for your own subclass, publish the config:

php artisan vendor:publish --tag="laravel-contacts-config"

// config/contacts.php
return [
    'models' => [
        'contact' => \App\Models\Contact::class,
    ],
];

Usage

Add the HasContacts trait to any model that should own contacts:

use Illuminate\Database\Eloquent\Model;
use LucaLongo\LaravelContacts\Models\Concerns\HasContacts;

class User extends Model
{
    use HasContacts;
}

That's it — the model now exposes a polymorphic contacts() relation plus four filtered helpers.

Adding contacts

$user->contacts()->create([
    'label' => 'Office',
    'email' => '[e-mail]',
    'phone' => '[phone]',
    'website' => 'https://example.com',
]);

$user->contacts()->create([
    'label' => 'Personal',
    'mobile' => '[phone]',
    'meta' => [
        'preferred_channel' => 'whatsapp',
        'timezone' => 'Europe/Rome',
    ],
]);

Reading contacts

The trait ships with helpers that filter the relation by the field you care about:

$user->contacts;   // every contact
$user->emails;     // only contacts with a non-null email
$user->phones;     // only contacts with a non-null phone
$user->mobiles;    // only contacts with a non-null mobile
$user->websites;   // only contacts with a non-null website

Each helper returns a MorphMany, so you can keep chaining:

$primaryEmail = $user->emails()->where('label', 'Office')->first()?->email;

The meta field

meta is cast to AsArrayObject, so you can read and write it like a native array and Laravel will persist the JSON for you:

$contact = $user->contacts()->first();

$contact->meta['preferred_channel'] = 'email';
$contact->save();

Available fields

Field	Type	Notes
label	string	Free label, e.g. Office, Billing
phone, mobile	string	Landline / mobile numbers
email	string
website	string
facebook, x, linkedin	string	Social handles or full URLs
push_token	string	Device push token
meta	array	Anything else, stored as JSON

The model has no $fillable and $guarded = [], so mass-assignment is open by design — guard your input at the request layer.

Testing

composer test

Changelog

See CHANGELOG for the release history.

Contributing

See CONTRIBUTING.

Security

Found a vulnerability? Please review the security policy before opening a public issue.

Credits

• Luca Longo
• All contributors

License

The MIT License (MIT). See LICENSE.md.