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

Введение

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

Список изменений содержится в YAML файле, который называется version.yaml, и находится в плагине в папке /updates. Там же располагаются файлы с миграциями и начальными данными. Пример структуры плагина:

plugins/
  author/
    myplugin/
      updates/                      <=== Папка с обновлениями
        version.yaml                <=== Файл с версиями
        create_tables.php           <=== Скрипт БД
        seed_the_database.php       <=== Файл миграции
        create_another_table.php    <=== Файл миграции

Процесс обновления

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

  1. Когда администратор авторизовался.
  2. Когда администратор нажал на кнопку "Обновить".
  3. Когда была вызвана консольная команда php artisan october:up.

Зависимости плагинов

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

<?php namespace Acme\Blog;

class Plugin extends \System\Classes\PluginBase
{
    public $require = ['Acme.User'];
}

В приведенном выше примере плагин Acme.Blog не будет обновляться до тех пор, пока плагин Acme.User не будет полностью обновлен.

Файл с версиями плагина

Файл version.yaml содержит версии плагина и комментарии к ним, а также ссылки на скрипты базы данных в определенном порядке. Прочтите статью Структура базы данных для получения информации о файлах миграции. Этот файл нужен для публикации плагина в Marketplace. Пример:

1.0.1: First version
1.0.2: Second version
1.0.3: Third version
1.1.0: !!! Important update
1.1.1:
    - Update with a migration and seed
    - create_tables.php
    - seed_the_database.php

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

Важные обновления

Иногда изменения в плагине могут нарушить работу сайта, на котором он был установлен. Если комментарий в файле version.yaml начинается с трех восклицательных знаков (!!!), тогда он будет считаться Важным и потребует от пользователя подтверждения перед обновлением. Пример важного комментария к обновлению:

1.1.0: !!! This is an important update that contains breaking changes.

Когда система обнаружит важное обновление, она предложит три варианта:

  1. Подтвердить обновление
  2. Пропустить обновление (только один раз)
  3. Пропустить обновление (всегда)

Миграции и начальные данные

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

1.1.1:
    - This update will execute the two scripts below.
    - some_upgrade_file.php
    - some_seeding_file.php

Используйте snake_case для названия файлов и CamelCase для названия классов. Пример:

<?php namespace Acme\Blog\Updates;

use Schema;
use October\Rain\Database\Updates\Migration;

/**
 * some_upgrade_file.php
 */
class SomeUpgradeFile extends Migration
{
    ///
}