Blog Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require bbit/blog-bundle:dev-master
   

   Ensure knp-markdown-bundle and eko/feedbundle are also installed (required dependencies).

2. Enable Bundle: Add new BBIT\BlogBundle\BBITBlogBundle() to AppKernel::registerBundles().

3. Basic Configuration: Update config.yml with minimal settings:

   bbit_blog:
       extend_template: 'YourBundle:Default:layout.html.twig'  # Must include a `blogContent` block
       disqus_shortname: 'YourDisqusShortname'  # Required for comments
   

4. First Use Case: Run migrations to create the blog tables:

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

   Access /blog to see the default blog listing.

Implementation Patterns

Core Workflows

1. Post Management:

   • Use BBITBlogBundle:Post:new to create posts via a form.
   • Posts support Markdown (via KnpMarkdownBundle) by default.
   • Example Twig template for listing posts:

     {% extends 'YourBundle:Default:layout.html.twig' %}
     {% block blogContent %}
         {% for post in posts %}
             <h2>{{ post.title }}</h2>
             {{ post.content|markdown }}
         {% endfor %}
     {% endblock %}
     

2. Routing:

   • Default routes:
     • /blog → Lists all posts.
     • /blog/{slug} → Shows a single post.
   • Override routes in routing.yml:

     bbit_blog_post:
         resource: "@BBITBlogBundle/Resources/config/routing.yml"
         prefix:   /my-custom-prefix
     

3. Feeds:

   • RSS/Atom feeds are auto-generated via EkoFeedBundle.
   • Customize feed settings in bbit_blog.eko_feed:

     eko_feed:
         feeds:
             post:
                 title: 'Your Blog Feed'
                 link:
                     route: bbit_blog_post_index  # Override default route
     

4. Integration with Forms:

   • Extend the BBIT\BlogBundle\Form\PostType form to add custom fields:

     use BBIT\BlogBundle\Form\PostType as BasePostType;
     
     class ExtendedPostType extends BasePostType {
         public function buildForm(FormBuilderInterface $builder, array $options) {
             parent::buildForm($builder, $options);
             $builder->add('custom_field', TextType::class);
         }
     }
     

   • Update services.yml to replace the default form:

     services:
         bbit_blog.form.post_type:
             class: YourBundle\Form\ExtendedPostType
             tags:
                 - { name: form.type, alias: bbit_blog_post }
     

Gotchas and Tips

Common Pitfalls

1. Template Block Requirement:

   • The extend_template must include a blogContent block. Forgetting this causes a Twig_Error_Runtime.
   • Fix: Verify your base template has:

     {# ... #}
     {% block blogContent %}{% endblock %}
     

2. Markdown Dependencies:

   • If Markdown rendering fails, ensure knp-markdown-bundle is properly configured with a parser (e.g., commonmark).
   • Debug: Check knp_markdown.parser.class in config.

3. Feed Generation:

   • Feeds may fail if the eko_feed configuration is incomplete.
   • Tip: Test feeds at /feed/atom or /feed/rss after setup.

4. Slug Conflicts:

   • Default slug generation may create duplicates. Override the slugger service:

     services:
         bbit_blog.slugger:
             class: YourBundle\Service\CustomSlugger
             arguments: ['@doctrine.orm.entity_manager']
     

Debugging Tips

1. Enable Debug Mode:

   # config.yml
   framework:
       profiler: { only_exceptions: false }
   

   Check the profiler for SQL queries and Twig errors.

2. Log Migrations: Run migrations with verbose output:

   php bin/console doctrine:migrations:migrate --dry-run -v
   

3. Clear Cache: After configuration changes, clear the cache:

   php bin/console cache:clear
   

Extension Points

1. Custom Post Types:

   • Extend the Post entity to add fields:

     // src/YourBundle/Entity/Post.php
     use BBIT\BlogBundle\Entity\Post as BasePost;
     
     class Post extends BasePost {
         /**
          * @ORM\Column(type="string", nullable=true)
          */
         private $customField;
     }
     

   • Update the form and controller accordingly.

2. Override Controllers:

   • Replace the default PostController:

     services:
         bbit_blog.controller.post:
             class: YourBundle\Controller\PostController
             arguments: ['@service_container']
             tags:
                 - { name: controller.service_arguments }
     

3. Add Custom Routes:

   • Use YAML or annotations to add routes for custom actions:

     # src/YourBundle/Resources/config/routing.yml
     your_blog_custom_route:
         path:     /blog/tag/{tag}
         defaults: { _controller: YourBundle:Post:taggedPosts }