Easy Blog Bundle Laravel Package

Getting Started

Minimal Steps to Begin

1. Installation Run composer require agence-adeliom/easy-blog-bundle in your Symfony project. Ensure your composer.json includes the custom Flex endpoint for Adeliom recipes.

2. Database Setup Generate and run migrations:

   php bin/console doctrine:migration:diff
   php bin/console doctrine:migration:migrate
   

3. EasyAdmin Integration Register the bundle in your config/packages/easy_admin.yaml:

   easy_admin:
       entities:
           - App\Entity\BlogPost
   

4. First Use Case Access /admin to manage blog posts via EasyAdmin’s CRUD interface. The bundle provides a pre-configured BlogPost entity with fields like title, content, slug, and publishedAt.

Implementation Patterns

Core Workflows

1. Entity Management

   • The bundle auto-generates a BlogPost entity (extendable via src/Entity/BlogPost.php).
   • Customize fields by overriding the entity or using EasyAdmin’s CRUD configuration:

     # config/packages/easy_admin.yaml
     easy_admin:
         entities:
             BlogPost:
                 class: App\Entity\BlogPost
                 list:
                     fields: ['title', 'publishedAt', 'tags']
                 form:
                     fields: ['title', 'content', 'slug', 'publishedAt', 'tags']
     

2. Tagging System

   • Uses a many-to-many relationship with a Tag entity (auto-created by the bundle).
   • Add tags via EasyAdmin’s form or programmatically:

     $post = new BlogPost();
     $post->addTag(new Tag('laravel'));
     $entityManager->persist($post);
     

3. Routing & Frontend

   • The bundle provides a basic controller (BlogController) for listing posts by tag/slug.
   • Override routes in config/routes.yaml:

     blog_index:
         path: /blog
         controller: App\Controller\BlogController::index
     

4. API Integration (Optional)

   • Expose endpoints via Symfony’s Serializer or API Platform:

     # config/packages/api_platform.yaml
     resources:
         App\Entity\BlogPost:
             collectionOperations:
                 get: ~
     

Integration Tips

• EasyAdmin Customization: Extend the CRUD with actions (e.g., publish/unpublish):

  actions:
      - { name: 'publish', icon: 'fas fa-check', label: 'Publish' }
  

• Event Listeners: Hook into lifecycle events (e.g., auto-generate slugs):

  // src/EventListener/BlogPostListener.php
  public function prePersist(BlogPost $post): void
  {
      $post->setSlug(Str::slug($post->getTitle()));
  }
  

• Asset Management: Use VichUploaderBundle for image uploads if extending the BlogPost entity.

Gotchas and Tips

Pitfalls

1. Migration Conflicts

   • If manually creating BlogPost or Tag entities, delete migrations first to avoid conflicts:

     php bin/console doctrine:migrations:diff --delete
     

   • The bundle’s migrations assume default entity namespaces (App\Entity\BlogPost).

2. EasyAdmin Version Mismatch

   • The bundle targets EasyAdmin 3.x. Ensure your easyadmin/easy-admin-bundle version is compatible (check Symfony Packagist).
   • Symptom: Blank admin dashboard or missing CRUD entries.
   • Fix: Downgrade/upgrade EasyAdmin to match the bundle’s requirements.

3. Slug Uniqueness

   • The bundle does not enforce unique slugs by default. Add a unique constraint in BlogPost:

     /**
      * @ORM\Column(type="string", length=255, unique=true)
      */
     private $slug;
     

4. Tag Auto-Completion

   • EasyAdmin’s tag field may not support auto-completion out of the box. Use a custom form type or EasyAdmin’s AutocompleteType.

Debugging

• Missing Entities in EasyAdmin: Clear cache and verify easy_admin.yaml:

  php bin/console cache:clear
  

  Check for typos in entity class names (e.g., App\Entity\BlogPost vs. App\Entity\Post).

• Database Errors: Run php bin/console doctrine:schema:validate to check schema consistency.

Extension Points

1. Custom Fields Add fields to BlogPost and update EasyAdmin’s CRUD:

   // src/Entity/BlogPost.php
   /**
    * @ORM\Column(type="string", length=255, nullable=true)
    */
   private $featuredImage;
   

   # easy_admin.yaml
   form:
       fields: ['featuredImage', 'title', ...]
   

2. Override Controllers Replace the default BlogController by copying src/Controller/BlogController.php to your project and updating routes.

3. Add Validation Extend BlogPost with constraints:

   use Symfony\Component\Validator\Constraints as Assert;
   
   /**
    * @Assert\NotBlank
    * @Assert\Length(max=500)
    */
   private $content;
   

4. Localization Translate labels in translations/easy_admin.en.yaml:

   blog_post:
       label: 'Blog Post'
       title: 'Title'
   

Pro Tips

• Soft Deletes: Integrate with gedmo/doctrine-extensions for soft-deleted posts:

  use Gedmo\Mapping\Annotation as Gedmo;
  
  /**
   * @Gedmo\SoftDeleteable(fieldName="deletedAt")
   */
  class BlogPost { ... }
  

• SEO Optimization: Use KnpLabs\DoctrineBehaviors for publishedAt and slug behaviors to reduce boilerplate.
• Testing: Mock the BlogPost entity in PHPUnit:

  $post = $this->createMock(BlogPost::class);
  $post->method('getTitle')->willReturn('Test Post');