How To: Building a Magento 2 Extension

August 4, 2016 by Leah Na'aman

Working with Magento 2 is a different experience to the one developers had with Magento 1 after numerous processes were streamlined and new tech stack components were brought into play.

Whether you’re new to Magento 2 or have been working with the platform for a while, our tips will make creating a Magento 2 extension a much smoother experience.

Get familiar with Composer

Magento 2 uses Composer to manage its components and their dependencies in PHP. It manages packages on a per-project basis, allowing you to single out the relevant libraries, which it then installs in a directory within the project.

To begin using Composer for your new extension, you’ll need a composer.json file. This file describes the dependencies of your project and may contain other metadata as well. To do this, you’ll need to specify the require key and then document the packages your project depends on using the project name and vendor name. Once this is done, just run the install command.

After installation has finished, Composer then writes a list of the exact versions installed into a composer.lock file. This is important because the install command checks for the lock file and then downloads the versions specified there.

Structure your module

Setting up Developer Mode

The simplest way to discover which mode is currently in play is to run a Current Mode command as the system user who owns Magento files. Enter a magento deploy:mode:show command and you’ll see a message informing you of the current application mode.

If you need to switch to Developer mode from Production mode, you’ll need to delete contents from var/generation and var/di directories and then set the mode:

magento deploy:mode:set developer

If you’re successful, you’ll see a Switched to Developer Mode message.

File structure

The following files are required for all components:

  • registration.php: Among other things, this file specifies the directory in which the component is installed by vendors in production environments
  • composer.json: Specifies component dependencies and other metadata.

Below is an example of a typical file structure for a Magento 2 module:

Magento 2 Extension File Structure

There are a few common module directories that can be used when creating a Magento 2 extension, such as:

  • Block: PHP view classes;
  • Controller: PHP controller classes;
  • etc: configuration files;
  • Model: PHP model classes;
  • Setup: classes for module database structure, as well as data setup.

Additional folders can be added for configuration and other supplementary functions for items like layout files and plug-ins.

Module XML

Magento 2 looks for configuration information for each module in that module’s etc directory. There you’ll find module.xml, which is a required file for registering the module. As well as telling Magento what dependencies the module has, it also describes the structure, content, filtering, and other features of a module. This was previously known as the app/etc/modules/Namespace_Module.xml file.

Dependency Injection

A dependency creates a connection between different objects in your code. Unfortunately, if there is a large amount of dependencies, your ability to reuse the code becomes limited. This means transferring these components to new projects will be a complicated job. Thankfully, this is a problem that can be solved by applying dependency injection.

Magento 2 uses DI as a substitute for Magento 1.x Mage class, as it facilitates loose coupling between entities in your code. Dependency Injection provides an object’s dependencies through its external environment rather than the manual internal creation.

Dependency management can be done through the Object Manager, which requires three types of configuration:

  • Class Metadata (definitions): describes the dependencies passed to an object.
  • Type Configuration: defines how a class is represented, as well as its lifestyle.
  • Abstraction-Implementation Mappings: maps the concrete implementations used when an interface requests an object.

For more information on these configurations, visit the Dependency Injection Developer Guide.


The new Magento Marketplace has a quality control system to ensure that only high-level extensions are available to the Magento community. This requires a technical review of all extensions before they are listed and includes the following checks:

  • Valid package type and structure
  • Code does not contain plagiarism
  • Code does not contain malware
  • Code follows Magento Coding Standards

To validate you Magento 2 extention, you’ll need to package your component, a process that includes:

  • Creating a Magento Composer file (json).
  • Registering the component using php.
  • Package and publish your component.

You can find the necessary script here to run an extension validation.

Release – upload to MagentoCommerce, Github or your own sever

Once you’ve used the validation tool to check your package, you can use Composer packages to distribute, install and upgrade components.

There are a number of rules to consider when releasing your extension in Magento Marketplace. For example, you shouldn’t use the word ‘Magento’ in the title, domain name or user name. Also, while you can feature a small Magento logo as part of your extension’s icon, it can’t look like the extension was actually made by Magento.

To upload, you’ll need to perform a zip operation on the directory containing your extension.

Below are detailed guidelines from Magento for hosting your Magento 2 extension

Hosting on GitHub and Packagist

Prerequisite: git must be set up on your machine.

  1. Navigate to your component directory, with the composer.jsonfile in the root, and make it a new git repository. See the GitHub documentation for details.
  2. When you have committed and pushed your component to your GitHub repository, you can either:
    • Use Composer to refer to it directly, or
    • Use the following steps to refer to the package through Packagist.
      1. Register an account at org.
      2. Click the Submit Package button and paste your GitHub repository link. Packagist automatically gathers the information from the component’s composer.jsonfile and link it to the GitHub repository, allowing you to reference the package as vendor/module without any additional repository information, because this is required solely using GitHub.


Hosting on a private repository

If you use the Setup Wizard, you must use the Magento Marketplace repository. A private repository can be used for development or private code but installation must be done with a command line interface (you can install a that specifies a private repository only with a command line installation).

  1. Set up your own Composer packaging repository using a system such as Satis or Toran.
  2. Create the package in a way similar to the described above.
  3. Submit/register the package on your own repository. For example, it can be hosted as a reference to a code repository or submitted as a zip-archive.
  4. To use the private packaging repository in a project, add the following to yourcomposer.jsonfile:

Using Private Packaging

All packages on the private repository can now be referenced within the require field.

Once this process is complete, you’re ready to upload your Magento 2 extension to Magento Marketplace.



  • Hi,
    I recently had the good fortune of reading your post regarding “How To: Building a Magento 2 Extension”. It is perfectly written and, contained sound, practical advice with valid facts and figures. I look forward to read your next informative write-up.
    I work for Baymediasoft – a Magento ecommerce development Company.
    Thank you.

    • Leah Na’aman

      Thanks Deepal! We look forward to sharing more great content with you 🙂