Composer használati tippek

Telepítés

A Composer egy futtatható .phar fájl, amelyet az alábbiak szerint tölthet le és telepíthet.

Windows

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

Linux, macOS

Mindössze 4 parancsra van szükséged, amelyeket erről az oldalról másolhatsz le.

Továbbá, a rendszerben található PATH mappába másolva a Composer globálisan elérhetővé válik:

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

Használat a projektben

A Composer projektben való használatának megkezdéséhez mindössze egy composer.json fájlra van szüksége. Ez a fájl leírja a projekt függőségeit, és egyéb metaadatokat is tartalmazhat. A legegyszerűbb composer.json így nézhet ki:

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

Itt azt mondjuk, hogy az alkalmazásunk (vagy könyvtárunk) függ a nette/database csomagtól (a csomag neve egy gyártó nevéből és a projekt nevéből áll), és azt a verziót szeretné, amelyik megfelel a ^3.0 verziókövetelménynek.

Tehát, amikor a composer.json fájl a projekt gyökerében van, és futtatjuk a:

composer update

Composer letölti a Nette adatbázist a vendor könyvtárba. Létrehoz egy composer.lock fájlt is, amely információt tartalmaz arról, hogy pontosan milyen könyvtárverziókat telepített.

A Composer létrehoz egy vendor/autoload.php fájlt. Ezt a fájlt egyszerűen beillesztheti, és minden további munka nélkül elkezdheti használni azokat az osztályokat, amelyeket ezek a könyvtárak biztosítanak:

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

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

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

Az összes használt csomag frissítéséhez a composer.json pontban meghatározott verziókövetelményeknek megfelelően a composer update paranccsal frissítheti az összes használt csomagot a legújabb verzióra. Például a "nette/database": "^3.0" függőség esetében a parancs a legújabb, 3.x.x.x verziót fogja telepíteni, de a 4-es verziót nem.

A composer.json fájlban lévő verziókövetelmények frissítéséhez pl. "nette/database": "^4.1", a legújabb verzió telepítésének lehetővé tételéhez használja a composer require nette/database parancsot.

Az összes használt Nette csomag frissítéséhez az összeset fel kell sorolni a parancssorban, pl:

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

Ami nem praktikus. Ezért használjon egy egyszerű Composer Frontline szkriptet, amely megteszi ezt Ön helyett:

php composer-frontline.php

Új projekt létrehozása

Új Nette projekt egy egyszerű parancs végrehajtásával hozható létre:

composer create-project nette/web-project name-of-the-project

A name-of-the-project helyett meg kell adnia a projekt könyvtárának nevét, és végre kell hajtania a parancsot. A Composer le fogja hívni a nette/web-project tárolót a GitHubról, amely már tartalmazza a composer.json fájlt, és rögtön ezután telepíti magát a Nette keretrendszert. Már csak a temp/ és a log/ könyvtárak írási jogosultságainak ellenőrzése van hátra, és már mehet is.

Ha tudod, hogy a PHP melyik verzióján lesz a projekt, mindenképpen állítsd be.

PHP verzió

A Composer mindig a csomagok azon verzióit telepíti, amelyek kompatibilisek a PHP aktuálisan használt verziójával (vagy inkább a PHP-nak a parancssorban a Composer futtatásakor használt verziójával). Ami valószínűleg nem ugyanaz a verzió, mint amit a webtárhelye használ. Ezért nagyon fontos, hogy a composer.json fájlodhoz hozzáadj információt a tárhelyeden használt PHP verziójáról. Ezután csak a tárhelyével kompatibilis csomagok verziói fognak települni.

Például, ha a projektet a PHP 8.2.3-as verzióján szeretné futtatni, használja a következő parancsot:

composer config platform.php 8.2.3

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

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

A PHP verziószáma azonban a fájlban máshol is szerepel, a require szakaszban. Míg az első szám azt a verziót adja meg, amelyhez a csomagokat telepíteni kell, addig a második szám azt mondja meg, hogy maga az alkalmazás milyen verzióra íródott. (Természetesen nincs értelme, hogy ezek a verziók különbözőek legyenek, így a dupla bejegyzés csak redundancia.) Ezt a verziót a paranccsal állítjuk 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 a PHP legalacsonyabb verzióját, amellyel kompatibilisek, és a legmagasabb verzióját, amellyel tesztelték őket. Ha a PHP egy még újabb verzióját tervezi használni, esetleg tesztelési céllal, a Composer elutasítja az ilyen csomag telepítését. A megoldás a --ignore-platform-req=php+ opció használata, amelynek hatására a Composer figyelmen kívül hagyja a szükséges PHP-verzió felső határértékeit.

Hamis jelentések

A csomagok frissítésekor vagy a verziószámok megváltoztatásakor konfliktusok fordulnak elő. Az egyik csomagnak vannak olyan követelményei, amelyek ütköznek egy másikkal, és így tovább. A Composer azonban időnként hamis üzeneteket ír ki. Olyan konfliktust jelent, amely valójában nem létezik. Ebben az esetben segít, ha törli a composer.lock fájlt, és újra megpróbálja.

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

Packagist.org – Globális tárolóhely

Packagist a fő csomagtároló, amelyben a Composer megpróbál csomagokat keresni, ha másképp nem szólnak neki. Saját csomagjaidat is közzéteheted itt.

Mi van akkor, ha nem akarjuk a központi tárolót

Ha vannak olyan belső alkalmazásaink vagy könyvtáraink a vállalatunkban, amelyeket nem lehet nyilvánosan a Packagist-en hosztolni, akkor létrehozhatunk saját tárolókat az adott projekthez.

A tárolókról bővebben a hivatalos dokumentációban.

Automatikus betöltés

A Composer egyik legfontosabb jellemzője, hogy automatikus betöltést biztosít minden általa telepített osztály számára, amit a vendor/autoload.php fájl beillesztésével indíthat el.

Lehetőség van azonban arra is, hogy a Composer segítségével a vendor mappán kívül más osztályokat is betöltsön. Az első lehetőség, hogy a Composer átvizsgálja a meghatározott mappákat és almappákat, megkeresi az összes osztályt, és felveszi őket az automatikus betöltőbe. Ehhez állítsa be a autoload > classmap címet a composer.json:

{
	"autoload": {
		"classmap": [
			"src/",      #  includes the src/ folder and its subfolders
		]
	}
}

Ezt követően minden egyes változtatásnál el kell indítani a composer dumpautoload parancsot, és hagyni kell, hogy az autoloading táblák újratermelődjenek. Ez rendkívül kényelmetlen, és sokkal jobb, ha ezt a feladatot a RobotLoaderre bízzuk, amely a háttérben automatikusan és sokkal gyorsabban végzi el ugyanezt a tevékenységet.

A második lehetőség a PSR-4 követése. Egyszerűen fogalmazva, ez egy olyan rendszer, ahol a névterek és az osztálynevek megfelelnek a könyvtárszerkezetnek és a fájlneveknek, azaz a App\Core\RouterFactory a /path/to/App/Core/RouterFactory.php fájlban található. Konfigurációs példa:

{
	"autoload": {
		"psr-4": {
			"App\\": "app/"   # the App\ namespace is in the app/ directory
		}
	}
}

Lásd a Composer dokumentációban, hogy pontosan hogyan kell konfigurálni ezt a viselkedést.

Új verziók tesztelése

Egy csomag új fejlesztői verzióját szeretné tesztelni. Hogyan kell ezt megtenni? Először is, add hozzá ezt az opciós párost a composer.json fájlhoz, amely lehetővé teszi a csomagok fejlesztői verzióinak telepítését, de csak akkor, ha nincs olyan stabil verzió-kombináció, amely megfelel a követelményeknek:

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

Javasoljuk a composer.lock fájl törlését is, mert néha a Composer érthetetlen módon megtagadja a telepítést, és ez megoldja a problémát.

Tegyük fel, hogy a csomag a nette/utils és az új verzió a 4.0. Telepítjük a következő paranccsal:

composer require nette/utils:4.0.x-dev

Vagy telepíthetsz egy adott verziót, például a 4.0.0-RC2-t:

composer require nette/utils:4.0.0-RC2

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

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

Parancsok hívása

Saját egyéni parancsait és szkriptjeit a Composeren keresztül úgy hívhatja meg, mintha azok natív Composer-parancsok lennének. A vendor/bin mappában található szkripteknek nem kell megadniuk ezt a mappát.

Példaként egy olyan szkriptet definiálunk a composer.json fájlban, amely a Nette Tester-t használja a tesztek futtatására:

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

Ezután a teszteket a composer tester segítségével futtatjuk. A parancsot akkor is meg tudjuk hívni, ha nem a projekt gyökérmappájában vagyunk, hanem egy alkönyvtárban.

Köszönet küldése

Mutatunk egy trükköt, aminek a nyílt forráskódú szerzők örülni fognak. A GitHubon könnyen adhatsz csillagot azoknak a könyvtáraknak, amelyeket a projekted használ. Csak telepítsd a symfony/thanks könyvtárat:

composer global require symfony/thanks

Majd futtasd le:

composer thanks

Próbáld ki!

Konfiguráció

A Composer szorosan integrálódik a Git verziókezelő eszközzel. Ha nem használja a Git-et, akkor ezt meg kell mondani a Composernek:

composer -g config preferred-install dist