Utiliser Composer pour exiger des référentiels Git dans les projets PHP
Français
L’outil de gestion des dépendances Compositeur fournit plusieurs façons d’inclure des référentiels Git dans un projet PHP : Hypertext Preprocessor (PHP).
Dans de nombreux cas, des référentiels ont été créés sur Packagist, il est donc très simple de les exiger avec Composer. Mais que faire lorsqu’un référentiel n’a pas été créé en tant que package sur Packagist ? Vous utilisez Composer pour demander le package directement à partir du référentiel. Cet article explique comment.
Noter: Une partie de la terminologie de cet article prête à confusion car plusieurs mots sont utilisés pour décrire différentes choses. Voici une liste de vocabulaire rapide qui vous aidera :
- Projet: Le logiciel personnalisé que vous construisez. Il peut s’agir d’un site Web, d’un utilitaire de ligne de commande, d’une application ou de tout autre élément dont vous rêvez.
- Emballer: Tout logiciel tiers que vous souhaitez télécharger et utiliser dans votre projet. Il peut s’agir d’une bibliothèque, d’un thème Drupal, d’un plugin WordPress ou de tout autre nombre de choses.
- Référentiel Git : Également appelé référentiel Git, il s’agit de l’hôte de contrôle de version d’un package. Les hôtes courants incluent GitHub, GitLab ou Bitbucket, mais tout référentiel Git accessible par URL fonctionnera pour ce didacticiel.
- Référentiels Composer : Dans un
composer.jsonfichier, il existe une propriété facultative nommée “dépôts”. Cette propriété est l’endroit où vous pouvez définir de nouveaux endroits où Composer doit chercher lors du téléchargement de packages.
Lors de l’ajout d’un dépôt Git à votre projet avec Composer, vous pouvez vous retrouver dans deux situations : Soit le dépôt contient un composer.json fichier, qui définit la manière dont le référentiel doit être géré en cas de besoin, ou non. Vous pouvez ajouter le référentiel Git à votre projet dans les deux cas, avec des méthodes différentes.
Dépôt Git avec composer.json
Lorsqu’un référentiel comprend un composer.json fichier, il définit les aspects de lui-même qui sont importants pour la façon dont Composer gère le package. Voici un exemple simple composer.json déposer un colis peut inclure :
{
"name": "mynamespace/my-custom-library",
"type": "library"
}
Cet exemple montre deux propriétés importantes qu’un composer.json fichier peut définir :
- Nom: Le nom d’espace de noms du package. Dans ce cas, “mynamespace” est l’espace de noms du package “my-custom-library”.
- Taper: Type de package représenté par le référentiel. Les types de package sont utilisés pour la logique d’installation. Par défaut, Composer autorise les types de packages suivants : bibliothèque, projet, métapaquet et plugin composer.
Vous pouvez le vérifier en regardant le composer.json fichier de n’importe quel projet GitHub populaire. Ils définissent chacun leur nom de package et le type de package en haut du fichier. Lorsqu’un référentiel a ces informations définies dans son composer.json fichier, nécessitant le référentiel dans votre projet est assez simple.
Exiger un référentiel Git contenant un fichier composer.json
Après avoir identifié un dépôt Git avec un composer.json fichier, vous pouvez exiger ce référentiel en tant que package dans votre projet.
Au sein de votre projet composer.json fichier, vous devez définir une nouvelle propriété (en supposant qu’elle n’existe pas déjà) nommée “dépôts”. La valeur de la propriété repositories est un tableau d’objets, chacun contenant des informations sur le référentiel que vous souhaitez inclure dans votre projet. Considère ceci composer.json fichier pour votre projet personnalisé.
{
"name": "mynamespace/my-project-that-uses-composer",
"repositories": [
{
"type": "vcs",
"url": "https://github.com/mynamespace/my-custom-library.git"
}
],
"require": {
"mynamespace/my-custom-library": "dev-master"
}
}
Vous faites ici deux choses importantes. Tout d’abord, vous définissez un nouveau référentiel que Composer peut référencer lors de la demande de packages. Et deuxièmement, vous avez besoin du package du référentiel nouvellement défini.
Noter: La version du package fait partie du exiger déclaration et non une partie de la dépôt biens. Vous pouvez exiger une branche spécifique d’un référentiel en choisissant une version nommée “dev-
Si tu devais courir composer install dans le contexte de ce fichier, Composer rechercherait un projet à l’URL définie. Si cette URL représente un dépôt Git contenant un composer.json qui définit son nom et son type, Composer téléchargera ce package dans votre projet et le placera à l’emplacement approprié.
Types de forfaits personnalisés
L’exemple de package présenté ci-dessus est du type “bibliothèque”, mais avec WordPress et Drupal, vous avez affaire à des plugins, des modules et des thèmes. Lorsque vous avez besoin de types de packages spéciaux dans votre projet, il est important de les installer à des emplacements spécifiques dans la structure de fichiers du projet. Ne serait-il pas agréable de convaincre Composer de traiter ces types de packages comme des cas particuliers ? Eh bien, vous avez de la chance. Il existe un plugin Composer officiel qui le fera pour vous.
Le Installateurs plugin for Composer contient la logique personnalisée requise pour gérer de nombreux types de packages différents pour une grande variété de projets. Il est extrêmement utile lorsque vous travaillez avec des projets qui ont des étapes d’installation de packages bien connues et prises en charge.
Ce projet vous permet de définir des types de packages tels que drupal-theme, drupal-module, wordpress-plugin, wordpress-theme et bien d’autres, pour une variété de projets. Dans le cas d’un package de thème Drupal, le plug-in Installers placera le référentiel requis dans le /themes/contrib dossier de votre installation Drupal.
Voici un exemple de composer.json fichier qui pourrait vivre dans un projet de thème Drupal en tant que son propre référentiel Git :
{
"name": "mynamespace/whatever-i-call-my-theme",
"type": "drupal-theme",
"description": "Drupal 8 theme",
"license": "GPL-2.0+"
}
Notez que la seule différence significative ici est que le type est désormais drupal-theme. Avec le type de thème drupal défini, tout projet utilisant le plugin Installers peut facilement nécessiter votre dépôt dans son projet Drupal, et il sera traité comme un thème contribué.
Exiger n’importe quel référentiel Git avec Composer
Que se passe-t-il lorsque le référentiel que vous souhaitez inclure dans votre projet ne définit rien sur lui-même avec un composer.json dossier? Lorsqu’un référentiel ne définit pas son nom ou son type, vous devez définir ces informations pour le référentiel dans le cadre de votre projet. composer.json dossier. Jetez un oeil à cet exemple:
{
"name": "mynamespace/my-project-that-uses-composer",
"repositories": [
{
"type": "package",
"package": {
"name": "mynamespace/my-custom-theme",
"version": "1.2.3",
"type": "drupal-theme",
"source": {
"url": "https://github.com/mynamespace/my-custom-theme.git",
"type": "git",
"reference": "master"
}
}
}
],
"require": {
"mynamespace/my-custom-theme": "^1",
"composer/installers": "^1"
}
}
Notez que votre type de référentiel est désormais “package”. C’est là que vous définirez tout ce qui concerne le package dont vous souhaitez avoir besoin.
Créez un nouvel objet nommé “package” dans lequel vous définissez toutes les informations essentielles que Composer doit connaître pour pouvoir inclure ce référentiel git arbitraire dans votre projet, notamment :
- Nom: Nom du package avec espace de noms. Il devrait probablement correspondre au référentiel dont vous avez besoin, mais ce n’est pas obligatoire.
- Taper: Le type de colis. Cela reflète la manière dont vous souhaitez que Composer traite ce référentiel.
- Version: Un numéro de version pour le référentiel. Vous devrez inventer cela.
- La source: Un objet contenant les informations de référentiel suivantes :
- URL : L’URL Git ou d’un autre système de contrôle de version (VCS) où se trouve le référentiel de packages
- Taper: Le type VCS du package, tel que git, svn, cvs, etc.
- Référence: La branche ou le tag que vous souhaitez télécharger
Je recommande de revoir le documents officiels sur les référentiels de packages Composer. Notez qu’il est également possible d’inclure des fichiers zip en tant que packages Composer. Essentiellement, vous êtes maintenant responsable de toutes les parties de la façon dont Composer traite ce référentiel. Étant donné que le référentiel lui-même ne fournit aucune information à Composer, vous êtes responsable de déterminer presque tout, y compris le numéro de version actuel du package.
Cette approche vous permet d’inclure presque n’importe quoi en tant que package Composer dans votre projet, mais elle présente des inconvénients notables :
- Composer ne mettra pas à jour le package à moins que vous ne changiez le
versiondomaine. - Composer ne mettra pas à jour les références de validation. Si tu utilises
mastercomme référence, vous devrez supprimer le paquet pour forcer une mise à jour, et vous devrez faire face à un fichier de verrouillage instable.
Versions de package personnalisées
Maintenir la version du package dans votre composer.json fichier n’est pas toujours nécessaire. Composer est suffisamment intelligent pour rechercher les versions de GitHub et les utiliser comme versions de package. Mais éventuellement, vous voudrez probablement inclure un projet simple qui n’a que quelques branches et aucune version officielle.
Lorsqu’un référentiel n’a pas de versions, vous serez responsable de décider quelle version la branche de référentiel représente pour votre projet. En d’autres termes, si vous souhaitez que composer mette à jour le package, vous devrez incrémenter la “version” définie dans le fichier de votre projet. composer.json fichier avant d’exécuter composer update.
Remplacer le fichier composer.json d’un dépôt Git
Lors de la définition d’un nouveau référentiel Composer du type package, vous pouvez remplacer le propre d’un package composer.json définitions. Considérez un référentiel Git qui se définit comme une bibliothèque dans son composer.json, mais vous savez que le code est en fait un thème Drupal. Vous pouvez utiliser l’approche ci-dessus pour inclure le référentiel Git dans votre projet en tant que thème Drupal, permettant à Composer de traiter le code de manière appropriée si nécessaire.
Exemple : Exigez Guzzle comme thème Drupal juste pour prouver que vous le pouvez.
{
"name": "mynamespace/my-project-that-uses-composer",
"repositories": [
{
"type": "package",
"package": {
"name": "mynamespace/guzzle-theme",
"version": "1.2.3",
"type": "drupal-theme",
"source": {
"url": "https://github.com/guzzle/guzzle.git",
"type": "git",
"reference": "master"
}
}
}
],
"require": {
"mynamespace/guzzle-theme": "^1",
"composer/installers": "^1"
}
}
Cela marche! Vous avez téléchargé la bibliothèque Guzzle et l’avez placée dans le /themes dossier de votre projet Drupal. Ce n’est pas un exemple très pratique, mais il met en évidence le degré de contrôle fourni par l’approche par type de package.
Résumé
Composer offre de nombreuses options pour inclure des packages arbitraires dans un projet. Déterminer comment ces packages sont inclus dans le projet revient principalement à qui définit les informations du package. Si le dépôt Git inclut un composer.json fichier qui définit son nom et son type, vous pouvez faire en sorte que Composer s’appuie sur le référentiel lui-même pour la définition.
Mais si vous souhaitez inclure un référentiel qui ne définit pas son nom et son type, il appartient à votre projet de définir et de gérer ces informations pour votre propre usage interne. Alternativement, si un dépôt ne définit pas un composer.json fichier, envisagez de soumettre une demande d’extraction qui l’ajoute.
Cet article est initialement paru sur le Blog de Daggerhart Lab et est republié avec autorisation.
(No Ratings Yet)
Loading...
