Nette Documentation Preview

syntax 
Composer: советы по использованию
*********************************

<div class=perex>

Composer - инструмент управления зависимостями в PHP. Он позволяет объявить библиотеки, от которых зависит ваш проект, и сам их установит и обновит. Мы узнаем:

- как установить Composer
- как использовать его в новом или существующем проекте

</div>


Установка
=========

Composer - исполняемый файл `.phar`, который вы скачиваете и устанавливаете следующим образом.


Windows
-------

Воспользуйтесь официальным установщиком [Composer-Setup.exe|https://getcomposer.org/Composer-Setup.exe].


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

Вам понадобятся всего 4 команды, которые можно скопировать с [этой страницы |https://getcomposer.org/download/].

Кроме того, скопировав его в папку, входящую в системный `PATH`, вы сделаете Composer доступным глобально:

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


Использование в проекте
=======================

Чтобы начать использовать Composer в своём проекте, вам нужен только файл `composer.json`. Этот файл описывает зависимости вашего проекта и может содержать другие метаданные. Простейший `composer.json` может выглядеть так:

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

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

Итак, имея файл `composer.json` в корне проекта, выполните:

```shell
composer update
```

Composer скачает Nette Database в каталог `vendor/`. Он также создаст файл `composer.lock`, в котором записано, какие именно версии библиотек были установлены.

Composer порождает файл `vendor/autoload.php`. Вы можете просто подключить этот файл и начать использовать классы библиотек без каких-либо дополнительных действий:

```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, вам пришлось бы перечислить их все в командной строке, например:

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

Это непрактично. Поэтому воспользуйтесь простым скриптом "Composer Frontline":https://gist.github.com/dg/734bebf55cf28ad6a5de1156d3099bff, который сделает это за вас:

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


Создание нового проекта
=======================

Новый проект на Nette можно создать одной командой:

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

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

Если вы знаете, на какой версии PHP будет размещён ваш проект, обязательно [задайте её |#Версия PHP].


Версия PHP
==========

Composer всегда устанавливает версии пакетов, совместимые с той версией PHP, которую вы сейчас используете (точнее, с версией PHP в командной строке, где запускается Composer). Она может отличаться от версии, которая используется на вашем хостинге. Поэтому принципиально важно добавить в файл `composer.json` сведения о версии PHP на хостинге. Тогда будут устанавливаться только версии пакетов, совместимые с хостингом.

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

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

Версия запишется в файл `composer.json` вот так:

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

Однако номер версии PHP указывается в файле и в другом месте, в секции `require`. Первое число определяет версию, под которую устанавливаются пакеты, а второе - версию, под которую написано само приложение. Например, PhpStorm по нему выставляет *PHP language level*. (Разумеется, различаться этим версиям смысла нет, так что двойная запись - недосмотр.) Задайте эту версию командой:

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

Или прямо в файле `composer.json`:

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


Игнорирование версии PHP
========================

Пакеты обычно указывают и самую низкую версию PHP, с которой они совместимы, и самую высокую, на которой они были протестированы. Если вы собираетесь использовать ещё более новую версию PHP, скажем ради тестирования, Composer откажется устанавливать такой пакет. Решение - параметр `--ignore-platform-req=php+`, который заставляет Composer игнорировать верхние границы требуемой версии PHP.


Ложные сообщения
================

При обновлении пакетов или изменении номеров версий иногда возникают конфликты. У одного пакета требования конфликтуют с другим и так далее. Однако иногда Composer выдаёт ложные сообщения. Он сообщает о конфликте, которого на самом деле нет. В таких случаях может помочь удаление файла `composer.lock` и повторная попытка.

Если сообщение об ошибке не исчезает, значит оно настоящее, и вам нужно его прочитать, чтобы понять, что и как изменить.


Packagist.org - глобальный репозиторий
======================================

[Packagist |https://packagist.org] - главный репозиторий, в котором Composer по умолчанию ищет пакеты. Здесь вы можете публиковать и собственные пакеты.


А если нам не нужен центральный репозиторий
-------------------------------------------

Если внутри компании у нас есть приложения или библиотеки, которые нельзя размещать публично, мы можем создать для них собственные репозитории.

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


Автозагрузка
============

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

Однако Composer можно использовать и для загрузки других классов вне каталога `vendor/`. Первый вариант - позволить Composer просмотреть заданные каталоги и подкаталоги, найти все классы и включить их в автозагрузчик. Для этого задайте в `composer.json` секцию `autoload > classmap`:

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

После этого вам придётся после каждого изменения выполнять команду `composer dumpautoload`, чтобы перегенерировать таблицы автозагрузки. Это крайне неудобно. Куда лучше поручить эту задачу [RobotLoader|robot-loader:], который делает то же самое автоматически в фоне и намного быстрее.

Второй вариант - придерживаться [PSR-4 |https://www.php-fig.org/psr/psr-4/]. Проще говоря, это система, в которой пространства имён и имена классов соответствуют структуре каталогов и именам файлов, например `App\Core\RouterFactory` будет находиться в файле `/path/to/App/Core/RouterFactory.php`. Пример настройки:

```js
{
	"autoload": {
		"psr-4": {
			"App\\": "app/"   # пространство имён App\ находится в каталоге app/
		}
	}
}
```

Подробности о настройке этого поведения см. в [документации Composer |https://getcomposer.org/doc/04-schema.md#psr-4].


Тестирование новых версий
=========================

Хотите протестировать новую разрабатываемую версию пакета? Вот как это сделать. Сначала добавьте в файл `composer.json` эту пару параметров. Она разрешает установку разрабатываемых версий, но Composer прибегнет к ним только тогда, когда ни одно сочетание стабильных версий не отвечает требованиям:

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


Вызов команд
============

Вы можете вызывать через Composer собственные заранее заданные команды и скрипты так, будто это его родные команды. Для скриптов, лежащих в каталоге `vendor/bin`, указывать этот путь не нужно.

В качестве примера определим в `composer.json` скрипт, который использует [Nette Tester |tester:] для запуска тестов:

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

Затем мы запускаем тесты командой `composer tester`. Команду можно вызвать, даже если вы находитесь не в корневом каталоге проекта, а в одном из его подкаталогов.


Скажите спасибо
===============

Покажем приём, который порадует авторов открытого кода. Вы можете легко поставить на GitHub звёзды библиотекам, которые использует ваш проект. Достаточно установить библиотеку `symfony/thanks`:

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

А затем выполнить:

```shell
composer thanks
```

Попробуйте!


Настройка
=========

Composer тесно интегрирован с системой контроля версий [Git |https://git-scm.com]. Если Git у вас не установлен, нужно сказать Composer, чтобы он его не использовал:

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

Composer: советы по использованию

Composer – инструмент управления зависимостями в PHP. Он позволяет объявить библиотеки, от которых зависит ваш проект, и сам их установит и обновит. Мы узнаем:

  • как установить 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 name-of-the-project

Замените name-of-the-project на имя каталога вашего проекта и выполните команду. Composer скачает с GitHub репозиторий nette/web-project, в котором уже есть файл 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 по умолчанию ищет пакеты. Здесь вы можете публиковать и собственные пакеты.

А если нам не нужен центральный репозиторий

Если внутри компании у нас есть приложения или библиотеки, которые нельзя размещать публично, мы можем создать для них собственные репозитории.

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

Автозагрузка

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

Однако Composer можно использовать и для загрузки других классов вне каталога vendor/. Первый вариант – позволить Composer просмотреть заданные каталоги и подкаталоги, найти все классы и включить их в автозагрузчик. Для этого задайте в composer.json секцию autoload > classmap:

{
	"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 эту пару параметров. Она разрешает установку разрабатываемых версий, но Composer прибегнет к ним только тогда, когда ни одно сочетание стабильных версий не отвечает требованиям:

{
	"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 собственные заранее заданные команды и скрипты так, будто это его родные команды. Для скриптов, лежащих в каталоге 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