Composer: tippek a használathoz

Telepítés

A Composer egy futtatható .phar fájl, amelyet a következő módon tölthet le és telepíthet:

Windows

Használja a hivatalos telepítőt Composer-Setup.exe.

Linux, macOS

Csak 4 parancsra van szükség, amelyeket másoljon le erről az oldalról.

Továbbá, ha egy olyan mappába helyezi, amely a rendszer PATH-jában van, a Composer globálisan elérhetővé válik:

$ mv ./composer.phar ~/bin/composer # vagy /usr/local/bin/composer

Használat a projektben

Ahhoz, hogy a projektünkben elkezdhessük használni a Composert, csak egy composer.json fájlra van szükségünk. Ez leírja a projektünk függőségeit, és tartalmazhat további metaadatokat is. Egy alap composer.json tehát így nézhet ki:

{
	"require": {
		"nette/database": "^3.0"
	}
}

Itt azt mondjuk, hogy az alkalmazásunk (vagy könyvtárunk) megköveteli a nette/database csomagot (a csomag neve a szervezet nevéből és a projekt nevéből áll), és olyan verziót szeretne, amely megfelel a ^3.0 feltételnek (azaz a legújabb 3-as verziót).

Tehát a projekt gyökerében van egy composer.json fájlunk, és elindítjuk a telepítést:

composer update

A Composer letölti a Nette Database-t a vendor/ mappába. Továbbá létrehoz egy composer.lock fájlt, amely információkat tartalmaz arról, hogy pontosan melyik verziójú könyvtárakat telepítette.

A Composer generál egy vendor/autoload.php fájlt, amelyet egyszerűen includálhatunk, és elkezdhetjük használni a könyvtárakat bármilyen további munka nélkül:

require __DIR__ . '/vendor/autoload.php';

$db = new Nette\Database\Connection('sqlite::memory:');

Csomagok frissítése a legújabb verziókra

A használt könyvtárak frissítését a composer.json-ban definiált feltételek szerinti legújabb verziókra a composer update parancs végzi. Pl. a "nette/database": "^3.0" függőségnél a legújabb 3.x.x verziót telepíti, de a 4-es verziót már nem.

A composer.json fájlban lévő feltételek frissítéséhez, például "nette/database": "^4.1"-re, hogy telepíthető legyen a legújabb verzió, használja a composer require nette/database parancsot.

Az összes használt Nette csomag frissítéséhez mindet fel kellene sorolni a parancssorban, pl.:

composer require nette/application nette/forms latte/latte tracy/tracy ...

Ami nem praktikus. Használja ezért az egyszerű Composer Frontline szkriptet, amely ezt megteszi Ön helyett:

php composer-frontline.php

Új projekt létrehozása

Új Nette projektet egyetlen paranccsal hozhat létre:

composer create-project nette/web-project projekt-neve

A projekt-neve helyére illessze be a projekt könyvtárának nevét, és erősítse meg. A Composer letölti a nette/web-project repository-t a GitHubról, amely már tartalmazza a composer.json fájlt, és rögtön utána a Nette Frameworköt. Már csak a jogosultságokat kell beállítani a temp/ és log/ mappákra való íráshoz, és a projektnek életre kell kelnie.

Ha tudja, milyen PHP verzióval fog futni a projekt a hostingen, ne felejtse el beállítani.

PHP verzió

A Composer mindig azokat a csomagverziókat telepíti, amelyek kompatibilisek az Ön által éppen használt PHP verzióval (pontosabban a parancssorban a Composer futtatásakor használt PHP verzióval). Ami azonban valószínűleg nem ugyanaz a verzió, mint amit a hostingja használ. Ezért nagyon fontos, hogy a composer.json fájlba hozzáadja az információt a hostingen lévő PHP verzióról. Ezután csak a hostinggal kompatibilis csomagverziók kerülnek telepítésre.

Azt, hogy a projekt például PHP 8.2.3-on fog futni, a következő paranccsal állítjuk be:

composer config platform.php 8.2.3

Így a verzió beíródik a composer.json fájlba:

{
	"config": {
		"platform": {
			"php": "8.2.3"
		}
	}
}

Azonban a PHP verziószám a fájl egy másik helyén is szerepel, mégpedig a require szekcióban. Míg az első szám azt határozza meg, hogy melyik verzióhoz települjenek a csomagok, a második szám azt mondja meg, hogy melyik verzióhoz íródott maga az alkalmazás. És például a PhpStorm ez alapján állítja be a PHP language level-t. (Természetesen nincs értelme, hogy ezek a verziók eltérjenek, tehát a kettős beírás egy átgondolatlanság.) Ezt a verziót a következő paranccsal állíthatja be:

composer require php 8.2.3 --no-update

Vagy közvetlenül a composer.json fájlban:

{
	"require": {
		"php": "8.2.3"
	}
}

PHP verzió figyelmen kívül hagyása

A csomagok általában megadják mind a legalacsonyabb PHP verziót, amellyel kompatibilisek, mind a legmagasabbat, amellyel tesztelve vannak. Ha még újabb PHP verziót tervez használni, például tesztelés céljából, a Composer megtagadja az ilyen csomag telepítését. A megoldás az --ignore-platform-req=php+ opció, amely miatt a Composer figyelmen kívül hagyja a megkövetelt PHP verzió felső határait.

Hamis jelentések

Csomagok frissítésekor vagy verziószámok változásakor előfordul, hogy konfliktus lép fel. Egy csomag olyan követelményekkel rendelkezik, amelyek ellentmondanak egy másiknak, és így tovább. A Composer azonban néha hamis jelentést ad. Olyan konfliktust jelez, amely valójában nem létezik. Ilyen esetben segít a composer.lock fájl törlése és az újrapróbálkozás.

Ha a hibaüzenet továbbra is fennáll, akkor komolyan kell venni, és ki kell olvasni belőle, mit és hogyan kell módosítani.

Packagist.org – központi repository

A Packagist a fő repository, amelyben a Composer megpróbálja megkeresni a csomagokat, hacsak nem mondjuk neki másképp. Itt publikálhatunk saját csomagokat is.

Mi van, ha nem akarjuk használni a központi repository-t?

Ha belső vállalati alkalmazásaink vannak, amelyeket egyszerűen nem hostolhatunk nyilvánosan, akkor létrehozunk hozzájuk egy vállalati repository-t.

Több információ a repository-król a hivatalos dokumentációban.

Autoloading

A Composer alapvető tulajdonsága, hogy autoloadingot biztosít az összes általa telepített osztályhoz, amelyet a vendor/autoload.php fájl includálásával indíthat el.

Azonban a Composert lehet használni további osztályok betöltésére is a vendor mappán kívül. Az első lehetőség az, hogy hagyjuk a Composert átkutatni a definiált mappákat és almappákat, megtalálni az összes osztályt, és bevenni őket az autoloaderbe. Ezt a composer.json autoload > classmap beállításával érhetjük el:

{
	"autoload": {
		"classmap": [
			"src/",      # beleveszi a src/ mappát és annak almappáit
		]
	}
}

Ezután minden változáskor futtatni kell a composer dumpautoload parancsot, és hagyni kell az autoloading táblák újragenerálását. Ez rendkívül kényelmetlen, és sokkal jobb ezt a feladatot a RobotLoaderra bízni, amely ugyanazt a tevékenységet automatikusan a háttérben és sokkal gyorsabban végzi.

A második lehetőség a PSR-4 betartása. Egyszerűsítve ez egy olyan rendszer, ahol a névterek és osztálynevek megfelelnek a könyvtárstruktúrának és a fájlneveknek, tehát pl. az App\Core\RouterFactory az /path/to/App/Core/RouterFactory.php fájlban lesz. Példa konfiguráció:

{
	"autoload": {
		"psr-4": {
			"App\\": "app/"   # az App\ névtér az app/ könyvtárban van
		}
	}
}

Hogyan konfigurálja pontosan a viselkedést, megtudhatja a Composer dokumentációjában.

Új verziók tesztelése

Szeretné tesztelni egy csomag új fejlesztői verzióját. Hogyan tegye? Először adja hozzá ezt a két opciót a composer.json fájlhoz, amely lehetővé teszi a fejlesztői verziójú csomagok telepítését, de csak akkor folyamodik ehhez, ha nincs olyan stabil verziókombináció, amely megfelelne a követelményeknek:

{
	"minimum-stability": "dev",
	"prefer-stable": true,
}

Továbbá javasoljuk a composer.lock fájl törlését, néha ugyanis a Composer érthetetlen módon megtagadja a telepítést, és ez megoldja a problémát.

Tegyük fel, hogy a nette/utils csomagról van szó, és az új verzió száma 4.0. Telepítse a következő paranccsal:

composer require nette/utils:4.0.x-dev

Vagy telepíthet konkrét verziót is, például 4.0.0-RC2:

composer require nette/utils:4.0.0-RC2

Ha azonban a könyvtártól egy másik csomag függ, amely egy régebbi verzióra van zárolva (pl. ^3.1), akkor ideális a csomagot frissíteni, hogy az új verzióval működjön. Ha azonban csak meg akarja kerülni a korlátozást, és rávenni a Composert, hogy telepítse a fejlesztői verziót, és úgy tegyen, mintha egy régebbi verzió lenne (pl. 3.1.6), használhatja az as kulcsszót:

composer require nette/utils "4.0.x-dev as 3.1.6"

Parancsok hívása

A Composer segítségével saját előre elkészített parancsokat és szkripteket hívhat meg, mintha natív Composer parancsok lennének. A vendor/bin mappában található szkriptek esetében nem kell ezt a mappát megadni.

Példaként definiálunk a composer.json fájlban egy szkriptet, amely a Nette Testerrel futtatja a teszteket:

{
	"scripts": {
		"tester": "tester tests -s"
	}
}

A teszteket ezután a composer tester segítségével futtatjuk. A parancsot akkor is meghívhatjuk, ha nem a projekt gyökérkönyvtárában vagyunk, hanem valamelyik alkönyvtárban.

Küldjön köszönetet

Mutatunk egy trükköt, amellyel örömet szerezhet az open source szerzőknek. Egyszerű módon adhat csillagot a GitHubon azoknak a könyvtáraknak, amelyeket a projektje használ. Csak telepíteni kell a symfony/thanks könyvtárat:

composer global require symfony/thanks

Majd futtatni:

composer thanks

Próbálja ki!

Konfiguráció

A Composer szorosan kapcsolódik a Git verziókezelő eszközhöz. Ha nincs telepítve, szólni kell a Composernek, hogy ne használja:

composer -g config preferred-install dist