Rewrite Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require atoolo/rewrite-bundle
   

   Enable the bundle in config/bundles.php:

   return [
       // ...
       Atoolo\RewriteBundle\AtooloRewriteBundle::class => ['all' => true],
   ];
   

2. Configuration: Add a basic config/packages/atoolo_rewrite.yaml:

   atoolo_rewrite:
       rules:
           - pattern: '/old-url'
             target: '/new-url'
             permanent: true
   

3. First Use Case: Test URL rewrites by accessing /old-url—it should redirect to /new-url (if permanent: true) or rewrite internally.

Key Files to Explore

• config/packages/atoolo_rewrite.yaml: Central configuration for rewrite rules.
• src/Controller/: Example controllers demonstrating integration (if any).
• tests/: Unit/integration tests for edge cases (e.g., SameNavigationUrlRewriteHandler).

Implementation Patterns

Core Workflows

1. Rule-Based Rewriting: Define rules in YAML/array format:

   rules:
       - pattern: '/blog/old-post'
         target: '/articles/new-post'
         priority: 100  # Higher priority = earlier execution
         context: ['web']  # Optional: Limit to specific contexts (e.g., 'api', 'web')
   

   • Dynamic Rules: Use placeholders like {slug} and resolve them via UrlRewriteContext:

     rules:
         - pattern: '/products/{slug}'
           target: '/catalog/{slug}'
           resolver: App\Resolver\SlugResolver  # Custom resolver class
     

2. Context-Aware Rewriting: Leverage UrlRewriteContext to conditionally apply rules (e.g., per locale/microsite):

   context:
       locales:
           - en
           - de
       microsites:
           - shop1
           - shop2
   

   Override rules per context:

   rules:
       - pattern: '/contact'
         target: '/support'
         context: ['web', 'en']  # Only for English web context
   

3. Event-Driven Integration: Listen to atoolo.rewrite.pre_rewrite and atoolo.rewrite.post_rewrite events to modify behavior:

   // src/EventListener/CustomRewriteListener.php
   public function onPreRewrite(RewriteEvent $event) {
       if ($event->getRequest()->getPathInfo() === '/admin') {
           $event->setTarget('/dashboard');
       }
   }
   

4. Controller Integration: Use the RewriteAwareTrait in controllers to access rewrite logic:

   use Atoolo\RewriteBundle\DependencyInjection\RewriteAwareTrait;
   
   class ProductController {
       use RewriteAwareTrait;
   
       public function show(Product $product) {
           $rewrittenUrl = $this->rewriteService->rewrite(
               '/old-product-url',
               new UrlRewriteContext(['locale' => 'en'])
           );
           // ...
       }
   }
   

Common Patterns

• SEO-Friendly Redirects: Use permanent: true for 301 redirects (e.g., /old-page → /new-page).
• Parameter Extraction: Capture dynamic segments (e.g., {id}) and pass them to resolvers.
• Fallback Rules: Define a catch-all rule for unmatched URLs:

  rules:
      - pattern: '/.*'
        target: '/404'
        priority: -100
  

Gotchas and Tips

Pitfalls

1. Rule Order Matters:

   • Rules are evaluated in priority order (highest first). Ensure specific rules (e.g., /blog/.*) precede generic ones (e.g., /.*).
   • Debug with bin/console debug:atoolo-rewrite to list active rules.

2. Context Mismatches:

   • Rules with context constraints won’t apply if the current context (e.g., locale) doesn’t match. Verify contexts in logs:

     # Enable debug logging
     atoolo_rewrite:
         debug: true
     

3. Circular Redirects:

   • Avoid chains like A → B → A. Test with:

     bin/console debug:router | grep "rewrite"
     

4. Resolver Dependencies:

   • Custom resolvers must implement Atoolo\RewriteBundle\Resolver\ResolverInterface. Forgetting this causes RuntimeExceptions.

5. Symfony Router Conflicts:

   • If routes conflict with rewrite patterns, use priority to force precedence. Example:

     # Ensure rewrite runs before Symfony's router
     framework:
         router:
             resource: "%kernel.project_dir%/config/routing.yaml"
             rewrite_bundle_priority: 200  # Higher than default (100)
     

Debugging Tips

• Log Rewrite Events: Enable debug mode in config/packages/dev/atoolo_rewrite.yaml:

  debug: true
  

  Check var/log/dev.log for resolved rules and context data.

• Dry-Run Rules: Use the atoolo:rewrite:validate command to test rules without executing them:

  bin/console atoolo:rewrite:validate /old-url
  

• Common Errors:

  Error	Cause	Fix
  No rewrite rule found	Missing or misconfigured pattern	Add a catch-all rule or check YAML.
  Resolver not found	Invalid resolver class	Verify the class implements the interface.
  Context not supported	Unmatched context	Adjust contexts or remove constraints.
  Invalid target URL	Malformed target (e.g., relative path)	Use absolute paths (e.g., /new-url).

Extension Points

1. Custom Handlers: Extend Atoolo\RewriteBundle\Handler\AbstractRewriteHandler to create reusable logic (e.g., TrailingSlashHandler).

2. Dynamic Rule Loading: Load rules from a database or API by implementing Atoolo\RewriteBundle\Loader\LoaderInterface:

   class DatabaseLoader implements LoaderInterface {
       public function load(array $config): array {
           return $this->fetchRulesFromDatabase();
       }
   }
   

   Register it in config/packages/atoolo_rewrite.yaml:

   loader: App\Loader\DatabaseLoader
   

3. Middleware Integration: Use Symfony’s middleware to pre-process requests:

   // src/Middleware/RewriteMiddleware.php
   public function handle(Request $request, callable $next) {
       $rewrittenUrl = $this->rewriteService->rewrite($request->getUri());
       if ($rewrittenUrl !== $request->getUri()) {
           return new RedirectResponse($rewrittenUrl);
       }
       return $next($request);
   }
   

4. Testing: Mock the RewriteService in PHPUnit:

   $rewriteService = $this->createMock(RewriteService::class);
   $rewriteService->method('rewrite')->willReturn('/rewritten-url');
   $this->container->set(RewriteService::class, $rewriteService);
   

Configuration Quirks

• Lang Prefix Handling: The bundle automatically handles /{locale}/ prefixes if framework.default_locale is set. For custom locales, ensure they’re listed in atoolo_rewrite.context.locales.

• Microsite Support: Use pparam (page parameter) for microsite-specific rules:

  rules:
      - pattern: '/{pparam}/product'
        target: '/{pparam}/catalog'
  

  Access pparam via $event->getPageParameter() in listeners.

• Performance: Cache rules in production by enabling:

  cache: true
  cache_lifetime: 3600  # 1 hour