Jak umístit kod na Packagist.org | Jiří Wolf - vývoj webových stránek, programování

23. 4. 2025

Tento článek popisuje jak správně strukturovat a nastavit vlastní Drupal téma vzhledu (nebo modul, nebo jakýkoli jiný kód platí to obecně) tak, aby se dalo spravovat a instalovat pomocí nástroje Composer.

Proč to dělat?

Správa vlastních modulů a témat pomocí Composeru přináší řadu výhod:

Jednotná správa závislostí: všechny závislosti projektu (včetně vašich vlastních rozšíření) jsou definovány na jednom místě (composer.json).
Snadnější instalace a aktualizace: instalace na novém prostředí nebo aktualizace je otázkou jediného Composer příkazu.
Znovupoužitelnost: kód můžete snadno použít ve více projektech.
Jasná verze: díky Git tagům a Packagistu mají vaše rozšíření jasně definované verze.
Moderní workflow: zapadá do standardního vývojového procesu moderního Drupalu.

Předpoklady:

Máte lokální vývojové prostředí s Drupalem 10 nebo 11, které je spravováno pomocí Composeru (např. s využitím drupal/recommended-project).
Máte vytvořený kód svého vlastního tématu vzhledu (např. se strojovým názvem např. moje_thema).
Máte nainstalovaný Git.
Máte účet na platformě pro hostování Git repozitářů (např. GitHub, GitLab, Bitbucket).
Máte účet na Packagist.org.
Máte základní znalost práce s Docker volumes (pokud používáte Docker).

Připravte své téma jako samostatný Git repozitář

Nejdůležitější koncept je pochopit, že vaše vlastní téma bude existovat jako zcela samostatný Git repozitář, nezávislý na Git repozitáři vaší hlavní Drupal instalace v samostatném adresáři umístěném mimo root Drupalu.

Neinicializujte Git repozitář uvnitř adresáře tématu (web/themes/custom/vase_tema/) v rámci repozitáře hlavní Drupal instalace. To vede k problémům s vnořenými repozitáři.

Správný postup:

Vytvořte na svém lokálním disku nový adresář mimo strukturu vaší hlavní Drupal instalace. Tento adresář bude kořenem Git repozitáře vašeho tématu.
```
# Příklad:
mkdir -p /cesta/mimo/drupal/projekty/moje-drupal-temata/moje-thema/
```
Přesuňte veškerý kód vašeho tématu (všechny soubory a podsložky, např. moje-thema.info.yml, moje-thema.libraries.yml, css/, js/, templates/ atd.) do tohoto nového adresáře. Pokud jste omylem již inicializovali Git uvnitř adresáře tématu v Drupalu, smažte adresář .git z původního umístění (web/themes/custom/moje-thema/.git).

Vytvořte soubor composer.json pro vaše téma

V kořenovém adresáři vašeho samostatného tématu (/cesta/mimo/drupal/projekty/moje-drupal-temata/moje-tema/) vytvořte soubor s názvem composer.json. Tento soubor definuje vaše téma jako Composer balíček a určí, kam se má instalovat.

Použijte typ balíčku "drupal-custom-theme", aby Composer věděl, že jde o vaše vlastní téma a nainstaloval ho do themes/custom.

composer.json

{
    "name": "jmeno-repozitare/moje-tema",
    "description": "Popis vašeho vlastního tématu vzhledu pro Drupal",
    "type": "drupal-custom-theme", // <--- Nastavte tento typ pro instalaci do themes/custom
    "license": "GPL-2.0-or-later",
    "require": {
        "drupal/core": "^10 || ^11"
    }
    // Zde můžete přidat další závislosti, autoloading nebo extra konfigurace
}

name: unikátní jméno balíčku ve formátu vendor/package. Zvolte si vase_vendor (např. vaši přezdívku, jméno firmy adp.) a package (strojový název tématu, moje-tema). Používejte malá písmena a pomlčky. Tento název balíčku je klíčový pro Composer a Packagist.
description: krátký popis tématu.
type: klíčové pro umístění instalace! Nastavte na "drupal-custom-theme". Tím Composeru a pluginu composer/installers řeknete, že jde o vaše vlastní téma a nainstaluje ho do adresáře definovaného pro tento typ (ve výchozím nastavení web/themes/custom/).
license: důležité pro Packagist! Uveďte licenci, pod kterou téma šíříte. Pro Drupal rozšíření je standard "GPL-2.0-or-later". Nezapomeňte mít i odpovídající soubor LICENCE v repozitáři.
require: zde definujte závislosti vašeho tématu. Minimálně kompatibilitu s Drupal core. ^10 || ^11 znamená kompatibilitu s Drupalem 10 i 11.

Inicializujte Git a nahrajte repozitář na GitHub/GitLab

Nyní z adresáře vašeho samostatného tématu vytvoříte Git repozitář a nahrajete ho na platformu jako GitHub.

Přejděte do adresáře tématu:

cd /cesta/mimo/drupal/projekty/moje-drupal-temata/moje-thema/

Inicializujte Git repozitář:

git init

Přidejte všechny soubory a proveďte první commit:

git add .
git commit -m "Initial commit of moje thema with custom type"

Vytvořte prázdný repozitář na GitHubu (nebo GitLabu apod.): Jděte na webovou stránku vaší Git hostingové platformy, vytvořte nový, prázdný repozitář (např. s názvem moje-thema). Nezaškrtávejte "Initialize with a README", "Add .gitignore" atd.
Propojte lokální repozitář se vzdáleným: Získejte URL (HTTPS nebo SSH) nově vytvořeného prázdného repozitáře. Přidejte ji jako "remote" s názvem origin:
```
git remote add origin https://github.com/jmeno-repozitare/moje-thema.git
# nebo přes SSH:
# git remote add origin git@github.com:jmeno-repozitare/moje-thema.git
```
Přejmenujte hlavní větev na main (doporučeno):
```
git branch -M main
```
Nahrajte lokální repozitář na GitHub:
```
git push -u origin main
```
Pokud používáte HTTPS, Git vás může požádat o přihlášení nebo zadání Personal Access Tokenu (PAT) pro GitHub.

Váš kód tématu je nyní v samostatném Git repozitáři na GitHubu.

Publikujte téma na Packagist.org

Packagist.org je hlavní repozitář pro balíčky Composeru pro PHP. Propojíte svůj Git repozitář s Packagistem.

Přejděte na Packagist.org a přihlaste se: https://packagist.org/ přihlaste se, ideálně s účtem propojeným s vaším GitHubem.
Přejděte na stránku "Submit": klikněte na tlačítko "Submit" v horní nabídce.
Zadejte URL vašeho Git repozitáře na GitHubu: vložte URL, kterou jste získali v Kroku 3 (např. https://github.com/jmeno-repozitare/moje-thema.git).
Zkontrolovat a odeslat: klikněte na "Check". Packagist načte váš composer.json. Pokud je platný a název balíčku v něm (např. "vasejmeno/moje-thema") odpovídá formátu vendor/package, zobrazí detaily balíčku. Packagist by měl rozpoznat typ "drupal-custom-theme". Klikněte na "Submit".

Váš balíček (téma) je nyní zaregistrován na Packagistu pod názvem, který jste uvedl v composer.json.

Nastavte automatické aktualizace pomocí Webhooku

Aby Packagist věděl o nových commitech a tazích, které pushnete na GitHub, nastavte webhook.

Získejte váš Packagist API Token: na Packagist.org jděte do Profile (nebo Settings -> Profile) a zkopírujte svůj API Token.
Na GitHubu jděte do nastavení repozitáře tématu: přejděte na stránku repozitáře na GitHubu -> záložka Settings -> Webhooks.
Přidejte nový Webhook: klikněte na "Add webhook".
Nastavte parametry:
- Payload URL: https://packagist.org/api/github?username=VASE_PACKAGIST_UZIVATELSKE_JM… (nahraďte vaším Packagist uživatelským jménem).
- Content type: application/json
- Secret: vložte váš Packagist API Token.
- Which events: vyberte "Just the push event."
- Active: zaškrtněte.
Uložte Webhook: klikněte na "Add webhook".

Nyní Packagist automaticky zaktualizuje váš balíček při každém pushnutí na GitHub.

Verzování tématu pomocí Git Tagů

Composer a Packagist používají Git tagy ve vašem repozitáři pro označení konkrétních verzí (např. 1.0.0).

Ujistěte se, že jste v adresáři samostatného repozitáře tématu (/cesta/mimo/drupal/projekty/moje-drupal-temata/moje-thema/).
Ujistěte se, že máte čistý pracovní adresář a nejnovější kód.
Vytvořte anotovaný tag (např. 1.0.0 pro první stabilní verzi):
```
git tag -a 1.0.0 -m "První stabilní verze tématu."
```
Použijte sémantické verzování (MAJOR.MINOR.PATCH).

Nahrajte tag na GitHub:

git push origin 1.0.0 # Nahrání konkrétního tagu
# nebo pro nahrání všech nových tagů:
# git push origin --tags

Po nahrání tagu Packagist (díky webhooku nebo manuální aktualizaci) rozpozná verzi 1.0.0 vašeho balíčku.

Lokální vývoj tématu v rámci Drupal projektu (pomocí Path Repository)

Při vývoji tématu přímo v kontextu vaší lokální Drupal instalace použijete Composer "path" repozitář. Toto vám umožní pracovat na souborech tématu na hostiteli a vidět změny okamžitě v běžícím Drupalu, zatímco Composer ví, že tento adresář představuje balíček.

Ujistěte se, že adresář tématu v Drupalu je čistý (bez vnořeného .git a ideálně prázdný nebo obsahuje jen symlink vytvořený Composerem z předchozích pokusů). Pokud jste ho přesunuli v Kroku 1, teď už by tam neměl být.
Upravte hlavní soubor composer.json vaší Drupal instalace (ten v kořenovém adresáři projektu).

Přidejte path repozitář: v sekci repositories přidejte odkaz na lokální cestu k adresáři vašeho samostatného tématu.

Pokud NEPOUŽÍVÁTE Docker (nebo je adresář tématu v hostitelském souborovém systému přístupný přímo):

{
    "repositories": [
        {
            "type": "composer",
            "url": "https://packages.drupal.org/8"
        },
        {
            "type": "path",
            "url": "/cesta/mimo/drupal/projekty/moje-drupal-temata/moje-thema/"
        }
        // ...
    ],
    "require": {
        // ...
        "jmeno-repozitare/moje-thema": "@dev" // Vyžadujeme vývojovou verzi z path repozitáře
    },
    "minimum-stability": "dev", // Povolte instalaci dev verzí
    "prefer-stable": true,
    "extra": {
        "installer-paths": {
            // ... ujistěte se, že cesta pro drupal-custom-theme míří do web/themes/custom
            "web/themes/custom/{$name}": ["type:drupal-custom-theme"],
            "web/themes/contrib/{$name}": ["type:drupal-theme"] // Ponechte pro contrib témata
        }
    }
}

Pokud POUŽÍVÁTE Docker:

Musíte adresář tématu z hostitele namapovat do kontejneru pomocí Docker Volume. Pak v composer.json použijete cestu uvnitř kontejneru.

Upravte docker-compose.yml (nebo docker run parametry) vašeho Drupal kontejneru a přidejte volume:

services:
  drupal_web: # Název vaší služby pro Drupal/webserver
    # ...
    volumes:
      - /cesta/mimo/drupal/projekty/moje-drupal-temata/moje-thema/:/app/themes/moje-thema # HOST_PATH:CONTAINER_PATH
      # ...

Nahraďte /cesta/mimo/drupal/projekty/moje-drupal-temata/moje-thema/ absolutní cestou na hostiteli.

V hlavním composer.json vaší Drupal instalace (který je namapován do kontejneru) nastavte path repozitář s cestou uvnitř kontejneru:

{
    "repositories": [
        {
            "type": "composer",
            "url": "https://packages.drupal.org/8"
        },
        {
            "type": "path",
            "url": "./web/themes/custom/moje-thema" // <--- Cesta uvnitř kontejneru
        }
        // ...
    ],
    "require": {
        // ...
        "jmeno-repozitare/moje-thema": "@dev"
    },
    "minimum-stability": "dev",
    "prefer-stable": true,
     "extra": {
        "installer-paths": {
            // ... ujistěte se, že cesta pro drupal-custom-theme míří do web/themes/custom
            "web/themes/custom/{$name}": ["type:drupal-custom-theme"],
            "web/themes/contrib/{$name}": ["type:drupal-theme"] // Ponechte pro contrib témata
        }
    }
}

Nainstalujte téma pomocí Composeru:
V kořenovém adresáři Drupal instalace spusťte Composer příkaz (pokud používáte Docker, spusťte ho uvnitř kontejneru přes docker exec nebo docker compose exec):
```
composer require jmeno-repozitare/moje-thema --prefer-source
# Pokud používáte Docker:
# docker compose exec vase_sluzba_drupalu composer require jmeno-repozitare/moje-thema --prefer-source
```
Parametr --prefer-source (nebo pokud Composer rozpozná path repozitář) zajistí, že Composer vytvoří symbolický odkaz z vendor adresáře nebo přímo do web/themes/custom/moje-thema na váš lokální adresář tématu. Díky typu "drupal-custom-theme" a výchozímu nastavení installer-paths se téma nainstaluje do adresáře web/themes/custom/moje-thema/. To vám umožní editovat soubory tématu v jeho samostatném adresáři a změny se okamžitě projeví v běžícím Drupalu.

Instalace tématu v jiném projektu (u klienta, na produkci)

Jakmile je vaše téma na Packagistu a má vydané tagy, jiní vývojáři nebo vaše další projekty ho mohou instalovat jednoduše pomocí Composeru.

V cílovém Drupal projektu (který je také spravován Composerem) spusťte v kořenovém adresáři:
```
composer require jmeno-repozitare/moje-thema:^1.0
# Nahraďte ^1.0 požadovanou verzí nebo omezením (např. ^1.1, 2.0.0)
```
Composer stáhne balíček z Packagistu (pomocí Git tagu) a díky typu "drupal-custom-theme" a standardním installer-paths v cílovém projektu ho nainstaluje do web/themes/custom/moje-thema/.

Odstraňování problémů (Shrnutí)

Chyba vnořených Git repozitářů (PHPStorm hláška): smažte adresář .git z podadresáře tématu uvnitř hlavní Drupal instalace (rm -rf web/themes/custom/moje-thema/.git). Téma musí mít svůj samostatný repozitář jinde.
Chyba vlastnictví Gitu v Dockeru (dubious ownership): uživatel Gitu uvnitř kontejneru nemá stejné UID/GID jako vlastník souborů na hostiteli namapovaných přes volume. Opravte spuštěním uvnitř kontejneru: git config --global --add safe.directory /var/www/html (nebo cestu, kterou Git hlásí jako problematickou).
Chyba stability Composeru (Could not find a version... matching your minimum-stability): vyžadujete vývojovou verzi (@dev nebo branch) balíčku, ale minimum-stability v hlavním composer.json je nastaveno příliš striktně (např. na stable). Upravte minimum-stability v hlavním composer.json na "dev" a volitelně přidejte "prefer-stable": true.
Chybějící informace o licenci na Packagistu: přidejte řádek "license": "GPL-2.0-or-later" do souboru composer.json vašeho tématu, commitněte změnu a pushněte ji na GitHub. Pak aktualizujte balíček na Packagistu (manuálně nebo přes webhook).

Závěr

Provedením těchto kroků jste transformovali své vlastní Drupal téma z lokálního souboru do plnohodnotného Composer balíčku, který má svůj vlastní život v samostatném Git repozitáři, je verzován pomocí Git tagů a je dostupný pro snadnou instalaci v jakémkoli jiném Composer-based Drupal projektu přes Packagist.

Díky správnému nastavení "type": "drupal-custom-theme" bude vaše téma automaticky instalováno do adresáře web/themes/custom/, což je správné místo pro vlastní rozšíření. Tento proces nejen zjednodušuje správu kódu, ale také otevírá dveře pro sdílení a znovupoužitelnost vašeho tématu.

Composer

Git

Pro vkládání komentářů se musíte přihlásit

Pokud by jste chtěli nové webové stránky a nebo redesign současných, zavolejte mi na mobil: +420 608 23 33 34, nebo mi pošlete zprávu na email: jiri.wolf@jw.cz.

Můžete taky využít tento formulář