Так как все больше компонентов Laravel в ядре Evo, то все основные вещи для разработки своих дополнений так же как в Laravel, поэтому настоятельно рекомендую сначала ознакомится с : https://laravel.com/docs/8.x/packages Так же не сильно сложно портировать дополнения для Laravel в Evolution CMS, почти всегда это чисто косметические правки и допиливание уже под свои нужды.
- Install
- Package structure
- Assets
- Lang
- Migrations
- Seeders
- Public
- Views
- src
- Как опубликовать свой пакет?
- Как мигрировать старые дополнения в EVO 3.0
Выполнить из папки core:
-
php artisan package:installrequire evolution-cms/example-package "*"
- необходимо что б пакет был зарегистирован на сайте packagist.org -
php artisan vendor:publish --provider="EvolutionCMS\Example\ExampleServiceProvider"
- если используется копирование файлов публичных и конфигов -
php artisan migrate
- если используются миграции -
php artisan db:seed --class=ExampleSeeder
- если используются сиды
Рекомендованная структура папок:
- Assets: для привычной структуры, в целом нам нужны только плагины и модули и можно вынести в корень, сниппеты и чанки могут понадобиться только для того что б мигрировать старые дополнения
- Lang: для мультиязычности
- Migrations: для миграций, в целом это для создания таблиц, но можно так же делать и другие действия, к примеру через миграции можно создавать шаблоны, тв, документы
- Seeders: для заполнения контентом, создания тв, шаблонов
- Public: все файлы которые нужны публично, в основном js, css, картинки
- Views: для шаблонов Blade
- src: тут все что попадает в автолоад composer-a -config: Файлы которые содержать настройки -Console: для консольных команд которые можно запускать через artisan или через cron -Controllers: тут создаем контроллеры -Http: тут фаил с кастомным роутингом -Middleware: создаем свои Middleware если нужно -Models: для моделек если создаем какие то таблицы или переопределяем работу уже готовых моделей
В целом структуру папок пакета можно менять под себя, данный пример носит рекомендованный характер
Ниже описание как работать с тем что лежит в папке assets
Есть возможность создавать чанки в файлах, можно глянуть тут: assets/chunks/
Для того что б чанки попали в систему нужно добавить в сервис провайдере в register из загрузку:
$this->loadChunksFrom(
dirname(__DIR__) . '/assets/chunks/',
$this->namespace
);
Далее можем использовать где нам нужно обращаясь к чанку по имени: namespace#chunkname:
$modx->getChunk('example#test');
Так же можно чанки складывать по папкам вложенны:
$modx->getChunk('example#subdir\test');
В целом в 3.0 использование чанков не имеет смысла, так как это все логичней и проще делать через Blade
Для того что б модуль появился в Админке его необходимо зарегистировать добавив в сервис провайдере в метод register:
$this->app->registerModule('Module from file', dirname(__DIR__).'/assets/modules/module/module.php');
ID модуля это md5('Название модуля') - это даст возможность сделать ссылку на модуль, так как модуль не создается в базе и соответственно цифрового id у него нет.
Плагины так же можно создавать в файлах и их нужно регистировать в сервиспровайдере:
//this code work for add plugins to Evo
$this->loadPluginsFrom(
dirname(__DIR__) . '/assets/plugins/'
);
Пример можно глянуть тут: assets/plugins/
Снипеты так же можно создавать в файлах и их нужно регистировать в сервиспровайдере:
$this->loadSnippetsFrom(
dirname(__DIR__). '/assets//snippets/',
$this->namespace
);
Пример можно глянуть тут: example/snippets/
Если используется namespace в пакете то название сниппета необходимо писать так же с ним: namespace#snippetname:
$modx->runSnippet('example#test');
Так же можно использовать вложенные сниппеты:
$modx->runSnippet('example#subdir\test');
Сниппеты так же как и чанки не рекомендую для использования, так как куда логичней всю необходимую логику уже писать в Контроллерах
Как правильно создавать ТВ можно глянуть в этом простом примере: https://github.com/extras-evolution/choiceTV/
Название tv должно быть по шаблону:
tvs/TVName/TVName.customtv.php
В рамках Evo 3.0 и пакета решаем вопрос просто перемещением папки с кастомным ТВ в нужную папку через добавление инструкции в сервиспровайдер:
$this->publishes([__DIR__ . '/../assets/tvs/TVName' => public_path('assets/tvs/TVName')]);
Далее после запуска команды artisan vendor:publish и выбора указанного пакета все файлы скопируются и все будет работать
Добавляем в сервис провайдере в boot()
$this->loadTranslationsFrom(__DIR__.'/../lang', 'example');
ссылку на то откуда брать переводы и какой у них namespace. Далее в папке создаем папки с языками( en, ru, итд.) и в них уже файлы с переводами
После можем использовать в Blade:
@lang('example::main.welcome')
Все работает точно так же как и в Laravel https://laravel.com/docs/8.x/migrations
Создаем фаил миграции в папке миграций и прописываем подключение пути для миграций в сервис провайдере:
$this->loadMigrationsFrom(__DIR__ . '/../migrations');
После установки дополнения выполням команду php artisan migrate
Создаем сид в папке seeders, добавляем запись о переносе в сервис-провайдер:
$this->publishes([__DIR__ . '/../seeders' => EVO_CORE_PATH . 'database/seeders']);
После установки выполням команду php artisan db:seed --class=ExampleSeeder
Данная папка содержит все что нужно для фронтовой части: css, js, images.
Добавляем в сервиспровайдере запись о том что нам нужно перенести:
$this->publishes([__DIR__ . '/../public' => public_path('assets/vendor/example')]);
А в BLade прописываем уже пути согласно тому куда файлы будут перемещены, для их перемещения используется команда artisan vendor:publish
Больше информации можно найти тут: https://laravel.com/docs/8.x/packages#public-assets
Добавляем в сервис провайдер в boot:
$this->loadViewsFrom(__DIR__ . '/../views', 'example');
После чего мы можем использовать шаблдоны blade c учетом неймспейсов:
return \View::make('example::example', ['data'=>'1']);
Если же нам нужно внести изменения в шаблон blade то создаем фаил в основном месте views создав там папку vendor и в ней папку с названием пакета :
/views/vendor/example/example.blade.php
Так же планируется всегда изменения базовых шаблонов из пакета то можно сразу перенести их в нужное место:
$this->publishes([__DIR__.'/../views' => public_path('views/vendor/example')]);
Детальней читаем в документации Laravel: https://laravel.com/docs/8.x/packages#views
В этой папке у нас лежит сервиспровайдер а так же все файлы которые попадают в автолоад composer-а, в целом это так же можно изменить если нужно в файле composer.json
Работа с конфигами такая же как в Laravel:
- https://laravel.com/docs/8.x/packages#configuration
- https://laravel.com/docs/8.x/packages#default-package-configuration
Мы можем создать для пакета свои настройки и после их добавить в системные что б их можно было изменять
Artisan - это интерфейс командной строки, включенный в Evolutions CMS. Он предоставляет ряд полезных команд, которые могут помочь вам при создании приложения. Более подробную информацию вы можете найти здесь: https://laravel.com/docs/8.x/artisan
запустить php artisan из папки core:
php artisan
для того что б увидеть все команды
Создаем фаил: core/custom/packages/example/src/Console/ExampleCommand.php
<?php
namespace EvolutionCMS\Example\Console;
use Illuminate\Console\Command;
class ExampleCommand extends Command
{
protected $signature = 'example:examplecommand';
protected $description = 'ExampleCommand';
public function __construct()
{
parent::__construct();
$this->evo = EvolutionCMS();
}
public function handle()
{
echo 'Hello Word';
}
}
Добавляем в сервис провайдере: core/custom/packages/example/src/ExampleServiceProvider.php
//добавить после строки: protected $namespace
protected $commands = [
'EvolutionCMS\Example\Console\ExampleCommand',
];
Также в методе register нашего сервис провайдера указываем:
//регистрация команд для artisan
$this->commands($this->commands);
Теперь можно использовать:
php artisan example:examplecommand
Данный функционал удобен для задач которые необходимо выполнять по крону или долгие и проще через консоль что б не было лимитов на время выполнения, которые обычно есть если выполняем какие то работы через браузер.
Контроллеры создаем в папке src/Controllers Можно глянуть примеры которые есть в текущем пакете.
Контроллеры гараздо удобней в использовании чем снипеты для основной работы. Но думаю те кто уже дошел до OOP и MVC понимают зачем это надо если нет то гуглим OOP, MVC и изучаем
Для использования кастомны роутингов (например ajax ответы) добавляем в сервиспровайдер boot():
include(__DIR__.'/Http/routes.php');
Как работать с роутингом читаем тут: https://laravel.com/docs/8.x/routing Так же рекомендую ознакомится с вот этим примером в котором создаем форму и отправляем ее: https://gist.github.com/Dmi3yy/10e5a004bb77a72a4446ac1ad4c2d9ad
Если вы понимаете что такое Middleware то и знаете как с ними работать :) Детальней читаем тут: https://laravel.com/docs/8.x/middleware
Из системных на текущий момент есть CheckAuthToken: https://github.com/evolution-cms/evolution/blob/3.x/core/src/Middleware/CheckAuthToken.php (удобно использовать если дружим EVO 3.0 c SPA)
Route::middleware(['EvolutionCMS\\Middleware\\CheckAuthToken'])->group(function () {
Route::get('/secureuserinfo', [EvolutionCMS\Example\Controllers\ExampleApiController::class, '`getInfo`']);
});
Модельки складываем в папку: src/Models Можно глянуть какие есть уже модели в Evo по умолчанию: https://github.com/evolution-cms/evolution/tree/3.x/core/src/Models all works same https://laravel.com/docs/6.0/eloquent
Опубликовать для того что б можно было найти в консольном extras который появился в evo 3.0, сделали так что б можно было скриптами настраивать установку EVO c любым набором дополнений без ручного добавления оных.
- Создаем пакет на Github (можно клонировать текущий), используем префикс evocms- в названии пакета, или как минимум пишем Evocms в файле composer.json в теге description. Это поможет находить все пакеты которые доступны для установки через Composer и сделанны для Evolution CMS https://packagist.org/?query=evocms
- Регистрируем на сайте https://packagist.org (в целом это работает для любого php решения)
- Пишем мне письмо на почту dmi3yy@evo.im если хотите что б было дополнение доступно Evo artisan Extras: я сколонирую в один из репозиториев для того что б было удобней следить и дополнять:
- https://github.com/evolution-cms-extras - используется для готовых к использованию компонентов
- https://github.com/evolution-cms-packages - используются как заготовки для того что б дальше на базе них создавать сайт
Активных авторов буду приглашать в команду evolution-cms-extras и evolution-cms-packages что б сами могли дополнять и развивать дополнения.
В целом изучив данные пример вы уже должны понимать как это сделать.
###№ Но если вы хотите сделать все быстро, но халтурно что б дополнение появилось в Evo artisan Extras то проще всего глянуть как я мигрировал DocLister:
- Создал composer.json фаил: https://github.com/evolution-cms-extras/DocLister/blob/master/composer.json
- Создал сервис провайдер: https://github.com/evolution-cms-extras/DocLister/blob/master/src/DocListerServiceProvider.php
- Перенес из папки инстал снипеты в пакет так что б они сразу работали (тут важно что б пакет был с пустым namespace): https://github.com/evolution-cms-extras/DocLister/tree/master/snippets
- Опубликовал пакет как описано выше: Publish package
Все, теперь можно устанавливать пакет и использовать его.