[Drupal 8] Migrating Drupal 7 modules to Drupal 8
Drupal, up until now a PAC (Presentation Abstraction Control) architecture, has taken a step closer to MVC (Model View Controller) architecture. Although nowhere have they mentioned about MVC, the new Drupal 8 is strictly object oriented. Another feature in Drupal 8, that is different from the existing versions of Drupal is that it is not entirely Drupal. Drupal 8 uses many components in symfony like it's ClassLoader, YAML file structure, twig and so on. For a detailed description please visit the Drupal 8 home page.
In this article, I will explain how to convert an existing Drupal 7 module to Drupal 8. In Drupal 7, the first steps you follow to create a module is
- Create a <module name>.info file
- Create a <module name>.module file
- Create a <module name>.install file if a schema is required
These are the basic steps for a simple module creation. Plugins, css, images, etc can be added as required.
This is basically the same in Drupal 8 except we have to follow a yaml file structure in Drupal 8. The <module name>.info file should be renamed as <module name>.info.yml.
Say, for a module zyx, if the zyx.info file in Drupal 7 was :
name = ZYX
description = Some module to something.
package = ZYX
core = 7.x
files[] = zyx.module
files[] = zyx.install
; Information added by Drupal.org packaging script on 2013-12-12
version = "7.x-3.0"
core = "7.x"
project = "zyx"
datestamp = "1386880109"
In Drupal 8, the zyx.info.yml would be :
name: ZYX
description: 'Some module to something.'
package: ZYX
core: 8.x
version: 7.x-3.0
project: zyx
datestamp: '1386880109'
type: module
After the <module name>.info.yml file has been defined, you can go to the extend page in your Drupal site and see that the module has appeared in Drupal 8. The <module name>.install and <module name>.module files remain where they are. The schema definition remains unchanged in Drupal 8. The .module file has many changes which we will discuss now.
Firstly, hook_menu has been replaced in Drupal 8 by another yml file called <module name>.routing.yml. This is also a requisite for Drupal 8 module. Clear the hook_menu and move it with corresponding yml syntax to the <module name>.routing.yml file in the root of the module folder :
In Drupal 7 :
<?php
function zyx_menu() {
$items = array();
$items['zyx/one'] = array(
'title' => 'Zyx entry',
'description' => 'Enter zyx info into database',
'page callback' => 'Drupal_get_form',
'page arguments' => array('zyx_form'),
'access arguments' => array('access zyx content'),
'type' => MENU_NORMAL_ITEM,
);
}
In Drupal 8 : zyx.routing.yml
zyx.form:
path: /zyx/one
defaults:
_title: 'Zyx entry'
_form: \Drupal\zyx\Form\ZyxForm
requirements:
_permission: 'access zyx content'
As you can see in the yml file, the path to the form is defined and we notice another difference, which is the form definition has been moved from the .module file to a class in the form folder. We have to create a folder structure in the module folder to implement the MVC part of Drupal 8 i.e.,
module/
src/
Controller/
Form/ !-- Each form should be in a separate ClassName.php file. If any.
Plugin/
Block/ !-- If any.
<module name>.module
<module name>.routing.yml
<module name>.menu.links.yml
<module name>.info.yml
<module name>.permissions.yml
<module name>.install
This is standard for all Drupal modules. This is the PSR-4 compatible folder structure (Confer with PSR documentation). The form should be defined in a php file in the Form folder. This is the controller for the form. An example would be, in this case, "ZyxForm.php". Delete the form definition in <module name>.module file and copy it into the controller class definition in the form folder making the changes like below. The form definition for this would be :
<?php
/**
* @file
* Contains \Drupal\zyx\Form\ZyxForm.
*/
namespace Drupal\zyx\Form;
use Drupal\Core\Form\FormBase;
use Drupal\Core\Form\FormStateInterface;
use Drupal\Core\Render\Element;
class Zyx extends FormBase {
/**
* {@inheritdoc}
*/
public function getFormId() {
return 'zyx_form';
}
public function buildForm(array $form, FormStateInterface $form_state) {
$form['zyx_data'] = array(
'#type' => 'textfield',
'#title' => t('Data'),
'#size' => 30,
'#maxlength' => 200,
'#description' => t('Zyx data.'),
'#required' => TRUE,
);
$form['submit'] = array(
'#type' => 'submit',
'#value' => t($submit),
);
return $form;
}
public function validateForm(array &$form, FormStateInterface $form_state) {
//Code to validate here. Same as Drupal 7.
}
public function submitForm(array &$form, FormStateInterface $form_state) {
//Code to submit here. Same as Drupal 7.
}
}
Secondly, permissions are no longer set inside the .module file itself. You have to include a .permissions.yml file.
In Drupal 7 :
<?php
/**
* Implements hook_permission().
*
* Access and view content defined.
*/
function zyx_permission() {
return array(
'access zyx content' => array(
'title' => t('Access content for the Zyx module'),
),
);
}
In Drupal 8 : zyx.permissions.yml
'access zyx content':
title: 'Access content for the Address book module'
Thirdly, menu links are a separate file named <module name>.lniks.menu.yml unlike Drupal 8 which included it in the hook_menu itself. It is as follows :
zyx.form:
route_name: zyx.form
title: 'Zyx Entry'
description: 'Enter zyx info into database'
parent: zyx.page
Fourthly, any custom page defined in the <module name>.module will also have to be removed from the <module name>.module file. This will have to be moved to the controller folder as a Controller class similar to how form was done only difference is the class to extend :
<?php /**
* @file
* Contains \Drupal\zyx\Controller\DefaultController.
*/
namespace Drupal\zyx\Controller;
use Drupal\Core\Controller\ControllerBase;
use Drupal\Core\Url;
/**
* Default controller for the zyx module.
*/
class ZyxController extends ControllerBase {
//Custom page function(s) here. Copy the functions and from <module name>.module and place it here.
}
Finally, blocks are implemented as plugins in Drupal 8. If you look at the folder structure mentioned above, you can see that in the plugin folder there is block folder. This is because blocks are no longer defined in the conventional style; hook_block_info(), hook_block_view() have been deprecated. Your block definitions should be in another controller class similar to form. An example :
ZyxChow.php
<?php
/**
* @file
* Contains \Drupal\zyx\Plugin\Block\ZyxChow.
*/
namespace Drupal\zyx\Plugin\Block;
use Drupal\Core\Block\BlockBase;
/**
* Provides the ZyxChow block.
*
* @Block(
* id = "zyx_chow",
* admin_label = @Translation("Zyx's Chow")
* )
*/
class ZyxChow extends BlockBase {
/**
* {@inheritdoc}
*/
public function build() {
// Code to create a block. Just like Drupal 7.
//Return a renderable array;
}
}
Here, the @block part in the comment section is a mandatory. It defines the machine name and name of the block.
These are the basic things to be changed in a Drupal 7 module to make it work in a Drupal 8 installation. A few key things to remember while migrating to Drupal 8 are the PSR-4 folder compatibility, YAML file and correct syntax to use, all paths should be defined in routing YAML file. Migrating a module to Drupal 8 can be very long and tedious due to the vast differences from Drupal 7 to Drupal 8. There is another way to migrate modules to Drupal 8, which is using a Drupal 8 module called Drupal module upgrader. This module is in its development stages and does the converting fine for modules with a simple file structure, although it is found to be buggy when migrating projects with more than one modules like the coder or devel module.
Resources:
