Packagist & Github – How-To Guide

Create a release tag

Packagist packages are based on *releases* i.e. point-in-time commits on Github that are “tagged” with specific text. In general, you would tag your releases with a version number – this is where Semantic Versioning comes in. Hopefully you’ve read that by now!

For our package, we’ll make the first release version 1.0 and make it available on Github.

git tag "v1.0"
git push --tags

At this point it’s a good idea to make sure the v1.0 release is available on Github. You can do this by going to the Github releases page for your repository. It will be something like this:

Connect Github to Packagist

For Packagist to “know” when you push new versions of your packages to Github, it’s necessary to setup a “hook”. This will make Github tell Packagist when a new release is available. This is a critical step if you want users of your package to get new versions as you release them.

Sign in to Packagist and go to your Packagist Profile page.

Click the “Show API Token” link and copy the API token.

Go back to your Github repository and click ‘Settings’ – it should be a link on the right of your screen. Select ‘Webhooks & Services’.

From here, click ‘Add Service’, select ‘Packagist’ and complete the form as requested. Here is where you put the API token you copied in the previous steps.

Make sure ‘Active’ is checked, then submit the form.

Submit the package to Packagist

If everything has worked so far, you’re now ready to make the package available to the public. Scary!

Copy the URL of your repository – it will be something like this (with username and repository names changed):

Go to the Packagist submit package page and paste the repository URL into the box provided.

Click ‘Check’ and wait for Packagist to do some stuff in the background. If Packagist is satisfied that your package is ready, you’ll get the option to Submit it. This is where you’ll quickly know if your package’s *composer.json* file isn’t formatted or written correctly.

That’s it! Your package is now ready for use by anyone using Composer packages.

After doing all the above, here’s the sequence of commands I used. They may not match your exact usage, but you can see the syntax in use here. Ignore the ^C part – my Internet connection died for a minute and I had the publish the tags twice.

Screenshot of the commands run to publish a Packagist package from Github