PHP: Use your private repository in Composer, without SSH keys
I don’t want everyone in Packagist to laugh at me
Having Github behind Packagist is a convenient way to make your packages public and available for you and everyone. There is a problem, though: you cannot do the same easily with private repositories.
The most direct alternative for using Composer with private packages is Private Packagist, a paid service. There are other alternatives too, like Satis or Packeton, but you will have to host it yourself. There is also Repman, which is free, but that may be too overkill to just wanting to use your private repository in your project.
If you want a free and simple route to host a private package in Github and download it to your project, there is one.
1. Preparing your package in Github
This step should be easy if you have already made a PHP package to be published in Packagist. Basically, make a valid composer.json with the name of the package, dependencies, autoloading, etc. Exactly like you would do to publish the package publicly.
For example, this is the composer.json of my private On-Premises Subscriptions package. I will use this as an example across the whole article.
Once our Composer manifest and private package are ready and working, we will point our project to use that code.
While you’re at it, it’s a good idea to release a
v1.0.0version so you can retrieve your package using versioning.
2. Preparing your credentials
Before going further, we need a way to authenticate with Github when retrieving the code from the repository. To do that without exposing our credentials (password) or going to generate SSH keys, which is a whole endeavour by itself, we can use Personal Access Tokens.
Go into your account or the link above, and grant repo all permissions.
After you save it with a name, like Laravel Subscription Package, Github it will show the token only once. Don’t close the window, just copy somewhere.
Treat this token as your password, so don’t go around showing it to the Internet: it still has write access to the private repository. You can blame Github for not having a scope for only reading private repositories, but is better than the aforementioned authentication mechanisms because, if leaked, it can be revoked.
I’m actually looking for support for my On-premises Subscription package, so visit to my Patreon if you have a couple of bucks to spare.
3. Add your package into your project
The next step is to go into the composer.json of your project, and add it as a dependency. Since Laragear Subscriptions just launched, we will set set is as version 1.*.
That, of course, won’t suffice. We also need to point where it is, which in this case, is our private repository in Github. We can use the repositories key to add the places that should be used to retrieve the packages.
Inside this array, we will list each repository with the package it provides, and what type is. In this case, the type is vcs, as git is a versioning system; our Laragear Subscription name as we declared and plan to use; and the URL of the git location.
Since I’m not using the default main/master branch, I’ll have to specify which to checkout using branch, but you can omit it otherwise.
Now, Composer needs credentials to use and retrieve the code.
4. Adding the credentials
Since our package it’s behind authentication, we will use the token we created so Composer can use it to enter the private repository and pull the code.
You can create an auth.json file and use the github-oauth key directly, along the Github token. This is the preferred way because you can add that file to .gitignore and avoid uploading it to the Internet. Otherwise, you can always just shove it inside the config key.
If you plan to use that token in a public repository, you should use Repository Secrets to manage the token instead of setting it in plain sight.
5. Testing it works
You can test if this works using the Composer CLI to test if your package can be picked up correctly.
If you don’t see a similar output, then you can easily check what the problem is: invalid tokens, badly written package name, or else.
6. Using your package
After you’re done with the above steps, and everything is correct, you can use composer update to upgrade your dependencies in your project, which will automatically pull the code from your private repository.
The neat thing about Composer is that is also aware of the releases in your Repository, that’s why we used 1.* instead of dev-1.x or dev-main for the version constraint.
Using releases to tag your code with different versions is an excellent way to mark stable releases.
In our case, we can benefit greatly by only downloading newer tags of our package instead of always retrieving whatever is being worked on the development branches.
That’s the easiest way to make your private package into your project without having to deal with Private Packagist or SSH keys.
Of course, it’s easier to use Private Packagist if you need to handle more than a couple of private packages, so don’t be shy to get a plan, or use Repman if you have exactly 0 dollars.
