Blog Bundle Laravel Package

Getting Started

Minimal Setup Steps

1. Installation

   composer require akyos/blog-bundle
   

   Add to config/bundles.php:

   return [
       // ...
       Akyos\BlogBundle\AkyosBlogBundle::class => ['all' => true],
   ];
   

2. Database Migrations Run:

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

3. First Use Case: Create a Blog Post

   • Use the provided CRUD controller (src/Controller/BlogController.php if auto-generated) or extend Akyos\BlogBundle\Controller\BlogController.
   • Example route (check routing.yml in the bundle):

     blog_post:
         path:     /blog/{slug}
         controller: Akyos\BlogBundle\Controller\BlogController::show
     

4. Frontend Assets The bundle uses Webpack Encore. Check assets/blog/ for SCSS/JS templates. Run:

   yarn install
   yarn build
   

Implementation Patterns

Core Workflows

1. Post Management

   • Entity: Extend Akyos\BlogBundle\Entity\Post or use as-is.

     use Akyos\BlogBundle\Entity\Post;
     $post = new Post();
     $post->setTitle('Hello World');
     $post->setSlug('hello-world');
     $post->setContent('...'); // Uses CKEditor (via `friendsofsymfony/ckeditor-bundle`)
     $entityManager->persist($post);
     

   • Repository: Inject Akyos\BlogBundle\Repository\PostRepository for queries.

     $recentPosts = $postRepository->findBy([], ['createdAt' => 'DESC'], 5, 0);
     

2. Pagination Leverage knp-paginator-bundle for lists:

   use Knp\Component\Pager\PaginatorInterface;
   $posts = $paginator->paginate(
       $postRepository->findAll(),
       $pageNumber,
       10
   );
   

3. Recaptcha Integration Use karser/recaptcha3-bundle for form submissions:

   {{ form_start(postForm) }}
       {{ form_widget(postForm) }}
       {{ recaptcha3_widget('blog_post') }}
   {{ form_end(postForm) }}
   

4. Custom Fields Extend Post with Doctrine extensions (e.g., sluggable, timestampable):

   # config/doctrine/orm/beberlei_doctrineextensions.orm.yml
   orm:
       mappings:
           gedmo_timestampable:
               type: attribute
               prefix: Gedmo\Timestampable\Entity
               dir: "%kernel.project_dir%/vendor/gedmo/doctrine-extensions/src/Entity"
               alias: GedmoTimestampable
               is_bundle: false
   

5. Fixtures for Development Use AliceDataFixtures to seed posts:

   # config/packages/doctrine.yaml
   imports:
       - { resource: ../fixtures/blog.yml }
   

   Example fixture (config/fixtures/blog.yml):

   Akyos\BlogBundle\Entity\Post:
       post_{1..10}:
           title: '<sentence(5)>'
           slug: '<slug>'
           content: '<paragraphs(3)>'
           published: true
   

Gotchas and Tips

Common Pitfalls

1. CKEditor Configuration

   • Ensure friendsofsymfony/ckeditor-bundle is configured in config/packages/fos_ckeditor.yaml.
   • Default config may not match your theme. Override via:

     fos_ckeditor:
         config:
             my_config:
                 toolbar: ['div', '|', 'bold', 'italic']
     

2. Slug Generation

   • The bundle uses beberlei/doctrineextensions for slugs. If slugs fail:
     • Check Post entity has @Gedmo\Mapping\Annotation\Slug and setSlug() method.
     • Ensure doctrine/orm is configured to use extensions:

       doctrine:
           orm:
               entity_managers:
                   default:
                       mappings:
                           gedmo_sluggable:
                               type: attribute
                               prefix: Gedmo\Sluggable\Entity
                               dir: "%kernel.project_dir%/vendor/gedmo/doctrine-extensions/src/Entity"
                               alias: GedmoSlugable
       

3. Recaptcha Validation

   • If submissions fail silently, verify:
     • karser_recaptcha3 is enabled in config/packages/karser_recaptcha3.yaml.
     • The form includes the hidden recaptcha3 field (see bundle docs).

4. Webpack Encore Conflicts

   • If assets fail to compile, check:
     • webpack.config.js includes the bundle’s entry points:

       Encore
           .enableSassLoader()
           .addEntry('blog', './assets/blog/app.scss')
           .splitEntry('./assets/blog/app.scss')
           .enableSingleRuntimeChunk();
       

     • Run yarn watch during development.

5. Doctrine Fixtures Order

   • Fixtures may fail if dependencies (e.g., Category) aren’t loaded first. Use order in blog.yml:

     Akyos\BlogBundle\Entity\Category:
         category_{1..3}:
             name: '<word>'
     Akyos\BlogBundle\Entity\Post:
         post_{1..10}:
             title: '<sentence(5)>'
             category: '@category_*'
     

Debugging Tips

1. Entity Not Found

   • Clear cache and regenerate metadata:

     php bin/console cache:clear
     php bin/console doctrine:schema:update --force
     

2. Symfony Apache Pack

   • If using symfony/apache-pack, ensure .htaccess is deployed:

     php bin/console apache-pack:install
     

3. Paginator Issues

   • Check knp_paginator is configured in config/packages/knp_paginator.yaml:

     knp_paginator:
         page_range: 5
         default_options:
             page_name: page
             sort_field_name: createdAt
             sort_direction_name: direction
             distinct: true
     

Extension Points

1. Custom Post Types

   • Create a new entity extending Post:

     use Akyos\BlogBundle\Entity\Post;
     class NewsPost extends Post {
         // Custom fields/methods
     }
     

   • Register a new repository and controller.

2. Override Templates

   • Copy templates from vendor/akyos/blog-bundle/Resources/views/ to templates/blog/ in your project.

3. Add Taxonomies

   • Extend the Category entity or create a new one (e.g., Tag). Use many-to-many relations:

     /**
      * @ORM\ManyToMany(targetEntity="App\Entity\Tag", inversedBy="posts")
      */
     private $tags;
     

4. API Endpoints

   • Use Symfony’s Serializer to expose posts as JSON:

     use Symfony\Component\Serializer\SerializerInterface;
     $posts = $serializer->serialize($posts, 'json', [
         'groups' => ['post:read']
     ]);
     

   • Add [Groups({"post:read"})] to Post properties for serialization control.