Getting Started

Install/upgrade with Composer and confirm your app meets the new floor: this release adds Laravel 9 support, so verify PHP 8.0+ and Laravel 9 constraints before updating. If you are already on Laravel 9, this is the release that removes the compatibility blocker.
Look first at the package changelog, service provider, config file, and migrations. The v1.7.0 schema change makes message_id nullable; read the migration and the message model to see how that column is cast and used.

Publish package assets and migrate:

php artisan vendor:publish --provider="Vendor\\Package\\PackageServiceProvider"
php artisan migrate

First use case: send a message/notification through the package, persist the resulting record, and verify the record can exist before the provider returns a message_id. This is the normal path for queued, pending, or failed sends.

Implementation Patterns

Send-then-update workflow: create the local message record first, dispatch the send, then update message_id when the provider responds. Treat message_id as an external correlation ID, not as the local primary key.
Nullable lifecycle: allow message_id to be null at creation and populate it asynchronously. In code that displays or exports messages, use a fallback such as $message->message_id ?? $message->id or an explicit “pending” label.
Queued integration: send from jobs rather than controllers for anything provider-facing. In the job, persist provider responses and failures; on failure, leave message_id null and store the error separately.
Events and listeners: use package events or model observers to sync message state to your app (CRM, audit log, dashboards) without coupling the send path to reporting logic.
Testing: use RefreshDatabase and factories that can create messages with and without message_id. Add a test that asserts downstream code handles null correctly.
Laravel 9 compatibility: include Laravel 9 in your CI matrix if you maintain integrations around the package, and check that your own composer constraints do not pin the package below v1.7.0.

Altering an existing column: making message_id nullable on an existing database may require doctrine/dbal on Laravel 9 when using change(). Test the migration against a production-like database, not only SQLite.
Audit null assumptions: search your codebase for message_id usage in strict type hints, string functions, unique indexes, API resources, Blade templates, and exports. Any code that assumes a non-null string will break.
Unique indexes and NULLs: MySQL, PostgreSQL, and SQLite generally allow multiple NULL values in a unique index. Do not rely on a unique constraint on message_id to prevent duplicate unsent messages.
Config quirks: republish config after upgrading, clear cached config, and confirm queue connection and retry settings. The nullable change is schema-level, but send behavior is still driven by config.
Debugging: log the raw provider response and distinguish “not sent yet” from “sent without a provider ID.” If the package has no status column, add your own state field rather than overloading message_id.
Extension points: prefer the package’s configurable message model, contracts, and events over editing vendor migrations. If you need custom persistence, bind your own implementation through the container rather than forking the package.