How to create a PHP package. Part 1: Composer

If you created a useful PHP library and want to share it with others or reuse it in your other projects, it will be convenient to pack it into a separate package. In this series of articles, we'll discover how to properly organize code into a reusable package, create a structure of the project, write unit tests, create an automatic code style check, implement CI using github actions, and much more. As an example, we will write step by step a small PHP library for syntax highlighting. It will accept text and return highlighted PHP code.

We will split the series into five parts.

In the first part:

1. Сreate composer.json and describe the dependencies.
2. Write an application for syntax highlighting.
3. Autoload classes with Composer

In the second part:

1. Install PHPUnit.
2. Write unit tests.
3. Configure PHPUnit with XML.
4. Code coverage.

In the third part:

1. Implement a code style check using PHP_CodeSniffer.
2. Configure PHP_CodeSniffer with XML.

In the fourth part:

• Create a git repository
• Create a Readme file.
• Deal with versioning and tagging.
• Publish the package on packagist.org

In the fifth part:

• Create CI/CD
• Add GitHub Actions for our repository.

1. Creating composer.json

As a first step, let's create a composer file. Composer is a dependency manager for PHP, like npm for Node.js

If you didn't install the composer yet, you can read how to install it here.

Dependencies are described in the composer.json file. To generate this file automatically, create a directory php-highlight-example for the project, open it and run:

composer init

You will be asked to answer a number of questions:

Package name (<vendor>/<name>) []: your.name/php-highlight-example
<vendor> usually matches your GitHub login, and a name is the name of the package itself.

Description []: A PHP library for highlighting code syntax.

Author []: My Name <my_email@example.com>

Minimum Stability []: (skip this)

Package Type []: library

License []: MIT

Would you like to define your dependencies (require) interactively?
Answer "no". We will add dependencies as we needed them.

Add PSR-4 autoload mapping? Maps namespace ... to the entered relative path. [src/, n to skip]: no

Next, check our composer.json. If everything is correct, enter "yes".

Our composer.json looks like this:

{
    "name": "demyanovs/php-highlight-example",
    "description": "A PHP library for highlighting code syntax.",
    "type": "library",
    "license": "MIT",
    "authors": [
        {
            "name": "Viacheslav Demianov",
            "email": "demyanovs@gmail.com"
        }
    ],
    "require": {}
}

You can read more about licenses on the Choose a License website.

2. Writing an application

Inside php-highlight-example directory, create the following structure:

    .
    ├── examples
    |   └── index.php
    ├── src
        ├── ColorsDto.php
    |   └── Highlighter.php
    └── composer.json

src/Highlighter.php

src/ColorsDto.php

Note that you need to replace the namespace Demyanovs\PHPHighlight with yours.

In PHP, you can use namespaces to set aliases for classes and paths, which solves the problem of class name conflicts in PHP when, for example, you use third-party classes or libraries with the same names.

Usually, the namespace is the same as the directory path, but this is optional.

If you are not familiar with the concept of namespaces, you can read more here.

Example of usage:

examples/index.php

3. Autoloading with composer

Now we need to tell the composer where to find our code. We will implement the PSR-4 autoloading standard.

Open composer.json file and after "require": {} add

    "autoload": {
        "psr-4": {
            "Demyanovs\\PHPHighlight\\": "src/"
        }
    },

What is PSR?
The PHP Standard Recommendation is a PHP specification published by the PHP Framework Interop Group. It serves the standardization of programming concepts in PHP. Read more.

And finally, to generate an autoloader file, we need to run the command:

composer install

This command will create a vendor folder with an autoloader file. There will be other dependencies, but we don't have any yet.

Now we can see how syntax highlighting works by opening our example file examples/index.php

What's next?

Our code was highlighted with colors, according to our settings. You can choose your colors.

In the next part, we will install PHPUnit and cover our code with tests.