pushinbr / nimbus
Nimbus: the API-first PHP framework for the PAM runtime.
Requires
- php: ^8.4
- pushinbr/pam-contracts: ^1.1
Requires (Dev)
- dragonmantank/cron-expression: ^3.4
- fakerphp/faker: ^1.24
- firebase/php-jwt: ^7.0
- league/flysystem: ^3.29
- league/oauth2-client: ^2.8
- phpstan/phpstan: ^2.1
- phpunit/phpunit: ^11.5
- psr/http-client: ^1.0
- psr/http-factory: ^1.1
- psr/http-message: ^2.0
- pushinbr/arcano: ^0.2.6
- symfony/mailer: ^7.3
- symfony/mime: ^7.3
- symfony/translation: ^7.3
Suggests
- ext-curl: HTTP/2 transport of the APNs push provider and fallback HTTP client outside PAM.
- ext-openssl: Signs the FCM and APNs tokens of the push notification channel.
- dragonmantank/cron-expression: Required by the scheduler (Nimbus\Scheduling).
- fakerphp/faker: Fake data in Nimbus\Database\Factory definitions.
- firebase/php-jwt: JWT access tokens (Nimbus\Auth\JwtCodec: HS256/RS256/ES256, JWKS).
- league/flysystem: Required by Nimbus\Storage (StorageManager, Disk, local disks).
- league/flysystem-aws-s3-v3: S3 disks and presigned uploads in Nimbus\Storage.
- league/oauth2-client: Social login (Nimbus\Auth\OAuth\SocialLogin); add provider packages such as league/oauth2-google or league/oauth2-github.
- psr/http-client: Send push and webhook notifications through any PSR-18 client (Psr18HttpClient).
- psr/log: PSR-3 logging; LoggerInterface resolves to the PAM runtime structured log.
- pushinbr/arcano: Required by the Arcano ORM integration (ArcanoServiceProvider, ArcanoManager).
- pushinbr/pam-http-psr: PSR-7, PSR-15 and PSR-17 interoperability.
- pushinbr/pam-socket: High-level event and room APIs for Pam WebSockets.
- symfony/mailer: Required by the mail notification channel (Nimbus\Notifications\Mail\MailChannel).
- symfony/translation: Translations from lang/ directories (Nimbus\Translation\Translator, __() and trans()).
Provides
None
Conflicts
- pushinbr/arcano: <0.2.3
Replaces
None
README
The API-first PHP framework for the PAM runtime: a Laravel-like application structure, one routes file, the Arcano ORM, and persistent PAM workers.
Official documentation · PAM introduction · Upgrade guide · Changelog · Architecture · Report an issue
Start here
Nimbus is a Composer package for the PAM runtime; it is not a standalone server. Install PAM first, open your application directory, and let PAM run Composer for you:
pam composer require pushinbr/nimbus
Routes live in one file, routes.php, which receives the router as $router:
use App\Controllers\ProductController; use Nimbus\RouteRegistrar; $router->get('ping', fn ($request, $response) => $response->json(['pong' => true])); $router->controller(ProductController::class, function (RouteRegistrar $router): void { $router->get('products', 'index'); $router->get('products/{product}', 'show'); $router->post('products', 'store'); }); // index, store, show, update and destroy, plus extras bound to the same controller $router->resource('users', UserController::class, function (RouteRegistrar $users): void { $users->post('{user}/ban', 'ban'); });
// index.php $app = new Nimbus\App(); $app->routes(__DIR__ . '/routes.php'); $app->listen(3000);
Standalone routes keep [Controller::class, 'method']; where(), name() and
middleware() chain on any route.
Controllers are resolved through the container. Both constructor dependencies and action parameters are injected:
final readonly class LoginController { public function __construct(private LoginService $login) {} public function onLogin(LoginRequest $request): AuthResource { return new AuthResource($this->login->handle($request->validated())); } }
Arcano ORM (optional)
Arcano is the PAM data mapper, derived from Cycle ORM: attribute entities, relations, an identity map, migrations and SQLite, MySQL, PostgreSQL and SQL Server drivers. Nimbus keeps its kernel independent from any database; install Arcano when the application needs one:
pam composer require pushinbr/arcano
Entities are plain classes with attributes:
use Arcano\Annotated\Annotation\{Column, Entity}; use Arcano\Annotated\Annotation\Relation\HasMany; #[Entity(role: 'author')] class Author { #[Column(type: 'primary')] public ?int $id = null; #[Column(type: 'string(120)')] public string $name = ''; /** @var list<Post> */ #[HasMany(target: Post::class, collection: 'array')] public array $posts = []; }
The provider compiles the entities of a directory and keeps the schema in a PHP
cache file. In development the cache is rebuilt when an entity file changes; in
production pass refresh: false and build the cache during deployment.
use Nimbus\Database\{ArcanoSchemaCompiler, ArcanoServiceProvider, DatabaseConfig}; $app->provider(new ArcanoServiceProvider( DatabaseConfig::fromEnvironment(), new ArcanoSchemaCompiler(__DIR__ . '/src/Entities', __DIR__ . '/var/arcano-schema.php', refresh: $debug), migrations: __DIR__ . '/database/arcano', ));
A compiled schema array (or Arcano\ORM\Schema) is accepted in place of the
compiler. The same DB_* variables configure the connection.
Every request Fiber gets its own connections and identity map, so transactions
and loaded entities cannot leak between persistent-worker requests. Request
cleanup rolls back unfinished transactions and disconnects. Resolve
ArcanoManager to work with entities:
$arcano = $app->container()->get(ArcanoManager::class); $author = $arcano->select(Author::class)->load('posts')->wherePK($id)->fetchOne(); $author->name = 'Ada'; $arcano->entityManager()->persist($author)->run();
Migrations
ArcanoMigrationManager writes migrations from the difference between the
entities and the database, runs them and rolls them back. Each migration runs
in its own transaction and is recorded in the migrations table.
$migrations = $app->container()->get(ArcanoMigrationManager::class); $migrations->generate(); // new files in database/arcano for the changed entities $migrations->migrate(); // runs the pending ones, returns their names $migrations->rollback(1); // reverts the last one $migrations->status(); // name, created_at, executed_at of every migration
Generated files can be edited, and migrations can be written by hand with the
Arcano\Migrations\Migration table API. Generation requires every existing
migration to have run, so the database reflects them.
Transactions, budgets and tenants
ArcanoManager is the TransactionManager of the application, and
DatabaseHealthCheck and QueryMonitor budgets read its connections.
Tenant-owned roles are protected once during boot with
$arcano->protectTenant(Order::class): selects are limited to the current
tenant, new entities get its key, and both fail closed without a TenantContext.
Connections, health and query budgets
Configure DB_CONNECTION (pgsql, mysql, sqlite or sqlsrv) and the
usual DB_HOST, DB_PORT, DB_DATABASE, DB_USERNAME and DB_PASSWORD
variables, read by DatabaseConfig::fromEnvironment(). PostgreSQL is the
production default; SQLite is convenient for tests. Each request Fiber gets its
own connections; request cleanup rolls back unfinished transactions and
releases them. Register DatabaseHealthCheck in a HealthRegistry for
readiness checks; its result reports latency and failure class without exposing
credentials.
Use QueryBudgetMiddleware during development and in performance-sensitive
routes to cap query count, accumulated database time and repeated SQL patterns:
$app->middleware(new QueryBudgetMiddleware( monitor: $app->container()->get(QueryMonitor::class), budget: new QueryBudget( maximumQueries: 30, maximumElapsedMilliseconds: 100, maximumDuplicateQueries: 3, ), failOnViolation: true, ));
Budgets are Fiber-local. Violations use the sequential integer-backed
QueryBudgetViolation enum, making them stable for CI reports and telemetry.
Route groups
$app->prefix('/api/v1') ->middleware(Authenticate::class) ->group(function (RouteRegistrar $routes): void { $routes->apiResource('/users', UserController::class); $routes->post('/login', [LoginController::class, 'onLogin']); });
Global, group and route middleware use the same PAM middleware contract.
head() and options() are available on both App and RouteRegistrar.
When no explicit OPTIONS route exists, PAM returns 204 with a deterministic
Allow header; every GET route automatically advertises and matches HEAD.
PAM suppresses the final HEAD body after middleware and error handling while
preserving its status and headers. An explicit OPTIONS or HEAD handler
always takes precedence.
Router configuration is bounded before the application freezes: 10,000 routes by default (configurable up to 100,000), 2 KiB paths, 128 segments, 32 route parameters and 512-byte custom constraints. Compiled patterns carry PCRE match and depth budgets, and oversized untrusted request paths bypass PCRE entirely.
Container lifetimes
$app->container()->bind(UserRepository::class, DatabaseUserRepository::class); $app->container()->singleton(Cache::class, RedisCache::class); $app->container()->scoped(CurrentUser::class);
scoped values are created once per request and discarded even when the
handler throws. This boundary is essential for PAM's persistent workers.
Typed configuration
Define configuration once and fail during boot when required environment is missing or malformed:
$config = Configuration::fromEnvironment([ new ConfigDefinition('app.port', 'PAM_PORT', ConfigType::Integer), new ConfigDefinition('auth.secret', 'AUTH_SECRET', sensitive: true), ]); $port = $config->integer('app.port');
Supported types are represented by the sequential integer-backed ConfigType
enum. Diagnostics should use $config->redacted(), which deterministically
masks sensitive values. Validation errors name the variable and expected type
without including its supplied value.
Validation and resources
final class LoginRequest extends FormRequest { public function rules(): array { return [ 'email' => ['required', 'string', 'email'], 'type' => ['required', Rule::enum(UserType::class)], ]; } } enum UserType: int { case Regular = 1; case Administrator = 2; }
Return a JsonResource from a handler to receive a consistent data envelope.
Validation failures use Problem Details with stable sequential integer codes.
Problem Details
Routing failures, HttpException instances and unexpected exceptions use one
safe Problem Details envelope with application/problem+json:
{"type":"https://pam.dev/problems/5","title":"Version conflict.","status":409,"code":5}
Exception details may add domain fields but cannot replace type, title,
status or code. Unexpected exception messages are logged and never returned
to the client. 405 responses retain their deterministic Allow header and
use the sequential MethodNotAllowed=9 problem code.
Quality gate
composer install composer verify
The verification gate runs PHPStan at level 9 and the PHPUnit suite on every
supported PHP version. It also compares all public classes, interfaces, enums,
methods, parameters, properties and constants against api-surface.json:
composer api:compat
The gate rejects unreviewed additions as baseline drift and rejects removed
symbols/members, signature changes, new interface methods, newly abstract/final
contracts and enum changes as incompatibilities. Run bin/api-compat update
after approving a compatible public addition. A breaking baseline update is
reserved for an intentional major version whose migration guide and changelog
are ready.
The same reviewed baseline generates the complete
public API reference. composer verify rejects stale
reference output; regenerate it only after explicitly accepting compatible API
additions:
composer docs:generate
See the Nimbus design and delivery contract for the complete 15-track implementation plan and current delivery status.
Distributed rate limiting
RateLimitMiddleware uses a bounded in-memory token bucket by default and
accepts any RateLimitStore for process-wide or distributed enforcement:
$app->middleware(new RateLimitMiddleware( requestsPerSecond: 20, burst: 40, store: $redisRateLimitStore, keyResolver: static fn (Request $request): string => 'token:' . $request->getHeader('authorization', 'anonymous'), ));
The middleware emits limit/remaining/retry headers and a Problem Details 429
response. Applications behind proxies must supply a key resolver that trusts
only their explicitly configured proxy boundary.
Signed bearer tokens
HmacTokenCodec provides a strict HS256 access-token foundation with bounded
token/payload sizes, constant-time signature and issuer/audience checks,
iat/nbf/exp validation, unique token IDs and abilities:
$tokens = new HmacTokenCodec( secret: $secretFromYourSecretManager, issuer: 'https://auth.example.com', audience: 'orders-api', ); $app->middleware(new AuthenticateMiddleware( new BearerTokenAuthenticator($tokens), $app->container(), ));
Set keyIdentifier on the active signing key and pass at most four retiring
keys through verificationKeys for bounded zero-downtime rotation. Unknown
kid values fail closed before claims are trusted. BearerTokenAuthenticator
also accepts a TokenRevocationStore; MemoryTokenRevocationStore is bounded
and intended for development/tests, while clustered applications should back
the contract with an atomic shared store.
Signing secrets must contain at least 32 bytes and must not be stored in source control. Access tokens are capped at 24 hours; renew them with the rotating refresh tokens below rather than issuing long-lived access tokens.
API authentication
Publish the tables once (personal_access_tokens, refresh_tokens,
auth_tokens, revoked_tokens, oauth_states):
$migrations->publish('create_auth_tables', \Nimbus\Auth\AuthTablesMigration::class);
Every stored token is the SHA-256 of a 256-bit random secret, compared in constant time; plain tokens exist only in the response that hands them out.
Personal access tokens
$tokens = new PersonalAccessTokens($databases); // ArcanoDatabaseProvider $new = $tokens->create('user:42', 'CLI', ['products:read', 'products:write']); return $response->json($new->toArray(), 201); // shows the plain token once $app->container()->instance(Authenticator::class, new PersonalAccessTokenAuthenticator($tokens)); $app->post('/products', CreateProduct::class)->can('products:write');
Tokens read nbp_{id}.{secret}, may expire (expiresAt), record
last_used_at (at most once a minute) and are revoked with revoke($id) or
revokeAll($subject). Abilities accept * and namespace wildcards
(products:*, orders.*). ChainAuthenticator combines authenticators, e.g.
JWT access tokens first and personal tokens next.
Access and refresh tokens
$pairs = new TokenPairIssuer($codec, new RefreshTokens($databases), accessTtlSeconds: 900); $pair = $pairs->issue('user:42', ['orders:read']); // after checking the password with Hash::check() return $response->json($pair->toArray()); // token_type, access_token, expires_in, refresh_token, scope
$codec is an HmacTokenCodec or a JwtCodec. refresh() spends the refresh
token and returns a new pair of the same family; a spent token presented again
revokes the whole family (reuse detection) and answers 401.
RefreshTokens::revokeAll($subject) logs a user out everywhere. Revoke a
stateless access token by its jti (TokenPrincipal::$tokenIdentifier) in a
shared TokenRevocationStore: DatabaseTokenRevocationStore or
Nimbus\Redis\RedisTokenRevocationStore (the memory store is per worker).
JWT
JwtCodec wraps firebase/php-jwt (composer require firebase/php-jwt):
$jwt = JwtCodec::hmac($secret, 'https://api.example.com', 'orders-api'); // HS256/384/512 $jwt = JwtCodec::asymmetric($publicPem, $privatePem, $issuer, $audience, 'ES256'); // RS256, ES256, EdDSA $jwt = JwtCodec::fromJwks($jwksDocument, 'https://idp.example.com', 'orders-api'); // verify only $app->container()->instance(Authenticator::class, new JwtAuthenticator($jwt, $revocations));
Keys are bound to their algorithm and tokens must carry kid, iss, aud,
sub and exp. Abilities travel in the scope claim (scp and abilities
arrays are accepted). JwtCodec::fromKeySet(new CachedKeySet(...)) verifies
against a remote JWKS cached through PSR-18/PSR-6.
Social login
SocialLogin runs the authorization-code flow of any league/oauth2-client
provider for API clients: GET /auth/oauth/{provider} returns
authorization_url and state, the state and PKCE verifier stay on the
server, and POST /auth/oauth/{provider}/callback (code, state) exchanges
the code and returns a Nimbus token.
$social = new SocialLogin( ['google' => new Google([...]), 'github' => fn () => new Github([...])], new DatabaseOAuthStateStore($databases), // or Nimbus\Redis\RedisOAuthStateStore $app->container()->get(SocialUsers::class), // your SocialUserResolver: find or create the user $pairs, // any LoginTokenIssuer abilities: ['*'], );
Password reset and e-mail verification
Implement AuthUser on the user and AuthUserProvider on its repository, then
register the routes:
$oneTime = new OneTimeTokens($databases); (new AuthRoutes( passwords: new PasswordResets($users, $oneTime, $notifier, 'https://app.example.com/reset?token={token}', afterReset: fn (AuthUser $user) => $refreshTokens->revokeAll($user->authIdentifier())), verification: new EmailVerification($users, $oneTime, $notifier, 'https://app.example.com/verify?token={token}'), tokens: $pairs, social: $social, throttleStore: new RedisRateLimitStore($redis), ))->register($app, '/auth');
| Route | Body | Answer |
|---|---|---|
POST /auth/password/forgot |
email |
202, the same for unknown addresses |
POST /auth/password/reset |
token, password |
204 or 422 |
POST /auth/email/verify |
token |
204 or 422 |
POST /auth/email/resend |
authenticated | 202 |
POST /auth/token/refresh |
refresh_token |
token pair or 401 |
POST /auth/token/revoke |
refresh_token |
204 |
Reset and verification tokens are single-use, expire (one hour and one day by
default) and replace the user's previous token. Links go out through the
Notifications module with send(), never queued, so tokens stay out of job
payloads; pass notification: to customise the MailMessage. Each user gets
at most one e-mail a minute and every route is rate limited per client IP.
New passwords are stored with Nimbus\Security\Hash.
Gates and policies
$gate = $app->gate(); $gate->before(fn (Principal $user, string $ability) => $user->identifier() === 'user:1' ? true : null); $gate->define('reports:export', fn (Principal $user) => $user->can('reports:*')); $gate->policy(Product::class, ProductPolicy::class); // update(Principal $user, Product $product): bool $app->put('/products/{product}', UpdateProduct::class)->can('update', 'product'); $app->get('/products', ListProducts::class)->can('view-any', Product::class); $app->post('/products', CreateProduct::class)->can('products:write');
can($ability, 'product') resolves the route parameter through bindRoute()
or RouteBindable and asks the policy method named after the ability
(view-any calls viewAny); policies are built by the container and may have
their own before(). Abilities without a policy or definition fall back to
the principal's can(), i.e. the token's abilities, so a policy can also
demand a scope ($user->can('products:write')). In handlers,
$gate->authorize('update', $product) throws 403 problem details
(401 without a principal); allows() and denies() return booleans.
File storage
Nimbus\Storage puts named disks over league/flysystem
v3. Nimbus does not require it: install league/flysystem for local disks and
league/flysystem-aws-s3-v3 for S3 (also AWS-compatible stores such as MinIO and R2).
$app->provider(new StorageServiceProvider( StorageConfig::fromEnvironment(), routes: '/files', // opt-in signed upload and download routes for local disks )); $disk = $app->storage()->disk(); // FILESYSTEM_DISK, `local` by default $disk->put('avatars/42.png', $bytes); $disk->get('avatars/42.png'); $disk->url('avatars/42.png'); // STORAGE_URL / AWS_URL prefix, or the S3 object URL $disk->temporaryUrl('invoices/7.pdf', 300); // download URL valid for 5 minutes
StorageConfig::fromEnvironment() defines local from STORAGE_ROOT (default ./storage)
and STORAGE_URL, and s3 when AWS_BUCKET is set (AWS_DEFAULT_REGION, AWS_ENDPOINT,
AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_USE_PATH_STYLE_ENDPOINT, AWS_URL).
APP_URL prefixes the signed routes. Pass an array of disks to the constructor for more,
or wrap any flysystem operator with StorageManager::filesystem($name, $operator). A
Disk is injectable and resolves to the default disk; Disk::filesystem() exposes the
flysystem operator for listing, moving and visibility.
Direct uploads
temporaryUploadUrl() returns a URL the client sends the file to with PUT, so the
upload does not pass through your handler:
$app->post('/avatars', static fn (Disk $disk, Response $response): Response => $response->json([ 'upload' => $disk->temporaryUploadUrl('avatars/42.png', ttl: 600, maxBytes: 2_000_000, contentType: 'image/png'), ]));
On S3 the URL is a presigned PutObject from the AWS SDK; S3 binds the content type
but cannot cap the size of a presigned PUT, so check Disk::size() once the client
reports the upload. On local disks it points at PUT {routes}/upload, which answers
413 above maxBytes, 415 for another content type and 403 for a tampered or
expired URL, then writes the body and answers 201 with {disk, path, size}. The
runtime buffers request bodies up to the maxBodyBytes listen option (2 MiB by
default); raise it for larger local uploads or use S3. GET {routes}/download streams
the file behind a local temporaryUrl().
Signed URLs
UrlSigner signs a path and its query with HMAC-SHA256 under a key derived from
APP_KEY; changing the path, any parameter or the expiry invalidates the signature,
which is compared in constant time. signed() guards a route or a group and answers
403 with problem code InvalidSignature:
$signer = $app->container()->get(UrlSigner::class); $link = $signer->temporary('/reports/7', ttl: 3600, query: ['format' => 'csv']); $app->get('/reports/{id}', ReportController::class)->signed();
Production building blocks
Nimbus exposes small, replaceable contracts instead of choosing application infrastructure:
- authenticators, principals and ability checks;
- idempotency and response-cache stores;
- request-scoped tenant resolution;
- transactions, events and bounded jobs;
- retry, circuit breakers and cooperative deadlines;
- normalized observations, health checks and scope diagnostics.
Shared production state belongs in atomic Redis/database/broker adapters. The included memory stores are bounded and intended for development and tests.
JobQueue defines reservation leases, acknowledgement, delayed release and
dead-letter transitions for durable adapters. The bounded memory implementation
and JobWorker exercise the same at-least-once lifecycle in tests:
$queue = new MemoryJobDispatcher(); $queue->dispatch(new SendInvoice($invoiceId), maximumAttempts: 3); $worker = new JobWorker( $queue, static fn (object $job): JobOutcome => JobOutcome::Complete, ); $worker->runOne();
Attempts increment when a lease is reserved. Expired leases can be reclaimed; exceptions and explicit retry outcomes release the job with a bounded delay, and exhausted jobs enter the dead-letter set. Only failure class names are retained, never exception messages that may contain application data.
Cross-process adapters should encode only SerializableJob implementations
through JobCodec. The codec uses an explicit name-to-class allowlist, a
versioned JSON envelope, a 64 KiB size limit and a depth limit. It never accepts
PHP serialized objects or client-supplied class names.
Queues and the scheduler
Two durable JobQueue drivers share the memory queue's lifecycle and add a
failed-jobs store (FailedJobRepository: failed(), retryFailed(),
forgetFailed()). Both accept only SerializableJob jobs, encoded by JobCodec.
$codec = new JobCodec([SendInvoice::class, SendReport::class]); $queue = new RedisJobQueue(RedisPool::fromEnvironment(), $codec, queue: 'default'); // or, with the Arcano integration: $queue = new DatabaseJobQueue($databases, $codec, queue: 'default'); $queue->dispatch(new SendInvoice($invoiceId), maximumAttempts: 5, delaySeconds: 60); $worker = new JobWorker( $queue, new InvokableJobHandler($app->container()), // calls $job->handle(...) with injection leaseSeconds: 60, retryPolicy: new ExponentialBackoff(baseSeconds: 5, maximumSeconds: 3_600), );
- Redis: pending jobs are a sorted set scored by availability (delays and
retries need nothing else); a reservation moves the job to a lease set. Every
transition is one Lua script, and keys share a
{queue}hash tag for Redis Cluster. - Database: tables
jobs,failed_jobsandscheduler_locks. Publish the migration once, then migrate:$migrations->publish('create_queue_tables', QueueTablesMigration::class). Postgres and MySQL reserve withSELECT ... FOR UPDATE SKIP LOCKED; SQLite (and SQL Server) reserve with a compare-and-swap update. - A worker that dies mid-job leaves its lease to expire and the job returns to the queue; a stale worker cannot complete or release a job someone else took over, because every transition checks the attempt count of its reservation. A job whose last attempt expired, a dead-lettered job and a payload that no longer decodes all land in the failed jobs, with the exception class only.
ExponentialBackoffdoubles the delay per attempt up to a ceiling, with equal jitter (between half and all of the delay) by default.
The scheduler needs dragonmantank/cron-expression
(composer require dragonmantank/cron-expression):
$schedule = new Schedule($queue, timezone: 'America/Sao_Paulo', container: $app->container()); $schedule->job(SendReport::class)->cron('0 * * * *'); $schedule->job(new PruneSessions())->dailyAt('03:00'); $schedule->call(fn () => $cache->prune())->everyFiveMinutes()->withoutOverlapping()->name('prune-cache'); $app->background() ->scheduler(new Scheduler($schedule, new RedisSchedulerLock(RedisPool::fromEnvironment()))) ->queue($worker);
Frequencies: cron(), everyMinute(), everyTwoMinutes(), everyFiveMinutes(),
everyTenMinutes(), everyFifteenMinutes(), everyThirtyMinutes(), hourly(),
hourlyAt(), daily(), dailyAt(), weekly(), weeklyOn(), monthly(),
monthlyOn(), plus timezone() per task. Each due task first claims its
(task, minute) key in the SchedulerLock, so it runs once per minute however
many workers or servers tick: use RedisSchedulerLock or DatabaseSchedulerLock
whenever more than one process runs the scheduler; MemorySchedulerLock (the
default) only covers one. withoutOverlapping() also skips a run while the
previous one holds its lock. Task names identify them across processes; jobs are
named after jobName() and callbacks after their file and line, so name
callbacks with name() when that is not stable.
Running inside PAM
No system cron and no extra process: start the server with task workers and the scheduler and queue run on them.
pam start index.php --workers 4 --task-workers 1
The PAM master sends one tick per second to the task-worker pool, authenticated
by the cluster's token and never two at once. App::handle() answers it by
calling Background::tick(), which runs the scheduler and then drains the queue
for at most 100 jobs or 0.8 s, so the next tick is not held up. HTTP workers never
run background work, and the tick header from public traffic is ignored.
Without task workers (a plain php process, a separate container), run the same
Background as a loop; it sleeps through Pam\Async\delay() under PAM and stops
on SIGTERM or SIGINT:
$background->run(intervalSeconds: 1.0); ## Web: sessions, CSRF, views and translation (optional) API apps need none of this. For server-rendered pages, register the providers: ```php use Nimbus\Http\CookieCodec; use Nimbus\Redis\RedisSessionStore; use Nimbus\Session\SessionServiceProvider; use Nimbus\Translation\TranslationServiceProvider; use Nimbus\View\ViewServiceProvider; $app->provider(new SessionServiceProvider(new RedisSessionStore($redis), cookies: CookieCodec::fromEnvironment())); $app->provider(new TranslationServiceProvider(__DIR__ . '/lang', 'pt_BR')); $app->provider(new ViewServiceProvider(__DIR__ . '/resources/views'));
SessionServiceProvider adds, in order, method override (_method), encrypted cookies, the session
and CSRF checks. Sessions are stored as JSON in Redis, the database (SessionTablesMigration), files
or memory, and are only written when the request used them. Inject Session (flash data, old input,
errors, regenerate()), CookieJar and RequestCookies; SessionAuthenticator::login() regenerates
the session id. CSRF accepts _token, X-CSRF-TOKEN or X-XSRF-TOKEN and skips bearer requests.
Templates live in resources/views/**/*.nim.php and are compiled once per worker:
<x-layout title="Products"> @foreach ($products as $product) <x-card :product="$product" class="mb-4"> <x-slot:footer>{{ __('products.price', ['value' => $product->price]) }}</x-slot> </x-card> @endforeach <form method="POST" action="/products">@csrf <input name="name" value="{{ old('name') }}"> @error('name') {{ $message }} @enderror </form> </x-layout>
// resources/views/components/card.nim.php @props(['product']) <div {{ $attributes->merge(['class' => 'card']) }}>{{ $product->name }} {{ $footer ?? '' }}</div>
Return view('products.index', ['products' => $products]) (or $views->make() from an injected
ViewFactory) from a route. Class components extend Nimbus\View\Component in app/Views/.
vendor/bin/nimbus-views check compiles every template and fails with file:line: message.
Translations come from lang/{locale}/*.php and lang/{locale}.json (__('messages.welcome', ['name' => $name]), trans_choice()); the locale is per request (?lang=, session, Accept-Language).
Admin panel over Arcano (optional)
Nimbus\Admin serves CRUD pages for Arcano entities, with the fields read from their #[Column]
attributes and belongs-to relations:
use Nimbus\Admin\Admin; Admin::panel($app, '/admin', loginUrl: '/login') ->resource(ProductAdmin::class) // an AdminResource subclass ->resource(Category::class); // or just the entity, with the defaults $app->gate()->define('viewAdmin', static fn (User $user): bool => $user->isAdmin);
Lists have search, filters (booleans, selects, belongs-to), sorting, pagination and bulk actions;
forms validate through the field rules (column size, #[Max]/#[Min]/... on the entity) or an
Input class. Every route needs viewAdmin; with a Gate policy the entity also needs viewAny,
create, update and delete. It requires the session (CSRF) and an Authenticator; templates are
.nim.php with a solid CSS (light and dark) and an optional 2 KB script. pam make:admin Product
creates app/Admin/ProductAdmin.php.
Notifications
Nimbus\Notifications sends one Notification through the channels its
via() returns: mail, push, database and webhook, or channels of your
own (NotificationChannel). Recipients implement Notifiable; the
RoutesNotifications trait reads routeNotificationFor<Channel>() methods, an
email property for mail and an id property for the stored key.
final class InvoicePaid extends Notification { public function __construct(private readonly Invoice $invoice) {} public function via(Notifiable $notifiable): array { return ['mail', 'push', 'database', 'webhook']; } public function toMail(Notifiable $notifiable): MailMessage { return MailMessage::make() ->subject("Invoice {$this->invoice->number} paid") ->greeting('Hello') ->line('We received your payment.') ->action('View invoice', $this->invoice->url); } public function toPush(Notifiable $notifiable): PushMessage { return PushMessage::make('Invoice paid', $this->invoice->number) ->data(['invoice' => $this->invoice->id]) ->collapseKey('invoices'); } public function toDatabase(Notifiable $notifiable): array { return ['invoice' => $this->invoice->id, 'amount_in_cents' => $this->invoice->amountInCents]; } public function toWebhook(Notifiable $notifiable): WebhookMessage { return WebhookMessage::make(['invoice' => $this->invoice->id])->event('invoice.paid'); } } $sender = new NotificationSender([ 'mail' => MailChannel::fromEnvironment(), 'push' => new PushChannel( FcmProvider::fromServiceAccountFile('/run/secrets/firebase.json'), ApnsProvider::fromKeyFile('TEAMID', 'KEYID', '/run/secrets/apns.p8', 'com.example.app'), onInvalidToken: static fn (PushTarget $target) => $devices->forget($target->token), ), 'database' => new DatabaseChannel($databases), 'webhook' => new WebhookChannel((string) getenv('WEBHOOK_SECRET')), ]); $notifier = new Notifier($sender, $queue); $notifier->send($user, new InvoicePaid($invoice)); // now $notifier->sendLater($users, new InvoicePaid($invoice)); // one job per user and channel
Register SendNotificationJob in your JobCodec and run SendNotificationHandler
in a JobWorker. Channels render the notification when it is queued, so the job
payload is plain JSON and the worker never reloads the notifiable. Retryable
failures (timeouts, HTTP 408/429/5xx, SMTP errors) return JobOutcome::Retry;
permanent ones (other 4xx, invalid addresses) are dead-lettered. Override
maximumAttempts() and delaySeconds() on the notification to tune them.
- Mail uses
symfony/mailer(composer require symfony/mailer).MailChannel::fromEnvironment()readsMAILER_DSN, orMAIL_MAILERas a DSN orsmtpwithMAIL_HOST/MAIL_PORT/MAIL_USERNAME/MAIL_PASSWORD, andMAIL_FROM_ADDRESS/MAIL_FROM_NAME. The route is an address, a list, or anaddress => namemap.html()andtext()replace the generated bodies. - Push routes are
PushTargetobjects orfcm:<token>/apns:<token>strings. FCM uses HTTP v1 with the service account (RS256 assertion, OAuth2 token cached per worker until five minutes before expiry). APNs uses token authentication (ES256 JWT reused for 50 minutes) over HTTP/2. Unregistered tokens are reported toonInvalidTokeninstead of failing the delivery. - Database writes to the
notificationstable ofdatabase/migrations/20261119.000000_0_create_notifications.php(copy it into your migrations directory).DatabaseNotificationslists, counts, marks read or unread, deletes and prunes, always scoped to the notifiable. - Webhook POSTs
{"id","event","created_at","data"}withNimbus-Event,Nimbus-Delivery(the notification id, for receiver deduplication) andNimbus-Signature: t=<unix>,v1=<hex HMAC-SHA256 of "t.body">. Receivers check it withWebhookSignature::verify($header, $body, $secret). The secret never enters the job payload; passsecretFor:for per-URL secrets.
Push and webhooks share the HttpClient interface. HttpClients::detect()
uses the non-blocking PAM client inside the runtime and ext-curl otherwise (and
for HTTP/2, which the PAM client does not speak); wrap any PSR-18 client with
Psr18HttpClient.
In tests, bind Notifier::fake() where a NotificationDispatcher is expected:
$notifications = Notifier::fake(); // ... exercise the code ... $notifications->assertSentTo($user, InvoicePaid::class); $notifications->assertSentLaterTo($user, InvoicePaid::class); $notifications->assertNothingSent();
Request lifecycle observers
Register a RequestLifecycleObserver with $app->observe() to build profilers,
traces and leak diagnostics around the complete request pipeline. Observers
start in registration order and finish in reverse order, receive the handled
failure when one occurred, and execute before the request scope is destroyed.
An observer cleanup failure is logged and cannot prevent later observers or
container cleanup from running.
MemoryProfiler is the bounded first PAM Lens collector. Enable it explicitly
with ProfilerMode::Development or ProfilerMode::Testing and register it as
an observer. It emits X-Debug-Token and stores only method, path, status,
duration, memory delta and failure class; request/response bodies and headers
are never retained. Disabled mode is the default and emits nothing.
OpenAPI and generated clients
$app->post('/users', [UserController::class, 'store']) ->name('users.store') ->summary('Create a user') ->tags(['Users']) ->input(StoreUserRequest::class) ->output(UserResource::class); $contract = $app->openApi('My API', '1.0.0'); $openapi = $contract->toJson(); $typescript = $contract->client(ClientLanguage::TypeScript); $kotlin = $contract->client(ClientLanguage::Kotlin); $swift = $contract->client(ClientLanguage::Swift);
CompatibilityChecker reports breaking path and operation removals using
sequential integer codes.
In-memory testing
Nimbus\Testing\TestCase (PHPUnit) builds and boots a fresh application per test and sends
requests to it in memory:
use Nimbus\Testing\RefreshDatabase; use Nimbus\Testing\TestCase; final class ProductTest extends TestCase { use RefreshDatabase; protected function createApplication(): App { $app = new App(discoverPackages: false); $app->provider(new ArcanoServiceProvider($config, $entities, migrations: $migrations)); $app->routes(dirname(__DIR__) . '/routes.php'); return $app; } public function testListsProducts(): void { ProductFactory::new()->count(3)->sequence(['name' => 'Keyboard'], ['name' => 'Mouse'])->create(); $this->getJson('/products') ->assertOk() ->assertJsonCount(3, 'data') ->assertJsonPath('data.0.name', 'Keyboard') ->assertJsonStructure(['data' => ['*' => ['id', 'name']]]); $this->actingAs($user) ->postJson('/products', ['name' => '']) ->assertUnprocessableEntity() ->assertJsonValidationErrors(['name' => 'required']); $this->assertDatabaseCount('products', 3); $this->assertDatabaseHas(Product::class, ['name' => 'Mouse']); } }
- Requests:
getJson,postJson,putJson,patchJson,deleteJson,json($method, ...)andget;withHeaders(),withHeader()andwithToken()apply to the following requests. actingAs($principal)binds anAuthenticatorreturning the principal, so routes withauth()/can()andAuthenticateMiddlewareresolved through the container see it.- Responses:
assertOk,assertCreated,assertNoContent,assertStatus,assertNotFound,assertUnauthorized,assertForbidden,assertUnprocessableEntity,assertHeader,assertHeaderMissing,assertJson(subset),assertExactJson,assertJsonPath(value or closure),assertJsonMissingPath,assertJsonCount,assertJsonStructure(*for lists),assertJsonValidationErrorsandassertJsonMissingValidationErrors(the 422 Problem Detailserrorsmember),json($path)anddump(). Failures are PHPUnit assertion failures. RefreshDatabaseruns the pending migrations, then opens a transaction that every request of the test shares and that is rolled back when the test ends. A request that leaves its own transaction open loses only its writes, as in production.assertDatabaseHas,assertDatabaseMissingandassertDatabaseCounttake a table or an entity class.
Without the base class, TestClient offers the same requests over any App:
(new TestClient($app)) ->withToken($token) ->postJson('/login', ['email' => 'dev@pam.dev']) ->assertSuccessful() ->assertJsonPath('data.status', 1);
Factories and seeders
Factories build Arcano entities with Faker (composer require --dev fakerphp/faker). Attributes named like constructor parameters go to the constructor; the rest are
set as properties.
/** @extends Factory<Product> */ final class ProductFactory extends Factory { protected string $model = Product::class; public function definition(): array { return [ 'name' => $this->faker->words(2, true), 'priceInCents' => $this->faker->numberBetween(100, 100_000), 'category' => CategoryFactory::new(), // made, then persisted by cascade ]; } public function archived(): self { return $this->state(['status' => ProductStatus::Archived]); } } ProductFactory::new()->makeOne(); // unsaved ProductFactory::new()->count(10)->archived()->create(); // persisted in one unit of work ProductFactory::new()->state(fn (array $a) => ['name' => strtoupper($a['name'])])->raw();
count(), state(), sequence(), afterMaking() and afterCreating() return copies;
make()/create() return one entity, or a list after count() (makeOne, makeMany,
createOne, createMany are typed). create() persists through the manager set with
Factory::useManager(), which TestCase and SeederRunner set; Factory::useFaker() changes
the locale or seed.
Seeders define run(), resolved through the container, and chain others with call():
final class DatabaseSeeder extends Seeder { public function run(ArcanoManager $arcano): void { $this->call([CategorySeeder::class, ProductSeeder::class]); } } (new SeederRunner($app))->run(DatabaseSeeder::class); // or $this->seed(...) in a TestCase
Run composer benchmark for the standalone router benchmark. Its schema 1 JSON
reports warmed static and constrained-dynamic throughput, p50/p95/p99 latency,
peak memory and the exact regression budget. composer verify runs
benchmark:check with intentionally conservative ceilings to catch severe
regressions while avoiding hardware-specific marketing claims.
License
Free and open-source under the Apache License 2.0. You may use, modify, and distribute this package for any purpose, including commercially.
See CONTRIBUTING.md to contribute and SECURITY.md for private vulnerability reporting.
Recommended PAM workflow
Start new applications with pam init my-api --template api. In an existing PAM project, install the higher-level router with pam composer require pushinbr/nimbus; PAM runs Composer inside its private Embed SAPI.
Run pam doctor after dependency changes and before creating a release. The project remains a normal Composer project with a standard manifest, lockfile, PSR-4 autoloading, and vendor/autoload.php.
API guide
| Surface | Use it for |
|---|---|
App |
Register routes, middleware, providers, error boundaries, and the listener. |
Router |
Compile and match method/path routes with typed results. |
Pipeline |
Execute middleware and the destination handler in order. |
CorsMiddleware |
Apply explicit origin, method, and header policy. |
RateLimitMiddleware |
Apply bounded per-key request limits. |
SecurityHeadersMiddleware |
Set conservative browser security headers. |
Route parameters are available through $request->route(). A path that exists for another method produces 405 behavior; an unknown path produces 404 behavior. Register error handling with onError() and keep transport-level timeouts and request limits in the PAM listener options.
Production checklist
- Keep request data and mutable state scoped to the current request.
- Test success, validation failure, exception, cancellation, and timeout paths.
- Configure explicit limits and avoid unbounded payloads, queues, or retained collections.
- Run
pam doctor,pam test, and the relevant integration suite before release. - Validate real dependencies and workload behavior; compatibility is not inferred from package installation alone.
Troubleshooting
- Class not found: run
pam composer install, verify PSR-4 configuration, and rerunpam doctor. - Behavior differs over the network: reproduce with PAM's transport integration tests; in-memory execution does not model the socket boundary.
- A dependency blocks a worker: use PAM-native I/O, a compatible event loop, a process pool, or additional isolated workers.
Documentation and support
Report security vulnerabilities through GitHub private vulnerability reporting or the PAM security policy, not a public issue.