In this article I will share my personal experience on how to build a Magento 2 Module outside of Magento 2 app/code directory. Having Magento 2 module in a separate repository might be useful in case you are planning to share it later with the community or sell it from Magento Marketplace. Other than that, the benefit is vital when it comes to project history. There are only module-related commits in your module repository.
There are 3 ways to develop a module in a separate repository:
1. git submodules
2. modman (Module Manager)
3. copy and paste Module related files manually (Ctrl+C, Ctrl+V). This might be a joke, however someone is doing it this way as well.
git submodule Command
This option comes first when I think about developing some stuff using GIT. A submodule command allows you to keep another Git repository in a subdirectory of your repository.
Usage is pretty straightforward. In Magento 2 root directory you have to execute the following command:
> cd /var/www/magento2/ > git submodule add email@example.com:mcspronko/magento-2-test-module.git
As a result new magento-2-test-module directory is created inside
My article is about different approach which I really enjoy to use.
Modman (Module Manager)
My attention came to one of community scripts for Magento 1 called modman. This is a bash script used to clone a repository where you store Magento Module into
.modman directory. Once repository is cloned into
.modman directory the modman script creates symlinks inside
app/code/ Magento directory. Actually, you can configure modman to symlink module’s repository to any directory. Later in this article I will show how to do it.
The modman has been created by Colin Mollenhour (Twitter: @colinmollenhour), one of well known Magento community members. The script helps me to develop my personal Magento 2 modules on day-to-day basis. Also, you can use modman to add a folder/project which is stored on your local computer to a Magento 2 project. I think this is a modman manager’s killer-feature. In addition to this, it allows to have more than 1 repository.
Ability to manage multiple Magento 2 Modules and check status of your changes for all connected repositories with simple modman status command enables developers to forget about routine repository management. The git submodule command does not allow to have such flexibility.
You can find script and detailed tutorial by navigating to the https://github.com/colinmollenhour/modman page.
Mechanics of Using Modman Manager
First Magento 2 Module Repository
Before we start let’s create new GIT repository. The magento-2-test-module repository will contain our Test Magento 2 module. In this article we are going to have Magento 2 basic module. The module can only register itself in Modules pool during Magento 2 application installation.
Prepare Magento 2 Module files
In order to prepare Magento 2 Module we have to clone newly created repository and add few files to describe Magento 2 Module. The following git command will download repository to your local environment:
git clone firstname.lastname@example.org:mcspronko/magento-2-test-module.git Cloning into 'magento-2-test-module'... warning: You appear to have cloned an empty repository.
The warning message only highlights the fact that there are no files in the repository. We are going to create them to describe Magento 2 Module:
registration.php file allows to notify autoloader about the location of the Module in Magento 2
module.xml main configuration file. For this article
module.xml has only module name equals “Pronko_Magento2TestModule” and setup_version equals “100.0.0”
composer.json where project “type” should be set to “magento2-module”.
4. modman configuration file
# modman configuration file src app/code/Pronko/Magento2TestModule
The picture shows Magento 2 Test Module Structure with our files:
The Magento 2 Test Module is also available on github: https://github.com/mcspronko/magento-2-test-module
I recommend to also check PHP Developers Guide to get more insights on how to develop and extend Magento functionality.
Few git commands to update remote repository:
$ git commit -m "Basic Magento 2 test module" $ git push origin master
The modman installation is pretty straight forward. There are 2 things to remember:
1. modman should be initialised in the Magento 2 project directory
2. modman configuration file should exist in Magento 2 Module. In our case this is inside
The following command downloads modman script:
bash < <(wget -q --no-check-certificate -O - https://raw.github.com/colinmollenhour/modman/master/modman-installer)
Let’s initialize modman in Magento 2 directory:
$ modman init Initialized Module Manager at /Users/pronko/Sites/magento2-clean
Next we clone our Magento 2 Test Module repository by modman command:
$ modman clone email@example.com:mcspronko/magento-2-test-module.git Cloning into 'magento-2-test-module'... remote: Counting objects: 12, done. remote: Compressing objects: 100% (8/8), done. remote: Total 12 (delta 0), reused 12 (delta 0), pack-reused 0 Receiving objects: 100% (12/12), done. Checking connectivity... done. Applied: src app/code/Pronko/Magento2TestModule Successfully create symlink new module 'magento-2-test-module'
All files from the magento-2-test-module repository are now have symlinks under
app/code/Pronko/Magento2TestModule directory as follow:
The modman status command is an analogue to git status and shows current status of changed files in the
` directory. Execution of modman status command in the Magento 2 root directory should show the following result:
$ modman status -- magento-2-test-module -- On branch master Your branch is up-to-date with 'origin/master'. nothing to commit, working directory clean
The Pronko_Magento2TestModule Magento 2 Module has been successfully added. During Magento installation the Pronko_Magento2TestModule module should be available under Step #4: Customise Your Store under Advances Modules Configurations section.
It is recommended to create new files under
directory. It will help to avoid issues when part of your module has symlinks and another part has files. I have found it easy to modify symlink files under
directory once files are created in the
directory. You may prefer to develop directly in the /.modman/magento-2-test-module directory as well.
Updating Module Repository
Once you are happy with development of your Magento 2 module the changes have to be committed. In case we run git status command from Magento 2 root directory it will show 2 untracked directories:
$ git status On branch 2.0 Your branch is up-to-date with 'origin/2.0'. Untracked files: (use "git add <file>..." to include in what will be committed) .modman/ app/code/Pronko/
We can even add these 2 directories to the .gitignore file to avoid confusion.
All module changes are now under
.modman directory. In order to see changed files we have to execute modman status command. As result it shows 1 new file for the magento-2-test-module repository:
$ modman status -- magento-2-test-module -- On branch master Your branch is up-to-date with 'origin/master'. Changes to be committed: (use "git reset HEAD <file>..." to unstage) new file: src/Plugin/Customer.php
Easiest way to update repository is to navigate inside
.modman/magento-2-test-module/ directory and perform git commands:
$ cd .modman/magento-2-test-module/ $ git add . $ git commit -m "New Customer Plugin" [master 7ac0798] New Customer Plugin 1 file changed, 9 insertions(+) create mode 100644 src/Plugin/Customer.php $ git push origin master Counting objects: 5, done. Delta compression using up to 8 threads. Compressing objects: 100% (4/4), done. Writing objects: 100% (5/5), 500 bytes | 0 bytes/s, done. Total 5 (delta 1), reused 0 (delta 0) To firstname.lastname@example.org:mcspronko/magento-2-test-module.git 59a7d64..7ac0798 master -> master
Don’t be confused with Magento 2 repository. There are no changes committed. Only the magento-2-test-module repository has been updated.
In this article we have reviewed 2 ways of adding Module which is stored in a separate repository to Magento 2 project for and continue testing and developing inside Module. For this purposes there are git submodule command can be used. It is less likely something I can recommend. I use modman Module Manager created by Colin Mollenhour which is simple bash script and streight forward to use. It also allows you to manage multiple Modules at a same time.
Follow me @max_pronko on Twitter. I will post more stuff and update you once it is available.
Leave your comments and feedback.
Max with his team of Magento enthusiasts won the Best Magento 1 to Magento 2 Migration Award at the Magento Imagine 2017. As CEO at Pronko Consulting, he is actively working with Magento 2, delivering superior customer experience. As one of the most famous developers on a market and in the Magento Community, he launched Magento 2 blog, Magento DevChannel – YouTube channel in 2017 where he shares his knowledge, experience and the best practices in the Magento field.
Subscribe to my Magento 2 tips and tutorials content.
Every week I send an interesting email directly to your inbox