Skip to content

Install

  • PHP 8.3–8.6 on the application host
  • Composer 2
  • Node.js 22 for the Cloudflare Worker toolchain
  • A Cloudflare account for deployment

See Compatibility for dependency constraints and tested versions. Your application and the Atoms CLI use host PHP. Atom classes, Support code, bundled shared code, migrations, and bundled dependencies execute in the Worker’s PHP 8.3 interpreter and must use PHP 8.3-compatible syntax.

The adapter accepts Laravel 11, 12 and 13. CI tests Laravel 12 and 13. See Laravel and Illuminate compatibility.

To create an application, follow New Laravel application.

Choose the adapter for the application you already have:

Terminal window
# Laravel
composer require atoms/laravel
# Symfony
composer require atoms/symfony
# Vanilla PHP
composer require atoms/client

Install the CLI for development and deployment:

Terminal window
composer require --dev atoms/cli

To use Eloquent inside your Atom (with Atom-specific models only!), you need to install a package that runs inside your Atom. See Eloquent and the query builder.

Add the static rules that protect the PHP↔Worker boundary:

Terminal window
composer require --dev atoms/phpstan-rules

Then include its configuration from your PHPStan config:

includes:
- vendor/atoms/phpstan-rules/rules.neon
Terminal window
vendor/bin/atoms init

The init command creates atoms.json and atoms-composer.json, and appends /.atoms/ and /.env.atoms.* to your .gitignore.

Create the Cloudflare Worker runtime:

Terminal window
npm exec --yes --package=@atomsphp/runtime-cloudflare -- \
atoms-runtime-cloudflare init atoms-worker
cd atoms-worker
npm ci
cd ..

Then fill in the generated atoms.json — at minimum a non-empty worker_name for each environment you deploy to. Declare a callback_url on that environment when its Worker must call app() or dispatch(); the deployed Worker URL belongs in the monolith’s independent ATOMS_ENDPOINT. See Configuration for every key, and for which settings belong in atoms-worker/wrangler.jsonc instead.

Values that belong to your machine rather than to the repository — a Cloudflare API token for local deploys, a callback URL pointing at your own tunnel — go in .env.atoms.<environment> beside atoms.json, which is the gitignored file init just made room for. It is optional; nothing needs one to start.

Continue with Laravel, Symfony, or plain PHP, then deploy the Worker.