Kompozytor: Jak Korzystać Z Repozytoriów Git

Nierzadko zdarza się, że chcemy użyć kompozytora do włączenia repozytoriów Git do naszego projektu PHP. W wielu przypadkach repozytoria zostały utworzone na packagist.org i wymaganie ich z kompozytorem jest bardzo proste. Ale co robimy, gdy repozytorium nie zostało utworzone jako pakiet na packagist? Odpowiedź jest taka, że używamy composera, aby wymagać pakietu bezpośrednio z repozytorium.

Nuta: Niektóre terminologie w poście są mylące, ponieważ wiele słów jest używanych do opisania różnych rzeczy. Oto krótka lista słownictwa, która pomoże:

• Projekt – Niestandardowe oprogramowanie, które budujemy. Może to być strona internetowa, narzędzie wiersza poleceń, aplikacja lub cokolwiek innego, co sobie wymarzymy.
• Pakiet - dowolne oprogramowanie stron 3rd, które chcemy pobrać i używać w ramach naszego projektu. Może to być biblioteka, motyw Drupal, wtyczka WordPress lub dowolna inna liczba.
• Repozytorium Git – AKA, repozytorium Git. Host kontroli wersji pakietu. Typowe hosty to: GitHub, GitLab lub Bitbucket; ale każde repozytorium Git dostępne pod adresem URL będzie działać w tym samouczku.
• Repozytoria kompozytora — w pliku composer.json znajduje się opcjonalna właściwość o nazwie "repozytoria". W tej właściwości możemy zdefiniować nowe miejsca, w których Composer może szukać podczas pobierania pakietów.

Dodając repozytorium Git do naszego projektu z kompozytorem, możemy znaleźć się w dwóch sytuacjach: repozytorium zawiera plik composer.json i określa, w jaki sposób repozytorium powinno być obsługiwane, gdy jest to wymagane, lub nie. Niezależnie od tego, w obu przypadkach jesteśmy w stanie dodać repozytorium Git do naszego projektu.

Zacznijmy od repozytorium Git, które zdefiniowało plik composer.json.

Git repo with composer.json Gdy repozytorium zawiera plik composer.json

, definiuje aspekty siebie, które są ważne dla sposobu, w jaki kompozytor zarządza pakietem. Oto przykład prostego pliku composer.json, który może zawierać pakiet.

{
    "name": "daggerhart/my-custom-library",
    "type": "library"
}

Pokazano dwie ważne właściwości, które może zdefiniować plik composer.json:

• name: Nazwa pakietu w przestrzeni nazw. W tym przypadku daggerhart jest przestrzenią nazw dla pakietu my-custom-library.
• type: Typ pakietu, który reprezentuje repozytorium. Typy pakietów są używane jako logika instalacji. Po wyjęciu z pudełka kompozytor pozwala na następujące typy pakietów: biblioteka, projekt, metapakiet, composer-plugin.

Możesz to sprawdzić, patrząc na plik composer.json dowolnego popularnego projektu. Każdy z nich definiuje nazwę pakietu i typ pakietu w górnej części pliku.

Gdy repozytorium ma te informacje zdefiniowane w pliku composer.json, wymaganie repozytorium w naszym projekcie jest stosunkowo proste.

Wymagaj repozytorium Git z plikiem composer.json Teraz, gdy zidentyfikowaliśmy repozytorium GIt z plikiem

composer.json, wymagajmy tego repozytorium jako pakietu w naszym projekcie.

W pliku composer.json naszego projektu musimy zdefiniować nową właściwość (zakładając, że jeszcze nie istnieje) o nazwie "repozytoria". Wartość właściwości repozytoria jest tablicą obiektów. Każdy obiekt zawierający informacje o repozytorium chcemy uwzględnić w naszym projekcie. Rozważ ten plik composer.json dla naszego niestandardowego projektu.

{
  "name":  "daggerhart/my-project-that-uses-composer",
  "repositories": [
    {
      "type": "vcs",
      "url": "https://github.com/daggerhart/my-custom-library.git"
    }
  ],
  "require": {
    "daggerhart/my-custom-library": "dev-master"
  }
}

Robimy tu dwie ważne rzeczy. Po pierwsze, definiujemy nowe repozytorium, do którego kompozytor może się odwoływać, gdy wymaga pakietów. Po drugie, wymagamy pakietu z nowo zdefiniowanego repozytorium.

Nuta: Wersja pakietu jest częścią instrukcji require, a nie częścią właściwości repozytorium. Możemy wymagać określonej gałęzi repozytorium, wybierając wersję o nazwie "dev-<branch name>".

Gdybyśmy mieli uruchomić composer install w kontekście tego pliku, kompozytor szukałby projektu pod zdefiniowanym adresem URL, a jeśli ten adres URL reprezentuje repozytorium Git, które zawiera plik composer.json, który definiuje jego nazwę i typ, kompozytor pobierze ten pakiet do naszego projektu i umieści go w odpowiedniej lokalizacji.

Niestandardowe typy

pakietów Przykładowy pakiet pokazany powyżej jest typu "biblioteka", ale często w naszej pracy z WordPressem i Drupalem mamy do czynienia z wtyczkami, modułami i motywami. Gdy w naszym projekcie wymagane są specjalne typy pakietów, ważne jest, aby były one instalowane w określonych lokalizacjach w strukturze plików projektu. Czy nie byłoby miło, gdybyśmy mogli przekonać kompozytora do traktowania tego typu pakietów jako szczególnych przypadków? Cóż, mamy szczęście. Istnieje oficjalna wtyczka kompozytora, która zrobi to za nas.

composer/installers - Wtyczka instalators composer zawiera niestandardową logikę wymaganą do obsługi wielu różnych typów pakietów dla wielu różnych projektów. Jest to niezwykle pomocne podczas pracy z projektami, które mają dobrze znane i obsługiwane kroki instalacji pakietów.

Ten projekt pozwala nam zdefiniować typy pakietów takie jak: drupal-theme, drupal-module, wordpress-plugin, wordpress-theme i wiele innych, dla różnych projektów. W przypadku pakietu drupal-theme, wtyczka composer/installers umieści wymagane repozytorium w folderze /themes/contrib naszej instalacji Drupal.

Oto przykład pliku composer.json, który może znajdować się w projekcie motywu Drupal jako własne repozytorium Git:

{
    "name": "daggerhart/whatever-i-call-my-theme",
    "type": "drupal-theme",
    "description": "Drupal 8 theme",
    "license": "GPL-2.0+"
}

Zauważ, że jedyną istotną różnicą jest to, że "type" jest teraz "drupal-theme". Po zdefiniowaniu typu drupal-theme, każdy projekt, który używa wtyczki composer/installers, może z łatwością wymagać naszego repozytorium w swoim projekcie Drupal i będzie traktowany jako motyw wniesiony.

Wymagaj dowolnego repozytorium Git za pomocą programu Composer

Teraz, gdy wiemy, jak wymagać repozytorium Git zawierającego plik composer.json, rozważmy przypadek, w którym repozytorium, które chcemy uwzględnić w naszym projekcie, nie definiuje niczego o sobie za pomocą pliku composer.json.

Krótko mówiąc, gdy repozytorium nie definiuje swojej nazwy lub typu, musimy zdefiniować te informacje dla repozytorium w pliku composer.json naszego projektu. Spójrz na ten przykład:Zauważ,

{
  "name": "daggerhart/my-project-that-uses-composer",
  "repositories": [
    {
      "type": "package",
      "package": {
        "name": "daggerhart/my-custom-theme",
        "version": "1.2.3",
        "type": "drupal-theme",
        "source": {
          "url": "https://github.com/daggerhart/my-custom-theme.git",
          "type": "git",
          "reference": "master"
        }
      }
    }
  ],
  "require": {
    "daggerhart/my-custom-theme": "^1",
    "composer/installers": "^1"
  }
}

że nasz typ repozytorium to teraz "pakiet". W tym miejscu określimy wszystko, czego chcemy wymagać. Następnie tworzymy nowy obiekt o nazwie "pakiet", w którym definiujemy wszystkie ważne informacje, które kompozytor musi znać, aby móc uwzględnić to dowolne repozytorium git w naszym projekcie. Tym:

• name — nazwa pakietu z przestrzenią nazw. Prawdopodobnie powinien pasować do repozytorium, którego wymagamy, ale nie musi.
• type — typ pakietu. Jak chcemy, aby kompozytor traktował to repozytorium.
• version — wymyślony numer wersji repozytorium.
• source — obiekt, który zawiera następujące informacje o repozytorium:
  • url – adres URL Git (lub innego VCS), pod którym można znaleźć repozytorium pakietu.
  • type — typ VCS dla pakietu. git, svn, cvs (?) ... itd.
  • reference — gałąź lub tag, który chcemy pobrać.

Polecam przejrzenie oficjalnej dokumentacji dotyczącej repozytoriów pakietów kompozytorskich. Zauważ, że możliwe jest również dołączenie plików zip jako pakietów edytora.

Zasadniczo jesteśmy teraz odpowiedzialni za wszystkie części tego, jak kompozytor traktuje to repozytorium. Ponieważ samo repozytorium nie dostarcza kompozytorowi żadnych informacji, jesteśmy odpowiedzialni za określenie prawie wszystkiego, w tym aktualnego numeru wersji pakietu.

Takie podejście pozwala nam zawrzeć prawie wszystko jako pakiet kompozytorski w naszym projekcie, ale ma pewne wady. Istotne wady:

• Program Composer nie zaktualizuje pakietu, chyba że zmienisz version pole.
• Composer nie zaktualizuje odwołań zatwierdzenia, więc jeśli użyjesz master jako odniesienia, będziesz musiał usunąć pakiet, aby wymusić aktualizację, i będziesz musiał poradzić sobie z niestabilnym plikiem blokady.

Niestandardowe wersje

pakietów Posiadanie wersji pakietu w naszym pliku composer.json nie zawsze jest konieczne. Composer jest na tyle sprytny, że szuka wydań GitHub i używa ich jako wersji pakietów. Ale w końcu okaże się, że chcemy włączyć prosty projekt, który ma tylko kilka gałęzi i nie ma oficjalnych wydań.

Jeśli repozytorium nie ma wydań, będziemy odpowiedzialni za podjęcie decyzji, jaką wersję reprezentuje gałąź repozytorium dla naszego projektu. Innymi słowy, jeśli chcemy, aby kompozytor zaktualizował pakiet, będziemy musieli zwiększyć "wersję" zdefiniowaną w pliku composer.json naszego projektu przed uruchomieniem composer update.

Nadpisywanie pliku composer.json repozytorium Git Ciekawą rzeczą, którą możemy zrobić podczas definiowania nowego repozytorium composer pakietu type, jest nadpisanie własnych definicji composer.json

pakietu. Rozważmy, że repozytorium Git definiuje się jako biblioteka w swoim composer.json, ale wiemy, że kod jest w rzeczywistości motywem drupala. Możemy użyć tego powyższego podejścia, aby dołączyć repozytorium Git do naszego projektu jako motyw drupala, umożliwiając kompozytorowi odpowiednie traktowanie kodu, gdy jest to wymagane.

Przykład: wymagamy Guzzle jako motywu drupala tylko po to, aby udowodnić, że możemy.

{
  "name": "daggerhart/my-project-that-uses-composer",
  "repositories": [
    {
      "type": "package",
      "package": {
        "name": "daggerhart/guzzle-theme",
        "version": "1.2.3",
        "type": "drupal-theme",
        "source": {
          "url": "https://github.com/guzzle/guzzle.git",
          "type": "git",
          "reference": "master"
        }
      }
    }
  ],
  "require": {
    "daggerhart/guzzle-theme": "^1",
    "composer/installers": "^1"
  }
}

To działa! Spowoduje to pobranie biblioteki Guzzle i umieszczenie jej w folderze /themes mojego projektu Drupal. Oczywiście nie jest to bardzo praktyczny przykład, ale mam nadzieję, że podkreśli, jak dużą kontrolę zapewnia podejście typu packge.

Summary

Composer oferuje nam wiele opcji dołączania dowolnych pakietów w naszym projekcie. Pytanie, w jaki sposób te pakiety są uwzględniane w projekcie, sprowadza się przede wszystkim do "kto definiuje informacje o pakiecie?". Jeśli repozytorium Git zawiera plik composer.json, który definiuje jego nazwę i typ, możemy poprosić kompozytora o poleganie na samym repozytorium dla definicji. Ale jeśli chcemy dołączyć repozytorium, które nie definiuje jego nazwy i typu, to do naszego projektu należy zdefiniowanie i utrzymanie tych informacji na własny użytek wewnętrzny.

Alternatywnie, jeśli repozytorium nie definiuje pliku composer.json, rozważ przesłanie żądania ściągnięcia, które go doda. ?

Odwołania:

• Composer: niestandardowa definicja pakietu
• Kompozytor: używanie repozytoriów VCS
• Drupal StackExchange: Jak dodać motyw z GitHub za pomocą Composer