People often asks us how to do a Magento 2 Composer Module Update for their extensions whenever they want to release a new version of their modules.

There are different ways of doing it, we will show you how to do with with git tags and a semantic versioning strategy for the releases, which we thing is the most professional and reliable way.

We will continue with the example of our previous post where we showed you how to create a hello world extension in Magento 2 with composer.

For the newcomers to composer, et me quickly give you an brief explanation of how does it work, more specifically, how we use it together with Magento 2 while developing new modules:

• To install a new extension developed by ourselves (or by a third party): We normally use “composer require vendor-name/extension-name” from the root folder of Magento 2. Which, by default (depending on the value we’ve set for “minimum-stability” and “prefer-stable” in our composer.json file) will attempt to install the latest version of that extension that meets its dependencies/requirements within your system/application. This means that, for example, if you are using php 5.5.x and the latest version of the extension that you are installing has a dependency (composer.json “require” section) like:

  "php":">=5.6"

  Then, the latest version of the extension cannot be installed on your system. Composer will firstly try to install a newer version of the dependency, and failing that, will search backwards previous versions of the extension until it finds the most recent version that works with php 5.5. Eventually, it will fail if it cannot find any version installable (that meets all the dependencies) in your system . Normally, you just run the command and everything runs smoothly, composer will take care of everything from you, but sometimes it will fail with an error like below:

  composer require lumbrales-software/magento2-first-module 
  Using version dev-master for lumbrales-software/magento2-first-module     
  ./composer.json has been updated
  Loading composer repositories with package information
  Updating dependencies (including require-dev)                             
  Your requirements could not be resolved to an installable set of packages.
  
    Problem 1
      - magento/project-community-edition dev-master requires magento/product-community-edition 2.0.2 -> no matching package found.
      - magento/project-community-edition 2.0.2 requires magento/product-community-edition 2.0.2 ->  no matching package found.
      - magento/project-community-edition 2.0.1 requires magento/product-community-edition 2.0.1 ->  no matching package found.
      - magento/project-community-edition 2.0.0-rc2 requires magento/product-community-edition 2.0.0-rc2 ->  no matching package found.
  

  This can sometimes require a system update, or like in the above example, adding a custom repository where composer can find the required package.

• To release a new version (code changes) of your extension: This is the interesting part. People are usually confused and run “composer update” and expect it to do the job, but the problem is that the above command can often lead to undesired and unexpected results, since it will try to update every single package, which is not always (almost never) what we want. Normally, you want to update an specific package, or maybe even a whole vendor, but not everything at once. Therefore, we recommend to tell composer what to do, like in the example of our previous post:

  # Update an specific package
  composer update lumbrales-software/magento2-first-module
  # Update all packages of the vendor
  composer update lumbrales-software/*
  

Having said that, now let’s focus on how to release a new version of our extension.

The process is actually simpler than it might seem, all you have to do is implement your new functionality, code changes, whatsoever, using whichever git branching strategy you want, and once you are ready, you can do the following steps:

• Merge your changes into the master branch
• Choose a version for the update/release, following the guidelines of semantic versioning:
  Given a version number MAJOR.MINOR.PATCH, increment the:
  1. MAJOR version when you make incompatible API changes,
  2. MINOR version when you add functionality in a backwards-compatible manner, and
  3. PATCH version when you make backwards-compatible bug fixes.

  Additional labels for pre-release and build metadata are available as extensions to the MAJOR.MINOR.PATCH format.
  Note: If you want to release a stable version, it has to be at least 1.0.0, otherwise it will be considered unstable by composer and might lead to issues while installing it.

• Update your composer.json with the new version (ie. “version”: “1.0.1”,) and commit the changes of the file.
• Create a git tag with the new version:

  git tag 1.0.1

• Push the changes and the tag:

  git push origin master
  git push --tag

• That’s it! Now, you should be able to run composer update your-vendor/your-module and it will fetch your changes:

composer update lumbrales-software/magento2-first-module -v
Loading composer repositories with package information
Reading composer.json of lumbrales-software/magento2-first-module (1.0.2)
Importing tag 1.0.2 (1.0.2.0)
Reading composer.json of lumbrales-software/magento2-first-module (1.0.1)
Importing tag 1.0.1 (1.0.1.0)
Reading composer.json of lumbrales-software/magento2-first-module (master)
Importing branch master (dev-master)
Updating dependencies (including require-dev)
  - Removing lumbrales-software/magento2-first-module (1.0.1)
  - Installing lumbrales-software/magento2-first-module (1.0.2)
    Downloading: 100%         
    Extracting archive

Writing lock file
Generating autoload files

Note: Sometimes composer seems to keep cached the repository changes and won’t fetch your new code changes, I found a workaround for that by clearing the cache with the below command (run it as your own risk):

rm -fr ~/.composer/cache/*

That’s about it, you now should be able to release code changes nicely, and for every new code changes you just need to bump the version accordingly and remember to push both the version update in the composer.json and the git tag.

Good luck!

Let us know if you have any issues with it and we’ll try to assist you.

If you are a developer new to Magento 2, you are probably wondering how to create a Magento 2 Composer Module. Hopefully the below steps will be useful to you. This is how I managed to do it, eventually.

First of all, you should familiarise yourself with composer, and it’s basic usage.

This guide asumes you’ve already installed and configured a vanilla Magento 2 project. If you haven’t done that yet, I’d advise you to check this out and follow the official guide. Feel free to drop me a line if you have any issues.

I’ve found quite a few sites that show how to create a Magento 2 module “the old way”, by copying the module contents inside app/code folder (note that in Magento 1.x it used to be app/code/codePool, but that doesn’t exist anymore in Magento 2).

However, as I’ve recently been working on Symfony 2 projects, I’m quite used to composer, and it’s usage to easily integrate third party components/packages. So, once I saw the file “composer.json” on the root directory of Magento 2, I knew that it should be the way forward in order to develop Magento 2 extensions.

Let’s get started. I’m assuming you’ve developed already your Magento 2 extension, as the purpose of this guide is to show how to package the extension within a composer (sub) module, and the creation of an extension would go beyond the scope of this post. Check this guide to find out how to create a Magento 2 extension, or just clone it’s source code from github.

• To begin with, you should create a new (github/bitbucket…) repository, and place your source code inside.
• In the root folder, create a new file named composer.json. This fille will describe the details of your package. This is how mine looks like:

  {
      "name": "lumbrales-software/magento2-first-module",
      "description": "Hello world Magento 2 Composer Module!",
      "require": {
          "magento/project-community-edition": "*"
      },
      "type": "magento2-module",
      "version": "0.1.0",
      "extra": {
          "map": [
              [
                  "*",
                  "Yourcompany/YourModule/"
              ]
          ]
      },
      "authors": [
          {
              "name": "Javi Lumbrales",
              "homepage": "https://www.lumbrales-software.com/",
              "role": "Developer"
          }
      ]
  }

  The most important parts described below:

  • The name of the package: This will serve as identifier of your package, and will be used later on.
  • Requirements: We’ve added “magento/project-community-edition” as a requirement, as this module requires Magento 2 in order to work.
  • Type: We specify “magento2-module” so that it’s contents are copied to app/local once the package is installed (more about this later).
  • Version: Not important, as we’ll use git tagging to handle the composer module updates.
  • Extra: – Map: This tells composer to copy all (*) contents into app/code/LumbralesSoftware/HelloWorld, so the root of your extension should be structured already. This means that you don’t need to keep your files under app/code/YourCompany/YourModule in your repository. Instead, they should be in the root straightly. This is how it your repository should look like:

Repository Root:
Block/
Controller/
etc/
…

• Push all your code to the master branch (I’ll explain the tagging on a separated post later on)
• Go to the root folder of your Magento 2 installation, and type the following commands in your terminal:

composer require magento/magento-composer-installer

This is a submodule required to properly install third party Magento 2 extensions as composer submodules (Remember the type:magento2-module mentioned at the beginning).

• Then, as your module is still not in a packages repository such as packagist.org, or packages.magento.com, you need to specify your own VCS repository so that composer can find it. In the repositories section of the composer.json file of the Magento 2 project (if the repositories section doesn’t exist, create it, else, add your repository at the end) add the following:

 "repositories": [
    {
      "type": "vcs",
      "url": "https://github.com/youraccount/yourmodule-repository"
    }
  ],

• Since your package is in a development stage, you will need to add the minimum-stability as well to the composer.json file:

"minimum-stability": "dev",

Note that this could be removed later on, once we have properly tagged/released a stable version of our package/extension.

• After that, you should be able to install your module as follows (remember how you named it):

composer require your-package/name #In our example the name was lumbrales-software/magento2-first-module

The above command should download your module and copy it’s content to app/code/YourCompany/YourModule

• Last, but not least, you will need to enable your module and clear Magento cache. Add a new entry in app/etc/config.php, under the ‘modules’ section (Magento 2 project):

  'Yourcompany_YourModule' => 1,

Note that this name should match with the name that you’ve put on the composer.json, section extra -> map.

That’s it, after that your module should be ready to go.

You can download the source code of my Magento 2 Composer Module sample here.

I hope it helps, and let me know if you have any issues!

In my next post I’ll show a basic usage of git tagging and composer to be able to easily release your module updates.

Credits:
https://www.ashsmith.io/2014/12/simple-magento2-controller-module/
https://alankent.wordpress.com/2014/08/03/creating-a-magento-2-composer-module/