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:
[php]
> cd /var/www/magento2/
> git submodule add git@github.com:mcspronko/magento-2-test-module.git
[/php]
As a result new magento-2-test-module directory is created inside /var/www/magento2/ project.
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:
[php]
git clone git@github.com:mcspronko/magento-2-test-module.git
Cloning into ‘magento-2-test-module’…
warning: You appear to have cloned an empty repository.
[/php]
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:
1. The registration.php file allows to notify autoloader about the location of the Module in Magento 2
2. The module.xml main configuration file. For this article module.xml has only module name equals “Pronko_Magento2TestModule” and setup_version equals “100.0.0”
3. The composer.json where project “type” should be set to “magento2-module”.
4. modman configuration file
[php]
# modman configuration file
src app/code/Pronko/Magento2TestModule
[/php]
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:
[php]
$ git commit -m "Basic Magento 2 test module"
$ git push origin master
[/php]
Modman Installation
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:
[php]
bash < <(wget -q –no-check-certificate -O – https://raw.github.com/colinmollenhour/modman/master/modman-installer)
[/php]
Let’s initialize modman in Magento 2 directory:
[php]
$ modman init
Initialized Module Manager at /Users/pronko/Sites/magento2-clean
[/php]
Next we clone our Magento 2 Test Module repository by modman command:
[php]
$ modman clone git@github.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’
[/php]
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:
[php]
$ modman status
— magento-2-test-module —
On branch master
Your branch is up-to-date with ‘origin/master’.
nothing to commit, working directory clean
[/php]
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.
Development
It is recommended to create new files under
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:
[php]
$ 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/
[/php]
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:
[php]
$ 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
[/php]
Easiest way to update repository is to navigate inside .modman/magento-2-test-module/ directory and perform git commands:
[php]
$ 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 git@github.com:mcspronko/magento-2-test-module.git
59a7d64..7ac0798 master -> master
[/php]
Don’t be confused with Magento 2 repository. There are no changes committed. Only the magento-2-test-module repository has been updated.
Summary
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.
Leave a Reply