Blog Bundle Laravel Package

Getting Started

Minimal Setup for Laravel (Symfony-like Integration)

Since this is a Symfony bundle, Laravel developers must use Laravel Symfony Bridge or Symfony Components via Composer. For this assessment, we'll assume integration via Symfony components or a Laravel-compatible wrapper.

1. Install Dependencies

   composer require aropixel/blog-bundle aropixel/admin-bundle
   

   (Note: Laravel may require manual Symfony container setup or a bridge like laravel-symfony-bundle.)

2. Configure config/packages/aropixel_blog.yaml

   aropixel_blog:
       categories: 'all'  # Enable categories
       entities:
           Aropixel\BlogBundle\Entity\PostInterface: App\Entity\Post  # Custom entity mapping
   

3. Run Migrations

   php artisan doctrine:migrations:migrate  # If using Laravel Doctrine Bridge
   

   (Laravel users may need to adapt this to Eloquent migrations or use a hybrid approach.)

4. Register Routes Add to routes/web.php (Symfony-style):

   use Symfony\Component\Routing\Loader\YamlFileLoader;
   $loader = new YamlFileLoader($kernel, new FileLocator(__DIR__.'/config/routes'));
   $router->import('@AropixelBlogBundle/Resources/config/routing/aropixel.yml');
   

5. First Use Case: Create a Post Use the Admin Bundle’s CRUD interface (if integrated) or manually create a post via:

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

Implementation Patterns

1. Entity Extension Workflow

• Extend Base Entities: Override Post, Category, or their translations to add custom fields (e.g., author, tags).

  // app/Entities/Post.php
  class Post extends BasePost {
      #[ORM\Column(type: 'json')]
      private array $tags = [];
  
      public function addTag(string $tag): self {
          $this->tags[] = $tag;
          return $this;
      }
  }
  

• Configure in aropixel_blog.yaml:

  aropixel_blog:
      entities:
          Aropixel\BlogBundle\Entity\PostInterface: App\Entity\Post
  

2. Multilingual Content Handling

• Enable i18n: Configure locales in aropixel_admin.yaml:

  aropixel_admin:
      locales: ['en', 'fr', 'es']
  

• Add Translations:

  $post->setTranslation('en', new PostTranslation('English Title', 'English Content'));
  $post->setTranslation('fr', new PostTranslation('Titre Français', 'Contenu Français'));
  

3. SEO and Media Management

• SEO Fields: Use built-in fields like metaTitle, metaDescription, and keywords.

  $post->setMetaTitle('Laravel SEO Guide');
  $post->setFeaturedImage($imageEntity); // Supports crops via VichUploaderBundle
  

• Scheduled Posts: Set publication dates:

  $post->setPublishedAt(new \DateTime('+7 days')); // Future date
  $post->setExpiresAt(new \DateTime('+30 days'));  // Expiry date
  

4. Integration with Admin Bundle

• Leverage Admin CRUD: If using Aropixel Admin, posts/categories auto-register as editable entities.
• Customize Forms: Override form types in aropixel_blog.yaml:

  aropixel_blog:
      forms:
          post_translatable: App\Form\ExtendedPostTranslatableType
  

5. Querying Posts

• Repository Methods: Use the bundle’s repository for common queries:

  $publishedPosts = $postRepository->findBy(['publishedAt' => null]); // Published now
  $postsByCategory = $postRepository->findByCategory($category);
  

• Custom DQL: Extend the repository or use native Doctrine queries.

Gotchas and Tips

1. Laravel-Specific Pitfalls

• Doctrine vs. Eloquent: The bundle uses Doctrine ORM. Laravel developers must:
  • Use laravel-doctrine/orm or spatie/laravel-doctrine for integration.
  • Avoid mixing Eloquent and Doctrine models for the same entities.
• Migration Conflicts: Run doctrine:migrations:migrate after configuring custom entities to avoid schema errors.

2. Configuration Quirks

• Entity Mapping Order: Custom entities must be configured before the bundle loads. Use a Kernel event listener if needed.
• Locale Detection: Multilingual features require at least 2 locales in aropixel_admin.yaml. Single-locale setups default to non-translatable forms.
• Route Prefixes: Ensure prefix: /admin in routing/aropixel.yml matches your Laravel admin route group.

3. Debugging Tips

• Entity Resolution Issues: If custom entities aren’t recognized, check:
  • The entities config in aropixel_blog.yaml.
  • Doctrine’s metadata cache (php bin/console cache:clear).
• Translation Missing: Verify:
  • The PostTranslation entity is properly extended.
  • The locale field is set on translations.
• Image Uploads: For VichUploaderBundle crops, ensure:
  • The Post entity has #[Vich\Uploadable] annotations.
  • The uploads directory is writable.

4. Performance Considerations

• N+1 Queries: Use fetch="EAGER" for translations or DQL joins:

  $query->leftJoin('post.translations', 't')
        ->where('t.locale = :locale');
  

• Caching: Cache category/post lists if frequently accessed:

  $cache->get('blog_posts', function() {
      return $postRepository->findAll();
  });
  

5. Extension Points

• Custom Repositories: Override PostRepository or CategoryRepository for complex queries.
• Event Listeners: Hook into lifecycle events (e.g., post.publish):

  // src/EventListener/PostPublishListener.php
  class PostPublishListener {
      public function onPostPublish(PostEvent $event) {
          // Send notification, log, etc.
      }
  }
  

• Twig Extensions: Add helpers for templates:

  // src/Twig/BlogExtension.php
  class BlogExtension extends \Twig\Extension\AbstractExtension {
      public function getFunctions() {
          return [
              new \Twig\TwigFunction('latest_posts', [$this, 'getLatestPosts']),
          ];
      }
  }
  

6. Common Errors & Fixes