structure-extensions.md 33.6 KB
Newer Older
1
Расширения
2 3
==========

4
Расширения - это распространяемые программные пакеты, специально разработанные для использования в приложениях Yii и
5 6
содержащие готовые функции. Например, расширение [yiisoft/yii2-debug](tool-debugger.md) добавляет удобную отладочную
панель в нижнюю часть каждой страницы вашего приложения, чтобы помочь вам разобраться в том, как генерируются
7 8
страницы. Вы можете использовать расширения для ускорения процесса разработки. Вы также можете оформить ваш код как
расширение, чтобы поделиться с другими людьми результатами вашей работы.
9

10 11
> Информация: Мы используем термин "расширение" для специфичных для Yii программных пакетов. Программные пакеты
  общего назначения, которые могут быть использованы с Yii, мы будем называть "пакет" или "библиотека".
12 13


14
## Использование расширений <a name="using-extensions"></a>
15

16 17
Чтобы использовать расширение, вам необходимо установить его. Большинство расширений распространяются как пакеты
[Composer](https://getcomposer.org/), которые могут быть установлены посредством следующих двух шагов:
18

19
1. Отредактируйте файл вашего приложения `composer.json`, указав, какие расширения (пакеты Composer) вы хотите
20 21
   установить.
2. Выполните команду `php composer.phar install`, чтобы установить указанные расширения.
22

23
Обратите внимание, что вам может потребоваться установить [Composer](https://getcomposer.org/), если у вас его нет.
24

25
По умолчанию, Composer устанавливает пакеты, зарегистрированные на [Packagist](https://packagist.org/) - крупнейшем
26
репозитории для пакетов Composer с открытым исходным кодом. Вы также можете
27 28 29
[создать свой репозиторий](https://getcomposer.org/doc/05-repositories.md#repository) и настроить Composer для его
использования. Это полезно, если вы разрабатываете закрытые расширения и хотите использовать их в нескольких своих
проектах.
30

31 32 33 34 35
Расширения, установленные Composer'ом, хранятся в директории `BasePath/vendor`, где `BasePath` -
[базовая директория](structure-applications.md#basePath) приложения. Composer - это менеджер зависимостей, и поэтому
после установки пакета он также установит все зависимые пакеты.

Например, для установки расширения `yiisoft/yii2-imagine` нужно отредактировать ваш `composer.json` как показано далее:
36 37 38 39 40 41

```json
{
    // ...

    "require": {
42
        // ... другие зависимости
43 44 45 46 47 48

        "yiisoft/yii2-imagine": "*"
    }
}
```

49 50
После установки вы можете увидеть директорию `yiisoft/yii2-imagine`, находящуюся по пути `BasePath/vendor`. Также вы
можете увидеть директорию `imagine/imagine`, которая содержит зависимый пакет.
51

52 53
> Информация: `yiisoft/yii2-imagine` является базовым расширением, которое разрабатывает и поддерживает команда
  разработчиков Yii. Все базовые расширения размещены на [Packagist](https://packagist.org/) и называются
54
  `yiisoft/yii2-xyz`, где `xyz` является названием расширения.
55

56 57
Теперь вы можете использовать установленное расширение как часть вашего приложения. Следующий пример показывает, как вы
можете использовать класс `yii\imagine\Image`, который содержится в расширении `yiisoft/yii2-imagine`.
58 59 60 61 62

```php
use Yii;
use yii\imagine\Image;

63
// генерация миниатюры изображения
64 65 66 67
Image::thumbnail('@webroot/img/test-image.jpg', 120, 120)
    ->save(Yii::getAlias('@runtime/thumb-test-image.jpg'), ['quality' => 50]);
```

68
> Информация: Классы расширений автоматически загружаются [автозагрузчиком классов Yii](concept-autoloading.md).
69 70


71
### Ручная установка расширений <a name="installing-extensions-manually"></a>
72

73 74
В некоторых редких случаях вы можете захотеть установить некоторые расширения вручную, а не полагаться на Composer.
Чтобы сделать это, вы должны
75

76 77 78
1. загрузить архив с файлами расширения и распаковать его в директорию `vendor`.
2. установить автозагрузчики классов, предоставляемые расширениями, если таковые имеются.
3. загрузить и установить все зависимые расширения в соответствии с инструкциями.
79

80 81 82 83 84
Если расширение не имеет автозагрузчика классов, но следует [стандарту PSR-4](http://www.php-fig.org/psr/psr-4/), то вы
можете использовать автозагрузчик классов, предоставленный Yii для загрузки классов расширений. Всё, что вам нужно
сделать, это объявить [псевдоним](concept-aliases.md#defining-aliases) для корневого каталога расширения. Например,
если вы установили расширение в директорию `vendor/mycompany/myext` и классы расширения находятся в пространстве имён
`myext`, то вы можете включить следующий код в конфигурацию вашего приложения:
85 86 87 88 89 90 91 92 93 94

```php
[
    'aliases' => [
        '@myext' => '@vendor/mycompany/myext',
    ],
]
```


95
## Создание расширений <a name="creating-extensions"></a>
96

97 98
Вы можете захотеть создать расширение, когда чувствуете необходимость поделиться своим хорошим кодом с другими людьми.
Расширение может содержать любой код, который вам нравится, например, класс-помощник, виджет, модуль и т.д.
99

100 101
Рекомендуется создавать расширение как [пакет Composer](https://getcomposer.org/), для того, чтобы его можно было
легко установить и использовать, как описано в предыдущей главе.
102

103
Ниже приведены основные шаги, которым нужно следовать, чтобы создать пакет Composer.
104

105 106 107 108 109 110
1. Создайте проект для вашего расширения и разместите его в VCS репозитории, таком как [github.com](https://github.com).
   Разработка и поддержка расширения должна выполняться в этом репозитории.
2. В корневой директории проекта создайте файл под названием `composer.json`, в соответствии с требованиями Composer.
   Вы можете обратиться к следующему разделу за более подробной информацией.
3. Зарегистрируйте ваше расширение в репозитории Composer, таком как [Packagist](https://packagist.org/), чтобы другие
   пользователи могли найти и установить ваше расширение, используя Composer.
111 112 113 114


### `composer.json` <a name="composer-json"></a>

115 116 117 118
Каждый пакет Composer должен иметь файл `composer.json` в своей корневой директории. Этот файл содержит метаданные о
пакете. Вы можете найти полную спецификацию по этому файлу в
[Руководстве Composer](https://getcomposer.org/doc/01-basic-usage.md#composer-json-project-setup). Следующий пример
демонстрирует файл `composer.json` для расширения `yiisoft/yii2-imagine`:
119 120 121

```json
{
122
    // название пакета
123 124
    "name": "yiisoft/yii2-imagine",

125
    // тип пакета
126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144
    "type": "yii2-extension",

    "description": "The Imagine integration for the Yii framework",
    "keywords": ["yii2", "imagine", "image", "helper"],
    "license": "BSD-3-Clause",
    "support": {
        "issues": "https://github.com/yiisoft/yii2/issues?labels=ext%3Aimagine",
        "forum": "http://www.yiiframework.com/forum/",
        "wiki": "http://www.yiiframework.com/wiki/",
        "irc": "irc://irc.freenode.net/yii",
        "source": "https://github.com/yiisoft/yii2"
    },
    "authors": [
        {
            "name": "Antonio Ramirez",
            "email": "amigo.cobos@gmail.com"
        }
    ],

145
    // зависимости пакета
146 147 148 149 150
    "require": {
        "yiisoft/yii2": "*",
        "imagine/imagine": "v0.5.0"
    },

151
    // указание автозагрузчика классов
152 153 154 155 156 157 158 159 160
    "autoload": {
        "psr-4": {
            "yii\\imagine\\": ""
        }
    }
}
```


161
#### Название пакета <a name="package-name"></a>
162

163 164 165
Каждый пакет Composer должен иметь название, которое однозначно идентифицирует пакет среди остальных. Название пакета
имеет формат `имяРазработчика/названиеПроекта`. Например, в пакете `yiisoft/yii2-imagine`, `yiisoft` является именем
разработчика, а `yii2-imagine` - названием пакета.
166

167
НЕ используйте `yiisoft` в качестве имени разработчика, так как оно зарезервировано для использования в коде ядра Yii.
168

169 170
Мы рекомендуем использовать префикс `yii2-` в названии проекта для пакетов, являющихся расширениями Yii 2, например,
`моёИмя/yii2-mywidget`. Это позволит пользователям легче определить, что пакет является расширением Yii2.
171 172


173
#### Тип пакета <a name="package-type"></a>
174

175 176
Важно указать тип пакета вашего расширения как `yii2-extension`, чтобы пакет можно было распознать как расширение Yii во
время установки.
177

178 179 180 181
Когда пользователь запускает команду `php composer.phar install` для установки расширения, файл
`vendor/yiisoft/extensions.php` будет автоматически обновлён, чтобы включить информацию о новом расширении. Из этого
файла приложение Yii может узнать, какие расширения установлены (информацию можно получить с помощью
[[yii\base\Application::extensions]]).
182 183


184
#### Зависимости <a name="dependencies"></a>
185

186 187 188 189
Ваше расширение зависит от Yii (естественно). Вы можете посмотреть список зависимостей в секции `require`, входящей в
файл `composer.json`. Если ваше расширение зависит от других расширений или сторонних библиотек, то вы также должны их
перечислить. Убедитесь, что в ограничениях вы указали соответствующую версию (например, `1.*`, `@stable`) для каждой
зависимости. Используйте стабильные версии зависимостей, когда будет выпущена стабильная версия вашего расширения.
190 191


192
#### Автозагрузка классов <a name="class-autoloading"></a>
193

194 195
Для того, чтобы ваши классы были загружены автозагрузчиком классов Yii или автозагрузчиком классов Composer, вы должны
внести секцию `autoload` в файл `composer.json`, как показано ниже:
196 197 198 199 200 201 202 203 204 205 206 207 208

```json
{
    // ....

    "autoload": {
        "psr-4": {
            "yii\\imagine\\": ""
        }
    }
}
```

209
Вы можете перечислить один или несколько корневых пространств имён и соответствующие им пути.
210

211 212 213
Когда расширение установлено в приложение, Yii для каждого указанного корневого пространства имён создаст
[псевдоним](concept-aliases.md#extension-aliases), который указывает на директорию, соответствующую пространству имён.
Например, указанная в секции `autoload` запись будет соответствовать псевдониму `@yii/imagine`.
214 215


216
### Рекомендованные практики <a name="recommended-practices"></a>
217

218 219 220
Поскольку расширения предназначены для использования другими людьми, вам придётся приложить дополнительные усилия в
процессе разработки. Ниже приведены некоторые общие и рекомендованные практики для создания высококачественных
расширений.
221 222


223
#### Пространства имён <a name="namespaces"></a>
224

225 226 227
Во избежание конфликтов имён, а также для того, чтобы ваши классы были автозагружаемыми, вы должны следовать
[стандарту PSR-4](http://www.php-fig.org/psr/psr-4/) или [стандарту PSR-0](http://www.php-fig.org/psr/psr-0/) в
использовании пространств имён и названии классов вашего расширения.
228

229 230 231
Пространства имён в ваших классах должны начинаться с `имяРазработчика\названиеРасширения`, где `названиеРасширения`
совпадает с названием проекта в названии пакета, за исключением того, что оно не должно содержать префикса `yii2-`.
Например, для расширения `yiisoft/yii2-imagine` мы используем `yii\imagine` в качестве пространства имён.
232

233 234
Не используйте `yii`, `yii2` или `yiisoft` в качестве имени разработчика. Эти имена являются зарезервированными для
использования в коде ядра Yii.
235 236


237
#### Классы начальной загрузки <a name="bootstrapping-classes"></a>
238

239 240 241 242 243
Иногда вы можете захотеть выполнить некоторый код своего расширения в стадии
[начальной загрузки](runtime-bootstrapping.md) приложения. Например, ваше расширение может ответить на событие
приложения `beginRequest`, чтобы установить некоторые настройки окружения. Вы можете в инструкции по установке вашего
приложения написать, что необходимо назначить обработчик события `beginRequest`, но лучшим способом будет сделать это
автоматически.
244

245 246
Для достижения этой цели вы можете создать так называемый *класс начальной загрузки*, реализовав интерфейс
[[yii\base\BootstrapInterface]]. Например,
247 248 249 250 251 252 253 254 255 256 257 258

```php
namespace myname\mywidget;

use yii\base\BootstrapInterface;
use yii\base\Application;

class MyBootstrapClass implements BootstrapInterface
{
    public function bootstrap($app)
    {
        $app->on(Application::EVENT_BEFORE_REQUEST, function () {
259
             // остальной код
260 261 262 263 264
        });
    }
}
```

265
Затем нужно добавить этот класс в файл `composer.json` вашего расширения, как показано далее,
266 267 268 269 270 271 272 273 274 275 276

```json
{
    // ...

    "extra": {
        "bootstrap": "myname\\mywidget\\MyBootstrapClass"
    }
}
```

277 278 279
Когда расширение будет установлено в приложение, Yii автоматически инициирует экземпляр класса начальной загрузки и
вызовет его метод [[yii\base\BootstrapInterface::bootstrap()|bootstrap()]]  в процессе начальной загрузки каждого
запроса.
280 281


282
#### Работа с базами данных <a name="working-with-databases"></a>
283

284
Ваше расширение может иметь доступ к базам данных. Не думайте, что приложения, которые используют ваше расширение,
285
всегда используют `Yii::$db` в качестве соединения с БД. Вместо этого вам следует объявить свойство `db` в классах,
286 287 288
которым необходим доступ в БД. Это свойство позволит пользователям вашего расширения настроить соединение с БД,
которое они будут использовать в вашем расширении. В качестве примера вы можете обратиться к классу
[[yii\caching\DbCache]] и посмотреть, как он объявляет и использует свойство `db`.
289

290
Если в вашем приложении необходимо создать определённые таблицы БД или сделать изменения в схеме БД, вы должны
291

292 293 294
- создать файлы [миграций](db-migrations.md) для изменения схемы БД вместо простых SQL-файлов;
- попытаться сделать миграции, применимые к различным СУБД;
- избегать использования [Active Record](db-active-record.md) в миграциях.
295 296


297
#### Использование ресурсов <a name="using-assets"></a>
298

299 300
Если ваше расширение является виджетом или модулем, то есть вероятность, что оно потребует некоторых
[ресурсов](structure-assets.md) для работы. Например, модуль может отображать некоторые страницы, которые содержат
301 302
изображения, JavaScript и CSS. Так как все файлы расширения находятся в директории, недоступной из интернета, у вас
есть два варианта сделать директорию ресурсов непосредственно доступной из интернета:
303

304 305 306
- попросить пользователей расширения вручную скопировать файлы ресурсов в определённую, доступную из интернета папку;
- объявить [связку ресурсов](structure-assets.md) и полагаться на механизм публикации ресурсов, который автоматически
  копирует файлы, описанные в связке ресурсов в папку, доступную из интернета.
307

308 309
Мы рекомендуем вам использовать второй подход, чтобы ваше расширение было более простым в использовании для других
людей.
310 311


312
### Интернационализация и локализация <a name="i18n-l10n"></a>
313

314 315
Ваше расширение может быть использовано в приложениях, поддерживающих разные языки! Поэтому, если ваше расширение
отображает содержимое конечному пользователю, вы должны попробовать
316
[интернационализовать и локализовать](tutorial-i18n.md) его. В частности,
317

318 319 320 321 322
- Если расширение отображает сообщения, предназначенные для конечных пользователей, сообщения должны быть обёрнуты в
  метод `Yii::t()` так, чтобы они могли быть переведены. Сообщения, предназначенные для разработчиков (например,
  внутренние сообщения исключений), не нужно переводить.
- Если расширение отображает числа, даты и т.п., они должны быть отформатированы, используя [[yii\base\Formatter]] с
  соответствующими правилами форматирования.
323

324
Для более подробной информации вы можете обратиться к разделу [Интернационализация](tutorial-i18n.md)
325 326


327
#### Тестирование <a name="testing"></a>
328

329 330
Вы хотите, чтобы ваше расширение было стабильным и не приносило проблем другим людям. Для достижения этой цели вы
должны протестировать ваше расширение перед его публикацией.
331

332 333 334 335
Рекомендуется создавать различные тесты для покрытия кода вашего расширения, а не вручную тестировать его. Каждый раз
перед тем, как выпустить новую версию расширения, вы можете просто запустить эти тесты чтобы убедиться, что всё
работает правильно. Yii имеет поддержку тестирования, которая может помочь вам легче писать модульные, приёмочные и
функциональные тесты. Для более подробной информации вы можете обратиться в раздел [Тестирование](test-overview.md).
336 337


338
#### Версионирование <a name="versioning"></a>
339

340 341
Вы можете давать каждому выпуску вашего расширения номер версии (например, `1.0.1`). Мы рекомендуем вам придерживаться
практик [семантического версионирования](http://semver.org) при определении, какой номер версии должен использоваться.
342

343
#### Публикация <a name="releasing"></a>
344

345
Чтобы позволить другим людям узнать о вашем расширении, необходимо опубликовать его.
346

347 348 349 350
Если это первый выпуск вашего расширения, вы должны зарегистрировать его в репозитории Composer, таком, как
[Packagist](https://packagist.org/). После этого вам остаётся только создать тег выпуска (например, `v1.0.1`) в VCS
репозитории вашего расширения и уведомить репозиторий Composer о новом выпуске. Люди смогут найти новую версию и
установить или обновить расширение через репозиторий Composer.
351

352 353
В выпусках вашего расширения помимо файлов с кодом вы также должны рассмотреть вопрос о включении следующих файлов,
которые помогут людям изучить и использовать ваше расширение:
354

355 356 357 358 359 360 361 362
* Файл readme в корневой директории пакета: он описывает, что ваше расширение делает, а также как его установить и
  использовать. Мы рекомендуем вам написать его в формате [Markdown](http://daringfireball.net/projects/markdown/) и
  дать ему название `readme.md`.
* Файл changelog в корневой директории пакета: он описывает, какие изменения произошли в каждом выпуске. Этот файл
  может быть написан в формате Markdown и назван `changelog.md`.
* Файл upgrade в корневой директории пакета: он даёт инструкции о том, как обновить старые версии расширения. Этот
  файл может быть написан в формате Markdown и назван `upgrade.md`.
* Руководства пользователя, демо-версии, скриншоты и т.д.: они необходимы, если ваше расширение предоставляет много
363
  возможностей, которые невозможно полностью описать в файле readme.
364 365 366
* Документация API: ваш код должен быть документирован, чтобы позволить другим людям легко читать и понимать его. Вы
  можете обратиться к [файлу класса Object](https://github.com/yiisoft/yii2/blob/master/framework/base/Object.php),
  чтобы узнать, как нужно документировать код.
367

368 369
> Информация: Ваши комментарии к коду могут быть написаны в формате Markdown. Расширение `yiisoft/yii2-apidoc`
  предоставляет инструмент для генерации документации API на основе ваших комментариев.
370

371 372
> Информация: Пока это не обязательно, но мы всё-таки рекомендуем вам придерживаться определённого стиля кодирования.
  Вы можете обратиться к [стилю кодирования фреймворка](https://github.com/yiisoft/yii2/wiki/Core-framework-code-style).
373 374


375
## Базовые расширения <a name="core-extensions"></a>
376

377 378 379
Yii предоставляет следующие базовые расширения, которые разрабатывает и поддерживает команда разработчиков Yii. Они все
зарегистрированы на [Packagist](https://packagist.org/) и могут быть легко установлены, как описано в подразделе
[Использование расширений](#using-extensions).
380 381

- [yiisoft/yii2-apidoc](https://github.com/yiisoft/yii2-apidoc):
382
  предоставляет расширяемый и высокопроизводительный генератор документации API. Оно также используется для генерации
383
  документации API фреймворка.
384
- [yiisoft/yii2-authclient](https://github.com/yiisoft/yii2-authclient):
385 386
  предоставляет набор наиболее часто используемых клиентов авторизации, таких, как Facebook OAuth2 клиент и GitHub
  OAuth2 клиент.
387
- [yiisoft/yii2-bootstrap](https://github.com/yiisoft/yii2-bootstrap):
388
  предоставляет набор виджетов, которые являются компонентами и плагинами [Bootstrap](http://getbootstrap.com/).
389
- [yiisoft/yii2-codeception](https://github.com/yiisoft/yii2-codeception):
390
  предоставляет поддержку тестирования, основанного на [Codeception](http://codeception.com/).
391
- [yiisoft/yii2-debug](https://github.com/yiisoft/yii2-debug):
392
  предоставляет поддержку отладки в приложениях Yii. Когда это расширение используется, отладочная панель появится в
393 394
  нижней части каждой страницы. Это расширение также предоставляет набор отдельных страниц для отображения более
  подробной отладочной информации.
395
- [yiisoft/yii2-elasticsearch](https://github.com/yiisoft/yii2-elasticsearch):
396 397 398
  предоставляет поддержку использования [Elasticsearch](http://www.elasticsearch.org/). Оно включает в себя поддержку
  основных поисковых запросов, а также реализует шаблон проектирования [Active Record](db-active-record.md), который
  позволяет хранить записи Active Record в Elasticsearch.
399
- [yiisoft/yii2-faker](https://github.com/yiisoft/yii2-faker):
400
  предоставляет поддержку использования [Faker](https://github.com/fzaninotto/Faker) для генерации фиктивных данных.
401
- [yiisoft/yii2-gii](https://github.com/yiisoft/yii2-gii):
402 403
  предоставляет веб-интерфейс для генерации кода, который является весьма расширяемым и может быть использован для
  быстрой генерации моделей, форм, модулей, CRUD и т.д.
404
- [yiisoft/yii2-imagine](https://github.com/yiisoft/yii2-imagine):
405 406
  предоставляет часто используемые функции для работы с изображениями, основанные на библиотеке
  [Imagine](http://imagine.readthedocs.org/).
407
- [yiisoft/yii2-jui](https://github.com/yiisoft/yii2-jui):
408
  предоставляет набор виджетов, основанный на взаимодействиях и виджетах [JQuery UI](http://jqueryui.com/).
409
- [yiisoft/yii2-mongodb](https://github.com/yiisoft/yii2-mongodb):
410
  предоставляет поддержку использования [MongoDB](http://www.mongodb.org/). Оно включает такие возможности, как
411
  базовые запросы, Active Record, миграции, кэширование, генерация кода и т.д.
412
- [yiisoft/yii2-redis](https://github.com/yiisoft/yii2-redis):
413
  предоставляет поддержку использования [redis](http://redis.io/). Оно включает такие возможности, как базовые запросы,
414
  Active Record, кэширование и т.д.
415
- [yiisoft/yii2-smarty](https://github.com/yiisoft/yii2-smarty):
416
  предоставляет шаблонизатор, основанный на [Smarty](http://www.smarty.net/).
417
- [yiisoft/yii2-sphinx](https://github.com/yiisoft/yii2-sphinx):
418 419
  предоставляет поддержку использования [Sphinx](http://sphinxsearch.com). Оно включает такие возможности, как базовые
  запросы, Active Record, генерация кода и т.д.
420
- [yiisoft/yii2-swiftmailer](https://github.com/yiisoft/yii2-swiftmailer):
421
  предоставляет возможности отправки email, основанные на [swiftmailer](http://swiftmailer.org/).
422
- [yiisoft/yii2-twig](https://github.com/yiisoft/yii2-twig):
423
  предоставляет шаблонизатор, основанный на [Twig](http://twig.sensiolabs.org/).