Nette Documentation Preview

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

<div class=perex>

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

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

</div>


Установка .[#toc-installation]
==============================

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


Использование в существующем проекте .[#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"
	}
}
```


Игнорирование версии PHP .[#toc-ignoring-php-version]
=====================================================

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


Ложные отчеты .[#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\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].


Тестирование новых версий .[#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: Лучшие практики}}

Советы по использованию 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.

Итак, когда у нас есть файл 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