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 (т.е. най-новата версия 3).

Имаме следователно в корена на проекта файл composer.json и стартираме инсталацията:

composer update

Composer ще изтегли Nette Database в папката 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 име-на-проекта

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

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

Версия на PHP

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

Това, че проектът ще работи например на PHP 8.2.3, настройваме с командата:

composer config platform.php 8.2.3

Така версията се записва във файла composer.json:

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

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

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 се опитва да търси пакети, ако не му кажем друго. Тук можем да публикуваме и собствени пакети.

Какво, ако не искаме да използваме централното хранилище?

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

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

Autoloading

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

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

{
	"autoload": {
		"classmap": [
			"src/",      # включва папката src/ и нейните подпапки
		]
	}
}

След това е необходимо при всяка промяна да се стартира командата composer dumpautoload и да се оставят autoloading таблиците да се прегенерират. Това е изключително неудобно и далеч по-добре е тази задача да се повери на 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. Командата можем да извикаме и в случай, че не сме в коренната папка на проекта, а в някоя поддиректория.

Изпратете благодарност

Ще ви покажем трик, с който ще зарадвате авторите на open source. По прост начин ще дадете звездичка в GitHub на библиотеките, които вашият проект използва. Достатъчно е да инсталирате библиотеката symfony/thanks:

composer global require symfony/thanks

И след това да стартирате:

composer thanks

Опитайте!

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

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

composer -g config preferred-install dist