Typed PHP, Stronger Types for Cleaner Code (2014)

Design

How To Package

If you want your code to be used (by anyone else), you’d be wise to package it in such a way that others will want to use it.

Make A Readme File

It sounds simple, but you’d be surprised how few developers actually do this! When other developers stumble across your repository (on Github/BitBucket/what-have-you), they won’t be impressed to see a bare-bones directory structure and nothing else.

Make a Readme file, and include the following…

A Few Examples

Show what your library can do. There are few things more frustrating than being enticed (to learn more about a library) by some marketing, only to have to figure it out from tests and/or source-code.

Those things are excellent places to learn, but they must be sought out, whereas a few examples (in your Readme file) are easy to find. Include examples covering the major aspects of your library.

In our case, this means an example (or two) about the procedural code underpinning the library. It means an example (or two) about the object-oriented wrappers, which provide fluent interfaces to traditionally procedural actions. It means providing an example (or two) about who to subclass the types for further customisation.

It’s not hard to make these - they can even be extracted from your unit tests…

Testing Instructions

Developers want to know how solid your code is. Sure you’re using SemVer, but how much test coverage do you have? Do your tests pass? Can I trust you?

The easiest want to answer these questions is to write the unit tests, and then provide instructions for how they can be run. You don’t require anything elaborate:

1 $ composer install && phpunit

That’s how you might be running your unit tests, and it’s easy to tell others how to run them.

Installation Instructions

Ok - you’ve convinced someone to use your [hopefully] well-tested library. The examples provide its value. So how do they install your library?

This is where you make a composer.json file and include Composer installation instructions. This will require a round-trip to Packagist, but you’ll be all the better for it.

Then just a simple set of instructions is all you need add:

1 $ composer require "vendor/library:1.0.0"

License

Include an open-source license. Something friendly like MIT will do nicely. Specify this in your Readme file, and include a clearly-named file (like LICENSE or license.md) which contains the full license.

Contribution Guidelines

This is optional, but greatly increases the chance that other developers will send compatible pull-requests. If you are fussy about code style (and you should be), then be sure to tell people how you want their submissions to look.

Conclusion

Building a new type system is only partly about code. There’s a lot of design consideration that goes into well-crafted libraries. Take the time to decide on a reasonable structure - one that allows consumers the most flexibility.

Test well. Package well. Be clear.