Spec-Zone.ru › Yii 2.0

Расширения

  1. Использование расширений
  2. Создание расширений
  3. Основные расширения

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

Информация: Мы используем термин «расширение» для обозначения пакетов программного обеспечения, специфичных для Yii. Для пакетов программного обеспечения общего назначения, которые могут использоваться без Yii, мы будем использовать термин «пакет» или «библиотека».

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

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

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

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

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

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

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

{
    // ...

    "require": {
        // ... other dependencies

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

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

Информация: yiisoft/yii2-imagine — это основное расширение, разработанное и поддерживаемое командой разработчиков Yii. Все основные расширения размещены в Packagist и имеют имена типа yiisoft/yii2-xyz, где xyz изменяется для разных расширений.

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

use Yii;
use yii\imagine\Image;

// generate a thumbnail image
Image::thumbnail('@webroot/img/test-image.jpg', 120, 120)
    ->save(Yii::getAlias('@runtime/thumb-test-image.jpg'), ['quality' => 50]);

Информация: Классы расширений автоматически загружаются с помощью автозагрузчика классов Yii.

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

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

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

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

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

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

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

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

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

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

composer.json

Каждый Composer-пакет должен иметь файл composer.json в своей корневой директории. Этот файл содержит метаданные о пакете. Вы можете найти полное описание этого файла в руководстве Composer. Следующий пример показывает файл 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\\": ""
        }
    }
}

Имя пакета

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

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

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

Тип пакета

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

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

Зависимости

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

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

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

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

Для получения более подробной информации об управлении активами, см. раздел Активы.

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

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

{
    // ....

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

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

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

Рекомендованные практики

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

Пространства имён

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

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

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

Классы инициализации

Иногда вы можете захотеть, чтобы ваше расширение выполняло код во время стадии инициализации приложения. Например, ваше расширение может реагировать на событие приложения 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 () {
             // do something here
        });
    }
}

Затем вы перечислите этот класс в файле composer.json вашего расширения следующим образом,

{
    // ...

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

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

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

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

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

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

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

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

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

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

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

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

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

Дополнительную информацию см. в разделе Локализация.

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

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

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

Версионирование

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

Выпуск

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

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

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

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

Информация: Комментарии к вашему коду можно писать в формате Markdown. Расширение yiisoft/yii2-apidoc предоставляет инструмент для генерации красивой документации API на основе ваших комментариев к коду.

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

Основные расширения

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

  • yiisoft/yii2-apidoc: предоставляет расширяемый и высокопроизводительный генератор документации API. Он также используется для генерации документации API основного фреймворка.
  • yiisoft/yii2-authclient: предоставляет набор часто используемых клиентов авторизации, таких как клиент Facebook OAuth2, клиент 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: предоставляет основанный на веб-приложении генератор кода, который легко расширяется и может использоваться для быстрого генерирования моделей, форм, модулей, 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.

© 2008–2017 by Yii Software LLC
Licensed under the three clause BSD license.
http://www.yiiframework.com/doc-2.0/guide-structure-extensions.html

Spec-Zone.ru

Настройки Оффлайн Что нового Помощь О нас
Spec-Zone .ru
спецификации, руководства, описания, API