DEV Community: Andrej Mihaliak

Campaigns for Laravel — send one message to many recipients on queued job batches

Andrej Mihaliak — Mon, 19 Oct 2026 10:58:42 +0000

Most apps grow a "send this to everyone" button sooner or later: a product announcement, a policy update, a back-in-stock alert. A loop in a controller is fine for ten recipients. For ten thousand it holds the request open, one bad address can stop the whole run, and once it starts you can't see how far it got or stop it.

That batching, progress and cancel plumbing gets rebuilt in project after project, so we packaged it once.

What Campaigns for Laravel does

Campaigns for Laravel sends one message to many recipients through Laravel queues and job batches. Every campaign is a job batch with one queued delivery job per recipient, so the request that starts it returns straight away and a queue worker does the sending.

Address recipients by email address, by a contact record, or by any model that owns contacts (it builds on our contacts package). An address added twice still gets one message.
Send now, or prepare now and start later.
Follow progress while the batch runs: status, sent, failed and still to go. A failed delivery is never counted as sent.
Cancel a running campaign and the remaining messages don't go out.
One failing recipient doesn't stop the rest. A campaign only ends as failed when not one message got through.
A campaign that is already sending can't be started a second time, not even by two requests at the same moment.

Install

composer require roundly-consulting/campaigns-for-laravel
php artisan vendor:publish --tag="campaigns-migrations" --tag="options-migrations" --tag="contacts-migrations"
php artisan migrate

Because every campaign is a job batch, the app needs Laravel's job_batches table (php artisan make:queue-batches-table if it has none) and a running queue worker.

Send a campaign

Create, address and send a campaign through the facade, then follow its progress:

use RoundlyConsulting\Campaigns\Facades\Campaigns;

$campaign = Campaigns::create('Buy today and spend less', '<p>Hello dear customer!</p>')
    ->from('no-reply@eshop.tld', 'Best E-Shop Ever')
    ->to(['john@doe.tld', 'jane@doe.tld'])     // emails, Contact records or HasContacts owners
    ->dispatch();                              // one queued delivery job per recipient

$progress = Campaigns::campaign($campaign->uuid)->progress();

$progress->percentage();                       // share delivered so far: 50.0
$progress->failed;                             // deliveries that failed
$progress->remaining();                        // recipients still to go

Campaigns::cancel($campaign->uuid);            // stop the rest

If you'd rather not use a facade, inject CampaignManager for the same API, or call the action classes directly.

Prepare now, start later

prepare() stores the campaign and its recipients and opens the batch without sending anything. Start it when you're ready, from a scheduled command, after an approval, or from a second button:

use RoundlyConsulting\Campaigns\Facades\Campaigns;

$campaign = Campaigns::create('Newsletter', '<h1>Hi</h1>')
    ->from('news@example.com', 'News')
    ->to(['ann@example.com', 'bob@example.com'])
    ->prepare();

Campaigns::start($campaign->uuid);
Campaigns::campaign($campaign)->progress()->percentage();
Campaigns::campaign($campaign)->recipients(limit: 50);
Campaigns::cancel($campaign);

recipients() pages through the recipients in the order they were added, each with whether its message went out or failed, and the error if it failed.

Email, notifications or your own job

Out of the box each recipient gets an email from the campaign's sender. The delivery step is a swappable job: set process-recipient-job to the shipped SendCampaignNotification, point CAMPAIGNS_NOTIFICATION at a subclass of CampaignNotification, and the same campaign goes out over a Laravel notification channel such as SMS or push. Any other channel fits behind the ProcessesCampaignRecipient contract.

By default campaigns live in memory for the process that sends them, so you don't need campaign tables to get started. To follow progress across requests, for a dashboard, a delayed send or an audit trail, switch to the database store:

CAMPAIGNS_STORE='RoundlyConsulting\Campaigns\Stores\DatabaseCampaignStore'
CAMPAIGNS_NOTIFICATION='App\Notifications\ProductLaunchNotification'

Change send defaults without a deploy

The default sender, sending queue and notification channel are stored options (from our options package), seeded from config. A stored value wins, and forgetting it falls back to config again:

use RoundlyConsulting\Campaigns\Options\DefaultChannel;
use RoundlyConsulting\Campaigns\Options\DefaultFromAddress;
use RoundlyConsulting\Options\Facades\Options;

Options::set(DefaultFromAddress::class, 'news@example.com');
Options::set(DefaultChannel::class, 'vonage');        // SendCampaignNotification routes here
Options::get('campaigns.from-address');               // by registry key
Options::forget(DefaultFromAddress::class);           // back to config('campaigns.from-address')

Events, commands and tests

Lifecycle events such as CampaignStarted, CampaignCompleted, CampaignCancelled, RecipientProcessed and RecipientFailed let your app log, notify or update a dashboard as a campaign moves. php artisan campaigns:list prints every campaign with its progress, and php artisan campaigns:cancel {uuid} stops one from the terminal.

In tests, Campaigns::fake() records every write and sends nothing: no batch, no queued job, no event. Assertions like assertDispatched(), assertCancelled() and assertRecipientFailed() check what your code would have sent.

Requirements

PHP ^8.4, Laravel 12 or 13, MIT license. Runtime dependencies are Laravel itself and a few of our own packages (contacts, options, enums and our package toolkit), nothing else.

Lifecycle for Laravel — Eloquent status transitions with quotas, expiry and rollbacks

Andrej Mihaliak — Mon, 19 Oct 2026 10:58:41 +0000

A status column on an Eloquent model usually starts as an enum and a couple of if checks. Then the rules pile up: who may publish, "at most five active listings per customer", listings that expire after 30 days, a support agent who needs to undo a wrong click. Soon nobody can say who changed a status, or why.

What it does

Lifecycle for Laravel is a state machine for Eloquent models with the business rules around it built in. You declare a model's states and the named transitions between them once, in a definition class. Every apply, check, scheduled run and rollback then goes through the same guard pipeline: Gate abilities, actor rules, required reasons, validated payloads, time windows, limits and your own guards. For the same input, check() and apply() return the same denials, so the button your UI shows matches what the server accepts.

Install

composer require roundly-consulting/lifecycle-for-laravel
php artisan vendor:publish --tag="lifecycle-migrations"
php artisan migrate

Define, attach, apply

Define the lifecycle once (php artisan make:lifecycle ListingLifecycle generates the class):

use RoundlyConsulting\Lifecycle\Definition\LifecycleBuilder;
use RoundlyConsulting\Lifecycle\Definition\LifecycleDefinition;

final class ListingLifecycle extends LifecycleDefinition
{
    public function define(LifecycleBuilder $lifecycle): void
    {
        $lifecycle->states(ListingStatus::class)   // a backed enum: draft, active, closed, expired
            ->initial(ListingStatus::Draft);

        $lifecycle->state(ListingStatus::Active)
            ->ttl('30 days')->expiresVia('expire')
            ->quota(5, scope: 'user_id');           // at most 5 active listings per user

        $lifecycle->transition('publish')->from(ListingStatus::Draft)->to(ListingStatus::Active)->ability('publish');
        $lifecycle->transition('close')->from(ListingStatus::Active)->to(ListingStatus::Closed)->requiresReason();
        $lifecycle->transition('expire')->from(ListingStatus::Active)->to(ListingStatus::Expired)->systemOnly();
    }
}

Attach it to the model:

use RoundlyConsulting\Lifecycle\Concerns\HasLifecycle;
use RoundlyConsulting\Lifecycle\Contracts\LifecycleSubject;

final class Listing extends Model implements LifecycleSubject
{
    use HasLifecycle;

    public function lifecycleDefinitions(): array
    {
        return ['status' => ListingLifecycle::class];
    }

    protected function casts(): array
    {
        return ['status' => ListingStatus::class];
    }
}

Then move it through its states:

use RoundlyConsulting\Lifecycle\Facades\Lifecycles;

Lifecycles::for($listing)->by($user)->apply('publish');      // draft → active, checked by the Gate

Lifecycles::for($listing)->can('close');                     // true
Lifecycles::for($listing)->because('Sold elsewhere')->apply('close');

Lifecycles::for($listing)->rollback();                       // undo the last transition
Lifecycles::for($listing)->history();                        // who did what, when and why

Saving a new status straight onto the model throws by default, so nothing gets around the rules by accident. Writes that skip Eloquent events (a query-builder update(), raw SQL) are picked up and recorded the next time the package touches that record, or for a whole table with php artisan lifecycle:adopt.

Quotas that hold under concurrent requests

A rule like "five active listings per user" is usually a count() before the save, and two requests arriving at the same moment both pass it. Here the quota is checked inside the transition's transaction, behind a lock row per scope value, so concurrent requests take turns. The maximum can also come from the subject, for example the customer's plan:

$lifecycle->state(ListingStatus::Active)
    ->quota(5, scope: 'user_id')                                              // static
    ->quota(fn (Listing $l): int => $l->user->plan->max_active, scope: 'user_id', name: 'plan'); // per subject

The package's test suite runs concurrent processes against PostgreSQL and MySQL that try to push more listings into the state than the quota allows; exactly the quota gets in. The docs cover the per-database details. Cooldowns, "reopen at most 3 times", a minimum time in a state, rate limits and deadlines sit next to quotas.

Expiry and scheduled transitions

A state can expire after a duration, at a date stored on the model or when a closure says so, with a grace period and warnings:

$lifecycle->state(ListingStatus::Active)
    ->ttl('30 days')                  // or ->ttl(fn (Listing $l) => $l->plan->duration) or ->expiresAtAttribute('ends_at')
    ->grace('3 days')
    ->warnBefore('7 days', '1 day')
    ->expiresVia('expire');

$lifecycle->transition('expire')->from(ListingStatus::Active)->to(ListingStatus::Expired)->systemOnly();

Each warning lead fires the LifecycleExpiring event at most once per expiry, so a reminder email doesn't go out twice. extend(), renew(), expireAt() and neverExpire() change the expiry of the current stay. Transitions can also be planned for later:

$scheduled = Lifecycles::for($post)->by($editor)->because('Launch')->with(['channel' => 'web'])->schedule('publish', $publishAt);
Lifecycles::for($post)->cancelScheduled('publish');     // bool

One command, lifecycle:sweep, scheduled every minute, runs due expiries and scheduled transitions, inline or through your queue, each in its own transaction, so one failing record doesn't hold up the others. Schedules that give up are listed and can be retried.

Undo and history

rollback() undoes the last transition and rollbackTo() goes back further. Rollback windows, irreversible transitions and conflict checks on snapshotted columns are declared on the transition, and a handler that implements CompensatesTransition can release whatever it reserved. History rows can't be updated or deleted through Eloquent; only lifecycle:prune and force-deleting a record remove them.

Testing

Lifecycles::fake() replaces the engine behind the facade and in the container. It still runs the checks that need no database against your real definition (unknown or wrong-source transitions, system-only moves, actor rules, reasons, payload rules), so a test can't pass code the engine would refuse on those grounds. Nothing is written, and there is an assertion for every kind of call:

it('reopens a listing', function (): void {
    Lifecycles::fake();
    $listing = Listing::factory()->create(['status' => ListingStatus::Closed]);

    $this->actingAs($owner)->post("/listings/{$listing->id}/reopen", ['reason' => 'Back in stock'])->assertRedirect();

    Lifecycles::assertTransitioned($listing, 'reopen', fn (TransitionResult $result) => $result->record->reason === 'Back in stock');
    expect($listing->fresh()->status)->toBe(ListingStatus::Closed);   // the fake never writes
});

For CI, lifecycle:validate reports unreachable states, dead ends and missing columns, and warns when the sweep isn't scheduled:

php artisan lifecycle:validate --strict

Requirements

PHP ^8.4, Laravel 12 or 13, and MySQL or PostgreSQL. MIT license. Runtime dependencies are Laravel components plus two of our own packages, enums-for-laravel and package-toolkit-for-laravel.

Auth for Laravel — headless multi-guard login with 2FA, passkeys and JWT sessions

Andrej Mihaliak — Mon, 05 Oct 2026 09:15:02 +0000

Every API-backed Laravel app we built needed sign-in, and the hand-written version kept having the same small gaps: a login error that told you whether an email was registered, a password reset that left old sessions alive, a two-factor step a client could skip. Each one is minor. Together they are how accounts get taken over. So we pulled all of it into one package and open-sourced it.

What it does

Auth for Laravel is headless account authentication for Laravel apps behind a mobile app or a single-page frontend. It owns the policy and orchestration; your app keeps its screens.

Four ways to sign in: password, magic link, email code and passkey.
A challenge engine for the second step (authenticator code, backup code or passkey), including forced enrolment when a guard requires two-factor.
RS256 access tokens with rotating refresh tokens, and device sessions a user can end one by one, all others, or everywhere.
Registration, invitations, email verification, email change and password resets.
A login-activity log, throttling, new-device alerts and a hook for your own risk rules.
Separate guards (users, clients, staff), each with its own model, config, endpoints, JWT audience and sessions.
Opt-in JSON endpoints and an event for every state change.

Installation

composer require roundly-consulting/auth-for-laravel
php artisan jwt:generate-keys
php artisan authentication:install   # publishes config + migrations, prints the guard wiring
php artisan migrate

authentication:install prints the config/auth.php guard wiring instead of editing your config, and php artisan authentication:check tells you what is still wrong.

Usage

Give the guard's model the contracts of the features it uses:

use Illuminate\Foundation\Auth\User as Authenticatable;
use Illuminate\Notifications\Notifiable;
use RoundlyConsulting\Auth\Concerns\HasAuthentication;
use RoundlyConsulting\Auth\Contracts\Account;
use RoundlyConsulting\Passkeys\Concerns\InteractsWithPasskeys;
use RoundlyConsulting\Passkeys\Contracts\HasPasskeys;
use RoundlyConsulting\RefreshTokens\Traits\HasRefreshTokens;
use RoundlyConsulting\TwoFactor\Concerns\HasTwoFactorAuthentication;
use RoundlyConsulting\TwoFactor\Contracts\TwoFactorAuthenticatable;

class User extends Authenticatable implements Account, HasPasskeys, TwoFactorAuthenticatable
{
    use HasAuthentication, HasRefreshTokens, HasTwoFactorAuthentication, InteractsWithPasskeys, Notifiable;

    protected function casts(): array
    {
        return [...$this->authenticationCasts(), ...$this->twoFactorCasts(), 'email_verified_at' => 'datetime'];
    }
}

use RoundlyConsulting\Auth\DataTransferObjects\PasswordCredentials;
use RoundlyConsulting\Auth\Facades\Authentication;
use RoundlyConsulting\Auth\Http\Resources\ChallengeResource;
use RoundlyConsulting\Auth\Http\Resources\TokenPairResource;

$guard = Authentication::guard('users');

$result = $guard->attempt(
    new PasswordCredentials(identifier: $request->string('email')->toString(), password: $request->string('password')->toString()),
    $guard->contextFrom($request),
);

return $result->isAuthenticated()
    ? TokenPairResource::make($result->tokens)
    : ChallengeResource::make($result->challenge);   // continue with $guard->challenges()->complete(…)

Rotate the refresh token, or sign the account out of every device:

$tokens = $guard->refresh($refreshToken, $guard->contextFrom($request));   // the old access token stops working

$guard->logoutEverywhere($user);

Finishing the second step

When a login returns a challenge, the client sends the code back and you complete it on the same guard. Backup codes and passkeys go through the same complete() call.

use RoundlyConsulting\Auth\DataTransferObjects\ChallengeFactorData;
use RoundlyConsulting\Auth\Enums\FactorMethod;

$context = $guard->contextFrom($request);

if ($result->requiresChallenge()) {
    $pending = $result->challenge;   // token, expiresAt, method, completed, remaining (ChallengeRequirement[]), attemptsLeft
    // … later, with the user's TOTP code:
    $result = $guard->challenges()->complete(new ChallengeFactorData(
        challengeToken: $pending->token,
        method: FactorMethod::Totp,
        context: $context,
        code: $request->input('code'),
    ));
}

Challenges are single-use and stored in the database, and each code attempt is counted before the code is checked, so parallel guesses get no extra tries.

Endpoints, per guard

The JSON endpoints are off until you switch them on, either with routes.enabled or explicitly:

// routes/api.php
Authentication::routes('users');                                      // defaults

Authentication::routes('clients')
    ->prefix('api/clients/auth')
    ->name('clients.auth.')
    ->middleware(['api'])
    ->authenticatedMiddleware(['authentication.active'])
    ->except(['registration', 'invitations.manage']);

A route exists only while its feature is enabled for that guard.

More than one kind of account

Scaffold a guard (model, migration, factory), then check it:

php artisan authentication:guard staff --model=StaffMember --no-passkeys
php artisan authentication:check staff

Guards share nothing: a users token on a clients route is a 401 even for the same primary key. Two-factor, passkeys, registration mode (open, invite-only or closed), verification and password rules are all set per guard.

Defaults we cared about

Password login, magic-link and email-code requests, and forgot password all answer the same way whether or not the address is registered.
Throttles take the attempt before the password is hashed, so concurrent guesses are all counted.
Emailed links and codes, invitations and challenges are single-use and stored only as keyed HMAC hashes.
By default a password, email or two-factor change ends the other sessions; the device that made the change gets a fresh token pair back.
Reusing a rotated refresh token kills that session and alerts the owner.

Testing

There is no Authentication::fake(), on purpose: the InteractsWithAuthentication helpers issue a real token pair, so tests hit the real guard, audience, denylist and token-version checks:

$this->actingAsAccount($user, 'users', [AuthMethodReference::Pwd]);   // a REAL token pair as the bearer
$this->assertLoginActivity('users', ActivityType::PasswordLogin, ActivityOutcome::Succeeded);
$this->assertTokensInvalidated($user, InvalidationReason::PasswordChanged);   // moved since actingAsAccount() (or pass `since:`)

Every write also fires an event, so Event::fake() covers the rest.

Social login and SSO

Neither ships in the package, but your existing SSO callback can vouch for the user and get the same token pair as any other login:

// SSO callback: the host vouches for the authentication
$pair = Authentication::guard('users')->issueTokens($user, $context, LoginMethod::Host, [AuthMethodReference::Mfa]);

Requirements

PHP ^8.4 (ext-bcmath, ext-mbstring, ext-openssl), Laravel 12 or 13, a cache store with atomic locks and a mail transport. MIT licensed. Runtime dependencies are only Laravel, Symfony and other Roundly packages, which Composer pulls in.

DEV Community: Andrej Mihaliak

Campaigns for Laravel — send one message to many recipients on queued job batches

What Campaigns for Laravel does

Install

Send a campaign

Prepare now, start later

Email, notifications or your own job

Change send defaults without a deploy

Events, commands and tests

Requirements

Links

Lifecycle for Laravel — Eloquent status transitions with quotas, expiry and rollbacks

What it does

Install

Define, attach, apply

Quotas that hold under concurrent requests

Expiry and scheduled transitions

Undo and history

Testing

Requirements

Links

Auth for Laravel — headless multi-guard login with 2FA, passkeys and JWT sessions

What it does

Installation

Usage

Finishing the second step

Endpoints, per guard

More than one kind of account

Defaults we cared about

Testing

Social login and SSO

Requirements

Links