Stand With Ukraine Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the bundle via Composer:

   composer require bw/stand-with-ukraine-bundle
   

   Register the bundle in config/bundles.php:

   return [
       // ...
       Bw\StandWithUkraineBundle\StandWithUkraineBundle::class => ['all' => true],
   ];
   

2. Enable Banner Add the banner Twig extension to your base template (e.g., base.html.twig):

   {% block stylesheets %}
       {{ parent() }}
       {{ stand_with_ukraine_banner_stylesheet() }}
   {% endblock %}
   
   {% block body_end %}
       {{ parent() }}
       {{ stand_with_ukraine_banner() }}
   {% endblock %}
   

3. First Use Case Immediately display the banner on all pages. No additional configuration is required for the basic banner.

Implementation Patterns

Banner Customization

• Override Banner Template Copy the default Twig template from vendor/bw/stand-with-ukraine-bundle/Resources/views/banner.html.twig to templates/bw_stand_with_ukraine/banner.html.twig to customize appearance (e.g., position, styling).

• Conditional Banner Display Use Twig logic to show/hide the banner dynamically:

  {% if app.request.get('_route') != 'homepage' %}
      {{ stand_with_ukraine_banner() }}
  {% endif %}
  

Russian IP/Blocklist Integration

• Block Russian IPs Enable blocking in config/packages/bw_stand_with_ukraine.yaml:

  bw_stand_with_ukraine:
      block_russian_ips: true
  

  • Custom Blocklist: Extend the default blocklist by overriding the Bw\StandWithUkraineBundle\Blocklist\RussianIpBlocklist service (see Extension Points).

• Language-Based Blocking Block users based on Accept-Language headers:

  bw_stand_with_ukraine:
      block_russian_language: true
      russian_languages: ['ru', 'ru-RU', 'ru-UA']  # Extend as needed
  

Integration with Security

• Firewall Integration Combine with Symfony’s firewall to redirect Russian IPs:

  # config/packages/security.yaml
  security:
      firewalls:
          main:
              pattern: ^/
              form_login: ~
              context: russian_block_context  # Custom context to check blocklist
  

  Create a custom context (e.g., RussianBlockContext) extending Bw\StandWithUkraineBundle\Security\RussianBlockContext.

Gotchas and Tips

Debugging

• Blocklist Updates The default blocklist is static (last updated in 2022). For production, extend the blocklist service to fetch updates from a reliable source (e.g., IP-API or IP2Location). Example extension:

  // src/Service/RussianIpBlocklist.php
  namespace App\Service;
  
  use Bw\StandWithUkraineBundle\Blocklist\RussianIpBlocklist as BaseBlocklist;
  
  class RussianIpBlocklist extends BaseBlocklist
  {
      public function isRussianIp(string $ip): bool
      {
          // Custom logic (e.g., API call) here
          return parent::isRussianIp($ip); // Fallback to default
      }
  }
  

  Register the service in config/services.yaml:

  services:
      App\Service\RussianIpBlocklist: ~
      Bw\StandWithUkraineBundle\Blocklist\RussianIpBlocklist: '@App\Service\RussianIpBlocklist'
  

• False Positives Russian IPs may belong to non-Russian users (e.g., VPNs, proxies). Test thoroughly in staging with a mix of Russian/non-Russian IPs before deploying to production.

Performance

• Cache Blocklist Cache the blocklist result to avoid repeated IP checks:

  bw_stand_with_ukraine:
      blocklist_cache_enabled: true
      blocklist_cache_ttl: 3600  # 1 hour
  

Extension Points

• Custom Banner Override the banner Twig template or use a custom Twig function:

  {% macro custom_banner() %}
      <div class="my-custom-banner">
          <a href="https://stand-with-ukraine.pp.ua">
              <img src="{{ asset('images/my-banner.svg') }}" alt="Support Ukraine">
          </a>
      </div>
  {% endmacro %}
  

• Event Listeners Listen to the bw_stand_with_ukraine.block_russian_ip event to log or notify when a Russian IP is blocked:

  // src/EventListener/RussianIpBlockListener.php
  namespace App\EventListener;
  
  use Bw\StandWithUkraineBundle\Event\RussianIpBlockEvent;
  use Symfony\Component\EventDispatcher\EventSubscriberInterface;
  
  class RussianIpBlockListener implements EventSubscriberInterface
  {
      public static function getSubscribedEvents(): array
      {
          return [
              RussianIpBlockEvent::NAME => 'onRussianIpBlock',
          ];
      }
  
      public function onRussianIpBlock(RussianIpBlockEvent $event): void
      {
          // Log or send notification
      }
  }
  

Configuration Quirks

• YAML vs. PHP Config The bundle supports both config/packages/bw_stand_with_ukraine.yaml and config/bundles.php overrides. Prioritize YAML for clarity:

  # config/packages/bw_stand_with_ukraine.yaml
  bw_stand_with_ukraine:
      banner_enabled: false  # Disable globally if needed
  

• Twig Autoescape Ensure the banner template respects autoescaping. Use |raw if embedding HTML:

  {{ stand_with_ukraine_banner()|raw }}