Laravel quickstart
The maintained example lives at examples/laravel/. It is the executable companion to this guide.
The adapter accepts Laravel 11, 12 and 13. CI tests Laravel 12 and 13. See Laravel and Illuminate compatibility.
New Laravel application
Section titled “New Laravel application”Run these commands in the directory where you want to create atoms-demo:
composer create-project laravel/laravel atoms-democd atoms-democomposer require atoms/laravel --with-all-dependenciescomposer require --dev atoms/cli atoms/testing atoms/phpstan-rulesphp artisan atoms:installnpm exec --yes --package=@atomsphp/runtime-cloudflare -- \ atoms-runtime-cloudflare init atoms-worker(cd atoms-worker && npm ci)Continue with Configure callback replay protection.
For this quickstart, use Laravel’s generated SQLite database with the database
nonce driver and namespace atoms-demo:local, then run php artisan migrate.
You can instead use your configured Laravel database connection or the Redis
nonce driver, as described below.
Next, create the Atom, add its migration, and check it. Set the local endpoint and start Atoms before Laravel as shown in Run it locally.
Configure the adapter
Section titled “Configure the adapter”For an existing Laravel application, install the packages from the installation guide, then initialize Atoms and publish the adapter configuration:
php artisan atoms:installThe installer preserves an existing atoms.json, published adapter config,
and phpstan.atoms.neon, so you can also run it after atoms init. Skip this
section if you created a new application above.
For a deployed Worker, set:
ATOMS_ENDPOINT=https://your-atoms-worker.example.workers.devATOMS_SHARED_SECRET=base64-of-32-random-bytesATOMS_ENDPOINT is the application-side URL for ordinary Atom RPC.
ATOMS_SHARED_SECRET is required and must be identical on this application and the Worker. Set it on the Worker with vendor/bin/atoms shared-secret:set, not with atoms:install or secrets:set. See Secrets and authentication for generating it, what it authenticates, and how to rotate it.
Configure callback replay protection
Section titled “Configure callback replay protection”Choose a shared nonce store before accepting app() or dispatch() callbacks.
Atoms ships both database and Redis implementations. No custom storage class
or container binding is required.
Database
Section titled “Database”Set these application environment variables:
ATOMS_CALLBACK_NONCE_DRIVER=databaseATOMS_CALLBACK_NONCE_NAMESPACE=my-app:productionAtoms uses the application’s default Laravel database connection. To choose
another connection from config/database.php, set
ATOMS_CALLBACK_NONCE_DB_CONNECTION to its name. All callback workers must
reach the same database. SQLite needs a shared persistent file on one host.
The package registers its migration when the database driver is selected. Run your normal migration command before accepting callbacks:
php artisan migrateThis creates atoms_callback_nonces on the selected connection. Atoms opens a
separate connection for nonce writes so application transactions cannot undo
them. Schedule php artisan atoms:nonces:prune through Laravel’s scheduler to
remove expired records.
Configure a named Redis connection in Laravel’s config/database.php, then
select it:
ATOMS_CALLBACK_NONCE_DRIVER=redisATOMS_CALLBACK_NONCE_NAMESPACE=my-app:productionATOMS_CALLBACK_NONCE_REDIS_CONNECTION=atoms_noncesThe name atoms_nonces refers to your Laravel Redis connection. Configure its
URL, credentials, and database through Laravel’s normal Redis settings. Both
PhpRedis and Predis are supported. Use a dedicated Redis database or instance
that application cache clears do not flush. Redis handles expiry; no database
migration or pruning command is needed for this backend.
Retention and upgrades
Section titled “Retention and upgrades”The package’s config/atoms.php exposes callback_nonce settings for the
driver, namespace, connection, retention, and clock allowance. If you published
an older configuration, merge the new callback_nonce section into it when customizing these settings.
Rebuild Laravel’s configuration cache after changing environment values.
Leave ATOMS_CALLBACK_NONCE_RETENTION_SECONDS unset to derive retention from
atoms.callback_timestamp_window and
ATOMS_CALLBACK_NONCE_CLOCK_ALLOWANCE_SECONDS, which defaults to 60. The
callback guide explains the calculation and
rollout requirements.
An unconfigured store rejects callbacks with 503. Application boot and
outbound-only calls still work. ATOMS_CALLBACK_NONCE_DRIVER=memory explicitly
selects the development/test store; it does not protect callbacks across PHP
requests. Existing custom NonceStore bindings remain supported.
Create an Atom
Section titled “Create an Atom”php artisan make:atom GameRoom<?php
namespace App\Atoms;
use Atoms\Atom;
/** @extends Atom<\Atoms\AtomMethods> */class GameRoom extends Atom{ public function join(string $playerId): int { return $this->db()->transaction(function (\Atoms\Database $db) use ($playerId): int { $db->execute( 'INSERT INTO players (player_id, visits) VALUES (?, 1) ' . 'ON CONFLICT(player_id) DO UPDATE SET visits = visits + 1', [$playerId], );
return (int) $db->query( 'SELECT visits FROM players WHERE player_id = ?', [$playerId], )[0]['visits']; }); }}Create app/Atoms/GameRoom/migrations/001_create_players.sql with this SQL:
CREATE TABLE players ( player_id TEXT PRIMARY KEY, visits INTEGER NOT NULL DEFAULT 0);Call it
Section titled “Call it”The facade returns a typed RPC proxy. The Atom id is the durable identity:
use App\Atoms\GameRoom;use Atoms\Laravel\Facades\Atoms;
$count = Atoms::get(GameRoom::class, 'room-42')->join('ada');Test it without Cloudflare
Section titled “Test it without Cloudflare”Use atoms/testing for fast local tests of Atom behavior, migrations, callbacks, broadcasts, and timers:
composer require --dev atoms/testinguse App\Atoms\GameRoom;use Atoms\Testing\AtomHarness;
$room = AtomHarness::for(GameRoom::class, 'room-42');
self::assertSame(1, $room->invoke('join', ['ada']));self::assertSame(2, $room->invoke('join', ['ada']));Check the Atom
Section titled “Check the Atom”php artisan atoms:install creates phpstan.atoms.neon with the Atoms rules,
analysis level 8, and source paths from atoms.json. Your application’s existing
PHPStan configuration is unchanged. Commit the generated file; later installer
runs preserve any edits you make to it.
Run validation and static analysis:
vendor/bin/atoms validatevendor/bin/phpstan analyse --configuration=phpstan.atoms.neonThe rules check which types can pass between Atoms and your application. They also detect uses of PHP time functions that are unsafe when the clock does not advance inside a turn.
Run it locally
Section titled “Run it locally”Set the application endpoint in .env before starting either process:
ATOMS_ENDPOINT=http://127.0.0.1:8787Start the local Worker in one terminal:
vendor/bin/atoms dev --env staging --callback-url http://127.0.0.1:8000/atoms/callbackOnce it is ready, start Laravel in another terminal:
PHP_CLI_SERVER_WORKERS=4 php artisan serve --host=127.0.0.1 --port=8000 --no-reloadLaravel needs at least two workers when an HTTP request invokes an Atom that calls back with $this->app(). One handles the waiting request; another handles the callback. Keep --no-reload so Laravel honors PHP_CLI_SERVER_WORKERS, and restart it after changing .env.
PHP CLI server workers are for local development and require process forking. On native Windows, run both processes in WSL2, or use Nginx with PHP-FPM configured for at least two concurrent requests. If the processes run in separate containers or hosts, replace the loopback callback URL with an address the Worker can reach.
atoms dev creates a shared secret in .env if needed and copies it to the Worker’s .dev.vars. Start Laravel afterward so it reads that value. No Cloudflare account is needed.
--env selects an environment from atoms.json; --callback-url overrides its callback address. See the CLI reference for other options and how settings are resolved.
Verify two calls
Section titled “Verify two calls”With both servers running, open a third terminal in the application root:
php artisan tinkerRun these calls in Tinker:
\Atoms\Laravel\Facades\Atoms::get(\App\Atoms\GameRoom::class, 'quickstart-1')->join('ada');\Atoms\Laravel\Facades\Atoms::get(\App\Atoms\GameRoom::class, 'quickstart-1')->join('ada');A new identity returns 1, then 2. Repeating the calls increments the
stored count. Use a new identity if you want to repeat the initial result.
Build and deploy
Section titled “Build and deploy”vendor/bin/atoms validatevendor/bin/atoms buildvendor/bin/atoms deploy --env productionSee Deploy for credentials, callback configuration, and propagation behavior.
Through Artisan
Section titled “Through Artisan”The service provider registers wrappers for the commands you run most:
atoms:deploy, atoms:dev, atoms:rollback, atoms:list, atoms:install
and make:atom. Each shells out to the same atoms binary and forwards your
options, so php artisan atoms:deploy --env production and
vendor/bin/atoms deploy --env production resolve identically.
Identically is the deliberate part. Artisan runs after Laravel has loaded your
application’s .env, and the wrapper hands the child the environment the
command was started with rather than the one the framework built — so a
local ATOMS_CALLBACK_URL in your .env is not a deployment input, while one
from your shell or from CI still is. Note also that Laravel reads its own
--env off the command line, so --env production makes it load
.env.production; that no longer decides anything on the Atoms side. See
Framework
commands.