README

Sillbeam — modular Symfony architecture, connecting feature modules, shared contracts and infrastructure.

A modular architecture layer for scalable, maintainable Symfony applications.

Website · Quick start · Documentation · Release notes · Report an issue

Sillbeam Core extends Symfony with explicit module boundaries, declared dependencies and optional Projects. It discovers your architecture, validates its dependency graph and checks static code references when Symfony builds the container. Symfony continues to handle services, routing and the application runtime.

Use it in an existing Symfony application or build a modular monolith from the start. Doctrine integration is optional, and the standard Symfony kernel is sufficient. SillbeamKernel provides a convenient alternative.

Modular architecture

Capability	Scope
Feature modules	Organize code through `#[SillbeamModule]` descriptors and declare direct dependencies.
Architecture checks	Detect cycles, missing dependencies, invalid boundaries and undeclared static cross-module references during container compilation.
Symfony services	Discover module services through native autowiring, autoconfiguration and Symfony service attributes.
Module routing	Import controller routes from active modules and Projects through one route-loader entry.
Optional Projects	Compose multiple surfaces with shared and private modules, including host-based routing.
Optional Doctrine integration	Register entity mappings from active modules and Projects when DoctrineBundle is installed.
Flexible discovery	Configure multiple roots, namespaces, exclusions and alternative controller or entity directories.
Architecture diagnostics	Inspect the catalog, activation reasons and dependency evidence as text or JSON.

Modules normally live in src/Module; Projects live in src/Project. These defaults can be configured. Each descriptor owns its directory and descendants. Descriptor filenames are flexible, but must match their PSR-4 class names.

Quick start

Requirements

PHP 8.4 or newer and Composer.
Symfony 7.4 or 8.x in the consuming application.
DoctrineBundle, only if you want automatic Doctrine entity mappings.

The current CI targets PHP 8.4/8.5 with Symfony 7.4/8.1. The independent v0.2.0 acceptance records its exact tested versions and historical limitations; the F01/F02 follow-up documents the subsequent Doctor corrections. The original report is not an unconditional release approval. Earlier compatibility snapshots describe their own historical scope.

Install with Composer

From the root of a fresh or existing Symfony application:

composer require websign-dev/sillbeam-core

Composer selects an available compatible release. This checkout prepares v0.3.0; a :^0.3.0 constraint requires that release to be published. See release status. Package installation and Flex recipe availability are separate. The existing Flex recipe registers the bundle and one route import when installed through your configured endpoint; it does not edit bin/console or services.yaml. Public Contrib approval is a separate step.

Before running Doctor, select the Core Application in your existing bin/console:

-use Symfony\Bundle\FrameworkBundle\Console\Application;
+use Sillbeam\Core\Console\Application;

Keep the bootstrap, Runtime callback, import aliases and kernel. This deliberate manual edit makes Doctor available even without the bundle or a working container. Then run:

php bin/console sillbeam:doctor

Review its concrete next steps:

Enable Sillbeam\Core\SillbeamCoreBundle::class => ['all' => true] in the existing bundle array if missing; preserve the other bundles and environment flags.
Keep exactly one sillbeam: { resource: ., type: sillbeam } import, normally in config/routes/sillbeam.yaml. Do not duplicate a Flex-provided import.
Append complete Module/Project discovery areas to broad native service imports' existing exclusions. Keep other exclusions and explicit services. For the usual App\ import of ../src/, an exclusion can be ../src/{DependencyInjection,Entity,Kernel.php,Module,Project}; use actual paths for custom roots.

Neither Doctor nor the recipe overwrites those native files. Dynamic configuration remains not verified; review it manually. A green Doctor result confirms static evidence only. No config/packages/sillbeam.yaml is required for the defaults. The installation guide includes exact edits, boot-failure recovery and the optional Doctrine setup.

php bin/console sillbeam:doctor
php bin/console sillbeam:architecture
php bin/console sillbeam:make:module Hello

Add the guide's Greeting service and HelloController to the new module. Then verify it:

php bin/console cache:clear
php bin/console sillbeam:architecture
php bin/console debug:router hello

A request to /hello through your existing development server returns Hello from Sillbeam. The descriptor command alone creates no route. Existing Projects must select the shared Hello module first; Project routes have prefixed names and optional host filters. Ordinary make/container commands require a usable architecture; the adapter keeps Doctor and reporting available before boot.

Modules and Projects

Declare another module in dependencies whenever your module directly references its classes. Sillbeam checks declarations and observed static references, and reports invalid access with file and line information. Unused imports do not create dependencies. Dynamic class names, PHPDoc and string service IDs are outside this analysis.

Without Projects, all enabled shared modules are active. With Projects, each Project selects shared modules and automatically includes its enabled private modules; dependencies complete its graph. Unassigned shared modules remain in the catalog but contribute no automatic services, routes or entity mappings.

Application layout	Use case
Symfony only	Keep a conventional Symfony application with no module or Project descriptors.
Modules only	Structure one application around enabled shared feature modules.
Project only	Use direct Project services, controllers and entities without modules.
Single Project	Group a surface and its private modules without requiring host configuration.
Multiple Projects	Compose surfaces with distinct hosts and shared or private modules.
Hybrid	Combine conventional Symfony code with module and Project directories.

Projects share the container, database and event system. They provide architectural ownership and routing composition, rather than process or tenant isolation. Global subscribers and handlers are not automatically restricted to a Project's host.

Read the module guide and Project guide for dependency rules, activation and routing.

Everyday workflow

Run these commands from your Symfony application's root:

Command	Purpose
`php bin/console sillbeam:architecture`	Explain architecture findings and contextual next steps.
`php bin/console sillbeam:graph`	Write `architecture.svg` directly in PHP (no extra tools); use `--module=Billing` for direct relationships or `--format=mermaid` for raw source (reference).
`php bin/console sillbeam:inspect:module Billing`	Inspect module state and merged direct relationships; use `-v` for technical evidence (reference).
`php bin/console sillbeam:doctor`	Inspect static installation evidence; review unverified checks manually.
`php bin/console sillbeam:doctor --format=json`	Export the versioned Doctor result with stable check IDs.
`php bin/console sillbeam:architecture --format=json`	Export the architecture catalog and dependency evidence.
`php bin/console sillbeam:report`	Write a standalone Markdown architecture report.
`php bin/console sillbeam:about`	Show application, runtime and module information.
`php bin/console debug:container`	Inspect Symfony service registration.
`php bin/console debug:router`	Inspect imported application routes.
`php bin/console doctrine:mapping:info`	Inspect entity mappings when DoctrineBundle is installed.

Architecture errors block ordinary container-backed commands. With Sillbeam\Core\Console\Application selected in the existing bootstrap, the exact architecture, report, module-inspection, graph and Doctor commands remain available before container compilation. Doctor recognizes conventional Runtime callbacks and stock Symfony 7.4/8.1 kernels statically; dynamic or ambiguous configuration remains not verified. Unknown routing does not hide independently proven service-import conflicts. The regular Symfony entry point can write cache files before Doctor runs. See the CLI reference and troubleshooting guide.

Documentation

Guide	Contents
Documentation overview	Guide index and starting points.
Getting started	Installation, descriptors and native Symfony integration.
Architecture	Discovery, ownership, compilation and dependency boundaries.
Modules	Descriptors, dependencies and activation rules.
Projects	Shared and private modules, hosts and request context.
Configuration	Discovery roots, exclusions and integration settings.
Public API	Attributes, registries and runtime interfaces.
English API JSON	Manually export English API JSON with `composer docs:export-json`; translation and integration are separate manual work.
Doctrine	Optional entity mapping integration.
Migration	Breaking changes and replacing the former Foundation features.
Testing	Repository checks and integration coverage.
Test applications	Example layouts and the isolated consumer application.

Release status

Sillbeam Core v0.3.0 is prepared for release acceptance, based on v0.2.0. It adds English PHPDoc/API documentation and manual JSON export, clearer installation guidance, Doctor JSON v1, compact module inspection and built-in SVG diagrams with explicit Mermaid source export. See the changelog, release notes, upgrade guide and initial acceptance evidence (2026-10-29).

This checkout does not establish publication or final approval. A stable :^0.3.0 installation requires the matching approved tag/version to become available through Packagist. Composer derives release versions from Git tags; no fixed package version field is added. The current development branch is dev-v0.3.x. Composer aliases dev-dev-v0.3.x, dev-dev and dev-main to 0.3.x-dev; these are development versions, not a stable 0.3.0 release. Composer adds dev- to each non-numeric Git branch name. Each alias applies when this metadata is present on its named branch.

The integration order is dev-v0.3.x → dev (automatic CI) → maintainer approval → main (automatic CI) → explicitly authorized release. Push CI runs only for main and dev; this development branch and pull requests do not trigger it. Manual workflow dispatch remains available. Configured CI and historical local results do not establish a current remote run; see the verification scope.

The compatible Flex recipe is prepared under 0.3/ for the Contrib submission. Its public availability is separate from the package release; manual integration remains supported. No tag, push, Packagist publication or Recipes Contrib submission is performed by the acceptance checks. Final release authorization belongs to the maintainer.

The v0.2 migration guide remains the historical guide for the earlier package/namespace rename. Historical reports retain their original findings and scope.

For reports even when the service container cannot compile, use Sillbeam\Core\Console\Application in the existing bin/console bootstrap. See CLI reporting for setup, JSON schema and exit codes.

Scope and migration

Sillbeam focuses on module architecture within Symfony. Services, HTTP handling and runtime behavior use Symfony's existing mechanisms. Applications supply their own business functionality and infrastructure integrations.

The former Foundation layer—including API, Security, User, entity bases, stores and infrastructure helpers—has been removed. This is a breaking change: replace existing usage according to the migration guide before updating. Strata remains a future idea and is not a dependency.

Development & support

From the Sillbeam repository root:

composer install
composer validate --strict
composer test
composer analyse
composer architecture
composer cs:check
composer test:consumer
composer test:flex-recipe
SILLBEAM_TEST_DOCTRINE=1 composer test:flex-recipe

The example applications cover six operating variants. The isolated consumer lives under apps/test-app; its setup is described in the test-app guide.

Read Contributing for development setup, required checks and pull request guidance, Support for assistance and Security for private vulnerability reporting.

When reporting an issue, include your PHP and Symfony versions, relevant Sillbeam configuration, the application layout and diagnostic output. Remove credentials from shared output.

License

Sillbeam is licensed under the MIT License.

Documentation · Report an issue · Back to top

websign-dev / sillbeam-core

Package info

Security

Statistics