PHPackages kwidoo/laravel-contacts - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. kwidoo/laravel-contacts ActiveLibrary kwidoo/laravel-contacts ======================= Simple contact management for Laravel. 1.2.0(1y ago)01MITPHPPHP ^8.2CI passing Since Sep 22Pushed 1y agoCompare [ Source](https://github.com/kwidoo/laravel-contacts)[ Packagist](https://packagist.org/packages/kwidoo/laravel-contacts)[ Docs](https://github.com/kwidoo/laravel-contacts)[ RSS](/packages/kwidoo-laravel-contacts/feed)WikiDiscussions master Synced 1mo ago READMEChangelogDependencies (7)Versions (12)Used By (0) [![Latest Version on Packagist](https://camo.githubusercontent.com/1881c10974b3f0e6c42ccc650f5401da7d02ee4bd70266a913c27d6f20698b68/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6b7769646f6f2f6c61726176656c2d636f6e74616374732e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/kwidoo/laravel-contacts)[![Total Downloads](https://camo.githubusercontent.com/683bb60785667fd423223709947ea6f54c981fab8535aa3711516a81f0f1cf43/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6b7769646f6f2f6c61726176656c2d636f6e74616374732e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/kwidoo/laravel-contacts)[![GitHub Actions](https://github.com/kwidoo/laravel-contacts/actions/workflows/main.yml/badge.svg)](https://github.com/kwidoo/laravel-contacts/actions/workflows/main.yml/badge.svg) Laravel Contacts ================ [](#laravel-contacts) A Laravel package that provides a robust, event-sourced approach to managing multiple contact types (e.g., phone, email) for your Eloquent models. It offers features such as: - Storing multiple contacts (phone/email, etc.) for a given model (e.g. `User`). - Event-sourced creation, verification, and deletion of contacts. - Configurable token-based verification mechanism (phone/email). - Ability to designate primary contacts (only one primary at a time). - Soft deletion with restore options. - Support for UUIDs (configurable). - Spatie Event Sourcing integration for auditing and replays. Table of Contents ----------------- [](#table-of-contents) 1. [Installation](#installation) 2. [Configuration](#configuration) 3. [Migrations](#migrations) 4. [Usage](#usage) - [Adding the HasContacts Trait](#adding-the-hascontacts-trait) - [Creating Contacts](#creating-contacts) - [Listing Contacts](#listing-contacts) - [Verifying Contacts](#verifying-contacts) - [Deleting and Restoring Contacts](#deleting-and-restoring-contacts) - [Setting a Primary Contact](#setting-a-primary-contact) 5. [Event Sourcing](#event-sourcing) 6. [Advantages](#advantages) 7. [Additional Notes](#additional-notes) --- Installation ------------ [](#installation) 1. Require this package in your Laravel application: ``` composer require kwidoo/contacts ``` 2. This package also relies on [Spatie's Laravel Event Sourcing](https://spatie.be/docs/laravel-event-sourcing) under the hood. If you have not already installed and configured Spatie's event sourcing package, you should do so. --- Configuration ------------- [](#configuration) 1. **Publish Config**: ``` php artisan vendor:publish --provider="Kwidoo\Contacts\ContactServiceProvider" --tag="config" ``` This will create a `config/contacts.php` file. Inside you will find the following key aspects: - **`model`** – The contact Eloquent model class (default: `Kwidoo\Contacts\Models\Contact`). - **`table`** – The database table for storing contacts (default: `contacts`). - **`uuid`** – Whether to use UUIDs as the primary key (boolean). - **`verifiers`** – A list of verifiers for different contact types (email, phone, etc.). - **`token`** – Configuration for token generation, including token length, TTL, and the token model/table. 2. **Bind Twilio or Other Services**: If you plan to use phone verification (`PhoneVerifier`), make sure you bind or configure any external SMS provider like Twilio. The example implementation references a `Kwidoo\MultiAuth\Services\TwilioService`. Adapt this service to your application’s needs. 3. **Event Sourcing**: This package automatically merges its required projector (`\Kwidoo\Contacts\Projectors\ContactProjector::class`) into your `event-sourcing.projectors` config. Make sure Spatie Event Sourcing is installed and configured appropriately. --- Migrations ---------- [](#migrations) After installing, run: ``` php artisan vendor:publish --provider="Kwidoo\Contacts\ContactServiceProvider" --tag="migrations" php artisan migrate ``` This will publish and run the necessary migrations for storing contacts and tokens in your database. --- Usage ----- [](#usage) ### Adding the HasContacts Trait [](#adding-the-hascontacts-trait) Any model (User, Company, etc.) that you wish to associate contacts with should implement `Kwidoo\Contacts\Contracts\Contactable` and use the `Kwidoo\Contacts\Traits\HasContacts` trait. Example on a `User` model: ``` namespace App\Models; use Illuminate\Foundation\Auth\User as Authenticatable; use Kwidoo\Contacts\Contracts\Contactable; use Kwidoo\Contacts\Traits\HasContacts; class User extends Authenticatable implements Contactable { use HasContacts; // Your model implementation } ``` > **Important**: The `HasContacts` trait adds a polymorphic relationship `contacts()` and also provides a `getPrimaryContactAttribute` accessor. ### Creating Contacts [](#creating-contacts) You can create a contact through the provided controller or directly through the `ContactService`. #### Via Controller and Routes [](#via-controller-and-routes) The package registers RESTful routes for `contacts`. You can do a POST request to `contacts` (by default at `/contacts`) with the request body containing: ``` { "type": "email", "value": "user@example.com" } ``` The validation ensures the `type` matches one of the configured verifiers (e.g., `email`, `phone`), and the `value` is unique for that model. If successful, the route redirects to `contacts.show` (by default `/contacts/{contact}`). #### Via `ContactService` [](#via-contactservice) If you prefer direct usage in your code: ``` use Kwidoo\Contacts\Contracts\ContactService; // Typically, $this->user is your model that implements Contactable $contactService = app(ContactService::class, [ 'model' => $this->user ]); $uuid = $contactService->create('email', 'user@example.com'); // Returns the UUID (or ID) of the newly created contact ``` ### Listing Contacts [](#listing-contacts) Using the built-in controller route: - `GET /contacts` – Lists all contacts, paginated. - If you wish to only get the contacts for a specific model (e.g., a single user), you need to ensure proper authorization or build your own route logic to filter the contacts. Or directly from your model: ``` $user->contacts; // returns a collection of Contact models ``` ### Verifying Contacts [](#verifying-contacts) Contacts can be verified via a token-based approach: 1. **Initiate Verification**: ``` POST /contacts/verify/{contact} ``` This calls `VerificationController@sendVerification`. It triggers a token generation and sends out the verification (via email or SMS, depending on the contact type). 2. **Complete Verification**: ``` GET or POST /contacts/verify/{contact}/{token} ``` This calls `VerificationController@verify`. If the token is valid, the `ContactVerified` event is recorded, and the contact is marked as verified. ### Deleting and Restoring Contacts [](#deleting-and-restoring-contacts) - **Delete (Soft Delete)**: ``` DELETE /contacts/{contact} ``` Calls the `ContactController@destroy` method, which uses `ContactService::destroy($contact)`. > **Note**: Attempting to delete a primary contact throws an exception. - **Restore**: ``` POST /contacts/restore/{uuid} ``` Calls `ContactController@restore`, which invokes `ContactService::restore($uuid)`. This un-deletes the contact if it was soft-deleted. ### Setting a Primary Contact [](#setting-a-primary-contact) By default, the **first** contact you create becomes the primary contact. You can change the primary contact via: ``` POST /contacts/{contact}/primary ``` This calls `ContactController@markAsPrimary`, leveraging the `ContactAggregateRoot` to update the primary contact. --- Event Sourcing -------------- [](#event-sourcing) This package uses [Spatie's Event Sourcing](https://spatie.be/docs/laravel-event-sourcing) to record: - **ContactCreated** – Fired when a new contact is created. - **StartVerification** – Fired when verification is initiated for a contact. - **ContactVerified** – Fired when a contact is successfully verified. - **ContactDeleted** – Fired when a contact is soft-deleted. - **PrimaryChanged** – Fired when the primary contact is changed. The `ContactProjector` listens for these events and updates the read models (the `contacts` table). If you need to replay or track changes, you can use event sourcing commands (e.g., `php artisan event-sourcing:replay`) to rebuild state. --- Advantages ---------- [](#advantages) 1. **Event-Sourced**: Full audit trail and ability to replay contact-related events. 2. **Multiple Contact Types**: Phone, email, or any custom type your application requires. 3. **Token-Based Verification**: Supports both email and phone verifications via token-based, OTP-like flows. 4. **Soft Delete + Restore**: Helps maintain history and preserves referential integrity. 5. **Primary Contact Management**: Ensures only one primary contact per model, with easy swaps. 6. **Configurable UUIDs**: Toggle between numeric IDs or UUIDs for your contacts. 7. **Extensibility**: Swappable verifiers, token generation, and external notification services (e.g., Twilio for SMS). 8. **Polymorphic**: Manage contacts for any Eloquent model (User, Company, etc.). --- Additional Notes ---------------- [](#additional-notes) - If you need to implement custom verifiers, simply create a class that implements the `Kwidoo\Contacts\Contracts\Verifier` interface and add it to the `contacts.verifiers` array in the configuration. - For phone verification, ensure you have a proper SMS provider service (like Twilio) configured and replace the existing reference `Kwidoo\MultiAuth\Services\TwilioService` with your own implementation if needed. - Make sure your policies (`view`, `delete`, `update`, etc.) align with your application’s authorization logic. The sample routes use typical Laravel policy checks, but you can modify or remove them as needed. Feel free to open issues or submit pull requests to enhance functionality or documentation. Enjoy managing your contacts in a more robust, scalable, and auditable fashion! ### Health Score 38 — LowBetter than 85% of packages Maintenance46 Moderate activity, may be stable Popularity1 Limited adoption so far Community8 Small or concentrated contributor base Maturity82 Battle-tested with a long release history Bus Factor1 Top contributor holds 73.5% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~347 days Recently: every ~360 days Total 11 Last Release 413d ago Major Versions v0.1.1 → v1.0.02021-02-02 PHP version history (5 changes)v0.0.1PHP >=5.5.9 v0.1.0PHP >=5.6.4|^7.0 v1.0.0PHP ^7.2.5|^8.0 v1.0.1PHP ^7.3|^8.0 1.0.3PHP ^8.2 ### Community Maintainers ![](https://www.gravatar.com/avatar/40e08f40bb6cff697b1703ccab1a57f3bd327faedf429df8e588d325a76de9f8?d=identicon)[samsite](/maintainers/samsite) --- Top Contributors [![AlexanderPoellmann](https://avatars.githubusercontent.com/u/6631793?v=4)](https://github.com/AlexanderPoellmann "AlexanderPoellmann (100 commits)")[![kwidoo](https://avatars.githubusercontent.com/u/14920653?v=4)](https://github.com/kwidoo "kwidoo (36 commits)") --- Tags laravelcontactslecturize ### Code Quality TestsPHPUnit ### Embed Badge ![Health badge](/badges/kwidoo-laravel-contacts/health.svg) ``` [![Health](https://phpackages.com/badges/kwidoo-laravel-contacts/health.svg)](https://phpackages.com/packages/kwidoo-laravel-contacts) ``` ### Alternatives [barryvdh/laravel-ide-helper Laravel IDE Helper, generates correct PHPDocs for all Facade classes, to improve auto-completion. 14.9k123.0M686](/packages/barryvdh-laravel-ide-helper)[lecturize/laravel-addresses Simple address and contact management for Laravel. 20164.1k](/packages/lecturize-laravel-addresses)[api-platform/laravel API Platform support for Laravel 59126.4k6](/packages/api-platform-laravel) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)