Рубрики
Uncategorized

Yii путь практики – Расширение расширения

Автор оригинала: David Wong.

Набросок

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

Основы

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

Information: The term "extension" used in this article refers specifically to Yii software packages. The terms "package" and "library" are used to refer to software packages that are not Yii-specific in the general sense.

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

  1. Измените композитора. Файл JSON вашего приложения, чтобы указать, какое расширение вы хотите установить (пакет Composer).

  2. Запустите composer install, чтобы установить указанное расширение.

Обратите внимание, что если вы еще не установили Composer, вам необходимо сначала установить его.

По умолчанию 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-это базовое расширение, поддерживаемое командой разработчиков. Все основные расширения централизованно управляются Packagist и называются yiisoft/yii2-xyz. Xyz, который имеет разные имена для разных расширений.

Теперь вы можете использовать установленные расширения как часть приложения.

В следующем примере показано, как использовать класс yiiimagineImage, предоставляемый расширением yiisoft/yii2-imagine:

use Yii;
use yii\imagine\Image;

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

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

Расширение для Ручной Установки

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

  1. Загрузите расширенный сжатый файл и распакуйте его в каталог поставщика.

  2. Если это так, установите автоматический загрузчик, предоставляемый расширением.

  3. Следуйте инструкциям, чтобы загрузить и установить все зависимые расширения.

Если расширение не предоставляет загрузчик классов, но также соответствует стандарту PSR-4, вы можете использовать загрузчик классов, предоставляемый Yii, для загрузки расширенных классов. Все, что вам нужно сделать, это объявить корневой псевдоним для расширенного корневого каталога.

Например, если расширение установлено в каталоге поставщик/моя компания/мой ext, а пространство имен класса расширения-myext, вы можете включить следующий код в файл конфигурации приложения:

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

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

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

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

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

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

  2. В корневом каталоге проекта создайте файл с именем composer. JSON, который нужен композитору. Пожалуйста, обратитесь к следующим главам для получения подробной информации.

  3. Зарегистрируйте свои расширения в репозитории Composer, например Packagist, чтобы другие пользователи могли находить и устанавливать ваши расширения с помощью Composer.

composer.json В каждом пакете Composer должен быть композитор. Файл JSON в корневом каталоге. Этот файл содержит метаданные пакета.

Полные технические характеристики этого документа вы можете найти в Руководстве по составлению. В следующем примере показан файл composer.json с расширением yiisoft/yii2-image.

{
    // 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": "[email protected]"
        }
    ],

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

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

Имя пакета

Каждый пакет Composer должен иметь уникальное имя пакета, чтобы его можно было идентифицировать по другим пакетам. Формат имени пакета-Имя поставщика/Название проекта.

Например, в имени пакета yiisoft/yii2-imagine имя поставщика и название проекта-yiisoft и yii2-imagine соответственно.

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

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

Тип пакета

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

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

полагаться на

Ваши расширения зависят от Yii (конечно). Так что вы должны перечислить это в композиторе. Файл JSON (yiisoft/yii2).

Если ваши расширения зависят от других расширений или сторонних библиотек, вы также должны перечислить их вместе. Убедитесь, что вы также указали соответствующие ограничения версии для каждого зависимого пакета (например, 1. *, @stable). Когда вы выпускаете стабильную версию, пакеты, от которых вы зависите, также должны использовать стабильную версию.

Большинство пакетов JavaScript/CSS управляются Bower, а не Composer. Вы можете использовать Composer Assetplugin, чтобы позволить ему управлять такими пакетами через Composer. Если ваше расширение зависит от пакета Bower, вы можете просто перечислить его в зависимостях композитора. Файл JSON, как показано в следующем примере.

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

Приведенный выше код указывает, что расширение зависит от пакета jQuery Bower.

Вообще говоря, вы можете указать пакеты Bower в composer. JSON с bower – активом/именем пакета и пакетами NPM с NPM – активом/именем пакета.

When Compower installs Bower and NPM packages, the contents of the packages are installed by default under @vendor/bower/PackageName and @vendor/npm/Packages, respectively.

На эти два каталога также можно указать псевдонимы @bower/Имя пакета и @npm/Имя пакета соответственно.

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

{
    // ....

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

Вы можете перечислить одно или несколько корневых пространств имен и их каталоги файлов.

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

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

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

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

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

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

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

Загрузка классов

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

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

Для достижения этой цели вы можете создать так называемый класс начальной загрузки (bootstrapping class) для реализации интерфейса yiibaseBootstrapInterface.

Например:

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 автоматически создает экземпляр класса начальной загрузки и вызывает его метод yiibaseBootstrapInterface:: bootstrap () во время процесса начальной загрузки каждого запроса.

Операционная база данных

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

Если ваше расширение требует создания определенных таблиц базы данных или изменения структуры базы данных, вам следует

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

  • Сделайте файлы миграции максимально подходящими для разных СУБД.

  • Избегайте использования активной записи в файлах миграции.

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

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

  • Позвольте расширенным пользователям вручную копировать эти файлы ресурсов в определенные папки, доступные для чтения в Интернете;

  • Подтвердите пакет активов и автоматически скопируйте эти файлы (файлы, перечисленные в пакете активов) в папки, доступные для чтения в Интернете, с помощью механизма публикации активов.

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

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

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

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

  • Если расширение отображает числа, даты и т.д., вам следует отформатировать с помощью соответствующих правил форматирования в yii18nFormatter.

тест

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

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

контроль версий

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

Выпускать

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

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

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

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

  • Файл Readme в корневом каталоге: в нем описано, что делает ваше расширение и как его установить и использовать. Мы рекомендуем вам написать в формате Markdown и назвать файл readme. МЭРИЛЕНД.

  • Файлы журнала изменений в корневом каталоге: в нем перечислены изменения, внесенные в каждую версию. Этот файл может быть записан в корневой каталог Markdown и назван списком изменений. МЭРИЛЕНД.

  • Обновление файлов в корневом каталоге: в нем содержатся рекомендации по обновлению расширения с других версий. Этот файл может быть записан в корневой каталог Markdown и назван списком изменений. МЭРИЛЕНД.

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

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

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

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

Расширение Ядра

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

  • Yiisoft/yii2-apidoc: Предоставляет расширяемый и эффективный генератор документов API. С его помощью также создается документ API основной платформы.

  • Yiisoft/yii2-authclient: Предоставляет набор часто используемых клиентов аутентификации, таких как клиент Facebook OAuth2 и клиент GitHub OAuth2.

  • Yiisoft/yii2-bootstrap: Предоставляет набор виджетов, инкапсулирующих компоненты начальной загрузки и подключаемые модули.

  • Yiisoft/yii2-кодирование: Обеспечивает поддержку тестирования на основе концепции.

  • Yiisoft/yii2-отладка: Обеспечивает поддержку отладки приложений Yii. При использовании этого расширения панель инструментов отладки будет отображаться в нижней части каждой страницы. Расширение также предоставляет отдельную страницу для отображения более подробной отладочной информации.

  • Yiisoft/yii2-elasticsearch: Обеспечивает поддержку использования эластичного поиска. Он включает базовую поддержку запросов/поиска и реализует шаблон ActiveRecord, чтобы вы могли хранить активные записи в эластичном поиске.

  • Yiisoft/yii2-faker: Обеспечивает поддержку использования Faker для создания имитируемых данных для вас.

  • Yiisoft/yii2-gii: Предоставляет генератор кода на основе страниц с высокой масштабируемостью и может использоваться для быстрого создания моделей, форм, модулей, CRUD и т.д.

  • Yiisoft/yii2-imagine: Предоставляет общие функции обработки изображений на основе Imagine.

  • Yiisoft/yii2-jui: Предоставляет набор виджетов, инкапсулирующих пользовательский интерфейс jQuery и их взаимодействие.

  • Yiisoft/yii2-mongodb: Обеспечивает поддержку использования MongoDB. Он включает в себя основные запросы, записи действий, миграцию данных, кэширование, генерацию кода и другие функции.

  • Yiisoft/yii2-redis: Обеспечивает поддержку использования redis. Он включает в себя основные запросы, записи о действиях, кэширование и другие функции.

  • Yiisoft/yii2-smarty: Предоставляет механизм шаблонов на основе Smart.

  • Yiisoft/yii2-sphinx: Обеспечивает поддержку использования Sphinx. Он включает в себя основные запросы, записи действий, генерацию кода и другие функции.

  • Yiisoft/yii2-swiftmailer: Предоставляет функцию доставки почты на основе swiftmailer.

  • Yiisoft/yii2-twig: Предоставляет механизм шаблонов на основе веток.