Composer – Lisäosien ja teemojen hallinta

Composer on PHP-maailman standardoitu riippuvuuksien hallintatyökalu. Sen avulla projektin käyttämät kirjastot, WordPressin ydin, lisäosat ja teemat voidaan määritellä yhdessä composer.json-tiedostossa.

Composerin käyttö tekee julkaisuprosesseista (CI/CD) toistettavia ja pitää Git-versionhallinnan puhtaana, sillä kolmansien osapuolten lähdekoodia (kuten wp.org:n lisäosia) ei tarvitse tallentaa suoraan omaan repositorioon.

Seravon oletusprojektipohja hyödyntää Composeria automaattisesti, ja suosittelemme sen käyttöä kaikille ammattimaisesti ylläpidetyille sivustoille.

Kuinka Composer toimii WordPressin kanssa?

WordPress-ympäristössä Composer määritellään projektin juurihakemistossa olevassa composer.json-tiedostossa. Määritys koostuu tyypillisesti kolmesta tärkeästä osiosta: repositories, require ja extra.

1. Repositoriot (Pakettien lähteet)

Jotta Composer löytää WordPressin viralliset lisäosat ja teemat, sille on määriteltävä lähteeksi WPackagist. Se on palvelu, joka peilaa koko WordPress.org-hakemiston Composer-yhteensopivaksi.

"repositories": [
  {
    "type": "composer",
    "url": "https://wpackagist.org",
    "only": [
      "wpackagist-plugin/*",
      "wpackagist-theme/*"
    ]
  }
]

Tähän osioon voit myöhemmin lisätä myös omia yksityisiä Git-repositorioita.

2. Vaaditut paketit (`require`)

Tässä osiossa luetellaan kaikki sivuston vaatimat paketit ja niiden versiot. Esimerkissä asennetaan WordPressin ydin, pakollinen Seravo-lisäosa sekä yksi wpackagist-lisäosa ja -teema:

"require": {
  "php": ">=8.0",
  "johnpbloch/wordpress-core": "^6.4",
  "seravo/seravo-plugin": "*",
  "wpackagist-plugin/two-factor": "^0.8",
  "wpackagist-theme/twentytwentyfour": "*"
}

Versiomerkintä ^6.4 tarkoittaa, että Composer sallii aliversioiden päivitykset (esim. 6.4.1), mutta ei automaattisesti siirry seuraavaan pääversioon (7.0).
Tähti * asentaa aina uusimman saatavilla olevan version.

3. Asennuspolut (`extra.installer-paths`)

Oletuksena Composer asentaisi kaikki paketit projektin juuren vendor/-hakemistoon. Koska WordPress odottaa löytävänsä lisäosat ja teemat tietyistä kansioista, polut täytyy ohjata oikein:

"extra": {
  "installer-paths": {
    "htdocs/wp-content/plugins/{$name}/": ["type:wordpress-plugin"],
    "htdocs/wp-content/mu-plugins/{$name}/": ["type:wordpress-muplugin"],
    "htdocs/wp-content/themes/{$name}/": ["type:wordpress-theme"]
  },
  "wordpress-install-dir": "htdocs/wordpress"
}

Tämä osio kertoo composer/installers-liitännäiselle, että jokainen paketti, jonka tyyppi on wordpress-plugin, asennetaan automaattisesti kansioon /htdocs/wp-content/plugins/.

Omien Git-repositorioiden (teemat ja lisäosat) liittäminen

Paras tapa hallinnoida omia räätälöityjä lisäosia ja teemoja on pitää ne omissa erillisissä Git-repositorioissaan (esim. GitHubissa tai Bitbucketissa) ja ladata ne Composerilla pääprojektiin.

1. Luo teeman tai lisäosan juureen oma `composer.json`:

{
  "name": "yritys/oma-teema",
  "type": "wordpress-theme",
  "license": "GPL-3.0-or-later",
  "description": "Räätälöity teema asiakkaalle"
}

2. Lisää Git-lähde pääprojektin `composer.json`-tiedostoon:

Lisää olemassa olevaan repositories-taulukkoon uusi tietue:

"repositories": [
  {
    "type": "vcs",
    "url": "[email protected]:yritys/oma-teema.git"
  }
]

3. Vaadi paketti:

"require": {
  "yritys/oma-teema": "dev-main"
}

Huom: dev-main tai dev-master hakee aina kyseisen haaran uusimman version. Voit myös käyttää aitoja versiotageja, jos julkaiset teemaasi tageilla (esim. 1.0.0).

Maksulliset ja yksityiset WordPress-lisäosat

WPackagist tarjoaa vain WordPress.orgin ilmaiset lisäosat. Kaupallisten Pro-lisäosien (kuten ACF Pro tai Gravity Forms) hallintaan Composerilla on kaksi yleistä ratkaisua:

Säilytä koodi projektin repositoriossa:
Helpoin tapa on asentaa lisäosa manuaalisesti ja ohittaa Composer. Lataa ZIP-tiedosto, pura se hakemistoon wp-content/plugins/kaupallinen-lisäosa/ ja lisää kyseinen kansio Gitin seurantaan tekemällä poikkeus .gitignore-tiedostoon:
```
!htdocs/wp-content/plugins/kaupallinen-lisäosa/
```
Käytä kolmannen osapuolen pakettivarastoja (Premium Repositories):
Monet kehittäjät käyttävät palveluita kuten Private Packagist, Satis tai kaupallisten lisäosien omia Composer-rajapintoja (esim. ACF Pro tarjoaa nykyään virallisen composer.json-yhteensopivan osoitteen tilaajilleen). Tällöin autentikointiavaimet sijoitetaan tyypillisesti auth.json-tiedostoon tai ympäristömuuttujiin (.env).

Komentojen ajaminen

Voit päivittää ja asentaa riippuvuudet paikallisessa ympäristössäsi tai SSH-yhteydellä palvelimella (projektin juurihakemistossa /data/wordpress/):

composer install – Asentaa paketit täsmälleen siinä versiossa, joka on lukittu composer.lock-tiedostoon. (Tätä komentoa CI/CD-järjestelmät ja julkaisuputket käyttävät).
composer update – Tarkistaa paketeista uudet sallitut versiot, asentaa ne ja päivittää composer.lock-tiedoston.
composer require wpackagist-plugin/nimi – Etsii lisäosan, lisää sen composer.json-tiedostoon ja asentaa sen välittömästi.

Yleisimmät virhetilanteet

PHP:n muisti loppuu kesken (Allowed memory size exhausted): Laajojen riippuvuuksien ratkaiseminen voi ylittää oletusmuistirajan. Ohita rajoitus yksittäisen ajon ajaksi komennolla COMPOSER_MEMORY_LIMIT=-1 composer update.
Yksityisen Git-repositorion lataus epäonnistuu (Permission denied): Ota SSH-yhteys palvelimelle agentin välityksellä (ssh -A käyttäjä@palvelin), jolloin Composer hyödyntää työasemasi SSH-avaimia. Vaihtoehtoisesti voit tallentaa rajapinta-avaimet projektin juuren auth.json-tiedostoon (varmista, että tiedosto on estetty .gitignore-listalla).
Paketti asentuu vendor/-kansioon wp-content/-hakemiston sijaan: Tarkista, että paketin omassa composer.json-tiedostossa on määritelty oikea tyyppi ("type": "wordpress-plugin", "wordpress-theme" tai "wordpress-muplugin").
Lukitustiedoston ristiriidat (composer.lock is not up to date): Jos composer.json-tiedostoa on muokattu käsin, päivitä lukitustiedoston tarkistussumma ajamalla composer update --lock.

Katso myös

Jos tarvitset apua yksityisten Git-repositorioiden SSH-avainten määrittelyssä Seravon palvelimelle tai Composer-asennusputkien virheenkorjauksessa, ota yhteyttä asiantuntijoihimme osoitteessa [email protected].

Aiheeseen liittyvät artikkelit