Blog Bundle Laravel Package

Getting Started

This is a Symfony bundle, not a Laravel package — the mental model is closest to a Laravel package that ships models, migrations, routes, and views all at once, except the "models" are Doctrine entities and the "views" are Twig templates you override by path.

• Install: composer require odiseoteam/blog-bundle. Then check composer show odiseoteam/blog-bundle for the required symfony/* and php constraints before assuming it fits your project. With Symfony Flex the bundle should be auto-registered in config/bundles.php; otherwise add Odiseo\Bundle\BlogBundle\OdiseoBlogBundle::class => ['all' => true].
• Look here first: vendor/odiseoteam/blog-bundle/src/Entity/ (what the domain actually models — posts, categories, tags, comments), then src/Resources/config/ (services, routing, Doctrine mappings) and the bundle's README for the config key name and route prefix. Read the entity classes before writing anything; the whole bundle's value and limits are visible there.
• Wire config: create config/packages/odiseo_blog.yaml (check the bundle's extension class or README for the exact root key and available options). Most bundles like this let you choose the entity classes to map — that's your extension point later.
• Schema: bin/console doctrine:migrations:diff and inspect the generated migration rather than running doctrine:schema:update --force. You want to see which tables it wants to create before touching a real database.
• Routes: import the bundle routing in config/routes.yaml if it isn't auto-loaded, e.g. a resource import with a prefix: you control. Then bin/console debug:router | grep -i blog to see exactly what URLs you got.
• First use case: render a list of posts. Inject the bundle's post repository into a controller, query for published posts ordered by publish date, and render them in your own template — don't try to use the bundle's controllers for your public site on day one. Get the data flowing first, then decide whether its controllers/templates are worth keeping.

Implementation Patterns

Repository-driven, controllers are yours. The reliable pattern with small bundles is: treat it as a data layer. Inject PostRepository (or whatever the bundle names it), add your own query methods via a custom repository class if the bundle's repositoryClass is configurable, and own the controllers and templates. This keeps you free to change the bundle later without rewriting routes.

Template override by path. If the bundle ships Twig templates, override them by placing files under templates/bundles/OdiseoBlogBundle/<subpath>/<file>.twig. Paths must match the bundle's internal structure exactly — copy the original file out of vendor/ first, then edit the copy. Never edit in vendor/.

Entity extension via inheritance mapping. The standard Symfony bundle idiom: create src/Entity/Post.php extending the bundle's Post, mark the parent as @MappedSuperclass/configure resolve_target_entities, and point the bundle config at your subclass. This is how you add fields (a cover image relation, SEO metadata, an author relation to your User). Do this before you run the first migration — changing it afterward means table churn.

Admin integration is a separate decision. These bundles usually assume an admin generator (Sonata or EasyAdmin depending on the version). Check what the bundle's forms/services expect. In practice it's often faster to build EasyAdmin CRUD for the entities yourself than to wire up a heavyweight admin dependency just for this bundle.

Publish workflow as an explicit state. Model draft vs. published with a nullable publishedAt timestamp and scope every public query to publishedAt IS NOT NULL AND publishedAt <= :now. Don't rely on a boolean flag the bundle may or may not expose — you want scheduled publishing for free.

Slug handling in one place. Whether the bundle generates slugs via a Doctrine listener or expects you to set them, centralize it. If you override the entity, add your own prePersist/preUpdate listener using a slugger service rather than sprinkling Str::slug-equivalents through controllers.

Feature-flag the bundle's own controllers. If you use them, namespace the route prefix (/blog) so you can replace one route at a time with your own implementation. Don't let bundle routes occupy /.

Gotchas and Tips

• Maintenance risk is the headline. With ~19 stars, zero dependents, and a last release in early 2024, treat this as unmaintained-ish. Pin the version in composer.json, and budget for forking it or copying the entities into your app if you hit an incompatibility with a newer Symfony or Doctrine ORM major (Doctrine 3 attribute mapping, #[ORM\...] vs. annotations, is the usual breakage point).
• Annotations vs. attributes. An older bundle will likely use docblock annotations. If your project runs Doctrine ORM 3, annotations may not be registered as a mapping driver at all — this can silently produce "no mapped entities" instead of a clear error. Check doctrine:mapping:info.
• Bundle not registered is the #1 error. There is no extension able to load the configuration for "odiseo_blog" means the bundle isn't in config/bundles.php or the config key is misspelled. Run bin/console debug:container --parameter=... or debug:config odiseo_blog after registering.
• Don't trust schema:update. Use doctrine:schema:validate after mapping changes; it catches bad association mappings (mappedBy/inversedBy mismatches and wrong targetEntity) far faster than a runtime exception on a page render.
• Migrations on existing data. If you're adding this to an app that already has a post table, the auto-generated diff will try to drop/alter columns. Read it line by line before applying.
• Template override paths are silent failures. A typo in templates/bundles/OdiseoBlogBundle/... means Symfony just falls back to the vendor template with no warning. Verify with bin/console debug:twig | grep -i blog, which lists the resolved override paths.
• Route collisions. Import the bundle routing last in config/routes.yaml (or with a distinct prefix) so your own routes win. debug:router shows the final resolved order.
• debug:container for autowiring. If repository injection fails, bin/console debug:container PostRepository shows whether an alias exists. If not, define one in config/services.yaml with an explicit arguments: binding — cheaper than guessing at the bundle's service IDs.
• Cache is the universal red herring. After changing bundle config or overriding an entity, bin/console cache:clear before you start debugging anything else. Mapping and container metadata are cached aggressively.
• Extension points, ranked by cost: (1) override Twig templates, (2) decorate/replace a bundle service in services.yaml, (3) extend entities via inheritance mapping, (4) fork. Try them in that order — each step up costs significantly more maintenance.
• Fixtures for testing. Use doctrine/doctrine-fixtures-bundle to seed posts so your functional tests don't depend on whatever the bundle's own test setup assumes. Given the project's size, don't expect comprehensive upstream test coverage to lean on.