📝 Community Note The content on this page was generated with the assistance of AI and is pending a human review. While we've done our best to ensure accuracy, there may be discrepancies or areas that could be improved.
routes.xml Reference Documentation
- File Location and Structure
- <config> Element
- <router> Element
- <route> Element
- <module> Element
routes.xml file is an essential configuration file in Magento 2, particularly when it comes to defining and
managing custom routes. This file plays a crucial role in routing HTTP requests to the appropriate controllers in your
Magento 2 module. In this document, you will learn how to effectively utilize the
routes.xml file to create and manage
routes in your Magento 2 module.
File Location and Structure
routes.xml file resides in the
etc/adminhtml directory of your module. The exact file path
depends on whether your module is for the frontend or admin area of Magento 2. The file follows a structured XML format
and consists of multiple elements that define the routes and their associated controllers.
Here is an example of the basic structure of a
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"xsi:noNamespaceSchemaLocation="urn:magento:framework:App/etc/routes.xsd"><router id="[ROUTER_ID]"><route id="[ROUTE_ID]" frontName="[FRONT_NAME]"><module name="[MODULE_NAME]"/></route></router></config>
Let's dive into each of these elements to gain a deeper understanding.
<config> element is the root element of the
routes.xml file. It defines the XML namespace and specifies the
schema location using the
xsi:noNamespaceSchemaLocation attributes, respectively. You don't need to
modify these attributes as they refer to the default schema provided by Magento.
<router> element is used to define the router ID, which is a unique identifier for the router. The router ID is
used to group related routes together. In most cases, you will use either
admin as the router ID. For
<router id="standard"> defines a router for the frontend area, whereas
<router id="admin"> defines a router
for the admin area.
<route> element represents a specific route in Magento 2. It consists of three attributes:
idattribute specifies a unique identifier for the route and is used internally by Magento to identify and match the incoming requests.
frontNameattribute defines the URL segment that precedes the action name in the URL. For example, if
frontName="custom", the URL
https://example.com/custom/index/indexwill map to the
Index/Indexaction of the associated controller.
- The optional
disabledattribute, when set to
true, disables the route. This can be useful when you want to temporarily deactivate a route without removing it from the
<module> element is a child element of the
<route> element, and it specifies the name of the module that handles
the route. The
name attribute should match the module's name as defined in its
Let's walk through an example to illustrate how the
routes.xml file works. Assume we have a module
Acme_CustomModule that needs to define a custom route for frontend pages.
Here is the
routes.xml file for this module:
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"xsi:noNamespaceSchemaLocation="urn:magento:framework:App/etc/routes.xsd"><router id="standard"><route id="custom" frontName="custom"><module name="Acme_CustomModule"/></route></router></config>
In this example, we defined a route with the
id of "custom" and
frontName of "custom". The associated module is
Now, let's assume we have a controller named
Index inside the
Acme\CustomModule\Controller\Index namespace. With
routes.xml configuration, the URL
https://example.com/custom/index/index will map to the
routes.xml file is a crucial component for defining and managing routes in Magento 2. By carefully configuring
this file, you can easily map incoming HTTP requests to the appropriate controllers within your module. Understanding
the structure and elements of the
routes.xml file will empower you to create custom routes efficiently. Remember to
adhere to the XML structure and use correct attribute values to ensure proper routing functionality.