README

Scafera Kernel is the execution core of the Scafera framework. It provides a minimal, controlled runtime environment and defines the boundaries within which applications operate.

Provides: The boot core of Scafera — discovers bundles, loads an architecture package, enforces structural boundaries, and hands off to Symfony. User projects never define a Kernel.

Depends on: A host project with a standard layout (public/, var/, config/), a Composer-installed architecture package implementing ArchitecturePackageInterface, Symfony 8 + FrameworkBundle, and an APP_SECRET provided via config/ overrides or OS env.

Extension points:

• Contracts in Scafera\Kernel\Contract\ — ArchitecturePackageInterface (primary), ValidatorInterface, AdvisorInterface, GeneratorInterface, PathProviderInterface, ViewInterface
• Attributes — #[Route] (HTTP), #[AsCommand] (CLI), #[Config] (env/parameter injection)
• DI tags — scafera.validator, scafera.advisor, scafera.path_provider (auto-collected)

Not responsible for: Routing/commands/services without an architecture package · folder conventions (owned by architecture packages) · presentation (scafera/frontend) · persistence (scafera/database) · logging (scafera/log) · HTTP header/CORS customization · .env files · config/packages/ scanning · userland event dispatch.

Headless by design

The kernel is intentionally non-functional without an architecture package. Without one:

• No user services are discovered or registered
• No routes are loaded (HTTP returns 404)
• Only built-in commands work (about, validate, cache:clear)

Install an architecture package (e.g. scafera/layered) to define structure, behavior, and rules.

Design principles

• Explicit execution — no hidden or implicit behavior in userland
• Separation of concerns — runtime and architecture are independent
• Extensibility through contracts — behavior is defined by implementing packages

How it works

Dynamic bundle discovery

Bundles are discovered automatically from Composer's installed.json. Any installed package declaring "type": "symfony-bundle" is registered at boot — no config/bundles.php needed.

• Install a capability package and its bundle is available
• Remove a package and its bundle disappears
• composer install --no-dev naturally excludes dev bundles

Configuration

User configuration goes in a single optional file:

config/config.yaml

This file can override any bundle configuration and set environment variables:

env:
  APP_DEBUG: '0'

framework:
  session:
    cookie_secure: true

Secrets like APP_SECRET belong in config/config.local.yaml (git-ignored). The scaffold plugin generates this file with a random secret during composer create-project.

There is no config/packages/ directory — the kernel does not scan for it.

Environment bootstrap

The Bootstrap class handles environment setup before the Symfony runtime takes over:

1. Sets APP_ENV and APP_DEBUG defaults (dev / 1)
2. Reads the env: section from config/config.yaml if present
3. Real OS environment variables always take precedence
4. Validates that APP_SECRET is set

Contracts

The kernel defines contracts that architecture and capability packages implement:

HTTP types

Controllers use these types instead of Symfony's HTTP classes directly. The ControllerBoundaryPass enforces this at compile time.

All types live in Scafera\Kernel\Http\.

Console

Testing

Example controller

use Scafera\Kernel\Http\Request;
use Scafera\Kernel\Http\Response;
use Scafera\Kernel\Http\Route;

#[Route('/orders/{id}', methods: 'GET', requirements: ['id' => '\d+'])]
final class ShowOrder
{
    public function __invoke(Request $request): Response
    {
        $id = $request->routeParam('id');
        // ...
        return new Response($content);
    }
}

Request

Properties:

• $request->query — ParameterBag of query string parameters
• $request->request — ParameterBag of POST body parameters
• $request->headers — HeaderBag of request headers

Methods:

• getMethod(): string — HTTP method (GET, POST, etc.)
• isMethod(string $method): bool
• getPath(): string — URL path without query string
• getUri(): string — full URI
• getContent(): string — raw request body
• json(): array — parsed JSON body
• routeParam(string $key, mixed $default = null): mixed — single route parameter
• routeParams(): array — all route parameters

Response types

new Response(string $content = '', int $status = 200, array $headers = [])
new JsonResponse(mixed $data = null, int $status = 200, array $headers = [])
new RedirectResponse(string $url, int $status = 302, array $headers = [])

Route attribute

#[Route(
    path: '/path/{param}',
    methods: 'GET',              // string or array: ['GET', 'POST']
    name: 'custom_route_name',   // optional, auto-generated if omitted
    requirements: ['param' => '\d+'],
    defaults: ['param' => '1'],
)]

Class-level #[Route] sets a prefix for method-level routes. A class-level #[Route] with no method-level routes maps to __invoke.

ParameterBag

• get(string $key, mixed $default = null): mixed
• has(string $key): bool
• all(): array
• getInt(string $key, int $default = 0): int
• getString(string $key, string $default = ''): string
• getBoolean(string $key, bool $default = false): bool

HeaderBag

• get(string $key, ?string $default = null): ?string — case-insensitive lookup
• has(string $key): bool
• all(): array

Built-in commands

vendor/bin/scafera validate           # Run all validators and advisors from installed Scafera packages
vendor/bin/scafera about              # Show framework and environment information

Scafera Packages

Architecture packages

Define folder structure, service discovery, and convention enforcement.

Capability packages

Add optional functionality. Install only what you need.

Tooling

Project templates

Requirements

• PHP >= 8.4
• Symfony 8

License

MIT