White Label Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require adespresso/white-label-bundle
   

   Add the bundle to AppKernel.php:

   new Ae\WhiteLabelBundle\AeWhiteLabelBundle(),
   

2. Basic Configuration: Define a config.yml (or packages/adespresso/white-label-bundle/white_label.yml in Symfony 5+) with a single white-label:

   ae_white_label:
       default_website: default_site
       websites:
           default_site:
               label: "Default Label"
               host: "*.example.com"  # Wildcard for subdomains
               method: byHost
               priority: 1
   

3. First Use Case: Use the whitelabel Twig function to conditionally render content:

   {% if whitelabel('default_site') %}
       <h1>Welcome to the Default Site</h1>
   {% else %}
       <h1>Welcome to the Generic Site</h1>
   {% endif %}
   

Implementation Patterns

Core Workflows

1. Domain-Based Routing:

   • Use byHost method to route traffic based on the HTTP Host header.
   • Example: foo.domain.com maps to foo_site in config.
   • Integration: Combine with Symfony’s router.request_context to dynamically adjust routes or assets.

2. User-Based Impersonation:

   • Use byUserParam to switch labels based on a user entity attribute (e.g., user.origin).
   • Example:

     user_param:
         key: origin
         value: "bar_website"
     

   • Integration: Extend the Ae\WhiteLabelBundle\Event\WhiteLabelEvent to fetch user data in event listeners.

3. Dynamic Asset Loading:

   • Override CSS/JS paths in Twig using the website function:

     <link rel="stylesheet" href="{{ asset(website('default_site').css_path ~ 'styles.css') }}">
     

   • Pattern: Store label-specific paths in config under custom_params:

     custom_params:
         css_path: "/bundles/foo_site/css/"
     

4. URL Generation:

   • Use impersonateUrl() to generate URLs for other white-labels:

     <a href="{{ path('home', {'_white_label': 'bar_site'}) }}">Switch to Bar Site</a>
     

   • Integration: Override Symfony’s UrlGenerator to respect _white_label parameter.

Advanced Patterns

1. Event-Driven Extensions:

   • Listen to ae_white_label.switch event to modify behavior dynamically:

     // services.yaml
     Ae\WhiteLabelBundle\EventListener\WhiteLabelSubscriber:
         tags:
             - { name: kernel.event_listener, event: ae_white_label.switch, method: onWhiteLabelSwitch }
     

   • Use Case: Log switches, update analytics, or trigger cache invalidation.

2. Database-Driven Labels:

   • Store label configurations in a database table (e.g., white_label_configs).
   • Implementation:
     • Create a custom loader for ae_white_label.websites in config.yml:

       websites: "@=service('app.white_label_loader').load()"
       

     • Implement WhiteLabelLoader to query your DB.

3. Multi-Tenant SaaS:

   • Combine with Doctrine extensions to scope queries per label:

     // In a repository
     $this->setWhiteLabel($whiteLabelId); // Hypothetical method
     

   • Pattern: Use the Ae\WhiteLabelBundle\WhiteLabelContext service to access the current label.

Gotchas and Tips

Pitfalls

1. Host Matching Quirks:

   • byHost uses exact matches by default. For subdomains, use wildcards (*.domain.com).
   • Fix: Ensure host values in config match the incoming Host header exactly or use regex via a custom WhiteLabelResolver.

2. Priority Conflicts:

   • If multiple labels match (e.g., byHost and byUserParam), the highest priority wins.
   • Debug: Use dump(website()) in Twig to inspect the resolved label.

3. Twig Function Scope:

   • whitelabel(), website(), and impersonateUrl() only work in Twig templates. For PHP logic, use the WhiteLabelContext service:

     $currentLabel = $this->get('ae_white_label.context')->getCurrentWebsite();
     

4. Caching Issues:

   • Symfony’s HTTP cache may not invalidate per-label. Solution:
     • Use Cache-Control: private headers.
     • Append _white_label to cache keys manually:

       $key = 'my_cache_' . $this->get('ae_white_label.context')->getCurrentWebsite();
       

5. Deprecated Symfony 2:

   • The bundle is Symfony 2-only. For Symfony 5/6, expect:
     • Bundle auto-registration issues (manually register in config/bundles.php).
     • Twig namespace changes (use {{ bundle('AeWhiteLabelBundle') }} if needed).

Debugging Tips

1. Enable Debug Mode: Add this to config.yml to log resolved labels:

   ae_white_label:
       debug: true
   

   Check var/log/dev.log for entries like:

   [WhiteLabel] Resolved 'foo_site' via 'byHost' (priority: 1)
   

2. Test Host Overrides: Use Symfony’s request_context to simulate different hosts in tests:

   $client->getContainer()->get('router.request_context')->setHost('foo.domain.com');
   

3. Validate Config: Run:

   php bin/console debug:config ae_white_label
   

   To ensure no syntax errors in YAML.

Extension Points

1. Custom Resolvers:

   • Implement Ae\WhiteLabelBundle\Resolver\WhiteLabelResolverInterface for new matching methods (e.g., byHeader for custom HTTP headers).
   • Register as a service tagged ae_white_label.resolver.

2. Twig Extensions:

   • Extend the bundle’s Twig functions by overriding the Ae\WhiteLabelBundle\Twig\WhiteLabelExtension service.

3. Database Backend:

   • Replace the config loader by implementing Ae\WhiteLabelBundle\Loader\WhiteLabelLoaderInterface.

4. Asset Pipeline:

   • Integrate with Symfony AssetMapper to generate label-specific manifests:

     custom_params:
         asset_manifest: "assets/foo_site.json"