Routes Deep Dive

Magento's route matching process resolves URLs to controllers.

Complete matching flow:

1. HTTP Request arrives
2. FrontController receives request
3. Router chain iterates
4. URL rewrites checked (url_rewrite table)
5. Route matching (routes.xml)
6. Controller resolution (frontName/controller/action)
7. Action execution

URL structure:

https://example.com/blog/post/view/id/5
         └─ domain ─┘└─ frontName ─┘└─ controller ─┘└─ action ─┘└─ params ─┘

Controller class resolution:

frontName: blog
controller: post
action: view

→ Vendor/Blog/Controller/Post/View.php
→ Class: Vendor\Blog\Controller\Post\View

Parameter extraction:

blog/post/view/id/5/key/value

→ id = 5
→ key = value

All URL segments after action become parameters

Route matching priority:

1. Exact URL rewrite match
2. Route with matching frontName
3. Default route (cms/index/index)
4. 404 Not Found

Custom routers handle non-standard URL patterns.

Custom router class:

<?php
namespace Vendor\Module\Router;

use Magento\Framework\App\Action\Forward;
use Magento\Framework\App\ActionFactory;
use Magento\Framework\App\RouterInterface;
use Magento\Framework\App\RequestInterface;

class CustomRouter implements RouterInterface
{
    public function __construct(
        private ActionFactory $actionFactory
    ) {}
    
    public function match(RequestInterface $request): ?ActionInterface
    {
        $path = trim($request->getPathInfo(), '/');
        
        // Match: product/URL_KEY
        if (preg_match('/^product\/([\w-]+)$/', $path, $matches)) {
            $request->setRouteName('catalog');
            $request->setControllerName('product');
            $request->setActionName('view');
            $request->setParam('url_key', $matches[1]);
            
            return $this->actionFactory->create(
                \Magento\Catalog\Controller\Product\View::class
            );
        }
        
        // Match: category/URL_KEY
        if (preg_match('/^category\/([\w-]+)$/', $path, $matches)) {
            $request->setRouteName('catalog');
            $request->setControllerName('category');
            $request->setActionName('view');
            $request->setParam('url_key', $matches[1]);
            
            return $this->actionFactory->create(
                \Magento\Catalog\Controller\Category\View::class
            );
        }
        
        return null; // Let next router try
    }
}

Register custom router:

<!-- etc/di.xml -->
<type name="Magento\Framework\App\Router\Base">
    <arguments>
        <argument name="actionList" xsi:type="array">
            <item name="custom_router" xsi:type="object">
                Vendor\Module\Router\CustomRouter
            </item>
        </argument>
    </arguments>
</type>

Router priority:

// Routers execute in order of registration
// First match wins

// Priority order:
1. UrlRewriteRouter (URL rewrites)
2. DefaultRouter (standard routing)
3. Custom routers (registered via di.xml)

URL rewrites intercept routing before standard route matching.

URL rewrite flow:

1. Request: /my-product.html
2. UrlRewriteRouter checks url_rewrite table
3. Found: target_path = catalog/product/view/id/5
4. Request is rewritten internally
5. Standard routing continues with rewritten path

Custom URL rewrite via code:

<?php
namespace Vendor\SEO\Service;

class UrlRewriteService
{
    public function __construct(
        private \Magento\UrlRewrite\Model\UrlRewriteFactory $rewriteFactory,
        private \Magento\UrlRewrite\Model\ResourceModel\UrlRewrite $rewriteResource
    ) {}
    
    public function createRewrite(
        string $requestPath,
        string $targetPath,
        int $storeId = 0,
        int $redirectType = 0
    ): void {
        $rewrite = $this->rewriteFactory->create();
        $rewrite->setStoreId($storeId);
        $rewrite->setRequestPath($requestPath);
        $rewrite->setTargetPath($targetPath);
        $rewrite->setRedirectType($redirectType);
        $rewrite->setEntityType('custom');
        $rewrite->setEntityId(0);
        
        $this->rewriteResource->save($rewrite);
    }
}

URL rewrite with router:

public function match(RequestInterface $request): ?ActionInterface
{
    $path = trim($request->getPathInfo(), '/');
    
    // Check for custom URL pattern
    if ($this->isCustomPattern($path)) {
        // Create URL rewrite on-the-fly
        $this->createRewrite($path, $this->getTargetPath($path));
        
        // Return forward to trigger rewrite
        $this->request->setPathInfo('/' . $this->getTargetPath($path));
        return null; // Let URL rewrite handle it
    }
    
    return null;
}

Debugging rewrites:

# Check rewrites
php bin/magento urlrewrite:index

# Clear rewrites
php bin/magento urlrewrite:reindex

# Check specific rewrite
mysql -u root -p magento -e "SELECT * FROM url_rewrite WHERE request_path = '/my-product.html';"

Advanced routing patterns for complex URL requirements.

Route with multiple parameters:

<route url="/V1/blog/:blogId/posts/:postId" method="GET">
    <service class="Vendor\Blog\Api\PostRepositoryInterface" method="getBlogPost"/>
</route>

Catch-all routes:

// Router that catches unmatched URLs
public function match(RequestInterface $request): ?ActionInterface
{
    $path = trim($request->getPathInfo(), '/');
    
    // If no route matched, try custom resolution
    if (!$request->getRouteName()) {
        $request->setRouteName('vendor_custom');
        $request->setControllerName('index');
        $request->setActionName('view');
        $request->setParam('path', $path);
        
        return $this->actionFactory->create(
            \Vendor\Custom\Controller\Index\View::class
        );
    }
    
    return null;
}

Route with condition:

public function match(RequestInterface $request): ?ActionInterface
{
    // Only route if specific condition is met
    if (!$this->isEnabled()) {
        return null;
    }
    
    $path = trim($request->getPathInfo(), '/');
    
    if ($this->matchesPattern($path)) {
        // Handle routing
    }
    
    return null;
}

Performance considerations:

1. Keep router logic simple (regex is expensive)
2. Return null quickly for non-matching paths
3. Use URL rewrites for static patterns
4. Cache router results when possible