README

Power in minimalism

Status: stable (v0.1.4) — production-ready, 1481 tests, 0 failures, API is stable.

Packagist: globus-studio/atomic-framework · composer require globus-studio/atomic-framework

A modular, full-featured PHP framework built on Fat-Free Framework. Ships with authentication, queue processing, task scheduling, caching, CLI tooling, WebSockets, and plugin management — all in a ~2 MB core.

Download the application skeleton for a quick start: Atomic Application

Quick example

composer create-project globus-studio/atomic-framework-application myapp
cd myapp
cp .env.example .env
php atomic init/key
php -S localhost:8000 -t public

Why Atomic

Install

Start a new project (recommended):

composer create-project globus-studio/atomic-framework-application myapp
cd myapp
cp .env.example .env
php atomic init/key

Add to existing project:

composer require globus-studio/atomic-framework

Capabilities

Application lifecycle

The bootstrap chain in bootstrap/app.php initializes the app via a fluent interface. Order matters — hooks fire at specific points:

$application = App::instance($atomic);

\App\Event\Application::instance()->init();
\App\Hook\Application::instance()->init();

$application
    ->config_loaded($loader)
    ->register_logger()
    ->register_exception_handler()
    ->prefly()
    ->register_locales()
    ->register_locale_hrefs()
    ->register_unload_handler()
    ->register_middleware()
    ->core_ready()
    ->register_core_plugins()
    ->register_plugins()
    ->register_routes()
    ->init_session()
    ->open_connections()
    ->register_user_provider()
    ->app_bootstrapped();

Routing

Routes are organized by type and loaded automatically based on request context:

// routes/web.php
$this->route('GET /dashboard', 'App\Http\Controllers\DashboardController->index');
$this->route('POST /contact', 'App\Http\Controllers\ContactController->submit', ['auth']);

Middleware

Named, parameterized middleware attached to route patterns:

// config/middleware.php
return [
    'auth'  => App\Http\Middleware\Authenticate::class,
    'admin' => App\Http\Middleware\RequireAdmin::class,
];

// routes/web.php
$this->route('GET /admin/*', 'AdminController->index', ['auth', 'admin']);

use Engine\Atomic\Core\Middleware\MiddlewareInterface;

class Authenticate implements MiddlewareInterface
{
    public function handle(\Base $atomic): bool
    {
        return Guard::is_authenticated();
    }

    public function process(mixed $request, callable $next): \Engine\Atomic\Http\Response
    {
        if (Guard::is_authenticated()) {
            return $next($request);
        }
        return \Engine\Atomic\Http\Response::json(['error' => 'Unauthorized'], 401);
    }
}

Controllers & Models

use Engine\Atomic\App\Controller;

class DashboardController extends Controller
{
    public function index(\Base $f3): void
    {
        $this->display('dashboard/index.html');
    }
}

use Engine\Atomic\App\Model;

class User extends Model
{
    protected $fieldConf = [
        'email'    => ['type' => \DB\SQL\Schema::DT_VARCHAR256, 'nullable' => false],
        'password' => ['type' => \DB\SQL\Schema::DT_VARCHAR256, 'nullable' => false],
    ];
}

Authentication

use Engine\Atomic\Auth\Auth;
use Engine\Atomic\Auth\GoogleAuth;

// Password-based login
$user = Auth::instance()->login_with_secret(
    ['email' => $email],
    $password
);

// OAuth login
$url = GoogleAuth::instance()->get_login_url();
$userId = GoogleAuth::instance()->handle_callback($code, $state);

// Session management
$currentUser = Auth::instance()->get_current_user();
Auth::instance()->logout();
Auth::kill_all_sessions($userId);

// Admin impersonation
Auth::instance()->impersonate_user($targetUuid);
Auth::instance()->stop_impersonation();

Security features: Bcrypt hashing (timing-safe), session regeneration on login, IP + User-Agent binding, dual rate limiting, OAuth state verification with hash_equals(), audit logging.

Database & Migrations

php atomic migrations/create create_posts_table
php atomic migrations/migrate
php atomic migrations/rollback
php atomic migrations/status

// database/migrations/20260101000000_create_posts_table.php
return [
    'table' => 'posts',
    'columns' => [
        'id'    => ['type' => 'BIGINT UNSIGNED', 'auto_increment' => true],
        'title' => ['type' => 'VARCHAR', 'length' => 256, 'nullable' => false],
        'body'  => ['type' => 'TEXT', 'nullable' => true],
        'uuid'  => ['type' => 'VARCHAR', 'length' => 128, 'nullable' => false],
    ],
];

Queue system

Dual-driver queue with Redis (Lua-scripted atomics) and Database (row-level locks):

use Engine\Atomic\Queue\Managers\Manager;

Manager::instance()->push('email', [
    'to'      => 'user@example.com',
    'subject' => 'Welcome',
]);

php atomic queue/worker         # Start worker
php atomic queue/monitor        # View queue status
php atomic queue/retry          # Retry failed jobs

Task scheduler

// routes/schedule.php
$scheduler->call(function () {
    Log::info('Cleanup executed');
})->daily()->at('03:00')->timezone('UTC');

php atomic schedule/run          # Execute due tasks
php atomic schedule/work         # Continuous scheduler loop
php atomic schedule/list         # List scheduled tasks

Plugins

Plugins are explicit providers — only classes listed in config/providers.php are loaded:

// config/providers.php
return [
    'plugins' => [
        Engine\Atomic\Plugins\WebSockets\WebSockets::class,
        App\Plugins\ExamplePlugin\ExamplePlugin::class,
    ],
];

plugins/
`-- ExamplePlugin/
    |-- ExamplePlugin.php
    |-- composer.json
    |-- vendor/autoload.php
    `-- routes/
        `-- api.php

php atomic plugin/make ExamplePlugin
php atomic plugin/deps install

Events & hooks

Events — hierarchical with priorities:

use Engine\Atomic\Event\Event;

Event::instance()->on('user.created', function ($data) {
    // Send welcome email
}, priority: 10);

Event::instance()->emit('user.created', ['user' => $user]);

Hooks — WordPress-compatible actions and filters:

use Engine\Atomic\Hook\Hook;

Hook::instance()->add_action('after_login', function ($user) {
    // Track login
});

$title = Hook::instance()->apply_filters('page_title', $rawTitle);

Caching

Multi-driver caching with cascade fallback. Redis, Memcached, folder, and database adapters share the same interface:

use Engine\Atomic\Tools\Transient;
use Engine\Atomic\Core\CacheManager;

// Transient storage (WordPress-like priority: Redis → Memcached → DB → Folder)
Transient::set('stats', $data, 3600);
$cached = Transient::get('stats');

// Cache cascade
$cache = CacheManager::instance()->cascade();
$cache->set('stats', $data, 3600);
$cache->clear('stats');

// Refresh cached generation in long-running workers
$cache->flush_local_cache();

Internationalization

use Engine\Atomic\Lang\I18n;

$i18n = I18n::instance();
echo $i18n->t('welcome_message');                // Simple translation
echo $i18n->tn('item', 'items', $count);         // Pluralization
echo $i18n->tx('menu', 'navigation');            // Contextual translation
echo $i18n->url('/about', 'fr');                 // Localized URL: /fr/about

Detection priority: URL prefix → GET parameter → Cookie → Session → Accept-Language header → default.

CLI

php atomic init                  # Scaffold project structure
php atomic init/key              # Generate application keys
php atomic version               # Display framework version
php atomic routes                # List all registered routes

php atomic cache/invalidate      # Fast generation invalidation
php atomic cache/clear           # Physical cache deletion
php atomic cache/prune           # Remove expired cache entries
php atomic db/tables             # List database tables
php atomic seed/users            # Seed user data
php atomic file/csv2pdf          # Convert CSV to PDF

Security

Dependencies

PHP extensions: json, session, mbstring, fileinfo, pdo, pdo_mysql, curl

Testing

composer test                    # Run all tests (1481 tests, 0 failures)
composer test-fw                 # Framework tests only
composer test-integration        # Integration tests only

php vendor/bin/phpunit --filter "Auth"    # Run specific test group

• 1481 tests across 70+ test classes
• 100% pass rate — 0 failures, 218 skipped (platform-specific: Redis, Memcached, pcntl on Windows)
• Covers: cryptography, authentication, authorization, validation, middleware, CSRF, events, hooks, routing, caching, scheduling, session management, theme management

Documentation

Links

License

GPL-3.0-or-later. See LICENSE.