Creating a PHP Package

Creating a PHP Package

Make sure you have composer installed if you want to use PHP packages.

If you’re new to PHP, then you may not know what a package is or why they’re nice. If you played with Legos as a kid, think about those blocks, they came in different shapes, sizes, and colors. Each had a purpose and was useful, maybe you didn’t always need them all, but you had them. Instead of writing all the PHP for your project, someone may have already written a few pieces, and you could use those with your code. The people who write packages usually spend lots of time testing them, to ensure they work properly in any circumstance. It would be impossible to write and test every aspect of your program as much as it would be if you used packages.

Perhaps you find yourself using some PHP you’ve written, over and over again; which is a good practice, but it can become time-consuming when you make it better and then have to update it everywhere else you used it. Creating your package would be a great solution to your dilemma. I recommend you follow semantic versioning, which will help prevent anything from breaking when you do an update.

Hopefully, you’re ready to get started, or maybe you already were. For this example, I’ll be using GitHub to host the repository, even though you may use other services. I’m going to assume you’re familiar with Git and GitHub, so go ahead and create a repo for this project.

For this example, we will be creating a package that replaces var_dump(). The PHP is simple and kind of pointless; however, it is useful for this post. Here is a list of the files you’ll need to create:

  • composer.json
  • src/Dump.php
  • src/ShowDumpContract.php
  • src/ShowDump.php

Our composer.json will look like this:


{
  "name": "levilol/dump",
  "description": "",
  "version": "1.0.0",
  "license": "MIT",
  "keywords": [""],
  "autoload": {
    "psr-4": {
      "levilol\": "src/"
    },
    "files": [ "src/Dump.php" ]
  },
  "require": {
    "php": ">=5.6"
  }
}

The name is important, it needs to be unique, it can usually mirror your repo username/project. Having a good description will help people find your package, the same goes for keywords. You should follow semantic versioning when releasing new versions; I suggest you start with 0.1.0 and move up as fast as you want. The license is up to you, for this example, I chose the MIT license. Autoload is where some of the magic starts to happen; PSR-4 saves you from having to include every file. The autoloader will include the file when you instantiate a class. We also want to include at least one file every time the program runs, whether it’s called or not, it will be loaded. Require can contain PHP versions, extensions, and other packages.

Our Dump file will declare a function and call the static method dump() in the ShowDump class. This function accepts a parameter of any type and passes that to our method.


<?php
use levilolShowDump;
function dump($var)
{
    foreach (func_get_args() as $var) {
        ShowDump::dump($var);
    }
}

I’ve always been told to code to an interface, so here is the interface for the ShowDump class. It has one method that accepts one parameter.


<?php
namespace levilol;
interface ShowDumpContract
{
    public static function dump($data);
}

Now it’s time for the meat and potatoes of this package. The dump() method is static, so you don’t have to instantiate the class, which we don’t need to do anyway since we have the dump() function. This method checks to see if you’re calling it from the command line interface and if you are, it calls the regular var_dump() and if you aren’t, it wraps the var_dump() in pre tags.


<?php
namespace levilol;
class ShowDump implements ShowDumpContract
{
    public static function dump($data)
    {
        if (PHP_SAPI == 'cli') {
            var_dump($data);
            return;
        }
        echo '<pre>';
        var_dump($data);
        echo '</pre>';
    }
}

You’re welcome to reference my example repo on GitHub. It has a few more files, such as tests and an README.md, which aren’t required.

Now you’ll need to head over to Packagist, sign in with your GitHub account, and submit your package. People can then require your package in two ways, via their composer.json or from the command line by typing composer require levilol/dump. The latter will add it to your composer.json file.

Please email me if something wasn’t clear or if you’re having trouble.