Weave Code
Laravel Notification Mastodon Laravel Package
revolution/laravel-notification-mastodon
A Laravel notification channel for sending notifications to Mastodon. Publish status updates directly from your app using Laravel's notification system, with simple configuration and support for the Mastodon API so you can integrate posting into existing workflows.
At a glance
Frequently asked questions about Laravel Notification Mastodon
- How do I install the revolution/laravel-notification-mastodon package?
- Install it with Composer using composer require revolution/laravel-notification-mastodon. The package registers itself through Laravel's package discovery, so manual service provider registration is normally not needed. After installation, configure Mastodon credentials and add the mastodon channel to your notification's via() method.
- Which Laravel and PHP versions does laravel-notification-mastodon support?
- Support depends on the composer constraints in the package's composer.json, so check those before committing. The channel follows Laravel's first-class notification contract, which keeps it compatible with modern Laravel releases. For an LTS application, verify the constraint coverage against your installed Laravel and PHP versions and run a test notification before rolling it out.
- How do I configure Mastodon credentials for Laravel notifications?
- Register an OAuth application on each target Mastodon instance and request a token with write:statuses scope, plus write:media if you plan to attach media. Because Mastodon is federated, credentials are per-instance and per-account, so routeNotificationForMastodon() should return the instance host and token rather than a single global API key. Store tokens encrypted and treat them as bearer credentials with write access.
- How do I send a Mastodon status from a Laravel notification?
- Add 'mastodon' to the array returned by your notification's via() method and implement toMastodon($notifiable) to return a MastodonMessage. The message object carries the status text along with optional visibility, content warning, and media. Laravel resolves the channel and posts the status through the Mastodon API when the notification is sent.
- Can I post to a Mastodon account without a notifiable model?
- Yes. Use on-demand routing with Notification::route('mastodon', $route) to target a system or brand account that is not represented by an Eloquent model. This is useful for release announcements, incident notices, and marketing drops. You still need to supply the instance host and token through the route or a custom routeNotificationForMastodon() implementation.
- How do I add media, content warnings, or set visibility on Mastodon posts?
- MastodonMessage exposes the status text plus visibility and content warning fields, and it supports media attachments. Media upload on Mastodon is asynchronous, so a status posted against an unprocessed media ID may fail or publish without the image. For media-bearing notifications, poll for processing completion or split the upload and publish into two phases.
- Does the package prevent duplicate Mastodon posts when a queued notification retries?
- Retry behavior is largely delegated to your Laravel queue configuration, and a naive retry can double-post to Mastodon. Mastodon supports an Idempotency-Key header on POST /api/v1/statuses, so confirm whether the package surfaces it. If it does not, enforce deduplication with WithoutOverlapping or RateLimited middleware, or include your own dedupe key in the payload.
- How do I test Mastodon notifications in Laravel without posting?
- Use Notification::fake() and assert that the expected notification was sent to the intended notifiable or on-demand route. This keeps tests offline and avoids hitting a real Mastodon instance. You can also assert the MastodonMessage contents, such as status text and visibility, without exercising the HTTP client.
- Is it safe to store Mastodon access tokens in a multi-tenant Laravel app?
- Treat Mastodon tokens as sensitive bearer credentials because they carry write scope. Store them encrypted, redact them from logs and exception reports, and scope them to the minimum required permissions. In a multi-tenant app, associate each token with its instance host and account so routing and revocation are explicit.
- What are the alternatives if laravel-notification-mastodon is abandoned?
- The package is small and single-maintainer, so treat it as unproven and plan for a one-file swap. Wrap it behind a thin adapter in your own namespace, or vendor a forked copy under the MIT license if maintenance stalls. If you need Mastodon plus Bluesky or X, consider a general social broadcast abstraction rather than a single-channel package.
Weaver
How can I help you explore Laravel packages today?