I’ve got a few PHP libraries and classes that I use regularly and, since making the decision to base all my projects on the Laravel framework, have gotten fairly used to installing packages using Composer.
I battled occasionally with getting my libraries to work with Laravel, mostly because of the way I’d written them, but I figured the smart way forward would be to make them available to other Composer users. For PHP, this means structuring the libraries in a specific way and making them available through Packagist, “The PHP package archivist”. You probably know this already, but when you add a package to your project’s composer.json file, Packagist is where it gets downloaded from.
Anyway, after some searching around, I found a bunch of articles that covered how to do *some* of the things needed to create Packagist packages, but no decent end-to-end guide.
So here we go – I’m going to write one. Hopefully it comes in useful.
Pre-requisites & initial steps
- Sign up for Github. It’s free until you need to go beyond their basic account limitations. Packagist packages are based on Github repository *releases* (or tags).
- Get familiar with Semantic Versioning, if you haven’t already.
- Sign up for Packagist. It’s also free.
- Decide on your *vendor* name – mine is ‘digitalformula’.
- Install Composer
It’s an excellent idea to have the same usernames on Github and Packagist, if possible.
Creating the base package structure
Create the directory structure for your package. There’s no “right” way to do this, but I’m following the structure used by almost every Packagist package I’ve installed so far. The structure below is for the package we’ll be creating in this article.
Here’s a basic explanation of what each part is.
- digitalformula – your *vendor* name, your Github username and your Packagist username.
- hello-world – the name of the package, following proper directory naming guidelines.
- .git – Git repository information. This gets generated by git when you run ‘git init’ below.
- .gitignore – list of files that should be ignored during git adds and commits. Each line should contain a filename, path or pattern.
- src – the ‘root’ directory for your package. It’s also where we’ll tell the PSR-0 autoloader to look – we’ll get to that in a bit.
- DigitalFormula – the first segment of the PHP namespace we’ll use. This must match your vendor name although at this point you’re free to use appropriate capitalisation, if you like.
- HelloWorld – the second segment of the PHP namespace we’ll use.
- HelloWorld.php – the PHP file containing our package’s code. Obviously more complex packages will have multiple files, but a single file will suit us just fine for now.
- LICENSE – the license that covers usage of your package.
- README.md – information about your package. Every Github repository should have one.
- composer.json – probably the most important file here. It describes your package, what it’s for, who worked on it, dependencies and how PSR-0 autoloading will work. Unless you’re interested in the technicalities (I’m not), don’t worry about how PSR-0 works. It just works, I promise.
For those wondering, the complete PHP namespace will be *DigitalFormula\HelloWorld*.
Hold on … namespace? What’s that? If you’re not already familiar with PHP namespacing, I highly recommend reading Dayle Rees’ excellent PHP Namespaces Explained article.