Banner Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   • Clone the repository into your project’s src/Awaresoft directory and symlink it (as per the README).
   • Ensure composer.json includes the bundle in require (or manually symlink BannerBundle to /src/Awaresoft/BannerBundle).
   • Clear Symfony cache:

     php bin/console cache:clear
     

2. Enable the Bundle: Add to config/bundles.php:

   return [
       // ...
       Awaresoft\BannerBundle\AwaresoftBannerBundle::class => ['all' => true],
   ];
   

3. First Use Case:

   • Display a Banner: Use the Sonata Block system to render a banner in your layout.

     {{ render(controller('AwaresoftBannerBundle:Default:block')) }}
     

   • Admin Configuration: Access the Sonata Admin for banners at /admin/banner.

Implementation Patterns

Core Workflows

1. Banner Creation:

   • Use Sonata Admin (/admin/banner) to define banners (title, content, visibility rules).
   • Example visibility rule (YAML config):

     # config/packages/awaresoft_banner.yaml
     awaresoft_banner:
         visibility:
             - { route: 'homepage', priority: 10 }
             - { route: 'product.*', priority: 5 }
     

2. Dynamic Rendering:

   • Inject the BannerManager service to fetch banners programmatically:

     use Awaresoft\BannerBundle\Manager\BannerManager;
     
     class MyController {
         public function __construct(private BannerManager $bannerManager) {}
     
         public function showHomepage() {
             $banners = $this->bannerManager->getVisibleBanners();
             // Render in Twig: {{ dump(banners) }}
         }
     }
     

3. Twig Integration:

   • Extend templates with banner blocks:

     {% block banner_area %}
         {% for banner in banners %}
             <div class="banner">
                 {{ banner.content|raw }}
             </div>
         {% endfor %}
     {% endblock %}
     

4. Fixtures:

   • Preload banners via Doctrine Fixtures:

     use Awaresoft\BannerBundle\Entity\Banner;
     
     public function load(ObjectManager $manager) {
         $banner = new Banner();
         $banner->setTitle('Promo');
         $banner->setContent('<h1>Sale!</h1>');
         $manager->persist($banner);
     }
     

Gotchas and Tips

Pitfalls

1. Symfony 2.x Dependency:

   • The bundle targets Symfony 2.x (not 3/4/5). Avoid mixing with modern Symfony features (e.g., make:controller).
   • Workaround: Use a legacy project or container aliases for compatibility.

2. Sonata Admin Quirks:

   • Block Registration: Ensure the block is registered in sonata_block.yaml:

     blocks:
         sonata.admin.block.admin_list:
             contexts: [admin]
         awaresoft_banner.block.banner:
             contexts: [admin, frontend]
     

   • Debug: Clear cache (ca:cl) if blocks fail to render.

3. Visibility Logic:

   • Priority-based rules (lower = higher priority) may conflict. Test with:

     $this->bannerManager->getVisibleBanners('homepage'); // Explicit route check
     

4. Database Schema:

   • The bundle assumes Doctrine ORM. If using Doctrine ODM, override the Banner entity manually.

Debugging Tips

• Log Visibility Rules: Enable debug mode and inspect BannerManager logs for skipped banners.

  $this->bannerManager->setDebug(true);
  

• Twig Debug: Dump banners in templates:

  {{ dump(app.container.get('awaresoft_banner.manager').getVisibleBanners()) }}
  

Extension Points

1. Custom Visibility Rules: Extend Awaresoft\BannerBundle\Visibility\VisibilityRuleInterface:

   class IpVisibilityRule implements VisibilityRuleInterface {
       public function isVisible(Banner $banner, Request $request) {
           return $request->getClientIp() === '127.0.0.1';
       }
   }
   

   Register in services.yaml:

   services:
       app.banner.ip_rule:
           class: App\Banner\IpVisibilityRule
           tags: [awaresoft_banner.visibility_rule]
   

2. Override Templates: Copy AwaresoftBannerBundle:Default:block.html.twig to templates/bundles/AwaresoftBanner/Default/block.html.twig.

3. Event Listeners: Hook into banner.pre_render or banner.post_save via Symfony events:

   services:
       app.banner.listener:
           class: App\Banner\BannerListener
           tags:
               - { name: kernel.event_listener, event: awaresoft_banner.pre_render, method: onPreRender }