How to create a PHP package. Part 4: Git, tags, packagist

In this chapter, we will push created package to github, talk a little bit about versioning, create first release, and, finally, publish the package on packagist.org to let the whole world install our library with a composer.

Github

I expect that you already know what git and github are. In a few words: git is a distributed version control system that tracks files changes, and github is a hosting service based on git which also provides other useful features. I also assume that you are already registered on github.com and installed git itself (if not, please, do it).

Let's create a new repository for the package. Click on "Create a new repository" and type a good name for it. Ideally, it should be obvious what your package does just from the title. I will call it php-highlight-example. Make the repository public, check "Add a README file", and choose a license (MIT in the example).

README.md file

README is the a face of our repo. It can explain what out repo does, how to install, use it and much more. As we checked "Add a README file" it will be created automatically in the root of the project and contains dummy data. You can check here what information is recommended to put in a README file. You can replace its content with this data:

.gitignore file

The last thing which will be good to do is to create a .gitignore file in the root of the project. It contains paths to the files and folders which we don't want to commit to the repo. In our case, we don't want to commit vendor folder, composer.lock file, and additionally, I excluded temporary folders from my idea, different cache files. Here is its content:

vendor
composer.lock
.idea
.phpunit.cache
.phpunit.result.cache
.phpcs-cache
.DS_Store

Pushing files to repo

Everything is prepared to be committed and pushed to our repository. Let's type these commands:

git init
git add .
git commit -m "init commit"
git branch -M main
git remote add origin git@github.com:demyanovs/php-highlight-example.git #don't fotget to replace this line with your's path
git push -f origin main

If you check out the repo now, you will see all the files from your project.

Tags and releases

Now when we pushed the project to the github, let's create our first release. But before we need to create a tag for the release. A tag is a reference to a specific commit that helps to navigate between commits. You can consider it as a bookmark. Usually, tags follow semantic versioning. A release is a package or archive of our code. You can add release notes and binaries to each release. To create a release you need to assign a tag to it.

Semantic versioning

In semantic versioning, we have 3 numbers divided by a dot. For example MAJOR.MINOR.PATCH:
MAJOR version when you make incompatible API changes (change public methods, a behavior of old methods, add incompatible dependencies, etc.),
MINOR version when you add functionality in a backward compatible manner (adds a new functionality, but doesn't break the old one)
PATCH version when you make backward compatible bug fixes (small changes which usually are not visible to the end users).
You can read more here.

To create a release, open the repository and click the related button:

Add tag and release with the same name: "1.0.0". The description can contain a changelog, but as it's our first release, we don't have much to add here.

Click "Publish release", and you just created your first release.

Packagist

We have everything to submit our package to packagist, to the repository, which aggregates public PHP packages. First, you need to register on packagist.org and then click to submit the package.

And that's it. Notice how it automatically detected out 1.0.0 release. If you create another release, it will be also displayed here.

Your package is now available for installation with a composer. All you need is to enter:

composer require demyanovs/php-highlight-example

It will download the latest version of the package. Or you can specify exact version which to download:

composer require demyanovs/php-highlight-example:1.0.0

What's next?

Now your package is available to everyone. And maybe someone will decide to contribute to your package. We need to be prepared for it. And we will in the next chapter.