Sillbeam Laravel Package

Getting Started

Sillbeam is a Symfony bundle, not a Laravel package — if you're coming from Laravel, mentally map it onto Symfony's kernel/bundle/container model before anything else. There is no service provider, no config/app.php array, and no Artisan. Everything you know about ModuleServiceProvider becomes a PHP class implementing Sillbeam's module contract, and everything you know about composer dump-autoload still applies.

Minimal path to first value:

1. composer require websign-dev/sillbeam:^0.1.0 — confirm you're on PHP 8.4+ and Symfony 7.4/8.x first; this package will not install on 7.3 or PHP 8.3.
2. If Flex doesn't offer a recipe (likely at 0.1.0), register the bundle manually in config/bundles.php and add the route import to config/routes.yaml exactly as the docs show. Do this before writing any module code — a half-registered bundle produces confusing "module not found" errors.
3. Run bin/console sillbeam:about immediately after registration. This is your ground truth for which modules/projects are active and how the package resolved your config. Run it again after every structural change.
4. Create one module, declare zero dependencies, put a single controller in it, and hit the route. That validates the whole chain: container registration → routing → module boundary resolution.
5. Run bin/console sillbeam:architecture and read the output. Get comfortable with its vocabulary before you have twenty modules, because that's when its warnings start mattering.

Where to look first: the documentation's module definition and Projects pages, in that order. Projects are the concept that will confuse you if you learn modules first and assume Projects are an afterthought — they change how the container is composed.

Implementation Patterns

Module-per-feature with explicit dependency declarations. The core day-to-day pattern: each feature ships as a module that declares what it depends on. The value only materializes if you actually declare dependencies rather than reaching across boundaries with use statements. Treat the dependency list as a design artifact reviewed in PRs, not boilerplate.

Projects for multi-surface composition. Compose shared modules plus surface-specific ones (e.g. admin surface, public surface, a customer-specific build) into Projects. This is the pattern that makes the package worth adopting over plain Symfony bundles: one codebase, several composed application surfaces, each pulling only the modules it needs. Set it up early — retrofitting Projects onto a flat module list is more churn than starting with them.

Validation in CI, not in your head. Wire sillbeam:architecture into CI as a failing step. The three checks it performs — circular dependencies, invalid boundaries, undeclared static cross-module references — are exactly the regressions that slip through code review. A non-zero exit on architectural drift is the highest-leverage thing you can do on day one.

Native Symfony integration means no new idioms for the boring parts. Keep using autowiring, service attributes, controller routing, and config overrides as you normally would. Resist the urge to build a Sillbeam-flavored abstraction over services — the bundle explicitly preserves the native runtime, and duplicating it just adds a layer that validation can't see through.

Doctrine mappings follow active modules. Entity mappings are registered automatically for active Modules and Projects, so you generally don't hand-write mapping config. When adding a module with entities, clear the cache and verify with sillbeam:about that the module is actually active — an inactive module's entities silently don't exist, which manifests as "class not found" deep in a query rather than a clear mapping error.

Inspect before you debug. Both commands are cheap. When something behaves unexpectedly — a route 404s, a service doesn't resolve, a mapping is missing — check sillbeam:about and sillbeam:architecture before adding dump() calls. Most surprises are "that module isn't active" or "that dependency direction is illegal."

Gotchas and Tips

Projects are not tenancy. The release notes state this plainly and it's the single most dangerous misconception. Projects share one Symfony container and one infrastructure stack. If you need per-tenant data isolation, container isolation, or per-tenant cache/queue separation, Sillbeam does not give it to you and cannot be retrofitted into giving it to you. Use Projects for packaging and composition, and keep a real tenancy solution for isolation.

Static analysis has a hard ceiling. Dynamically resolved class references — service locator lookups, $container->get($className), class names assembled from strings, config-driven class resolution — are invisible to the dependency validator. You can absolutely build a boundary violation the tool will not catch. The practical consequence: prefer constructor injection and literal class references at boundaries, and be extra careful reviewing code that resolves classes dynamically.

Pre-1.0 means the API moves. ^0.1.0 will pull 0.2, 0.3, etc., and the public API may change across those. If this is going into anything long-lived, pin more tightly than the caret allows and read the changelog before bumping. Budget for upgrade work; don't assume minor-version stability just because the version string looks semver-ish.

The manual registration path is the default path. With no Flex recipe guaranteed, expect to hand-edit config/bundles.php and config/routes.yaml. Commit those edits deliberately — they're the kind of change that gets lost in a rebase and produces an app that "works locally."

PHP 8.4 is a real floor. Not a soft recommendation. If your CI matrix or production image is on 8.3, resolve that before evaluating the package; you'll otherwise spend the evaluation fighting the installer.

Missing dependencies fail at validation time, not boot time. An undeclared or missing module dependency may surface as a container or architecture error rather than a clean startup failure. When a fresh checkout misbehaves, run both commands before assuming a code problem.

Extension points: configuration overrides and native Symfony mechanisms (compiler passes, service decoration, bundle config) remain available. Prefer those over wrapping Sillbeam internals — at 0.1.0, internals are the least stable surface in the package.