composer.texy

Съвети за използване на Composer
********************************
<div class=perex>


Composer е инструмент за управление на зависимостите в PHP. Тя ви позволява да декларирате библиотеките, от които зависи проектът ви, и ще ги инсталира и актуализира вместо вас. Научаваме:

- как да инсталирате Composer
- да го използвате в нов или съществуващ проект

</div>


Инсталиране на .[#toc-installation]
===================================

Composer е изпълним файл `.phar`, който можете да изтеглите и инсталирате, както следва


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

Използвайте официалния инсталатор [Composer-Setup.exe |https://getcomposer.org/Composer-Setup.exe].


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

Необходими са ви само 4 команди, които можете да копирате от [тази страница |https://getcomposer.org/download/].

Освен това, когато се копира в папка, разположена в системата `PATH`, Composer става глобално достъпен:

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


Използване в съществуващ проект .[#toc-use-in-project]
======================================================

За да започнете да използвате Composer в проекта си, се нуждаете само от файла `composer.json`. Този файл описва зависимостите на вашия проект и може да съдържа други метаданни. Най-простият `composer.json` може да изглежда по следния начин:

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

Тук казваме, че нашето приложение (или библиотека) зависи от пакета `nette/database` (името на пакета се състои от името на доставчика и името на проекта) и се нуждае от версия, която отговаря на ограничението `^3.0`.

Така че, когато имаме файла `composer.json` в корена на проекта и стартираме

```shell
composer update
```

Composer ще зареди изходните файлове на Nette в директорията `vendor`. Създава се и файл `composer.lock`, който съдържа информация за това кои версии на библиотеките са инсталирани.

Composer генерира файла `vendor/autoload.php`. Можете просто да включите този файл и да започнете да използвате класовете, които тези библиотеки предоставят, без да е необходима допълнителна работа:

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

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


Актуализиране на пакетите до най-новите версии .[#toc-update-packages-to-the-latest-versions]
=============================================================================================

За да обновите всички използвани пакети до най-новата версия в съответствие с ограниченията на версиите, определени в `composer.json`, използвайте командата `composer update`. Например зависимостта `"nette/database": "^3.0"` ще инсталира най-новата версия 3.x.x, но не и версия 4.

За да актуализирате ограниченията на версията във файла `composer.json` например до "nette/database": "^4.1"`, для установки последней версии, используйте команду `composer require nette/database`.

За да актуализирате всички използвани пакети Nette, трябва да ги изпишете в командния ред, напр:

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

Това не е практично. Затова използвайте прост скрипт "Composer Frontline":https://gist.github.com/dg/734bebf55cf28ad6a5de1156d3099bff, който ще направи това вместо вас:

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


Създаване на нов проект .[#toc-creating-new-project]
====================================================

Нов проект на Nette може да бъде създаден чрез изпълнение на проста команда:

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

Вместо `name-of-the-project` посочете името на директорията на проекта и изпълнете командата. Composer ще изтегли хранилището `nette/web-project` от GitHub, което вече съдържа файла `composer.json`, и веднага след това ще инсталира самата рамка Nette. Остава само да [проверите разрешенията за запис на |nette:troubleshooting#Setting-Directory-Permissions] директориите `temp/` и `log/`, и сте готови да започнете работа.

Ако знаете на каква версия на PHP ще бъде хостван проектът, не забравяйте да [я настро |#PHP Version]ите.


Версия на PHP .[#toc-php-version]
=================================

Composer винаги инсталира версиите на пакетите, които са съвместими с версията на PHP, която използвате в момента (или по-скоро с версията на PHP, използвана в командния ред при стартиране на Composer). Вероятно това не е същата версия, която използва вашият уеб хост. Ето защо е много важно да добавите информация за версията на PHP на вашия хостинг във файла `composer.json`. След това ще бъдат инсталирани само версии на пакети, съвместими с хоста.

Например, за да настроите проекта да работи с PHP 8.2.3, използвайте командата:

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

По този начин версията се записва във файла `composer.json`:

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

Номерът на версията на PHP обаче е посочен и на друго място във файла, в раздела `require`. Докато първият номер определя версията, за която ще бъдат инсталирани пакетите, вторият номер казва за каква версия е написано самото приложение.
(Разбира се, няма смисъл тези версии да се различават, така че двойното вписване е излишно.) Тази версия се задава с командата:

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

Или директно във файла `composer.json`:

```js
{
	"require": {
		"php": "8.2.3"
	}
}
```


Фалшиви доклади .[#toc-false-reports]
=====================================

При надграждане на пакети или промяна на номера на версиите се случват конфликти. Един пакет има изисквания, които са в конфликт с друг и т.н. Понякога обаче Composer отпечатва фалшиви съобщения. Той съобщава за конфликт, който в действителност не съществува. В този случай помага да изтриете файла `composer.lock` и да опитате отново.

Ако съобщението за грешка продължава, то е мислено сериозно и трябва да прочетете от него какво и как да промените.


Packagist.org - глобално хранилище .[#toc-packagist-org-global-repository]
==========================================================================

[Packagist |https://packagist.org] е основното хранилище на пакети, в което Composer се опитва да търси пакети, освен ако не е посочено друго. Тук можете да публикувате и свои собствени пакети.


Какво да правим, ако нямаме нужда от централно хранилище .[#toc-what-if-we-don-t-want-the-central-repository]
-------------------------------------------------------------------------------------------------------------

Ако компанията ни има вътрешни приложения или библиотеки, които не могат да бъдат публично хоствани в Packagist, можем да създадем собствени хранилища за тези проекти.

Прочетете повече за хранилищата в [официалната документация |https://getcomposer.org/doc/05-repositories.md#Репозитории].


Автоматично зареждане .[#toc-autoloading]
=========================================

Ключова характеристика на Composer е, че той предоставя автозареждаща програма за всички инсталируеми класове, която стартирате, като включите файла `vendor/autoload.php`.

Възможно е обаче да използвате Composer и за зареждане на други класове извън папката `vendor`. Първият вариант е да позволите на Composer да сканира определени папки и подпапки, да намери всички класове и да ги включи в автоматичния модул. За тази цел задайте `autoload > classmap` във файла `composer.json`:

```js
{
	"autoload": {
		"classmap": [
			"src/",      #  включает папку src/ со всеми вложенными директориями
		]
	}
}
```

Впоследствие трябва да стартирате командата `composer dumpautoload` при всяка промяна и да позволите на таблиците на автоматичния модул да се възстановят. Това е изключително неудобно и е много по-добре да оставите тази задача на [RobotLoader |robot-loader:], който върши същата работа автоматично във фонов режим и много по-бързо.

Вторият вариант е да следвате [PSR-4 |https://www.php-fig.org/psr/psr-4/]. Казано по-просто, това е система, в която пространствата от имена и имената на класовете съответстват на структурата на директориите и имената на файловете, т.е. `App\Router\RouterFactory` се намира в `/path/to/App/Router/RouterFactory.php`. Примерна конфигурация:

```js
{
	"autoload": {
		"psr-4": {
			"App\\": "app/"   # пространство имён App\ указывает на директорию app/
		}
	}
}
```

Вижте [документацията на Composer |https://getcomposer.org/doc/04-schema.md#PSR-4] за това как точно да конфигурирате това поведение.


Тестване на нови версии .[#toc-testing-new-versions]
====================================================

Искате да тествате нова версия на даден пакет. Как го правите? Първо, добавете тази двойка опции към `composer.json`, която ще ви позволи да инсталирате версии на пакети за разработка, но ще го направи само ако няма стабилна версия, която да отговаря на изискванията:

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

Препоръчваме също така да изтриете файла `composer.lock`, защото понякога Composer неразбираемо отказва да се инсталира и това ще реши проблема.

Да предположим, че пакетът е `nette/utils`, а новата версия е 4.0. Инсталирате го с помощта на командата:

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

Или можете да инсталирате конкретна версия, например 4.0.0-RC2:

```shell
composer require nette/utils:4.0.0-RC2
```

Ако друг пакет зависи от библиотеката и е заключен към по-стара версия (напр. `^3.1`), би било идеално пакетът да се актуализира, за да работи с новата версия.
Ако обаче искате просто да заобиколите ограничението и да накарате Composer да инсталира версията за разработка и да се преструва, че е по-стара версия (например 3.1.6), можете да използвате ключовата дума `as`:

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


Команди за повикване .[#toc-calling-commands]
=============================================

Можете да извиквате собствени персонализирани команди и скриптове чрез Composer, сякаш те са местни команди на Composer. Не е необходимо в тази папка да се посочват скриптове, разположени в папката `vendor/bin`.

Като пример дефинираме скрипт във файла `composer.json`, който [Nette Tester |tester:] използва за изпълнение на тестове:

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

След това стартираме тестовете, като използваме `composer tester`. Можем да извикаме командата, дори ако не се намираме в главната папка на проекта, а в поддиректория.


Изпращане на благодарствена бележка .[#toc-send-thanks]
=======================================================

Ще ви покажем един трик, с който ще зарадвате авторите на софтуер с отворен код. Можете лесно да присвоите звезда в GitHub на библиотеките, които използват вашия проект. Просто инсталирайте библиотеката `symfony/thanks`:

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

След това въведете:

```shell
composer thanks
```

Опитайте!


Конфигурация .[#toc-configuration]
==================================

Composer е тясно интегриран с инструмента за контрол на версиите [Git |https://git-scm.com]. Ако не използвате Git, трябва да информирате Composer:

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

{{sitename: Най-добри практики}}