Kit Bundle Laravel Package

Getting Started

First, a scope check: this is a Symfony bundle, not a Laravel package. You cannot composer require it into a Laravel app and use it directly. If you are a Laravel developer, treat it as a reference implementation for entity traits, form types, and command utilities—or use it only in a Symfony 8.1 project.

Minimal steps:

1. Confirm you are on Symfony 8.1. The release note says “but really you need 8.1,” which is ambiguous; verify the actual composer.json constraints before installing.
2. Install and enable the bundle:

composer require survos/kit-bundle:^2.0

// config/bundles.php
return [
    // ...
    Survos\KitBundle\KitBundle::class => ['all' => true],
];

3. Inspect what the bundle auto-registers:

php bin/console about
php bin/console debug:router
php bin/console list
php bin/console debug:twig
php bin/console debug:asset-map

4. Look first at the bundle source, not for docs:

   • vendor/survos/kit-bundle/src/KitBundle.php
   • vendor/survos/kit-bundle/src/DependencyInjection/
   • vendor/survos/kit-bundle/config/services.yaml
   • any src/Traits, src/Form, src/Command directories

5. First real use case: create a controller in src/Controller with a #[Route], a command in src/Command with #[AsCommand], a template under templates/, and an asset under assets/. Re-run the debug commands. If they appear without extra config, the convention layer is working. Then add one of the bundle’s entity traits to a test entity and run doctrine:schema:validate.

6. If you are on Symfony 7.x, the 2.x line likely will not install. Check for a 1.x tag or copy the specific traits/utilities you need.

Implementation Patterns

Mirror the expected conventions. The bundle’s value is auto-registration by convention. Put routes in src/Controller, commands in src/Command, templates in templates/, and assets in assets/. Do not invent parallel directories unless you also wire them manually.

Entity traits. Use the bundle’s traits inside your entities:

use Survos\KitBundle\Traits\IdentifiableTrait;
use Survos\KitBundle\Traits\TimestampableTrait;

#[ORM\Entity]
class Product
{
    use IdentifiableTrait;
    use TimestampableTrait;
}

Check the trait source for expected interfaces, lifecycle callbacks, or mapping attributes. If the trait provides $id, do not declare another one.

Form types. If the bundle provides base form types, extend them and let Symfony autowire the result. If a provided type is not registered as a service, check whether it is abstract or excluded from services.yaml.

Twig namespaces. Bundle templates are usually reachable via the bundle namespace, e.g. @Kit/.... Override them in the app at:

templates/bundles/KitBundle/

Add your own namespaces in config/packages/twig.yaml if the bundle does not do it for you.

AssetMapper paths. The bundle likely prepends paths into framework.asset_mapper.paths. Use debug:asset-map to confirm. If you need to exclude a path, you generally need a compiler pass, because prepended config is merged, not replaced.

Commands. Place commands in src/Command and use #[AsCommand(name: 'app:something')]. If the bundle offers a base command, extend it and rely on autowiring for dependencies. Do not instantiate commands manually.

Day-to-day workflow.

1. Add a controller/command/template/asset in the conventional location.
2. Run debug:router, list, debug:twig, and debug:asset-map.
3. If it appears, continue. If not, inspect the bundle’s DependencyInjection extension and services.yaml.
4. Clear cache after any config change.

Integration with an existing app. If you already have route imports, command registration, Twig namespaces, or AssetMapper paths, test in a branch. The bundle’s prepends can create duplicate route names, duplicate command names, or duplicate asset paths. Use the debug commands to diff before/after enabling the bundle.

Gotchas and Tips

• The release note is ambiguous. “But really you need 8.1” probably means Symfony 8.1, not PHP 8.1. Verify composer.json. Symfony 8.1 requires a modern PHP runtime; do not assume PHP 8.1 is sufficient.
• Pin the version. Zero stars and a one-line changelog mean you should use ^2.0.1 and read the source before depending on any specific behavior. There is no documented BC policy.
• Auto-registration failures are usually collisions. Duplicate route names, duplicate command names, and Twig namespace clashes are common. debug:router, list, and debug:twig expose them. Clear cache after config changes.
• AssetMapper paths are prepended, not replaced. If you also add the same path in importmap.php or framework.asset_mapper.paths, you can get duplicate or confusing resolution. Use debug:asset-map to verify.
• Doctrine trait mapping needs validation. Traits with #[ORM\Column] properties usually map correctly when used in an entity, but mapped superclasses and id generation strategies can behave differently. Run doctrine:schema:validate after adding a trait.
• Base classes may be abstract or excluded from autoconfiguration. If you extend one and dependency injection fails, check debug:container and add explicit service config.
• Commands are lazy by default. If a command does not show in list, check the #[AsCommand] name, the namespace, and whether the directory is autoloaded.
• Template override path is bundle-short-name specific. For KitBundle, overrides go under templates/bundles/KitBundle/. Renaming or aliasing the bundle breaks overrides.
• Cache is the usual suspect. After enabling the bundle or changing its config:

php bin/console cache:clear

• Laravel developers: do not install this in a Laravel app. It will pull Symfony components and likely conflict. If you want the patterns, copy the traits, form types, and command utilities into your Laravel codebase and adapt them.
• Extension points are limited to what the bundle exposes. Prefer template overrides, service decoration, and bundle config. If the extension has no config to disable auto-registration, a compiler pass that removes prepended config is the clean escape hatch; forking is the last resort.
• Add a convention smoke test to CI. Run debug:router, list, debug:twig, and debug:asset-map and assert expected entries exist. This catches regressions when the bundle or Symfony is upgraded.