Redirect Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require wozbe/redirect-bundle
   

   Add to AppKernel.php:

   new Wozbe\RedirectBundle\WozbeRedirectBundle(),
   

2. Basic Configuration (config/packages/wozbe_redirect.yaml):

   wozbe_redirect:
       domains:
           example.com:
               aliases:
                   - www.example.com
                   - example.com.old
   

3. First Use Case:

   • Place the bundle before your main routing bundle in AppKernel.php to ensure redirects fire early.
   • Test by visiting http://www.example.com—it should redirect to http://example.com.

Implementation Patterns

Core Workflow

1. Define Domains: Configure all domain variants in config/packages/wozbe_redirect.yaml under domains. Use a canonical domain (e.g., example.com) and list all aliases (e.g., www.example.com).

2. Event-Based Integration:

   • The bundle hooks into Symfony’s kernel.request event. No manual checks needed in controllers.
   • For custom logic, listen to wozbe_redirect.pre_redirect (Symfony 2.x) or extend the bundle’s RedirectListener.

3. Dynamic Configuration:

   • Load domains from a database? Override Wozbe\RedirectBundle\Domain\DomainManager and inject your data source.
   • Example:

     # config/services.yaml
     Wozbe\RedirectBundle\Domain\DomainManager:
         arguments:
             $domains: '%kernel.project_dir%/config/domains.json'
     

4. Path Preservation:

   • Redirects automatically preserve the requested path (e.g., /blog → /blog on the canonical domain).
   • Disable this by setting preserve_path: false in config.

5. HTTP Status Codes:

   • Defaults to 301 (permanent). Change globally:

     wozbe_redirect:
         status_code: 302
     

Gotchas and Tips

Pitfalls

1. Order Matters:

   • Place WozbeRedirectBundle before other bundles (e.g., FrameworkBundle) in AppKernel.php. Otherwise, redirects may fail silently.

2. Case Sensitivity:

   • Domains are case-sensitive in HTTP headers. Ensure config matches exactly (e.g., WWW.EXAMPLE.COM ≠ www.example.com).

3. HTTPS/HTTP Mismatches:

   • The bundle does not handle protocol switching (e.g., http → https). Use Symfony’s HttpsRedirectListener or a reverse proxy (e.g., Nginx) for this.

4. Subdomains vs. Domains:

   • The bundle treats sub.example.com as a separate domain. For wildcard redirects, use a regex alias:

     example.com:
         aliases:
             - '*.example.com'  # Redirects all subdomains to example.com
     

5. Caching Headers:

   • If using a CDN or proxy, ensure Cache-Control headers don’t interfere with redirects. Test with curl -I.

Debugging Tips

1. Check Redirects:

   • Enable debug mode (APP_DEBUG=true) to see if the bundle fires. Look for 301/302 logs in Symfony’s profiler.

2. Log Configuration:

   • Add this to config/packages/monolog.yaml to log redirects:

     handlers:
         redirect:
             type: stream
             path: "%kernel.logs_dir%/redirect.log"
             level: debug
             channels: ["wozbe_redirect"]
     

3. Bypass Redirects:

   • Temporarily disable the bundle in AppKernel.php to isolate issues:

     // Disable for testing
     // new Wozbe\RedirectBundle\WozbeRedirectBundle(),
     

Extension Points

1. Custom Redirect Logic:

   • Override the RedirectListener to add conditions (e.g., skip redirects for /admin):

     // src/EventListener/CustomRedirectListener.php
     use Wozbe\RedirectBundle\Event\PreRedirectEvent;
     
     public function onPreRedirect(PreRedirectEvent $event) {
         if ($event->getRequest()->getPathInfo() === '/admin') {
             $event->setRedirect(false);
         }
     }
     

     Register as a service with tag kernel.event_listener and priority 255 (highest).

2. Database-Backed Domains:

   • Extend DomainManager to fetch domains from Doctrine:

     use Doctrine\ORM\EntityManagerInterface;
     
     public function __construct(EntityManagerInterface $em) {
         $domains = $em->getRepository(Domain::class)->findAll();
         parent::__construct($this->mapDomains($domains));
     }
     

3. Internationalized Domain Names (IDN):

   • Convert domains to ASCII (Punycode) before comparison:

     wozbe_redirect:
         convert_idn: true
     

4. Analytics Tracking:

   • Use the wozbe_redirect.post_redirect event to log redirects to Google Analytics:

     public function onPostRedirect(PostRedirectEvent $event) {
         // Track via GA or custom analytics
     }