Composer: tippek a használathoz
*******************************

<div class=perex>

A Composer egy eszköz a PHP függőségek kezelésére. Lehetővé teszi számunkra, hogy felsoroljuk azokat a könyvtárakat, amelyektől a projektünk függ, és telepíti és frissíti őket helyettünk. Megmutatjuk:

- hogyan telepítsük a Composert
- használatát új vagy meglévő projektben

</div>


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 |https://getcomposer.org/Composer-Setup.exe].


Linux, macOS
------------

Csak 4 parancsra van szükség, amelyeket másoljon le [erről az oldalról |https://getcomposer.org/download/].

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

```shell
$ 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:

```js
{
	"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:

```shell
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:

```php
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.:

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

Ami nem praktikus. Használja ezért az egyszerű "Composer Frontline":https://gist.github.com/dg/734bebf55cf28ad6a5de1156d3099bff szkriptet, amely ezt megteszi Ön helyett:

```shell
php composer-frontline.php
```


Új projekt létrehozása
======================

Új Nette projektet egyetlen paranccsal hozhat létre:

```shell
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 |nette:troubleshooting#Könyvtárjogosultságok beállítása] 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ó].


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:

```shell
composer config platform.php 8.2.3
```

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

```js
{
	"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:

```shell
composer require php 8.2.3 --no-update
```

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

```js
{
	"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 |https://packagist.org] 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 |https://getcomposer.org/doc/05-repositories.md#repositories].


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:

```js
{
	"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|robot-loader:] 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|https://www.php-fig.org/psr/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ó:

```js
{
	"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|https://getcomposer.org/doc/04-schema.md#psr-4].


Ú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:

```js
{
	"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:

```shell
composer require nette/utils:4.0.x-dev
```

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

```shell
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:

```shell
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|tester:] futtatja a teszteket:

```js
{
	"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:

```shell
composer global require symfony/thanks
```

Majd futtatni:

```shell
composer thanks
```

Próbálja ki!


Konfiguráció
============

A Composer szorosan kapcsolódik a [Git |https://git-scm.com] verziókezelő eszközhöz. Ha nincs telepítve, szólni kell a Composernek, hogy ne használja:

```shell
composer -g config preferred-install dist
```

{{sitename: Best Practices}}