Developers / Modules

Как создавать модули для LaIOT

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

Перейти к загрузке модуля Открыть каталог

Коротко

Формат поставки: zip или Git

Manifest: обязателен `module.php`

Документация: только `Docs/*.md`

Публикация: после фоновой проверки и ручной модерации

Шаг 1

Подготовить структуру модуля

В корне архива должен лежать `module.php`, а папки и файлы модуля должны быть упакованы без лишнего внешнего уровня.

Шаг 2

Заполнить module.php

Указать `code`, `version`, `name`, `category`, `description`, зависимости и служебные пути.

Шаг 3

Добавить Docs/*.md

Документация для карточки модуля подтягивается только из markdown-файлов внутри `Docs`. PHP-файлы оттуда не исполняются.

Шаг 4

Собрать zip или подготовить Git URL

Публикация поддерживает ручную загрузку zip-архива или импорт из Git-репозитория.

Шаг 5

Отправить модуль через кабинет

Система проверит структуру, категорию, checksum и подпишет релиз перед ручной модерацией в админке.

Структура архива

Что должно лежать в модуле

Ниже пример рекомендуемой структуры по реальному модулю. В корне обязательно должен лежать `module.php`. Папка `Docs` может содержать markdown-документацию, а `index.php` внутри неё допустим только как часть поставки, но не выполняется маркетом.

Backups/
|-- module.php
|-- Commands/
|   `-- RunScheduledDatabaseBackupCommand.php
|-- Docs/
|   |-- index.php
|   `-- overview.md
|-- Livewire/
|   `-- Admin/
|       `-- Dashboard.php
|-- Providers/
|   `-- BackupsServiceProvider.php
|-- Resources/
|   |-- assets/
|   |   `-- backup.png
|   `-- views/
|       `-- livewire/
|           `-- admin/
|               `-- dashboard.blade.php
|-- routes/
|   `-- admin.php
`-- Services/
    |-- BackupManager.php
    |-- BackupRestoreService.php
    `-- BackupSettings.php

Категории

Актуальные категории из админки

device Устройства

Модули для взаимодействия с устройствами или обеспечивающие транспорт информации от устройств в систему и обратно.

automatization Автоматизация

Модули позволяющие автоматизировать процессы в системе

interface Интерфейс

Модули расширяющие возможности интерфейсов системы

access Доступ и права

Модули расширяющие возможности авторизации и контроля доступа

system Система

Модули обеспечивающие расширение возможностей системы и предназначенные в основном для администраторов.

В `module.php` можно указывать `slug` категории. Для совместимости маркет также принимает точное имя категории, но внутри нормализует его в `slug`.

Обязательные поля

Минимальный контракт manifest

code

Уникальный системный код модуля в slug-формате.

version

Обязательная версия в semver-формате.

name

Название модуля для каталога.

Базовый manifest модуля

<?php

use App\Modules\Backups\Livewire\Admin\Dashboard;
use App\Modules\Backups\Providers\BackupsServiceProvider;

return [
    'code' => 'backups',
    'version' => '0.1.0',
    'name' => 'Бекапы',
    'description' => 'Резервные копии базы данных, расписание и восстановление в один клик.',
    'category' => 'system',
    'requires' => [
        'core' => '^0.1',
        'composer' => [
            ['name' => 'spatie/laravel-backup', 'constraint' => '9.4'],
        ],
    ],
    'icon' => 'Resources/assets/backup.png',
    'routes' => [
        'admin' => 'routes/admin.php',
    ],
    'views' => [
        'path' => 'Resources/views',
        'namespace' => 'backups',
    ],
    'providers' => [
        BackupsServiceProvider::class,
    ],
    'livewire' => [
        'admin.backups.dashboard' => Dashboard::class,
    ],
];

Документация

Как модуль попадает в карточку маркета

Маркет ищет документацию только в `Docs/*.md`.

Если найдено несколько markdown-файлов, в качестве главного документа приоритетно используются `overview.md`, `readme.md`, затем `index.md`.

`Docs/index.php` и другие PHP-файлы не исполняются и не участвуют в рендеринге документации на сайте.

Публикация

Что происходит после отправки

1. Архив или Git-источник уходит в фоновую обработку.

2. Система безопасно распаковывает модуль и проверяет структуру, category, версию и документацию.

3. Считается checksum и создается подпись нашим ключом.

4. Релиз попадает на ручное подтверждение в админку.

5. После публикации модуль появляется в каталоге и в API маркета для клиентских систем.