Download the PHP package survos/kit-bundle without Composer

survos/kit-bundle

Convention-based base class for Symfony 8 bundle development.

The goal is simple: if a Survos bundle has conventional Symfony code, installing the bundle should make that code available without a recipe full of repeated wiring.

• src/Command/ classes with #[AsCommand] should become console commands.
• src/Controller/ classes with #[Route] should be routable when the bundle opts into route loading.
• templates/ should be available as a Twig namespace.
• assets/ should be available to AssetMapper when the bundle declares an asset package.
• src/Entity/ can be mapped into Doctrine when the bundle explicitly opts in.

Doctrine deserves special attention: when a bundle maps entities, installing that bundle changes what Doctrine considers part of the application model. That is useful for bundles like key-value-bundle, but it means the app developer must review and apply schema changes.

Two audiences

This document distinguishes two roles:

• Bundle author — writes the bundle (extends AbstractSurvosBundle or AbstractUxBundle, ships it as a package)
• App developer — installs and configures the bundle in their Symfony application

For bundle authors

Extend AbstractSurvosBundle

What the base class handles automatically

Declaring the bundle dependency

Use #[RequiredBundle] to declare that your bundle needs kit-bundle active. Symfony enforces this automatically — no recipe, no documentation note, no forgotten bundles.php entry:

Doctrine Entity Mapping

HasDoctrineEntities opts a bundle into Doctrine ORM mapping. It registers the bundle's src/Entity/ directory as attribute-mapped Doctrine entities during container prepending.

This is not a passive convenience. For app developers, installing a bundle that uses HasDoctrineEntities means Doctrine may discover new mapped classes and therefore new tables, columns, indexes, or relations.

Expected app workflow:

Bundle author opt-in:

By default, the entity namespace is derived from the bundle namespace:

Override entityNamespace() only when the entities are not in the standard namespace:

Override doctrineAlias() only when the default alias, the bundle class name without Bundle, is not what you want.

Route Configuration

Every bundle that uses HasConfigurableRoutes should expose the same two app options:

That gives apps parity with traditional config/routes/*.yaml imports:

• routes_enabled: false means "do not auto-import this bundle's controller attributes"
• route_prefix: /custom-prefix means "mount the bundle's routes under this URL prefix"

The bundle must then call captureRouteConfig() and registerRouteLoader() from loadExtension(), and addRouteLoaderCompilerPass() from build().

UX / AssetMapper Bundles

Bundles that ship reusable frontend assets should extend AbstractUxBundle. It extends AbstractSurvosBundle, enables AssetMapper registration by default, and registers itself as a no-op compiler pass so asset-heavy bundles can override process() when they need compile time wiring.

Overriding Conventions

Override twigNamespace() to customise or disable Twig path registration:

Override assetNamespace() or define ASSET_PACKAGE to control AssetMapper registration:

For app developers

Most behaviour is automatic. The only knobs exposed are route registration, which apps sometimes need to take over manually.

routes_enabled: false is the escape hatch: the bundle's controllers are still registered as services, but no routes are loaded. Use this when you want to mount the bundle's routes under a custom prefix in your own config/routes/ file, or only expose a subset of them.

Commands, Twig paths, and AssetMapper registration have no on/off toggle — they are unconditional. To suppress a command, use Symfony's built-in console.command tag exclusion or remove the command class from the bundle if you're forking it.

Before / after

A typical bundle before kit-bundle (~90 lines):

After kit-bundle:

Commands, Twig paths, and entity mappings are handled by convention. Route loading keeps a small explicit hook so each bundle can expose the standard routes_enabled and route_prefix escape hatches.

Requirements

• PHP 8.4+
• Symfony 8.1+
• doctrine/orm — optional, only needed when using HasDoctrineEntities
• symfony/asset-mapper — optional, only needed for Stimulus / UX bundles