Are you looking for the best way to add new code to a Magento 2 site? There are two ways you can add new code to Magento 2 projects: you can work the traditional way, adding code to app/code and app/design, or you can use Composer to add the code into your project. In this first article of our Magento 2 Development Series, Yoda, one of our Magento Certified Developers explains how to create your first Composer package and how to add it to your project.
What is Composer?
Composer is a dependency management system for PHP projects. It allows you to easily create and manage projects by declaring what packages and libraries your project requires. It will then seek out those packages and install them along with any code they depend on to function.
Thinking about what dependencies mean can be difficult if you’re new to the concept. The Magento 2 package relies on a number of modules and packages to work including Magento_Catalog; Magento_Catalog relies on other packages such as Magento_Eav which relies on Magento_Store, and so on. Composer finds every single package required by the packages you need and the packages they need until it runs out of required packages. Then it installs them for you without you having to lift a finger.
When it comes to updating software, Composer will update it for you with a single command – either what you specify or every package that has a pending update.
Composer is the preferred means of adding code to a Magento project including the base Magento installation itself. While it is possible to download a full copy of the source code for any particular version, Magento recommend that you use Composer to install it, and the same applies to any modules or themes you’re adding.
There are some pros and cons to both approaches, covered below.
|Don’t need to set up Composer||Need to handle all updates manually|
|Keep working the way things have been done in the past||Need to ensure you have all required code in place manually|
|Easy to install third-party modules from their own sites|
|Composer handles version updates for you||Can be more difficult to install third-party modules as many extension developers don’t use Composer|
|Less files in your version control system||Need to learn how to use Composer|
|Custom code can be stored in a centralised system for easy update across many websites|
|Easy to install Magento Marketplace extensions|
|Required code is included and installed automatically|
What’s Available in Composer?
There are thousands of packages available for download through Composer, via Packagist, Github and more. Private Composer repositories such as the Magento Marketplace, and those used by vendors such as Amasty allow you to add even more options (license purchase may be required).
You can even create your own Composer repository to host your own repositories.
Composer supports accessing both Composer repositories and VCS repositories such as Github and Bitbucket, so wherever and however you’re storing your code, you have options if you don’t want to set up your own Composer repository.
Creating Your First Composer Package
The first steps in creating your Composer package are to determine the vendor and package names. In most cases, the vendor is the person or organisation that wrote the code, and the package name should align with what the package is doing.
At Digital Six, we have a custom Magento module we use to send email alerts of critical issues. It’s called DigitalSix_Alerts. From this, we can derive our Composer package name which is “digitalsix/module-alerts”.
The naming convention we use is [vendor]/[type]-[name]. As the Alerts module is a M2 Module, its type is “module”. A frontend theme would have the type “theme-frontend”.
In order to have a Composer package, we need to have a composer.json file in the root folder for the code. This file tells Composer everything it needs to know such as what the package name is, what the version is, what other packages are required, and so on. The easiest way to create this file is to use the Composer software wizard to make it for you.
Most M2 packages will require PHP7 and “magento/magento-composer-installer”. For an example of how this should look inside your composer.json file, you can look at the composer.json of any Magento 2 module.
Once you have a finished composer.json file, you technically have your first Composer package, but you’re going to need to store it somewhere if you want Composer to be able to find it. We store our Composer packages on our private Git server, but you can store your’s wherever works for you.
Creating a Private Composer Repository
This step is not required. You can give Composer direct access to your VCS system whether that’s a private Git repository, Github, or somewhere else, but you may find you need to add them all individually and that can be an issue. We found it easiest to create our own private Composer repository.
We did this by installing Satis. It’s not the easiest tool to use, and there are alternative systems including ones with web UIs, but Satis works for us and we’ve applied some updates including a cron job to check for updates on a regular basis. Once you’ve added the details of your Composer package and where to find it in Satis, it can track what versions are available for anyone connecting to the Composer repository.
Adding a New Composer Repository to your Project
If you want to use a Composer repository or other source such as a private Git repository in order to fetch code, you’ll need to add it to your project’s composer.json file.
The simplest way to do this is to use the Composer software tool to add it for you.
composer config repositories.[name] [type] [address]
The name is technically optional but is useful for descriptive purposes. The type will generally be “composer”, “git”, or “vcs”. The address is where to find the Composer repository.
composer config repositories.example composer https://composer.example.com//
Adding your Composer Package to Your Project
You’ve created your first Composer package, and you’ve told your Composer project where it can find the files. The next step is to install your package.
The way we do this is we tell Composer that your package is required by the project:
composer require digitalsix/module-alerts
This will get it to start checking the locations it knows it can find code until it finds a package that matches the name you’ve supplied. Once it’s found the package, it starts determining what packages it requires until it has the complete picture of what it needs.
As long as there are no conflicts in required code, your package will be installed.
Composer is a powerful tool, and it’s an essential tool to master if you’re serious about Magento development. Whether you’re writing your own modules for clients or for sale, or whether you’re just developing websites with pre-existing code, working with Composer will make your life easier in the long run as well as the short-term.
There are a lot of things that can be done with Composer and a great deal many more options and ways to use it than we can cover in one article. If you need more information, there are a number of useful resources on how to use Composer out there if you search for them.
Look out for our next article in our Magento 2 Development Series, where we’ll explain the benefits and difficulties of using interfaces in Magento 2.