Расширения

Расширения - это распространяемые программные пакеты, специально разработанные для использования в Yii-приложениях и предоставляющие готовые к использованию функции. Например, расширение yiisoft/yii2-debug добавляет удобную панель отладки внизу каждой страницы вашего приложения, чтобы помочь вам более легко понять, как создаются страницы. Вы можете использовать расширения, чтобы ускорить процесс разработки. Вы также можете упаковать свой код как расширение, чтобы поделиться с другими людьми своей замечательной работой.

Использование расширений

Чтобы использовать расширение, вам нужно сначала установить его. Большинство расширений распространяются как пакеты Composer, которые можно установить, выполнив следующие два простых действия:

  • Измените файл composer.json вашего приложения и укажите, какие расширения (пакеты Composer) вы хотите установить.
  • Запустите composer install чтобы установить указанные расширения.

Обратите внимание, что вам может потребоваться установить Composer, если у вас его нет.

По умолчанию Composer устанавливает пакеты, зарегистрированные на Packagist - самый большой репозиторий для пакетов с открытым исходным кодом. Вы можете искать расширения на Packagist. Вы также можете создать свой собственный репозиторий и настроить Composer для его использования. Это полезно, если вы разрабатываете частные расширения, которые вы хотите использовать только в своих проектах.

Расширения, установленные Composer, хранятся в каталоге BasePath/vendor, где BasePath ссылается на базовый путь приложения. Поскольку Composer является диспетчером зависимостей, при установке пакета он также устанавливает все зависимые пакеты.

Например, чтобы установить расширение yiisoft/yii2-imagine, измените свой composer.json следующим образом:

{
    // ...

    "require": {
        // ... другие зависимости

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

После установки вы должны увидеть каталог yiisoft/yii2-imagine под BasePath/vendor. Вы также должны увидеть другой каталог imagel/imagine, который содержит установленный зависимый пакет.

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

use Yii;
use yii\imagine\Image;

// создать миниатюру изображения
Image::thumbnail('@webroot/img/test-image.jpg', 120, 120)
    ->save(Yii::getAlias('@runtime/thumb-test-image.jpg'), ['quality' => 50]);

Установка расширений вручную

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

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

Если расширение не имеет автозагрузчика классов, но следует стандарту PSR-4, вы можете использовать автозагрузчик классов, предоставленный Yii, для автоматической загрузки классов расширения. Все, что вам нужно сделать, это просто объявить корневой псевдоним для корневого каталога расширения. Например, предположив, что вы установили расширение в каталоге vendor/mycompany/myext и классы расширения находятся в пространстве имен myext, вы можете включить в свою конфигурацию приложения следующий код:

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

Создание расширений

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

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

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

  1. Создайте проект для своего расширения и разместите его в репозитории VCS, например github.com. В этом репозитории должны быть выполнены работы по разработке и обслуживанию расширения.
  2. В корневом каталоге проекта создайте файл composer.json, как того требует Composer.
  3. Зарегистрируйте свое расширение в репозитории Composer, таком как Packagist, чтобы другие пользователи могли найти и установить расширение с помощью Composer.

composer.json

Каждый пакет Composer должен иметь файл composer.json в корневом каталоге. Файл содержит метаданные о пакете. В следующем примере показан файл composer.json для расширения yiisoft/yii2-imagine:

{
    // package name
    "name": "yiisoft/yii2-imagine",

    // package type
    "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"
        }
    ],

    // package dependencies
    "require": {
        "yiisoft/yii2": "~2.0.0",
        "imagine/imagine": "v0.5.0"
    },

    // class autoloading specs
    "autoload": {
        "psr-4": {
            "yii\\imagine\\": ""
        }
    }
}

Package Name

Каждый пакет Composer должен иметь имя пакета, которое однозначно идентифицирует пакет среди всех остальных. Формат имен пакетов называется vendorName/projectName. Например, в названии пакета yiisoft/yii2-imagine имя поставщика и название проекта - yiisoft и yii2-imagine, соответственно.

НЕ используйте yiisoft в качестве имени вашего поставщика, так как он зарезервирован для использования кодом ядра Yii.

Мы рекомендуем вам прикрепить yii2- к имени проекта для пакетов, представляющих расширения Yii 2, например myname/yii2-mywidget. Это позволит пользователям легче определить, является ли пакет расширением Yii 2.

Package Type

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

Когда пользователь запускает composer install для установки расширения, файл vendor/yiisoft/extensions.php будет автоматически обновлен, чтобы включить информацию о новом расширении. Из этого файла приложения Yii могут узнать, какие расширения установлены (информация может быть доступна через yii\base\Application::$extensions).

Dependencies

Ваше расширение зависит от Yii. Поэтому вы должны указать его (yiisoft/yii2) в записи require в composer.json. Если ваше расширение также зависит от других расширений или сторонних библиотек, вы также должны их перечислить. Убедитесь, что вы также указали соответствующие ограничения версии (например, 1. *, @stable) для каждого зависимого пакета. Используйте стабильные зависимости, когда ваше расширение выпущено в стабильной версии.

Большинство пакетов JavaScript/CSS управляются с помощью Bower или NPM вместо Composer. Yii использует плагин активов Composer, чтобы позволить управлять этими видами пакетов через Composer. Если ваше расширение зависит от пакета Bower, вы можете просто перечислить зависимость в composer.json следующим образом:

{
    // package dependencies
    "require": {
        "bower-asset/jquery": ">=1.11.*"
    }
}

В приведенном выше коде указано, что расширение зависит от пакета jquery Bower. В общем случае вы можете использовать bower-asset/PackageName для ссылки на пакет Bower в composer.json и использовать npm-asset/PackageName для обращения к пакету NPM. Когда Composer устанавливает пакет Bower или NPM, по умолчанию содержимое пакета будет установлено в каталогах @vendor/bower/PackageName и @vendor/npm/Packages соответственно. Эти два каталога также можно отнести к использованию более коротких псевдонимов @bower/PackageName и @npm/PackageName.

Class Autoloading

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

{
    // ....

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

Вы можете указать одно или несколько корневых пространств имен и соответствующие им пути к файлам.

Когда расширение установлено в приложении, Yii создаст для каждого перечисленного корневого пространства имен псевдоним, который ссылается на каталог, соответствующий пространству имен. Например, указанное выше объявление autoload будет соответствовать псевдониму с именем @yii/imagine.

Рекомендуемая практика

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

Namespaces

Чтобы избежать коллизий имен и сделать классы в вашем расширении автозагружаемыми, вы должны использовать пространства имен и называть классы в своем расширении, следуя стандарту PSR-4 или стандарту PSR-0.

Пространства имен классов должны начинаться с vendorName\extensionName, где extensionName похож на имя проекта в имени пакета, за исключением того, что он не должен содержать префикс yii2. Например, для расширения yiisoft/yii2-imagine мы используем yii\imagine как пространство имен для его классов.

Не используйте yii, yii2 или yiisoft в качестве имени вашего поставщика. Эти имена зарезервированы для использования кодом ядра Yii.

Bootstrapping Classes

Иногда вы можете захотеть, чтобы ваше расширение выполняло некоторый код во время этапа начальной загрузки приложения. Например, ваше расширение может захотеть откликнуться на событие beginRequest приложения, чтобы отрегулировать некоторые параметры среды. Хотя вы можете дать указание пользователям расширения явно включить свой обработчик события в расширение в событие beginRequest, лучше сделать это автоматически.

Для достижения этой цели вы можете создать так называемый класс начальной загрузки, реализуя yii\base\BootstrapInterface. Например:

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 () {
             // сделать что-то здесь
        });
    }
}

Затем вы указываете этот класс в файле composer.json вашего расширения, как показано ниже:

{
    // ...

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

Когда расширение установлено в приложении, Yii автоматически создает экземпляр класса bootstrapping и вызывает его метод bootstrap() во время процесса начальной загрузки для каждого запроса.

Работа с базами данных

Вашему расширению может потребоваться доступ к базам данных. Не думайте, что приложения, использующие ваше расширение, всегда будут использовать Yii::$db в качестве соединения с БД. Вместо этого вам нужно объявить свойство db для классов, которые требуют доступа к базе данных. Свойство позволит пользователям вашего расширения настраивать, какое соединение с БД они хотели бы использовать вашему расширению. В качестве примера вы можете обратиться к классу yii\caching\DbCache и посмотреть, как он объявляет и использует свойство db.

Если вашему расширению необходимо создать конкретные таблицы БД или внести изменения в схему БД, вы должны

  • Обеспечить миграцию для манипулирования схемой БД, вместо использования простых файлов SQL;
  • Попытайтесь сделать миграции применимыми к разным СУБД;
  • Избегайте использования Active Record в процессах миграции.

Использование Assets

Если ваше расширение представляет собой виджет или модуль, скорее всего, для его работы может потребоваться некоторое количество ресурсов. Например, модуль может отображать некоторые страницы, содержащие изображения, JavaScript и CSS. Поскольку файлы расширения находятся в одном каталоге, который не доступен в Интернете при установке в приложении, у вас есть два варианта, чтобы файлы активов были доступны через веб:

  • Попросить пользователей расширения вручную скопировать файлы активов в определенную папку, доступную в Интернете;
  • Объявлять набор ресурсов и полагаться на механизм публикации активов, чтобы автоматически копировать файлы, перечисленные в наборе активов, в папку, доступную в Интернете.

Интернационализация и локализация

Ваше расширение может использоваться приложениями, поддерживающими разные языки! Поэтому, если ваше расширение отображает контент для конечных пользователей, вы должны попытаться интернационализировать и локализовать его. В частности,

  • Если расширение отображает сообщения, предназначенные для конечных пользователей, сообщения должны быть обернуты в Yii::t(), чтобы они могли быть переведены. Сообщения, предназначенные для разработчиков (например, внутренние сообщения об исключениях), не нужно переводить.
  • Если расширение отображает числа, даты и т. д., Их следует отформатировать с помощью yii\i18n\Formatter с соответствующими правилами форматирования.

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

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

Рекомендуется создавать различные тестовые сценарии для расширения кода расширения вместо того, чтобы полагаться на ручные тесты. Каждый раз, когда вы выпускаете новую версию своего расширения, вы можете просто запустить эти тесты, чтобы убедиться, что все в порядке. Yii предоставляет поддержку тестирования, которая может помочь вам более легко писать модульные тесты, приемочные тесты и тесты функциональности.

Версии

Каждому выпуску расширения необходимо присвоить номер версии (например, 1.0.1). 

Релизы

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

Если вы в первый раз выпускаете расширение, вам следует зарегистрировать его в репозитории Composer, таком как Packagist. После этого все, что вам нужно сделать, - просто создать тег release (например, v1.0.1) в репозитории VCS вашего расширения и уведомить репозиторий Composer о новой версии. Затем люди смогут найти новую версию и установить или обновить расширение через репозиторий Composer.

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

  • Файл readme в корневом каталоге пакета: он описывает, что делает ваше расширение, и как его установить и использовать. Мы рекомендуем вам записать его в формате Markdown и назвать файл как readme.md.
  • Файл журнала изменений в корневой папке пакета: в нем перечислены изменения, внесенные в каждую версию. Файл может быть записан в формате Markdown и назван как changelog.md.
  • Файл обновления в корневом каталоге пакета: в нем приводятся инструкции о том, как обновить устаревшие версии расширения. Файл может быть записан в формате Markdown и назван как upgrade.md.
  • Обучающие программы, демонстрации, скриншоты и т. д .: они необходимы, если ваше расширение предоставляет множество функций, которые не могут быть полностью охвачены в файле readme.
  • Документация API: ваш код должен быть хорошо документирован, чтобы позволить другим людям легче читать и понимать его. Вы можете обратиться к файлу класса Object, чтобы узнать, как документировать код.

Core Extensions

Yii предоставляет следующие основные расширения, которые разрабатываются и поддерживаются командой разработчиков Yii. Все они зарегистрированы на Packagist и могут быть легко установлены.

  • yiisoft/yii2-apidoc: обеспечивает расширяемый и высокопроизводительный генератор документации API. Он также используется для создания документации базового API-интерфейса.
  • yiisoft/yii2-authclient: предоставляет набор обычно используемых клиентов auth, таких как клиент OAuth2 для Facebook, клиент GitHub OAuth2.
  • yiisoft/yii2-bootstrap: предоставляет набор виджетов, которые инкапсулируют компоненты и плагины Bootstrap.
  • yiisoft/yii2-codeception: предоставляет поддержку тестирования на основе Codeception.
  • yiisoft/yii2-debug: обеспечивает поддержку отладки для приложений Yii. Когда это расширение используется, панель инструментов отладчика появится внизу каждой страницы. Расширение также предоставляет набор автономных страниц для отображения более подробной информации отладки.
  • yiisoft/yii2-elasticsearch: предоставляет поддержку для использования Elasticsearch. Он включает базовую поддержку запросов/поиска, а также реализует шаблон Active Record, который позволяет хранить активные записи в Elasticsearch.
  • yiisoft/yii2-faker: предоставляет поддержку для использования Faker для генерации ложных данных для вас.
  • yiisoft/yii2-gii: предоставляет генератор кода на основе Web, который является очень расширяемым и может использоваться для быстрого создания моделей, форм, модулей, CRUD и т. д.
  • yiisoft/yii2-httpclient: предоставляет HTTP-клиент.
  • yiisoft/yii2-imagine: обеспечивает широко используемые функции обработки изображений, основанные на Imagine.
  • yiisoft/yii2-jui: предоставляет набор виджетов, которые инкапсулируют взаимодействия и виджеты JQuery UI.
  • yiisoft/yii2-mongodb: предоставляет поддержку для использования MongoDB. Он включает в себя такие функции, как базовый запрос, Active Record, миграции, кэширование, генерация кода и т. д.
  • yiisoft/yii2-redis: предоставляет поддержку для использования redis. Он включает такие функции, как базовый запрос, Active Record, кеширование и т. д.
  • yiisoft/yii2-smarty: предоставляет механизм шаблонов на основе Smarty.
  • yiisoft/yii2-sphinx: предоставляет поддержку для использования Sphinx. Он включает такие функции, как базовый запрос, Active Record, генерация кода и т. д.
  • yiisoft/yii2-swiftmailer: предоставляет функции отправки электронной почты на основе swiftmailer.
  • yiisoft/yii2-twig: предоставляет механизм шаблонов на основе Twig.