Install

Pre-1.0

Atoms is currently experimental and in early stages. The goal is to keep the current atoms/core runtime API frozen and only add to it.

Requirements

• PHP 8.3 or 8.4 on the application host
• Composer 2
• Node.js 22 for the Cloudflare Worker toolchain
• A Cloudflare Workers Paid account

PHP

Choose the adapter for the application you already have:

# Laravel
composer require atoms/laravel

# Symfony
composer require atoms/symfony

# Vanilla PHP
composer require atoms/client

Install the CLI for development and deployment:

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.

Static Analysis

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

composer require --dev atoms/phpstan-rules:^0.6

Then include its configuration from your PHPStan config:

includes:
    - vendor/atoms/phpstan-rules/rules.neon

Initialize the project

vendor/bin/atoms init

The init command creates atoms.json and atoms-composer.json, and appends /.atoms/ and /.env.atoms.* to your .gitignore. It also prints a command that scaffolds the matching version of the Cloudflare Worker runtime:

npm exec --yes --package=@atomsphp/runtime-cloudflare@0.6.0 -- \
  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.

Next

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