Composer is a dependency management tool for PHP. It allows you to specify the exact versions of packages that your project needs. This is useful for ensuring that your project is always using the latest stable versions of its dependencies, or for testing out new features that are not yet released in a stable version.

In some cases, you may want to require a specific branch of a package instead of a specific version. This can be useful for testing out a new feature that is not yet released in a stable version, or for using a branch that fixes a bug that has not yet been merged into the master or main branch.

Prefixing with dev-

To require a specific branch name on Composer, you need to use the dev- prefix. Composer will detect this prefix and understand that a branch is required instead of a version requirement.

For example, to require the my-bug-fix branch of the nunomazer/laravel-samehouselibrary, you would use the following command:

composer nunomazer/laravel-samehouse:dev-my-bug-fix

This will tell Composer to download the my-bug-fix branch of the nunomazer/laravel-samehouse Laravel package instead of the latest stable version.

Using dev- with Custom Repositories in Composer

If you want to require a specific branch from a fork or custom repository, you can use the dev- prefix along with the repository details.

{
 "repositories": {
   "mazer": {
     "type": "vcs",
     "url": "[email protected]:nunomazer/laravel-samehouse.git"
   }
 },
 "require": {
   "nunomazer/laravel-samehouse": "dev-my-bug-fix"
 }
}

UnexpectedValueException

What if you receive the following error when running composer:

[UnexpectedValueException]
Could not parse version constraint branch_name: Invalid version string "branch_name"

Well this means that you didn’t paid attention to the instructions ;-) … you just forgot to prefix the branch_name with dev-. So using the complete version branch name with prefix must fix it: dev-branch_name.

Final Considerations

Here are some additional things to keep in mind when requiring a specific branch name on Composer:

  • The branch name must be prefixed with dev-.
  • The branch name must be a valid branch name on the package’s repository.
  • If the package’s repository does not have a branch with the specified name, Composer will fail to install the package.