Overcoming Challenges in Magento Extension Development

Writing and maintaining Magento Open Source / Adobe Commerce extensions is a lucrative but challenging activity. Some challenges developers face on the road to success are unique to these platforms, while others are universal to the industry. Most fall somewhere in between.

In this article, I explore how to successfully navigate three particularly sticky aspects of Magento extension development: managing a massively extensible platform, keeping good testing practices and supporting a range of platform versions simultaneously.

3 Strategies for Navigating Extensibility

The first challenge to Magento extension development is the very concept of extensibility. Historically, Magento took an “extend everything” approach. In recent years, the platform has progressively reduced the extensible surface area. This reduction in extensible surface is both healthy and necessary for Magento to remain viable as a product. Too much extensibility leads to poor software implementation, security holes, hard-to-trace bugs and, eventually, so much tech debt piles up that innovation halts.

So, how can developers navigate this landscape of extensibility landmines? Simply put, it’s time to go back to the basics. Here are three strategies to consider:

1.     Look for Application Programming Interfaces (APIs)

Pay attention to code that Magento has marked as an API. In the new era of limited extensibility, the marked APIs are Magento’s guarantee of long-term support for extensibility on that feature.

2.     Limit Your Code’s Dependencies

Magento’s dependency injection is a wonderful, horrible monster. This means you should limit the dependencies your code has on external code. It’s so easy to get everything your code needs injected into one place without needing to know the details — this is great. However, too many dependencies on external code cause fragility, as the underlying software evolves and changes. By keeping your own components small and focused and limiting the dependencies that are injected, it’s easier to find and fix issues that come with platform evolution.

3.     Focus on Your Team

This is the most important strategy you can take. What knowledge and expertise does your team have? What kind of tools are ergonomic for them? How would they naturally build the same software if they weren’t working atop Magento?

For years, many of us would pride ourselves on being able to do things “the Magento way.” It was the subject of talk and debate and a touchstone we measured ourselves against. But, really, we’re all here to make profitable software. That means if our teams can most effectively work with a pattern or a tool that isn’t in the Magento core, we should consider that seriously and include those utilities whenever reasonable.

Prevent ‘Testing Heartache’ With Good Practices

A long-standing pain point for Magento extension developers is testing. Actually, let’s rephrase that — a long-standing pain point for all software developers is testing!

In recent years, Magento has moved mountains to improve the platform’s testing framework. But, brass tacks, Magento isn’t just some code; it’s a whole software platform. That means there are databases, file systems, caches and the above-mentioned extensibility, all adding their own pile of complexity into the test environment.

When it comes to testing an extension, there are three common approaches.

Option #1: Doing Nothing

The most tempting approach is to simply not use automated testing. Please, don’t fall for this false economy! It sounds good now, but many, many people will be driven to tears because of this decision down the road. The team will be plagued with repeated effort, slow lifecycle iterations, missing or misunderstood use cases, and so on — it feels worth it in the moment, but it's not.

Option #2: Utilizing Provided Scaffolding and Frameworks

A better option is to use the scaffolding and frameworks Magento offers. Their test frameworks basically fall into the categories of unit tests via PHPUnit and functional tests via Magento Functional Testing Framework (MFTF). These are powerful tools that should be seriously considered. Magento uses these tools to test their own code, so any developer choosing this option will have first-class support. However, there are reasons one might choose to not use these tools in some projects. In particular, MFTF, which has its own domain-specific language, is yet another tool that the development team has to master and remain knowledgeable about. This adds cognitive load as well as time and financial costs to the team. Also, the test frameworks themselves evolve with the platform, so tests written in one version of Magento may break, not because the code under test fails, but because the test framework changes.

Option #3: Finding a Happy Medium

Many extension development teams instead choose a middle road. They put the focus back on the team and what’s considered ergonomic to them. Developers may choose to use the “good parts” of Magento’s testing framework, such as PHPUnit — supplemented with fooman/magento2-phpunit-bridge — while filling the gaps with whatever testing tools are better understood by their team. For example, rather than investing human time and effort in learning MFTF, perhaps your team already knows Puppeteer or Cypress. Those tools can effectively fill the same testing gap as MFTF, but are more universal, so the knowledge and training transfers in and out of the team more easily. Put another way, it’s easier to onboard an engineer onto a team that’s using an industry-standard testing platform than it is to bring one onto a team using a platform they’ve never seen before.

Legacy Support Planning: A Key to Growth

Software grows, changes and improves to keep up with the needs of its users. If it doesn’t, it typically becomes defunct. When working in a complex platform, this growth is magnified. Not only does the extension provider-written software change, the underlying platform changes as well. In short, Magento consists of hundreds of thousands of lines of code that are ever shifting and changing.

Most of us writing code for Magento would prefer if all users immediately upgraded to the latest edition whenever there was a new release. However, that’s not practical for many. The merchants selling on a Magento store have finances to monitor, they have large sunk cost in their current solution and they may have little-to-no incentive to upgrade their shop. For most merchants, even a minor platform upgrade carries steep costs and high risks; thus, they’ll put it off as long as possible.

That leaves extension developers in the “wild” with the challenge of maintaining one extension across multiple platform versions. This could include being cross-compatible with different APIs, different PHP versions and more.

There are different extension versions and release schemes that can help mitigate the impacts of multi-version support, but none of them are surefire solutions.

The most important thing a developer can do is, simply, have a plan. Consider questions like these and make a plan you can follow as new releases become available:

• How long does the organization support an individual Magento release?
• Does the team you’re on have early access to new releases?
• Regardless of early access, how long before or after a new Magento release does testing commence?
• How long before or after a Magento release will your team guarantee compatibility?

Beyond having a plan, and well-communicated customer expectations, the rest comes down to testing practices. Everything previously mentioned about testing is doubly relevant when supporting multiple platform versions. Ensure the team’s testing is reliable, fast and fits their methods of working.

Magento Extension Development Challenges Solved

Working on one tiny piece of a very large and complex ecosystem comes with many challenges, mostly in the form of complexity inherited from the platform.

To work effectively despite all of this, remember to:

• Stick to the basics
• Invest in the techniques and tools that work well for your team
• Stay on top of testing
• Have a plan

With these tips in mind, you (and your team) are well on your way to developing successful — and lucrative — Magento extensions.