Zo maak je je eigen Composer package

Met hergebruik van code komt het probleem van beheer van dependencies, van oudsher een nogal handmatig en foutgevoelig proces. Gelukkig hebben de meeste programmeertalen dit probleem de laatste jaren opgelost door verschillende tools te introduceren die het beheer van dependencies vergemakkelijken. In het PHP ecosysteem is Composer de standaard geworden dankzij het gebruiksgemak, de flexibiliteit en de brede acceptatie.

Hoewel Composer is gebouwd voor het beheer van dependencies, kun je het ook gebruiken voor taken als:

• Autoloading: Automatisch laden van classes en functions uit externe libraries om ze gemakkelijk toegankelijk te maken vanuit je code en het proces van het integreren van externe code in je project te vereenvoudigen.
• Code genereren: Genereren van boilerplate code voor je project, zoals configuratiebestanden of andere veelgebruikte stukjes code om het ontwikkelproces te versnellen en consistentie te garanderen.
• Scripting: Een ingebouwd scriptsysteem kan veelvoorkomende taken automatiseren, zoals het uitvoeren van tests of het genereren van documentatie vanuit je codebasis. Dit kan helpen om je ontwikkelworkflow te stroomlijnen en handmatig werk te verminderen.

Deze stap-voor-stap handleiding leidt je door het maken van je eigen Composer package en het publiceren ervan naar Packagist, een repository voor PHP packages die developers over de hele wereld kunnen gebruiken in hun eigen projecten.

Hoe werkt Composer?

Laten we er eerst voor zorgen dat we Composer begrijpen. Eenvoudig gezegd werkt Composer met een composer.json bestand dat de definities bevat voor de dependencies in je PHP project. Het zoekt die packages op in een centrale repository en downloadt en installeert die dependencies vervolgens automatisch met behulp van de package repo.

Ervan uitgaande dat Composer al is geïnstalleerd in je PHP werkomgeving, zie je hier hoe het download- en installatieproces van de dependencies eruit ziet:

1. Definieer de vereiste dependencies voor je project in een composer.json bestand in de hoofdmap van je project. Dit bestand bevat informatie over vereiste libraries en hun versies en eventuele andere configuratie-instellingen of dependencies voor die libraries.
2. Los dependencies op in Composer met commando’s als install om de vereiste dependencies te installeren; update om bestaande dependencies bij te werken; en require om nieuwe dependencies toe te voegen aan het composer.json bestand. Wanneer je een commando uitvoert, leest Composer het composer.json bestand om de vereiste dependencies te bepalen, controleert de packagerepo voor de nieuwste versie van elke dependency die geschikt is voor je PHP omgeving en controleert dan op eventuele conflicten of versiebeperkingen.
3. Composer downloadt en installeert de vereiste dependencies, inclusief libraries, in de vendor directory van je project. Composer maakt een composer.lock bestand aan met de exacte versies van de geïnstalleerde dependencies.
4. Composer stelt een autoloader in die classes en functions van de geïnstalleerde dependencies automatisch laadt. Dit maakt het gemakkelijk om de geïnstalleerde libraries in je project te gebruiken zonder dat je elk bestand handmatig hoeft op te nemen.

Kortom, Composer vereenvoudigt het beheer van dependencies in PHP projecten en maakt het eenvoudig om externe libraries en frameworks te installeren, bij te werken en te gebruiken.

Een Composer package maken en publiceren

Deze tutorial laat zien hoe je een eenvoudige PHP library genaamd tempconv maakt, die Celsius temperatuur omzet naar Fahrenheit en vice versa, en sluit af door het te publiceren als Composer package.

Vereisten

Je hebt een paar dingen nodig voordat je begint:

• PHP en Composer goed geïnstalleerd op je systeem. Op het moment van schrijven is de laatste Composer versie v2.6.6, maar deze instructies zouden met elke v2 variant moeten werken.
• Een GitHub account om een repository aan te maken voor het hosten van je code.
• Een Packagist account om je library te publiceren.

Een project repository maken

Maak je eigen GitHub repository voor deze tutorial, waar je je voltooide librarycode en bestanden naartoe kunt pushen.

Deze tutorial gebruikt de projectnaam tempconv. Geef in het veld Description korte details over de applicatie. Vink het vakje aan om een README bestand toe te voegen, kies het Composer sjabloon voor de optie Add .gitignore, en selecteer een licentie naar keuze- deze tutorial gebruikt MIT License. Klik tot slot op Create repository.

De repository klonen

Kloon de repository die je zojuist hebt gemaakt naar je lokale machine. Vergeet niet om de URL te vervangen door je eigen URL, zowel hier als in deze tutorial:

$ git clone https://github.com/rexfordnyrk/tempconv.git

Dit maakt een map aan met de naam tempconv in je huidige werkmap. Op dit moment bevat het alleen README.md, LICENSE en .gitignore bestanden, maar je zult je packagebestanden hier ook aanmaken.

Je PHP library maken

Voeg in jouw projectmap een bestand TemperatureConverter.php toe met de volgende code:

<?php

namespace RexfordnyrkTempconv;

class TemperatureConverter
{
    //Caller must provide the temperature value and the unit either C Celsius or F Fahrenheit
    public function convert($temperature, $unit)
    {
        //Checking whether the unit we're working with is Celsius or Fahrenheit
        if ($unit === 'C') {
            $fahrenheit = ($temperature * 9 / 5) + 32;
            return $fahrenheit;
        } elseif ($unit === 'F') {
            $celsius = ($temperature - 32) * 5 / 9;
            return $celsius;
        } else {
            //Throwing error if the unit provided is neither C nor F
            throw new InvalidArgumentException('Invalid unit, only C (Celsius) or F (Fahrenheit) are allowed');
        }
    }
}

Deze klasse heeft een enkele methode genaamd convert die de temperatuur en de eenheid als argumenten neemt en de geconverteerde temperatuur teruggeeft. Er wordt een uitzondering gegooid als de eenheid ongeldig is.

Dat is genoeg voor nu. In een echt scenario zou je waarschijnlijk unit tests schrijven om ervoor te zorgen dat je code werkt zoals verwacht na aanpassingen of updates.

Je composer package maken.

Nu je librarycode klaar is, is het tijd om er een Composer package van te maken. Je genereert een composer.json bestand voor je package met behulp van een stap-voor-stap wizard, en we behandelen enkele best practices voor het organiseren van je code als een package voordat je het naar je repository pusht.

Een composer.json package bestand genereren

Hoewel je de inhoud van een composer.json bestand handmatig in de root van je projectmap kunt schrijven, is het beter om het te genereren met het volgende Composer commando:

$ composer init

Dit commando leidt je door een kleine stap-voor-stap wizard. De antwoorden die je geeft op vragen zoals de naam van je package, beschrijving, informatie over de auteur en licentietype zullen het composer.json bestand van je package genereren.

De documentatie van Composer beschrijft de verwachte waarden en andere opties die je kunt gebruiken om de composer.json van je project te definiëren.

Merk op dat de wizard waar van toepassing voorgedefinieerde antwoorden op de vragen geeft, zoals het afleiden van je naam en e-mail van git. Verander ze gerust als je dat wilt.

Deze library is voor functionaliteit niet afhankelijk van andere packages, dus je kunt No antwoorden op vragen die dependencies specificeren.

De wizard toont je een voorbeeld van de gegenereerde bestandsinhoud en vraagt je om het te bevestigen om de wizard te voltooien.

Pakketbestanden organiseren

Het voltooien van de wizard creëert twee mappen naast het composer.json bestand:

• src voor je sourcecode
• vendor voor je gedownloade dependencies

Verplaats het bestand TemperatureConverter.php naar de src map. Als jouw library dependencies heeft, voer dan composer install uit om de autoloader te genereren en de packagedependencies te installeren.

Code uploaden naar GitHub

Voeg jouw wijzigingen en nieuwe bestanden toe aan git:

$ git add -A

Commit de wijzigingen in de lokale repository en push het naar de remote repo op GitHub, zodat je het project eenvoudig kunt publiceren in het volgende gedeelte:

$ git commit -am "Initial Release" && git push

Een releaseversie voor je library maken

Met je code in je repo kun je een release van je library maken met een versienummer zodat andere developers je stabiele en major updates kunnen bijhouden.

Navigeer naar je repo op GitHub en klik op Releases onder de About sectie. Op de Releases pagina, waar je naar verwachting nu niets hebt, klik je op Create a new release.

Vul een paar details over je release in, zoals de tag versie en de titel van de release. De tag versie moet een unieke identificatie voor deze release zijn (voorbeeld: v1.0.0), en de titel van de release moet de veranderingen in de release beschrijven (voorbeeld: Eerste release).

Optioneel kun je een beschrijving van de release toevoegen. Als je een bestand wilt uploaden, zoals een gecompileerde binary of een sourcecode archief, sleep het bestand dan naar het gebied Attach binaries by dropping here of selecteer het, maar dat is niet nodig voor deze tutorial.

Klik op Publish release om de release te maken.

Je project zou nu beschikbaar moeten zijn op de Releases pagina van je repository. Gebruikers kunnen alle bestanden downloaden die je hebt toegevoegd en de release notities bekijken. Bovendien, als je een tag voor de release hebt toegevoegd, kunnen andere developers die tag gebruiken om de exacte code te bekijken die in de release is opgenomen.

Je library is klaar om met de wereld te delen. Laten we het publiceren als een package op Packagist.

Aan de slag met Packagist

Packagist is de belangrijkste package repository voor PHP. Het biedt een centrale locatie voor developers om hun PHP packages te publiceren en te delen, en voor andere developers om die packages te ontdekken en te gebruiken in hun eigen projecten. Laten we je package publiceren!

Navigeer naar de Packagist website, klik op Log in, en selecteer GitHub als inlogmethode om je GitHub account te gebruiken voor authenticatie.

Klik op Authorize om Packagist toegang tot je account te geven.

Je Composer package indienen op Packagist

Om een package op Packagist te publiceren, dien je de GitHub repository in die het composer.json bestand bevat dat je package en zijn dependencies beschrijft. Klik op Submit op de site van Packagist, geef de URL van je repo op de pagina die verschijnt en klik op Check om het te valideren.

Als de repository geldig is, detecteert Packagist de naam van het package en wordt de Check knop Submit.

Klik op Submit en Packagist neemt even de tijd om je project in te stellen en te publiceren.

Dat is het! Je package is nu beschikbaar op Packagist voor andere developers om te gebruiken als dependency in hun eigen projecten.

Je Composer package in andere projecten gebruiken

Je kunt je gepubliceerde package in andere projecten gebruiken door het toe te voegen als een dependency in het composer.json bestand. Je kunt het bestand handmatig aanmaken en bewerken, maar het is beter om het Composer commando als volgt te gebruiken:

$ composer require rexfordnyrk/tempconv

Composer maakt het composer.json bestand automatisch aan als het nog niet bestaat, dan wordt het package gevonden, gedownload en autoloads vanuit Packagist. De uitvoer zou er ongeveer zo uit moeten zien:

Maak een demo.php bestand om je demo applicatiecode te bevatten om met je library te werken.
Je kunt dan de class TemperatureConverter op deze manier gebruiken in je applicatiecode:

<?php
use RexfordnyrkTempconvTemperatureConverter;

require_once './vendor/autoload.php';

$converter =  new TemperatureConverter();

$fahrenheit = $converter->convert(20, 'C');
echo "20°C is equivalent to $fahrenheit °Fn";

$celsius = $converter->convert(68, 'F');
echo "68°F is equivalent to $celsius °Cn";

Deze code gebruikt de class TemperatureConverter om temperaturen 20 Celsius en 68 Fahrenheit om te rekenen en de resultaten uit te voeren. Het geïmporteerde autoloader.php bestand is gemaakt door Composer om alle dependencies te laden die je nodig hebt. Dat zorgt ervoor dat de class automatisch wordt geladen wanneer dat nodig is.

Voer tot slot deze code uit in je terminal:

$ php demo.php

Je zou een uitvoer moeten hebben die hierop lijkt:

$ php demo.php
20°C is equivalent to 68 °F
68°F is equivalent to 20 °C

Samenvatting

Je hebt zojuist een eenvoudige PHP library gemaakt die temperatuur omzet van Celsius naar Fahrenheit en vice versa in een object-georiënteerde class die kan worden hergebruikt in andere applicaties. Je hebt gezien hoe je Composer kunt gebruiken om een package te maken van de class met het Composer Init commando, en je hebt wat basic code organisatie best practices geleerd voor je library. Je hebt je library gepubliceerd op Packagist, zodat jij en andere developers deze kunnen gebruiken als dependency in andere projecten.

Als je klaar bent met het ontwikkelen van je applicatie, moet je deze natuurlijk ook hosten. Til je PHP development naar een hoger niveau met Web Applicatie Hosting van Kinsta. Je kunt je op Composer gebaseerde PHP applicatie binnen enkele minuten deployen. Voeg simpelweg je applicatie toe via de git repository van je project en Kinsta doet de rest. Het detecteert automatisch het Composer bestand en bouwt je applicatie automatisch. Begin vandaag nog zonder risico!

Rexford Nyarko

Rexford Nyarko is a solution architect with a background in software and network systems, cloud environments, server administration, and various database technologies. Rexford particularly enjoys explaining technical concepts to non-technical audiences.