README

High‑performance PHP API framework components for building secure, scalable backends. This repository contains the framework runtime (router, DI, HTTP, caching, security, queues, etc.). For a ready‑to‑use application skeleton, see the API skeleton link below.

Requirements

• PHP 8.3+
• Composer 2+

Installation

Install as a library into your application:

composer require glueful/framework

If you want a pre‑scaffolded app, use the API skeleton instead (recommended to get started quickly).

Quick Start (framework usage)

Bootstrap and handle a request:

<?php
declare(strict_types=1);

use Glueful\Framework;
use Symfony\Component\HttpFoundation\Request;

require __DIR__ . '/vendor/autoload.php';

$framework = Framework::create(__DIR__)
    ->withConfigDir(__DIR__ . '/config')
    ->withEnvironment($_ENV['APP_ENV'] ?? 'development');

$app = $framework->boot();

// Define a quick route (see cookbook for best practices)
$router = $app->getContainer()->get(Glueful\Routing\Router::class);
$router->get('/ping', fn() => new Glueful\Http\Response(['ok' => true]));

$request = Request::createFromGlobals();
$response = $app->handle($request);
$response->send();
$app->terminate($request, $response);

Getting Started

• Getting started guide: https://glueful.com/getting-started
• New to Glueful? Begin with:
  • Routing: https://glueful.com/essentials/routing
• Prefer a pre‑scaffolded app? Use the API skeleton (see below).

Documentation

• Official docs website: https://glueful.com (mirror: https://glueful.dev)
• Logging bootstrap guide: docs/LOGGING_BOOTSTRAP.md
• Changelog: CHANGELOG.md
• Roadmap: ROADMAP.md
• Breaking changes process: BREAKING_CHANGE_PROCESS.md

Highlights

• High-Performance Router: O(1) static route lookup, dynamic route bucketing, attribute-based routing, middleware pipeline
• Dependency Injection: Symfony Container with service providers, lazy services, ApplicationContext injection
• Authentication: JWT, LDAP, SAML SSO, API keys with session analytics; opt-in email-PIN 2FA
• Encryption: AES-256-GCM authenticated encryption with key rotation support
• File Uploads: Blob storage with visibility controls, signed URLs, thumbnail generation, media metadata
• Caching: Multi-driver support (Redis/Memcached/File) with distributed caching; tag-based invalidation on the Redis driver
• Queue System: Job processing with Redis/Database backends, auto-scaling workers
• Security: Enhanced rate limiting, CSRF protection, security headers, lockdown mode
• Database: Query builder, migrations, connection pooling (MySQL, PostgreSQL, SQLite)
• Extensions: Modular extension system with lifecycle management
• CLI Tools: Comprehensive scaffold commands, migrations, cache management

Email Two-Factor Authentication (2FA)

Baseline email-PIN 2FA ships in core and is off by default — a fresh install behaves exactly like a pre-2FA framework. To enable it (no source-code editing required):

1. Run the 010_AddTwoFactorEnabledToUsers migration (ships in api-skeleton).
2. Install glueful/email-notification (provides the email channel + two-factor-pin template).
3. Set TWO_FACTOR_ENABLED=true in .env.
4. Enroll users via POST /2fa/enable or php glueful 2fa:enable <user-uuid>.

Once enabled, POST /auth/login returns a challenge_token (and emails a 6-digit PIN) for enrolled users instead of tokens; the client completes login at POST /2fa/verify. Richer factors (TOTP, WebAuthn, recovery codes) ship separately as glueful/mfa.

Generating an SDK client

Glueful produces a high-quality openapi.json; client generation is delegated to best-of-breed tools per language. The generate:client command builds the right shell invocation for you:

# Produce the spec
php glueful generate:openapi

# TypeScript types via openapi-typescript
php glueful generate:client typescript --output=./sdk

# Other languages via openapi-generator-cli
php glueful generate:client python --output=./python-client
php glueful generate:client go --output=./go-client

By default the command prints the shell command so you can pin a specific generator version in CI. Add --execute to run the generator directly. See docs/WEBHOOKS.md for how to surface outbound webhooks in the spec for SDK consumers.

Deployment Notes

• For long-running servers (RoadRunner, Swoole, FrankenPHP), set APP_LONG_RUNNING=true to enable worker-safe lifecycle handling.
• If your deploy process preserves file mtimes and you see stale routing, clear the route cache as part of deploy:
  • php glueful route:cache:clear

API Skeleton (recommended to start)

For a ready‑to‑run project scaffold, use the API skeleton and follow its README. It wires this framework, public entrypoints, config, and examples:

• Packagist: https://packagist.org/packages/glueful/api-skeleton

Quick start:

composer create-project glueful/api-skeleton my-app
cd my-app
php glueful serve

Contributing

Contributions are welcome. Please open issues or PRs. For larger proposals, consider starting with a discussion referencing the implementation plans in docs/implementation_plans/.

License

MIT — see LICENSE.