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:

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

Contracts

The kernel defines contracts that architecture and capability packages implement:

Contract	Purpose
`ArchitecturePackageInterface`	Defines an architecture package
`ValidatorInterface`	Hard validation rule (affects exit code)
`AdvisorInterface`	Soft advisory check (never affects exit code)
`GeneratorInterface`	Code generator for `scafera make:*` commands
`PathProviderInterface`	Registers paths shown by `info:paths`
`ViewInterface`	Template rendering (implemented by `scafera/frontend`)

HTTP types

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

Type	Purpose
`Scafera\Kernel\Http\Request`	Wraps the incoming HTTP request
`Scafera\Kernel\Http\Response`	Plain HTTP response
`Scafera\Kernel\Http\JsonResponse`	JSON HTTP response
`Scafera\Kernel\Http\RedirectResponse`	Redirect HTTP response
`Scafera\Kernel\Http\Route`	Attribute for defining routes
`Scafera\Kernel\Http\ParameterBag`	Query and request parameters (typed getters)
`Scafera\Kernel\Http\HeaderBag`	Request headers (case-insensitive)

All types live in Scafera\Kernel\Http\.

Console

Type	Purpose
`Scafera\Kernel\Console\Command`	Base command class with `handle()` method
`Scafera\Kernel\Console\Input`	Command input wrapper
`Scafera\Kernel\Console\Output`	Command output wrapper with `success()`, `error()`, `warning()`
`Scafera\Kernel\Console\Attribute\AsCommand`	`#[AsCommand]` attribute

Testing

Type	Purpose
`Scafera\Kernel\Test\WebTestCase`	HTTP test base with `get()`, `post()`, etc.
`Scafera\Kernel\Test\TestResponse`	Fluent assertions: `assertOk()`, `assertJsonPath()`, etc.
`Scafera\Kernel\Test\CommandTestCase`	Console test base
`Scafera\Kernel\Test\CommandResult`	Command output assertions

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.

Package	Description
`scafera/layered`	Layered architecture conventions

Capability packages

Add optional functionality. Install only what you need.

Package	Description
`scafera/auth`	Authentication and access control
`scafera/database`	Database persistence (Doctrine)
`scafera/file`	File upload, validation, and storage
`scafera/form`	Form handling and DTO validation
`scafera/frontend`	Template rendering (Twig)
`scafera/log`	Structured logging (PSR-3)
`scafera/translate`	Translation and locale management

Tooling

Package	Description
`scafera/scaffold`	Composer plugin that scaffolds project files

Project templates

Package	Description
`scafera/layered-web`	Layered web application template

Requirements

PHP >= 8.4
Symfony 8

License

MIT

scafera / kernel

Maintainers

Package info

Statistics

Security