Съвети за използване на Composer

Инсталиране на

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

Windows

Използвайте официалния инсталатор Composer-Setup.exe.

Linux, MacOS

Необходими са ви само 4 команди, които можете да копирате от тази страница.

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

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

Използване в съществуващ проект

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

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

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

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

composer update

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

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

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

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

Актуализиране на пакетите до най-новите версии

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

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

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

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

Това не е практично. Затова използвайте прост скрипт Composer Frontline, който ще направи това вместо вас:

php composer-frontline.php

Създаване на нов проект

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

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

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

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

Версия на PHP

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

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

composer config platform.php 8.2.3

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

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

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

composer require php 8.2.3 --no-update

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

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

Пренебрегване на версията на PHP

Пакетите обикновено посочват както най-ниската версия на PHP, с която са съвместими, така и най-високата версия, с която са тествани. Ако планирате да използвате още по-нова версия на PHP, може би за целите на тестването, Composer ще откаже да инсталира такъв пакет. Решението е да използвате опцията --ignore-platform-req=php+, която кара Composer да игнорира горните граници на изискваната версия на PHP.

Фалшиви доклади

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

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

Packagist.org – глобално хранилище

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

Какво да правим, ако нямаме нужда от централно хранилище

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

Прочетете повече за хранилищата в официалната документация.

Автоматично зареждане

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

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

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

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

Вторият вариант е да следвате PSR-4. Казано по-просто, това е система, в която пространствата от имена и имената на класовете съответстват на структурата на директориите и имената на файловете, т.е. App\Core\RouterFactory се намира в /path/to/App/Core/RouterFactory.php. Примерна конфигурация:

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

Вижте документацията на Composer за това как точно да конфигурирате това поведение.

Тестване на нови версии

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

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

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

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

composer require nette/utils:4.0.x-dev

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

composer require nette/utils:4.0.0-RC2

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

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

Команди за повикване

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

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

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

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

Изпращане на благодарствена бележка

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

composer global require symfony/thanks

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

composer thanks

Опитайте!

Конфигурация

Composer е тясно интегриран с инструмента за контрол на версиите Git. Ако не използвате Git, трябва да информирате Composer:

composer -g config preferred-install dist