Creating a Magento 2 Controller

22nd October 2016

Creating a Magento 2 controller within a custom module will enable us to access a specific route on the storefront and perform some functionality. If you’re familiar with creating a controller in earlier versions, there are some differences when creating them in Magento 2.

Controllers in Magento 2 differ from Magento 1 as for every action we have one controller class with an execute() method.

In Magento 1, the action is taken from the name of the method within the controller class.

In Magento 1, the following URL has a front name of custom which is set in the config.xml configuration file, a controller class name of UserController and an action method of createAction.

http://www.somesite.com/custom/user/create

Using the same URL, within Magento 2 we get a front name of custom, a folder within a Controller directory named User, and a controller class name of Create with the execute() method.

Let’s demonstrate this in action by setting up a basic module, starting with the module.xml.

// app/code/Siphor/Custom/etc/module.xml

<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:Module/etc/module.xsd">
    <module name="Siphor_Custom" setup_version="1.0.0" />
</config>

Then add the module’s registration.php file.

// app/code/Siphor/Custom/registration.php
<?php
\Magento\Framework\Component\ComponentRegistrar::register(
    \Magento\Framework\Component\ComponentRegistrar::MODULE,
    'Siphor_Custom',
    __DIR__
);

Then, run the following commands to enable your module and run the database upgrade.

$ /path/to/your/php bin/magento module:enable --clear-static-content Siphor_Custom
$ /path/to/your/php bin/magento setup:upgrade

The route configuration needs to be added within a routes.xml configuration file. As this example shows how to add a frontend route, this configuration file will reside in a frontend directory. Similarly, adminhtml routes belong in an adminhtml directory.

// app/code/Siphor/Custom/etc/frontend/routes.xml

<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../../../../../../lib/internal/Magento/Framework/App/etc/routes.xsd">
    <router id="standard">
        <route id="custom" frontName="custom">
            <module name="Siphor_Custom" />
        </route>
    </router>
</config>

The frontName attribute of the <route> node will be the front name i.e. the first part of the URL after the first “/”.

Now add the controller class. The controller class’ name will match the ‘action’ part of the URL and will reside within a User directory within the module’s Controller directory.

// app/code/Siphor/Custom/Controller/User/Create.php

<?php
namespace Siphor\Custom\Controller\User;
 
class Create extends \Magento\Framework\App\Action\Action
{
    public function execute()
    {
        echo "Welcome to the Siphor\Custom\Controller\User\Create execute() method!";
        exit();
    }
}

Note that the class extends Magento\Framework\App\Action\Action for adding frontend controllers. Admin controllers should extend Magento\Backend\App\Action

Refresh the cache and static content, head to the URL on your Magento store and you should see the message from the controller class method being printed out.

Note: This article is based on Magento CE version 2.1.