Clone the repository
There are many possible ways to work on Magento modules within a development instance.
Usually it boils down to one of the following three approaches:
Clone the module into
Add the repository as a composer git source and install the module into vendor with
composer require --prefer-source
Clone the repository to a local directory, for example
Then add that folder as a path repository to the Magento
composer.jsonfile, and install the module with composer.
Each of the approaches works fine and has its benefits and drawbacks.
In the following I want to briefly compare the approaches and then give a recommendation with step by step instructions.
If you are not interested in the comparison and just want the steps to follow, feel free to skip ahead.
The first option has the least overhead when getting started, but it has the downside it doesn't allow for Modules to have the code in a
src/ subdirectory (as is conventionally used for compat modules). Also, composer dependencies for the module are not installed without a more complex, non-standard composer setup, or by installing them manually.
So unless you want to use a “non-hyva” directory structure for the module, don’t develop under
If you still want to clone the repo into
app/code/, then be aware that you will need to adjust the composer autoloader configuration in the Magento root
composer.json so the modules
registration.php is loaded and PHP can find the class files. After any changes you will need to run
The second option is working in
vendor/ directly. In practice, working in
vendor/ works fine, however, it is not recommended by composer, as there are a couple of things to watch out for.
The vendor directory is intended to be ephemeral, so it is possible to lose code by running the wrong composer commands.
composer.json files in modules installed in
vendor/ can really confuse composer, so that can sometimes take a bit of time to clean up again.
In summary, working in
vendor/ directly works, but it isn’t the most clean setup.
The third option takes a bit more work up front. However, it has the benefit that your code doesn't actually live in
vendor/, so you will not lose it as easily due to overeager composer commands.
One thing to be aware of is the IDE of your choice could be confused by the fact that every file is present in the project twice. Excluding one of the two locations from your IDE’s index fixes that.
Note that composer can still become confused by changes to the
composer.json file in your module, just like with option 2.
Setting up a local path composer repository
If you don’t have any strong preference we recommend you take the third option.
The following steps describe how to set up a local path composer repository in your development environment.
First, create the directory you want to store your local code in. When using this approach I use a folder called
local-src/within the Magento base directory, but it’s your choice what to call it.
Clone the Compatibility Module repository into the directory.
Add the local-src subdirectories as a composer path repository.
composer.jsonfile and move the local-src repository to the top of the repository list, so it takes precedence over any remote repositories:
Install the module with composer.
If you get an error that the package in
local-src/*does not match the configured minimum-stability and therefore is not installable, tell composer what branch to install by adding the
mainwith whatever branch name you want to check out.
Exclude one of the directories from your IDE index.
PHPStorm does that automatically, but it also adds the
vendor/moduledirectory to the PHP include path to enable get autocompletion.
It is usually easiest to right-click on the
local-srcfolder and select Mark Directory as > Excluded. Then remove the exclusion of the
vendor/hyva-themes/magento2-your-modulein the PHPStorm Settings under Directories.
Enjoy work in
Composer fails to install dev-main from a path repository
If you chose the
path composer repository approach, you might get an error like the following when running
composer require hyva-themes/your-module:
The problem here is that composer is unable to determine the version of the package in the
It occurs with virtualized development environments like for example
warden, when the
git command to clone the repo into
local-src/ is run on the host system, but the
composer require command is run inside the container.
Composer uses the currently checked out branch or tag name to determine the version in the package.
In virtualized environments,
.git directories are usually not synchronized into the container. This means composer inside the container is unable to determine the currently checked out branch or tag, and thus doesn't know which version of the package is present in the
There are a number of possible solutions.
- You can work around this by cloning the repository inside the container instead of in the host system.
This way the
.gitdirectory will be present inside the container, but it will not be possible to run git commands from the host system.
- You can add the version for a given package to the
local-srcrepository configuration in the root
- You can add
"version": "dev-main"to the packages
This is not recommended, because it easily leads to inconsistencies if the composer.json is commited into git with the version, and the value is not updated when a release is tagged.