Custom PHP Composer Package on GitLab with PHPUnit Tests

In this guide, you’ll learn how to create a custom PHP Composer package with PHPUnit tests. Follow the step-by-step process to set up your package, write a sample PHP class, and integrate unit tests for your code. Additionally, explore options to publish your package using GitLab or Packagist. This tutorial is designed to help PHP developers streamline their workflow and improve code reusability by creating and sharing their own packages.

In order to optimize the workflow and maximize efficiency, it might be useful to extract common code to reusable packages. A common package system is composer. In this article, we will demonstrate, how to create a custom composer package. At the end, it is shown, how to publish the package on packagist for everybody, as well as how to use the package in a self-hosted GitLab environment.

System prerequisites:

PHP
Composer (See here for installation details)
Git and a (new) Git repository for the package to create

Step 1: Initialize the project

First, we will set up our new package. We will write a simple Hello World package for demonstration.

git clone <REPOSITORY_URL>
cd <REPOSITORY>
composer init

After entering composer init some information is requested, similar to the following:

Package name (<vendor>/<name>) [doblhofer/helloworld]: doblhofer/helloworld
Description []: This is an example project to show how to create a composer package with PHPUnit tests
Author [Philipp Doblhofer <E-Mail>, n to skip]: 
Minimum Stability []: dev
Package Type (e.g. library, project, metapackage, composer-plugin) []: library
License []: Apache-2.0

Define your dependencies.

Would you like to define your dependencies (require) interactively [yes]? no
Would you like to define your dev dependencies (require-dev) interactively [yes]? no
Add PSR-4 autoload mapping? Maps namespace "Doblhofer\Helloworld" to the entered relative path. [src/, n to skip]: src/

{
    "name": "doblhofer/helloworld",
    "description": "This is an example project to show how to create a composer package with PHPUnit tests",
    "type": "library",
    "license": "Apache-2.0",
    "autoload": {
        "psr-4": {
            "Doblhofer\\": "src/"
        }
    },
    "authors": [
        {
            "name": "Philipp Doblhofer",
            "email": "<E-Mail>"
        }
    ],
    "minimum-stability": "dev",
    "require": {}
}

Do you confirm generation [yes]? yes
Generating autoload files
Generated autoload files
Would you like the vendor directory added to your .gitignore [yes]? yes

After that, we will install PHPUnit for the package with the following command:

composer require --dev phpunit/phpunit

After that, the resulting configuration file composer.json should be similar to the following:

{
    "name": "doblhofer/helloworld",
    "description": "This is an example project to show how to create a composer package with PHPUnit tests",
    "type": "library",
    "license": "Apache-2.0",
    "autoload": {
        "psr-4": {
            "Doblhofer\\": "src/"
        }
    },
    "authors": [
        {
            "name": "Philipp Doblhofer",
            "email": "<YOUR_MAIL>"
        }
    ],
    "homepage": "https://www.philipp-doblhofer.at/en/blog/custom-php-composer-package-on-gitlab-with-phpunit-tests/",
    "minimum-stability": "dev",
    "require-dev": {
        "phpunit/phpunit": "^10.1"
    }
}

More details for the structure of the configuration file can be found here: https://getcomposer.org/doc/04-schema.md

Step 2: Create a sample PHP class

For our example library, we will create a simple class HelloWorld with a method sayHello()

<?php

namespace Doblhofer;

class HelloWorld {
    public function sayHello() {
        return 'Hello World!';
    }
}

Step 3: Write a Unit-Test for our class

In order to test the functionality, we write a test case for our class. If we modify our code in the future, it has to satisfy the test cases, in order to be deployed. We can therefore guarantee, that if it passes all tests, the code covers the requirements specified in the test cases.

For our simple class, the test case is also simple:

<?php

namespace Doblhofer\Tests;

use Doblhofer\HelloWorld;
use PHPUnit\Framework\TestCase;

class HelloWorldTest extends TestCase
{
    public function testSayHello()
    {
        $helloWorld = new HelloWorld();
        $this->assertEquals('Hello World!', $helloWorld->sayHello());
    }
}

In order to use the PHPUnit Framework, we can call PHPUnit with command-line arguments, or specify the options in a configuration file:

<?xml version="1.0" encoding="UTF-8"?>
<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:noNamespaceSchemaLocation="https://schema.phpunit.de/10.0/phpunit.xsd"
         bootstrap="vendor/autoload.php"
         colors="true">
    <testsuites>
        <testsuite name="Doblhofer/HelloWorld Test Suite">
            <directory>tests</directory>
        </testsuite>
    </testsuites>
</phpunit>

More details on the configuration can be found in the PHPUnit documentation: https://docs.phpunit.de/en/10.0/

After that, we can execute the test suite:

./vendor/bin/phpunit

If all was set up correctly, a similar output should be shown – all tests passed:

PHPUnit 10.1-dev by Sebastian Bergmann and contributors.

Runtime:       PHP 8.2.3
Configuration: <FOLDER>/helloworld/phpunit.xml

.                                                                   1 / 1 (100%)

Time: 00:00.003, Memory: 6.00 MB

OK (1 test, 1 assertion)

Step 4a: Publish the package with GitLab

Sometimes, you want to use your own composer packages, without making them public. In this case, we can you a (self-hosted) GitLab repository as a source for composer. In order to work, the project has to be in a group in GitLab! In order to create the packages, we can create the following CI-configuration as an example:

phpunit:
  stage: test
  image: php:latest
  script:
    - apt-get update && apt-get -y install git unzip
    - curl -sS https://getcomposer.org/installer | php -- --install-dir=/usr/local/bin --filename=composer
    - composer install
    - ./vendor/bin/phpunit

publish:
  image: curlimages/curl:latest
  stage: deploy
  variables:
    URL: "$CI_SERVER_PROTOCOL://$CI_SERVER_HOST:$CI_SERVER_PORT/api/v4/projects/$CI_PROJECT_ID/packages/composer?job_token=$CI_JOB_TOKEN"
  script:
    - version=$([[ -z "$CI_COMMIT_TAG" ]] && echo "branch=$CI_COMMIT_REF_NAME" || echo "tag=$CI_COMMIT_TAG")
    - insecure=$([ "$CI_SERVER_PROTOCOL" = "http" ] && echo "--insecure" || echo "")
    - response=$(curl -s -w "\n%{http_code}" $insecure --data $version $URL)
    - code=$(echo "$response" | tail -n 1)
    - body=$(echo "$response" | head -n 1)
    # Output state information
    - if [ $code -eq 201 ]; then
        echo "Package created - Code $code - $body";
      else
        echo "Could not create package - Code $code - $body";
        exit 1;
      fi

This will execute the test suite for each commit and if it succeeds, it will deploy the package.

If we want to make a specific version, we can create a tag with (For more information about semantic versioning, see https://www.philipp-doblhofer.at/en/blog/automatic-changelog-and-versioning-with-git/)

git tag v1.0.0
git push origin v1.0.0

If the package registry is activated in GitLab, you can see the created packages:

If we want to use the package in another project, we have to do the following:

Create a private access token in GitLab, and add it to the composer configuration (keep the access token private!):

composer config -g gitlab-token.<GITLAB-DOMAIN> <ACCESS-TOKEN>

After that, we have to add the repository to the composer.json file of the project which will use the package (So it is an other file than the file before!)

	... 
	"repositories": [
        {
        "type": "composer",
        "url": "https://<GITLAB-DOMAIN>/api/v4/group/<GROUP-ID>/-/packages/composer/packages.json"
    	}
    ],
    ...

Step 4b: Publish the package to packagist

In order to make the package available for publicity, create an account at packagist.org. After that you can submit the package with the URL to the repository:

Step 5: Use the custom package

We can now install the package with

composer require doblhofer/helloworld

And use it for example with this example script:

<?php

require_once('../vendor/autoload.php');

use Doblhofer\HelloWorld;

$helloWorld = new HelloWorld();
echo $helloWorld->sayHello();

php src/index.php

A Demo-Repository for the example can be found here: https://gitlab.com/philipp.doblhofer/helloworld

The Packagist-Paket is located at https://packagist.org/packages/doblhofer/helloworld