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 app/code
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 local-src/.
Then add that folder as a path repository to the Magento composer.json file, 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.

app/code/Hyva/YourCompatModule

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 app/code/.

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 composer dump-autoload.

vendor/hyva-themes/magento2-your-compat-module

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.

Also, changing 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.

local-src/magento2-your-compat-module

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

Tip

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.
```
mkdir local-src
```

Clone the Compatibility Module repository into the directory.

cd local-src
git clone git@gitlab.hyva.io:hyva-themes/hyva-compat/magento2-your-module.git
cd ..

Add the local-src subdirectories as a composer path repository.

composer config repositories.local-src path 'local-src/*'

Then open your root composer.json file and move the local-src repository to the top of the repository list, so it takes precedence over any remote repositories:

"repositories": {
    "local-src": {
        "type": "path",
        "url": "local-src/*"
    },
    "private-packagist": {
        "type": "composer",
        "url": "https://hyva-themes.repo.packagist.com/CUSTOMERNAME/"
    },
    "0": {
        "type": "composer",
        "url": "https://repo.magento.com/"
    },

Install the module with composer.
```
composer require hyva-themes/magento2-your-module
```
Composer will create a symlink from the local-src/magento2-your-module folder to
vendor/hyva-themes/magento2-your-module.
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 :dev-[BRANCH] suffix, e.g.
```
composer require hyva-themes/magento2-your-module:dev-main
```
Where you replace main with 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/module directory to the PHP include path to enable get autocompletion.
It is usually easiest to right-click on the local-src folder and select Mark Directory as > Excluded. Then remove the exclusion of the vendor/hyva-themes/magento2-your-module in the PHPStorm Settings under Directories.
Enjoy work in vendor/hyva-themes/magento2-your-module.

Troubleshooting

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:

Package hyva-themes/your-module exists in composer repo
(https://hyva-themes.repo.packagist.com/NAMEOFTHEVENDOR) and path
repo (local-src/*) which has a higher repository priority.  
The packages with higher priority do not match your constraint and are
therefore not installable.

The problem here is that composer is unable to determine the version of the package in the local-src/* repo.

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 path repo.

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 .git directory 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-src repository configuration in the root composer.json

    {
       "type": "path",
       "url": "local-src/*",
       "options": {
           "versions": {
               "hyva-themes/your-module": "dev-main"
           }
       }
   }

Now composer will always assume this is the version of the given package. Be mindful to update this value, too, when checking out or tagging a different version.

You can add "version": "dev-main" to the packages composer.json file.
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.