Port Magento 1 Modules to Magento 2 with Plugins
Port Magento 1 Modules to Magento 2 with Plugins

Port Magento 1 Modules to Magento 2 with Plugins

Published August 13, 2015 in Development
Making Magento Code More Portable
Making Your Magento Code More Portable
July 28, 2015
What to Expect When Expecting Magento 2
What to Expect When You’re Expecting… Magento 2
October 15, 2015

Project Overview

One of Magento’s biggest strengths is its multi-store functionality. The ability to override data and configuration for a given website or store while inheriting higher scope values is particularly powerful, allowing merchants and developers to create tailored experiences without the overhead of managing completely different stores.

Although very powerful and flexible, managing many system configuration values for many different websites and stores can make it easy to overlook when a value is overridden at a more specific scope.

A similar problem exists when managing a large codebase with many subclasses. It’s sometimes easy to overlook when a method is overridden by a subclass, wasting development time. I’ve always been a fan of PHP Storm’s indication when a method is overridden by a subclass — the visibility that a simple icon provides is incredible.

PHP Storm method override icon

While working on a particularly multi-store-heavy site, I found myself similarly wasting time when I would fail to notice (or check) if a system configuration value was overridden at a more specific scope, and wished I had a similar visual cue. This prompted me to explore creating a module which would add this type of functionality to the system configuration.

Due to the recent release of Magento 2 RC2, I also wanted to explore porting this module to Magento 2.

 

Magento 1 Module

Requirements

Conceptually, this is a relatively simple addition. When each field is rendered, compare its value at the current scope to the values at more specific scopes. If the field’s value is different at any more specific scopes, add a visual indication to the right-most column with details and links to the overriding scopes.

Implementation

As with most modules which inject new functionality into existing areas of Magento, there are two big parts to the approach: find the most suitable point to modify or interact with core code, then use that interaction point to call custom logic which implements new functionality.

Interaction Point

After several debugging sessions, I found that there are no templates or layout XML for individual system configuration fields — we’ll be dealing with straight PHP for this modification. In particular, I need a to find a point in the core where (a) enough information about the field is present to perform value comparisons and (b) I can also influence the output of the scope label column.

In general, Mage_Adminhtml_Block_System_Config_Form::initFields() loops over elements of a group, and encapsulates the entire rendering of a field row. However, it doesn’t dispatch any events, nor is it well structured to subclass without copying the method contents forward — in fact, a rewrite of this method would require copying forward more than 200 lines of very logic-dense code. As such, it is an undesirable interaction point.

Mage_Adminhtml_Block_System_Config_Form::getScopeLabel(), however, seems promising; a simple method which accepts a field element, determines its scope label, and then returns the scope label as a string. A subclass could add content to the returned string without having to copy any code forward. Unfortunately, the element parameter does not contain sufficient information to get the field’s values, rendering this interaction point unusable for our purposes.

After much effort to find a “surgical” interaction point, I came to realize that, unfortunately, it would be necessary to rewrite Mage_Adminhtml_Block_System_Config_Form and copy its entire initFields() method forward. In an effort to avoid any more direct modifications than necessary, the only change I made to this method was to add an event before the element is rendered. This event, in turn, is observed by the module to effect the desired new functionality.

NOTE: this very compatibility concern was quickly manifested — on EE 1.10 (at least), the config scope hints are shown and accurate, but the UI input near them is always blank. After some investigation, this is due to differences in initFields() between the two versions. At this point, reconciling the different version is prohibitively time-consuming.

Custom Logic Implementation

Having determined an interaction point, the actual new functionality must be implemented. After some consideration, I decided to structure the encapsulated value override detection according to the following logic, given a config path and current context scope and scope ID.

  1. Get field’s precise value at context scope.
  2. Generate scope tree below current scope.
  3. Iterate over scope tree, getting values at each precise scope.
  4. If the iteration scope’s value does not match the context scope’s value, then add it to an array of overriding scopes.
  5. Finally, format output HTML string based on override array.

The most complicated part of this logic was reviewing the plethora of system config methods available through the core, and determining which is the best one to use for each of these steps. In particular, getting the precise value of a path at a given scope required using different methods from different models depending on the actual scope. That is, if a given field is set at the default, website, and store values, I couldn’t simply use Mage::getStoreConfig() to get the website value — this method expects a store instance, and passing in one of the website’s child stores would return the store’s value, which may differ from the website value. In addition, since it was necessary to use lower level methods to get precise values, I had to ensure that fields with a backend model were handled correctly.

However, after some trial and error to find core methods to robustly handle these issues, the resulting logic was complete.

Results

After adding a few styles and a tiny bit of Prototype UI javascript, the desired functionality works like a charm — fields overridden at more specific scopes now clearly indicate this fact.

Magento 1 config scope hints screenshot

Packaging

As with any other module distributed on GitHub, the standard packaging system is to create a modman config file to allow developers and merchants automated installations.

Magento 2 Module

Requirements

Magento 2 not only provides a much improved and better-designed framework on which to build, but also the opportunity to rethink existing approaches and requirements. However, given that this project was specifically intended to start as the concrete exercise of a straight port, the requirements were exactly the same as the Magento 1 module.

NOTE: this port was implemented and tested on Magento 2 version 0.74.0-beta4.

Implementation

This module has the same approach considerations as its Magento 1 inspiration: find the best way to interact with the core, then use that interaction point to implement custom functionality to accomplish the requirements. Due to significant architectural differences in M1 and M2, the M2 module would need to be restructured, pulling in a much code from the M1 version as possible.

Interaction Point

The biggest liability of the M1 module is the fact that, despite using a proper extension mechanism (block rewrite), a huge amount of logic had to be copied from the core and modified to create an interaction point, creating a significant surface area for compatibility issues.

In an effort to improve the interaction point in M2, I revisited the oh-so-close \Magento\Config\Block\System\Config\Form::getScopeLabel() method. Unlike M1, the M2 version of this method accepts a more specific object as its parameter, which handily does have all the required information to get its value. This small change means that the surface area of the interaction point (along with the possibility for compatibility issues) is significantly reduced.

Using my Magento customization bag of tricks, honed over the last three years and spanning as many certifications, I examined the options to interact with the getScopeLabel() method. As always, my first consideration is to determine which events, if any, can be observed. Alas, as is too often the case, there are no events which can be used.

In the absence of a usable event, my next consideration is to determine if the interaction point can be created by subclassing Form and overriding the getScopeLabel() method. Subclassing the Form class is still not ideal, as it would require a rewrite to take effect system-wide. While no code will be copied forward, this rewrite would conflict with any other module which also rewrites this class.

If only Magento could have anticipated my requirements and dispatched an event which passed the method’s arguments and also provided the opportunity to append to the method’s return value …

Fortunately, Magento 2, introduces the concept of plugins — a brand new extension mechanism which provides this exact functionality. Instead of depending on developers to anticipate all possible future customizations and dispatch corresponding events, plugins can intercept method calls before or after invocation, providing extremely flexible global interaction points.

In order to accomplish this module’s requirements, it actually needs to observe both before (to have original arguments present) and after (to append to the return value) getScopeLabel() invocation. This is supported by the around plugin listener type.

di.xml

Plugin.php

With this small amount of code, the module has a perfect interaction point, without having to rewrite the block — the chances of compatibility issues have never been lower.

Custom Logic Implementation

With a slick interaction point established, the M1 custom logic must be ported to M2. This was surprisingly easy — the only significant changes were that the config models must be injected rather than pulled off the old global Mage class and the logic had to be updated to use the M2 config methods to find config values for comparison.

Due to the robust dependency injection support in M2, I had to do nothing special to get instances of the config models — simply adding them to the constructor was sufficient. Adjusting for the new config model methods was also trivial. In fact, it was easy to find new methods which greatly simplified the previously unintuitive mechanisms for finding the precise value of a config field at a given scope. All in all, porting the module’s business logic didn’t take more than a half hour or so.

Results

Porting over the tiny bit of CSS into LESS and porting the tiny bit of UI javascript from Prototype to jQuery took no time at all, and before I knew it I had successfully ported my M1 module to M2.

Magento 2 config scope hints screenshot

Packaging

With the minor detail of actually accomplishing the requirements out of the way, it was time to package up the module and make it easy for merchants and developers to install. Due to Magento 2’s standardization on composer, this was very straightforward.

The module was committed to GitHub at the module root level, and a simple composer.json file added.

With this file in place, merchants and developers can easily install the module by running commands similar to the following from their Magento 2 root directory.

Pro Tips and Lessons Learned

Although I consider this port to have gone very smoothly, there were a few roadblocks for which the solution was not obvious. These are the gotchas and hiccups that I encountered and their solutions.

Outdated / missing documentation

When following Magento’s official developer documentation (as opposed to the old documentation which, annoyingly, seems to outrank the new docs in Google search results), a module’s basic declaration is of the following form.

Following that snippet, I created my module shell, only to be greeted with the following error message.

As stated in the error message, the schema_version attribute should actually be setup_version. Not a big change, but it’s kind of concerning that such a fundamental snippet is factually incorrect in the documentation — especially since this will be each new developer’s first stop.

At the very least, however, the presence of that error message demonstrated that my module was, indeed, being loaded. However, after fixing the attribute name, I couldn’t seem to get any of my module’s functionality to work. Struggling with out of date and missing documentation, I assumed that my dependency injection XML was simply incorrect. After much trial and error and debugging, I realized my module simply wasn’t enabled.

Although the documentation does give the following note, it doesn’t say how to actually enable a module — I’m doing development and I don’t have a deployment configuration file!

The enabled/disabled flag for a module is no longer set within a module; it is controlled by the deployment configuration file, with enabled=1, disabled=0. This is controlled by administrators and integrators, not by module developers.

With no actual documentation to guide me, I eventually figured out that modules must be enabled in app/etc/config.php. However, editing this file manually is discouraged, so the following commands (currently) are the best way to enable a module manually.

Since I think these documentation gaps are critical, I’ve created a pull request to update the documentation.

Developer Mode

Looking up errors in var/report gets old pretty quickly, so one of the first things I needed to figure out is how to display errors by enabling developer mode. Fortunately, it’s really straightforward — the MAGE_MODE environmental variable must be set to the value developer, as shown in the following examples.

  • Apache config: SetEnv MAGE_MODE developer
  • Bash .bash_profile: export MAGE_MODE=developer

Compiled Assets

Due to Magento 2 “compilation” of interceptors and views, I frequently ended up with Magento running out of date code. Having to work with this type of issue was not entirely unforeseen, but it took a few tries to figure out the exact directories to flush. For back end compiled assets (such as interceptors), deleting the contents of var/generation will cause them to be regenerated. For front end assets (such as LESS files), var/view_preprocessed should be flushed.

Where to go from here

As mentioned earlier, Magento 2 is not only an updated framework but also an opportunity to rethink existing solutions. Although this module provides value as a straight port, there is room to improve its adherence to Magento 2 conventions.

For example, in my opinion, the admin UI should be rethought — the tiny icon looks out of place on M2 and having all the content in the last store config field column doesn’t work as well, especially considering the semi-responsive nature of the M2 admin.

Another possible step forward, if the UI is updated to be more consistent with Magento 2 admin, and given the fact that Magento is accepting community contributions via GitHub, is that this module might be worth porting it to the core and issuing a pull request to be included in Magento 2 core.

Where to get it

Interested in using one of these modules or just want to review the entire source code? They’re freely available and liberally licensed at the following GitHub links.

Use it wisely!

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.

Most Recent PostsView all
September 17, 2019

Five Essential Components of Successful eCommerce Search

Having an effective on-site search strategy is more important than ever for today’s online retailers. According to a blog by Econsultancy, 30% of users on eCommerce […]
August 13, 2019

Automation Emails – The Key to Easy Email

Email is one of the most powerful tools in marketing. It can quickly become one of your top revenue generators and, if done right, provide you […]
August 2, 2019

Tombow’s Magento 1 to Magento 2 Migration