Конфигурационные файлы

Содержание...

Конфигурационные файлы должны храниться в поддиректории приложения lib/config/.

app.php

Файл app.php — это главный конфигурационный файл приложения. В нем задаются название приложения, путь к иконке, номер версии, признак наличия фронтенда и другие параметры.

Пример
<?php
  
return [
    'name'     => 'My app',
    'img'      => 'img/myapp.png',
    'rights'   => true,
    'frontend' => true,
    'version'  => '1.0.0',
];

Список некоторых параметров в файле app.php:

  • name — название приложения, обязательный параметр. Это название видно в главном меню выбора приложений в бекенде. Если приложение многоязычное, то в качестве названия нужно ключ локализации для строки, которая будет автоматически переведена на каждый из поддерживаемых языков.
  • img — относительный путь к файлу иконки приложения — от корня директории приложения. Иконка видна рядом с названием приложения в главном меню бекенда. Изображение иконки должно быть размером 48x48 пикселей. Параметр img — необязательный. Если он не указан, то файл с иконкой должен быть размещен по стандартному пути: img/[app_id].png.
  • icon — массив путей к файлам дополнительных иконок различного размера. Используется вместо параметра img в тех случаях, когда иконки нескольких размеров представлены отдельными файлами. Иконки размеров 24х24 и 16х16 используются для интеграции с приложением «Сайт». Если отдельных файлов иконок нет, то используется стандартная иконка размером 48х48, которая масштабируется браузером.

    Пример: 
    'icon' => [
    48 => 'img/site.png',
    24 => 'img/site24.png',
    16 => 'img/site16.png'
],
  • prefix — префикс названий таблиц приложения в базе данных. Необязательный параметр. Значение по умолчанию — идентификатор приложения app_id.
  • rights — флаг, обозначающий, используются ли в приложении расширенные настройки доступа. Необязательный параметр. Значение по умолчанию: false. Подробнее о системе разграничения прав написано в статье «Права доступа».
  • frontend — флаг, обозначающий, есть ли у приложения фронтенд. Необязательный параметр. Значение по умолчанию: false.
  • version — номер версии приложения.
  • sash_color — обозначение цвета маркера приложения для записей в «Ленте событий» Webasyst.
  • vendor — идентификатор разработчика Webasyst, обязателен для публикации приложения в магазине Webasyst­.
  • routing_params — массив дополнительных параметров, которые применяются по умолчанию при добавлении для правила маршрутизации приложения в структуре сайта. По умолчанию правило создается публично доступным.

    Пример параметра для создания скрытого правила маршрутизации приложения: 
    'routing_params' => [
    'private' => true,
],

db.php

В файле db.php описывается структура таблиц приложения:

[
    'table1' => [
        'field1' => [ТИП_ПОЛЯ,  ДОПОЛНИТЕЛЬНЫЕ ПАРАМЕТРЫ...],
        'field2' => [ТИП_ПОЛЯ,  ДОПОЛНИТЕЛЬНЫЕ ПАРАМЕТРЫ...],
        ...
    ],
    'table2' => [ 
        ...
    ]
];

Он используется для создания таблиц при установке приложения.

Типы полей — стандартные для MySQL строковые обозначения 'int', 'varchar', 'text', 'datetime' и т. д.

Пример

<?php

return [
    'myapp' => [
        'id' => ['int', 11, 'null' => 0, 'autoincrement' => 1],
        'contact_id' => ['int', 11, 'null' => 0, 'default' => '0'],
        'name' => ['varchar', 255, 'null' => 0, 'default' => ''],
        'text' => ['text', 'null' => 0],
        'datetime' => ['datetime', 'null' => 0],
        ':keys' => [
            'PRIMARY' => 'id',
            'datetime' => 'datetime',
        ],
    ],
];

Формировать такой файл вручную не нужно. Удобнее его сгенерировать его консольной командой из уже существующих таблиц, которые вы создали для разработки приложения средствами СУБД. Если структура таблиц изменилась в ходе разработки, обновлять этот файл тоже можно с помощью консольной команды.

routing.php

Файл routing.php задает правила маршрутизации HTTP-запросов для фронтенда приложения.

Пример

<?php

return [
    'post/[i:id]/?'      => 'frontend/post',
    'comment/add/[i:id]' => 'frontend/addComment'
    'rss/?'              => 'frontend/rss',
    ''                   => 'frontend',
    '[s:url]/?'          => 'frontend/post'
];

Подробнее о маршрутизации во фронтенде написано в статье «Маршрутизация HTTP-запросов».

logs.php

В файл logs.php перечисляется список действий пользователей приложения, которые должны записываться в системный журнал действий.

Пример

<?php
  
return [
    'board_add'            => [],
    'board_edit'           => [],
    'board_delete'         => [],
    'sticky_add'           => [],
    'sticky_edit'          => [],
    'sticky_move_to_board' => [],
    'sticky_delete'        => [],
];

Подробнее читайте в статье «Журнал действий пользователя».

factories.php

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

В файле должен содержаться ассоциативный PHP-массив. Ключами массива должны быть имена параметров, которые нужно переопределить; значениями — новые значения для этих параметров.

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

Параметры, которые можно переопределять:

  • 'front_controller' — имя класса фронт-контроллера для обработки запросов к бекенду приложения; по умолчанию используется класс waFrontController.
  • 'default_controller' — имя класса контроллера по умолчанию, который обрабатывает запросы к классам экшенов; по умолчанию используется класс waDefaultViewController.
  • 'view' — имя класса шаблонизатора для формирования HTML-кода веб-страниц; по умолчанию используется класс waSmarty3View. Параметры, которые можно передать в конструктор стандартного класса:
    • 'auto_literal' — нужно ли игнорировать теги Smarty, если они окружены пробелами; значение по умолчанию — true.
    • 'left_delimiter' — набор символов, использующихся в качестве левого ограничителя для тегов Smarty; значение по умолчанию — символ {.
    • 'right_delimiter' — набор символов, использующихся в качестве правого ограничителя для тегов Smarty; значение по умолчанию — символ }.
    • 'template_dir' — путь к директории, внутри которого содержится поддиректория templates/ с файлами HTML-шаблонов приложения; по умолчанию используется основная директория с исходными файлами приложения.
    • 'compile_dir' — путь к директории, в которой должны сохраняться скомпилированные файлы HTML-шаблонов; по умолчанию используется директория wa-cache/apps/[app_id]/templates/compiled/.
  • 'captcha' — имя класса для формирования капчи; по умолчанию используется класс waCaptcha. Массив параметров для конструктора класса капчи зависит от указанного класса. Параметры для стандартного класса waCaptcha:
    • 'chars' — строка символов, из которых должен формироваться текст капчи; по умолчанию используются символы строки 'abdefhknrqstxyz23456789'.
    • 'fonts' — массив строк с именами файлов шрифтов, которые должны выбираться в случайном порядке для формирования текста капчи; по умолчанию используется шрифт DroidSans. Файлы шрифтов должны размещаться в директории wa-system/captcha/data/.
    • 'width' — ширина капчи в пикселях; по умолчанию — 120.
    • 'height' — высота капчи в пикселях; по умолчанию — 40.
    • 'font_size' — размер шрифта в единицах "pt"; по умолчанию — 25.
    • 'background' — имя графического файла для формирования фона изображения капчи. Файл должен размещаться в директории wa-system/captcha/data/; по умолчанию фон белый, без изображения.
Пример

Переопределение формата скобок (двойные вместо стандартных одинарных) в HTML-шаблонах для тегов Smarty.

<?php
  
return [
    'view' => [
        'waSmarty3View',
        [
            'left_delimiter'  => '{{',
            'right_delimiter' => '}}',
        ]
    ],
];

Файл конфигурации расширенных прав доступа

Для конфигурирования расширенных прав нужно объявить класс, унаследованный от waRightConfig. PHP-файл класса должен иметь имя вида [app_id]RightsConfig.class.php. Пример для приложения guestbook — guestbookRightConfig.class.php:

<?php 

class guestbookRightConfig extends waRightConfig
{
    public function init()
    {
          $this->addItem('delete', 'Can delete posts', 'checkbox');
    }
}

Пользовательские конфигурационные файлы

Файлы стандартной конфигурации

У приложения могут быть и любые собственные конфигурационные файлы для хранения любых параметров, необходимых для его работы. Все конфигурационные файлы приложения рекомендуется хранить в директории wa-apps/[app_id]/lib/config/. Удобный способ хранения конфигурационных данных — это PHP-файл, в котором выполняется массив значений.

Массив — не единственный возможный способ хранения конфигурационных данных в PHP-файле. Разработчик каждого приложения может самостоятельно определять формат данных и способ их чтения. Например, содержимое конфигурационного файла может содержать класс либо результат работы функций serialize() и json_encode().

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

Простой пример конфигурационного файла statuses.php со списком статусов:

<?php

return [
    'new',
    'discussion',
    'closed',
    'reopened',
    'canceled',
    'deleted',
];

Для того чтобы считать содержимое файла, удобно использовать метод wa()->getConfig()->getConfigPath('filename.php', false, 'myapp').

В качестве аргумента $config нужно указать имя конфигурационного без расширения .php.

Пример

$default_statuses = wa()->getConfig()->getConfigPath('statuses.php', false, 'myapp');

Такой код вернет путь к файлу wa-apps/myapp/lib/config/statuses.php.

Файлы пользовательской конфигурации

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

Пользовательские параметры, значения которых не затрагиваются обновлениями, нужно хранить в конфигурационных файлах в директории wa-config/apps/[app_id]/. Чтобы получить путь к файлу в этой директории, используйте метод wa()->getConfig()->getConfigPath('filename.php', true, 'myapp').

Пример

$user_statuses = wa()->getConfig()->getConfigPath('statuses.php', true, 'myapp');

Такой код вернет путь к файлу wa-config/apps/myapp/statuses.php.