Composer használati tippek
**************************

<div class=perex>

A Composer egy függőségkezelő eszköz PHP-ban. Lehetővé teszi, hogy bejelentse, hogy a projektje mely könyvtáraktól függ, és a program telepíti és frissíti azokat Ön helyett. Megtanuljuk:

- hogyan kell telepíteni a Composert
- hogyan használjuk új vagy meglévő projektben

</div>


Telepítés .[#toc-installation]
==============================

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


Windows .[#toc-windows]
-----------------------

Használja a [Composer-Setup.exe |https://getcomposer.org/Composer-Setup.exe] hivatalos telepítő programot.


Linux, macOS .[#toc-linux-macos]
--------------------------------

Mindössze 4 parancsra van szükséged, amelyeket [erről az oldalról |https://getcomposer.org/download/] másolhatsz le.

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

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


Használat a projektben .[#toc-use-in-project]
=============================================

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:

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

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

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

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


Csomagok frissítése a legújabb verziókra .[#toc-update-packages-to-the-latest-versions]
=======================================================================================

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:

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

Ami nem praktikus. Ezért használjon egy egyszerű "Composer Frontline":https://gist.github.com/dg/734bebf55cf28ad6a5de1156d3099bff szkriptet, amely megteszi ezt Ön helyett:

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


Új projekt létrehozása .[#toc-creating-new-project]
===================================================

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

```shell
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 |nette:troubleshooting#setting-directory-permissions] 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 Version].


PHP verzió .[#toc-php-version]
==============================

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:

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

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

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

```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 .[#toc-ignoring-php-version]
===============================================================

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 .[#toc-false-reports]
======================================

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 .[#toc-packagist-org-global-repository]
===========================================================================

[Packagist |https://packagist.org] 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 .[#toc-what-if-we-don-t-want-the-central-repository]
----------------------------------------------------------------------------------------------------

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


Automatikus betöltés .[#toc-autoloading]
========================================

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

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

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

Lásd a [Composer dokumentációban |https://getcomposer.org/doc/04-schema.md#psr-4], hogy pontosan hogyan kell konfigurálni ezt a viselkedést.


Új verziók tesztelése .[#toc-testing-new-versions]
==================================================

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:

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

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

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

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

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


Parancsok hívása .[#toc-calling-commands]
=========================================

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 |tester:] használja a tesztek futtatására:

```js
{
	"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 .[#toc-send-thanks]
====================================

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:

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

Majd futtasd le:

```shell
composer thanks
```

Próbáld ki!


Konfiguráció .[#toc-configuration]
==================================

A Composer szorosan integrálódik a [Git |https://git-scm.com] verziókezelő eszközzel. Ha nem használja a Git-et, akkor ezt meg kell mondani a Composernek:

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

{{sitename: Legjobb gyakorlatok}}