Eigenes PHP Composer Paket in GitLab mit PHPUnit Tests

In diesem Artikel wird gezeigt, wie ein eigenes PHP Composer Packet unter zusätzlicher Verwendung von PHPUnit erstellt werden kann. Anschließend wird gezeigt, wie das Paket sowohl öffentlich mit Packagist, als auch für private Verwendung mit GitLab verteilt werden kann. Diese Anleitung wurde erstellt, um PHP-Entwicklern dabei zu helfen, ihren Arbeitsablauf zu optimieren und die Wiederverwendbarkeit von Code zu verbessern, indem sie ihre eigenen Pakete erstellen und teilen.

Um einen optimalen Arbeitsablauf und eine effiziente Vorgehensweise zu erlangen, ist es oft nützlich, Code-Teile in eine wiederverwendbare Bibliothek auszulagern. Ein gängiges System für PHP ist hierbei composer. In diesem Artikel wird gezeigt, wie ein eigenes composer Paket erstellt werden kann. Es wird gezeigt, wie dieses sowohl auf Packagist als auch in einer selbst-gehosteten GitLab Umgebung verteilt werden kann.

Voraussetzungen

PHP
Composer (Hier finden sich Details zur Installation)
Git und ein (neues) Git Repository für das neue Paket

Schritt 1: Projekt initialisieren

Zuerst wird das neue Paket konfiguriert. Wir werden ein einfaches Hello World Paket zur Demonstration erstellen.

git clone <REPOSITORY_URL>
cd <REPOSITORY>
composer init

Nachdem composer init eingegeben wurde, werden einige Informationen abgefragt:

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

Anschließend installieren wir PHPUnit für das Paket mithilfe des folgenden Befehles:

composer require --dev phpunit/phpunit

Danach sollte die Datei composer.json in etwa wie folgt aussehen:

{
    "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"
    }
}

Mehr Details wie das composer-Paket konfiguriert werden kann, findet sich hier: https://getcomposer.org/doc/04-schema.md

Schritt 2: Beispiel PHP-Klasse erstellen

Für unser Beispiel, erstellen wir eine einfache Klasse HelloWorld mit einer Methode sayHello()

<?php

namespace Doblhofer;

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

Schritt 3: Erstellen des Unit-Tests

Um die Funktionalität unseres Codes zu testen, schreiben wir eine Testfall. Wird der Code in Zukunft modifiziert, wird jedesmal gegen diesen Testfall abgeprüft. Dadurch kann garantiert werden, dass die Klasse genau die Funktionalität erfüllt, die entsprechend der Anforderungen in den Testfällen abgedeckt worden idz.

In unserem Fall ergibt sich folgender einfache Testfall zur Veranschaulichung:

<?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());
    }
}

Um PHPUnit zu verwenden, können entweder beim Aufruf Befehlszeilenargumente mitübergeben werden, oder die Einstellungen werden über eine Konfigurationsdatei festgelegt:

<?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>

Mehr Informationen über die Konfigurationsmöglichkeiten finden sich in der PHPUnit Dokumentation: https://docs.phpunit.de/en/10.0/

Anschließend können wir die Testfälle ausführen:

./vendor/bin/phpunit

Sofern alles korrekt aufgesetzt worden ist, sollte die Ausgabe ähnlich wie nachfolgend sein – alle Tests erfolgreich abgeschlossen:

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)

Schritt 4a: Verteilung des Paketes mit GitLab

Soll ein composer-Paket verwendet werden, ohne dass der Code veröffentlicht werden soll, kann dies beispielsweise mit einem GitLab-Repository erfolgen. Hinweis: Aktuell muss dass Projekt in einer Gruppe in GitLab sein, um mit nachfolgender Vorgehensweise verwendet werden zu können! Um das Paket zu testen und bei Erfolg zu Veröffentlichen, erstellen wir folgendes CI-Skript:

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

Mit diesem Skript wird bei jedem Commit die Testsuite ausgeführt und sofern diese erfolgreich abgeschlossen worden ist wird das Paket (privat) veröffentlicht.

Um eine konkrete Version festzulegen, kann ein Tag erstellt werden (Für mehr Informationen zur semantischen Versionierung, siehe https://www.philipp-doblhofer.at/blog/automatischer-changelog-und-versionierung-mit-git/)

git tag v1.0.0
git push origin v1.0.0

Wenn die Paket-Registry in GitLAb aktiviert ist, können hier die erstellten Pakete angezeigt werden:

Um das Paket in einem anderen Projekt zu verwenden, muss folgendes durchgeführt werden:

Zuerst muss ein Access Token erstellt werden, und diese bei composer hinterlegt werden (Den Access Token geheim halten!):

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

Anschließend muss das Repository in der composer.json Datei hinterlegt werden (Achtung, dies ist nicht die Datei von vorhin, sondern die des neuen Projektes, dass das Paket verwenden soll!)

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

Schritt 4b: Paket mit Packagist veröffentlichen

Um das Paket öffentlich zur Verfügung zu stellen, muss lediglich ein Account bei packagist.org erstellt werden. Anschließend kann über „Submit“ und der URL des Repositories das Paket verteilt werden:

Schritt 5: Das Paket verwenden

Wir können nun im neuen Projekt das Paket mit folgendem Befehl einbinden:

composer require doblhofer/helloworld

Anschließend kann es einfach verwendet werden:

<?php

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

use Doblhofer\HelloWorld;

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

php src/index.php

Ein Demo-Repository für das Beispiel-Paket findet sich unter https://gitlab.com/philipp.doblhofer/helloworld

Das Packagist-Paket findet sich unter https://packagist.org/packages/doblhofer/helloworld