Blog Bundle Laravel Package

Getting Started

Important: This is Still a Symfony Bundle

BlogBundle 3.0 is a rewrite built on AdminBundle 3.0. It is not a Laravel package. The new release doubles down on Symfony/Twig integration ("shared list and actions macros"), which makes Laravel adoption harder, not easier. There is no in-place upgrade path from BlogBundle 1.x/2.x — v3.0 requires a fresh installation.

1. Confirm your Laravel stack can run Symfony 6.4+/Doctrine ORM 2–3

   • AdminBundle 3.0 requires Symfony 6.4, 7.x, or 8.x and Doctrine ORM 2 or 3.
   • Eloquent alone will not work; you need laravel-doctrine/orm (or equivalent) for entity mapping and migrations.

2. Install the AdminBundle 3.0 dependency first

   composer require aropixel/admin-bundle:^3.0 aropixel/blog-bundle:^3.0
   

   BlogBundle 3.0 will not resolve without AdminBundle ^3.0.

3. Follow the official installation guide — not the legacy config The 3.0 install steps live at:

   • doc/installation.md (BlogBundle)
   • UPGRADE-3.0.md (read even if "upgrading" — it explains the new entity/UI wiring)
   • AdminBundle 3.0 install docs

   Do not reuse aropixel_blog.yaml from v2 — the config surface changed in the rewrite (see Gotchas).

4. First Use Case: Content Management via AdminBundle 3.0 UI The primary intended workflow is admin-driven, not programmatic. After installing, posts and categories are managed through AdminBundle 3.0's CRUD UI using the shared list/actions macros. In a Laravel app this means:

   • Standing up AdminBundle's Symfony container inside your Laravel app (Symfony bridge / hybrid), or
   • Skipping the UI entirely and driving entities via the Doctrine EntityManager (loses the "shared macros" benefit).

5. First programmatic post (unchanged in shape)

   $post = new App\Entity\Post();
   $post->setTitle('Laravel + Symfony Bridge');
   $post->setSlug('laravel-symfony');
   $post->setContent('...');
   $em->persist($post);
   $em->flush();
   

   If multilingual: attach a translation (see i18n below) — v3.0 ships its own doc/i18n.md.

Implementation Patterns

1. Lean on AdminBundle 3.0, Not Custom CRUD

v3.0's headline feature is that posts/categories are managed entirely in the AdminBundle 3.0 UI using shared list and actions macros. Implications for Laravel:

• You don't write controllers for admin screens — you configure AdminBundle resources.
• Customization happens through macro overrides and AdminBundle config, not Laravel Blade views.
• If your team is Eloquent-only, you lose this benefit. Use it only if you're already running an AdminBundle bridge.

2. Multilingual Content (first-class in 3.0)

v3.0 promotes i18n to its own doc (doc/i18n.md). Pattern:

$post->setTranslation('en', new PostTranslation('Title', 'Body'));
$post->setTranslation('fr', new PostTranslation('Titre', 'Corps'));

Locales are configured on AdminBundle (not BlogBundle) in 3.0 — check AdminBundle 3.0 config, not the old aropixel_blog.yaml locales key.

3. Entity Extensions — Verify Before Building On Them

The v2 pattern of mapping Aropixel\BlogBundle\Entity\PostInterface → App\Entity\Post may have changed in the rewrite. Check UPGRADE-3.0.md for the new extension strategy before writing entity subclasses. Do not assume the old aropixel_blog.entities key still exists.

4. Doctrine Repositories

Querying via Doctrine repositories (as in v2) is still the way to consume posts programmatically — the rewrite is primarily UI/admin-focused:

$repo = $em->getRepository(App\Entity\Post::class);
$published = $repo->findBy(['publishedAt' => null]);

Confirm repository method signatures against v3.0 source; interfaces may have shifted.

5. Form Type Overrides

If v2's aropixel_blog.forms.* override points still exist (verify in doc/installation.md), the same pattern applies. Otherwise, extension moves into AdminBundle 3.0 form configuration.

Gotchas and Tips

1. No Upgrade Path — Treat v3.0 as a Greenfield Install

UPGRADE-3.0.md explicitly states there is no in-place upgrade. Any v2 config, custom entities, or repository overrides must be re-validated against 3.0 docs before copying. Budget rework time if you were on 2.x.

2. AdminBundle 3.0 Is a Hard Requirement

• Version constraints: AdminBundle ^3.0, Symfony 6.4/7.x/8.x, Doctrine ORM 2 or 3.
• If you're pinned to Symfony 5.x or Doctrine ORM 2 with older APIs, you cannot install BlogBundle 3.0 at all. This is a bigger constraint for Laravel-with-Doctrine-bridge setups than v2 was.

3. Laravel-Specific Pitfalls (unchanged, still real)

• Doctrine vs. Eloquent: 3.0 remains Doctrine-only. Mixing Eloquent and Doctrine models on the same entities will still bite.
• Macros are Twig — AdminBundle 3.0's "shared list and actions macros" are Twig macros. Laravel Blade cannot render them directly. Running AdminBundle in Laravel requires the Symfony Twig stack via a bridge.
• Routes/services: Still Symfony routing and DI. The routes/web.php + YamlFileLoader trick from the old assessment works only if you're already bridging Symfony routing.

4. Configuration Quirks to Re-verify

The v2 assessment referenced:

• aropixel_blog.categories: 'all'
• aropixel_blog.entities.PostInterface: App\Entity\Post
• aropixel_blog.forms.post_translatable

None of these are confirmed in the 3.0 release notes. Read doc/installation.md and UPGRADE-3.0.md end-to-end before configuring. The rewrite's config surface is the most likely source of "silent no-op" bugs (config accepted but ignored).

5. i18n Behavior

3.0 has its own i18n doc — treat it as authoritative rather than inferring from AdminBundle 2.x behavior. Common failure modes still apply:

• Translations must be persisted AND have a locale set.
• Locales are declared at the AdminBundle layer in 3.0.

6. Debugging Checklist

7. Performance (still applicable)

• Eager-load translations (fetch="EAGER" or JOINs) — N+1 on multilingual is the classic trap.
• Cache category/tag lists if they render in navigation.
• The admin UI's shared macros don't change query behavior; still audit repository calls.

8. Extension Points (re-verify signatures in 3.0)

• Custom repositories — still valid; confirm base class signature.
• Doctrine lifecycle event listeners — still valid (post.publish, prePersist, etc.); confirm event names haven't changed.
• AdminBundle macros — new primary extension point in 3.0; override in your AdminBundle config rather than extending BlogBundle classes directly.