How to require a fork with composer?

How to require a fork with composer?

  1. Blog
  2. 15 November 2026
  3. 3 min read

Stefan Bogdanescu

Founder & Senior Architect

How to Require a Fork with Composer

When you need to use a specific fork of an open-source project that isn't yet packaged on Packagist, Composer forces you to register the repository first. The error no matching package found is your immediate signal that Composer cannot locate the package in its standard search paths. This usually happens because the repositories section in your composer.json is defined incorrectly or lacks the necessary details for Composer to map the package name to a Git URL.

To resolve this, you must add a repository definition that explicitly tells Composer where to fetch the code. In the scenario provided, the user attempts to use Nodge's fork of lessphp. The configuration snippet shows a common mistake: defining a "package" type repository without ensuring the version constraint in the require section matches the available versions in that specific repository definition.

The source material demonstrates a valid approach using a package-type repository definition, but there is a critical detail regarding how the version is handled. When you define a repository as a "package," you are essentially creating a virtual package within your project's dependency graph. You must ensure that the version field inside the repositories section aligns with what you specify in the require section.

Here is the corrected structure for your composer.json. Note the specific placement of the version constraint:

{
    "name": "your-project/your-package",
    "description": "Project description",
    "type": "project",
    "license": "MIT",
    "authors": [
        {
            "name": "Your Name",
            "email": "you@example.com"
        }
    ],
    "require": {
        "php": ">=5.3.3",
        "nodge/lessphp": "dev-master"
    },
    "repositories": [
        {
            "type": "package",
            "package": {
                "name": "nodge/lessphp",
                "description": "Nodge's fork of lessphp",
                "type": "library",
                "version": "dev-master",
                "source": {
                    "url": "https://github.com/Nodge/lessphp.git",
                    "type": "git",
                    "reference": "master"
                },
                "dist": null,
                "autoload": {
                    "classmap": ["lessc.inc.php"]
                }
            }
        }
    ]
}

In this configuration, the version field inside the repositories block is set to dev-master. This tells Composer that whenever it resolves the package name nodge/lessphp against this virtual repository, it should look for the version dev-master. Consequently, your require section can safely ask for "nodge/lessphp": "dev-master".

A frequent pitfall occurs when developers omit the version field inside the repository definition or mismatch it with the requirement. If you do not specify a version in the package definition, Composer might assume a default or fail to match the specific Git tag or branch you intend to use. Additionally, while the example uses classmap for autoloading, this is highly specific to that particular fork. Generally, using psr-4 autoloaders is preferred if the upstream project supports it, but for forks that rely on legacy files like lessc.inc.php, the classmap approach ensures the file is found immediately without needing to modify the autoloader configuration of the main framework.

You might wonder why not just use a VCS repository type instead. While composer.json supports "type": "vcs" repositories which point directly to a Git URL, the "package" type allows you to define metadata like description, homepage, and specific autoload rules within the same block as the versioning logic. This is often cleaner for single-package forks where you want to treat the fork exactly as if it were a stable release on Packagist, just hosted differently.

Once the file is saved, running composer update will trigger Composer to fetch the repository definition, locate the Git URL, and clone the master branch into your vendor/nodge/lessphp directory. If you later decide to switch back to the official version on Packagist, you can simply remove the entry from the repositories section and change the requirement to "lessephp": "1.4.0" (or whatever the latest stable version is), provided the package exists in the main registry.

This method of requiring forks is standard practice when upstream projects lag behind or when a specific fix needs immediate integration without waiting for an official release cycle. It gives you full control over which branch or tag your application depends on, ensuring stability across deployments as long as you pin the version string correctly.

Our network