Composer with local repository

Some time ago I was working on a Laravel project. This project needed an internal package that we developed ourselves—a small library for API communication. Usually, we publish that package to GitHub and then install it via Composer with a private repository.

But there are times when I’m not ready to publish it anywhere. The package is still messy, still changing a lot. I just want to quickly try out that package in my Laravel project without the hassle of push-pull to a repo.

This is where I finally discovered Composer path.

The beginning of the confusion

So here’s the story: I had two folders:

/home/salim/projects/my-app
/home/salim/projects/my-package

my-app is a Laravel application, while my-package is a local package I was developing. I wanted my-app to directly use my-package without having to publish it anywhere.

At first, I tried to directly use require in Composer:

composer require salim/my-package:dev-my-feature-123

But of course it failed, because Composer had no idea where that package was.

Finding the way: repository type `path`

After fiddling with the Composer documentation, I found out there’s a way: repository type path.

With this, I can tell Composer: “Hey, if you need the package salim/my-package, don’t look on Packagist or GitHub. Just look in this nearby folder.”

The way is simply to add the configuration in the composer.json of my-app. You can even set a pretend version that you’ll release later:

{
  "repositories": [
    {
      "type": "path",
      "url": "/home/salim/projects/my-package",
      "options": {
        "versions": {
          "salim/my-package": "1.1.15"
        }
      }
    }
  ],
  "require": {
    "salim/my-package": "1.1.15"
  }
}

Then run:

composer update salim/my-package

Composer immediately understands, and my local package gets installed automatically.

The big advantages

The nicest thing about path is that you can directly edit the package source code without needing to publish it again. Composer will create a symlink (if the OS supports it), so changes in the my-package folder are instantly reflected in my-app.

For example, if I add a new method in MyService.php in my-package, then… boom! it can immediately be used in my-app.

Lessons I learned

From this experience, here are a few important notes:

Use path for quick experiments.
It’s great if the package is still changing a lot and you don’t want the hassle of publishing.
Remember that this is local.
Once it’s stable, it’s better to publish it to GitHub/Packagist or an internal repo so others can use it too.
Pay attention to symlink.
Composer usually creates a symlink, but if it’s not possible, it will copy files instead. So if changes don’t show up immediately, most likely the symlink didn’t work.

Conclusion

For me personally, Composer path feels like a secret shortcut that makes the workflow much more flexible. It’s like having an experimental kitchen at home before finally serving a neat dish on someone else’s dining table.

If you often build PHP packages for internal projects, give this a try. Who knows, this feature might just be your lifesaver too.

18 Oct 2023 Composer