Так як все більше компонентів Laravel в ядрі Evo, то всі основні речі для розробки своїх доповнень так само як у Laravel, тому рекомендую спочатку ознайомитися з: https://laravel.com/docs/11.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.х використання чанків не має сенсу, тому що це все логічніше і простіше робити через 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:
evo()->runSnippet('example#test');
Також можна використовувати вкладені сніпети:
evo()->runSnippet('example#subdir\test');
Сніпети так само як і чанки не рекомендую для використання, тому що куди логічніше всю необхідну логіку вже писати в Контролерах
Як правильно створювати ТВ можна глянути у цьому простому прикладі: https://github.com/extras-evolution/choiceTV/
Назва tv має бути за шаблоном:
tvs/TVName/TVName.customtv.php
У рамках Evo 3.х та пакету вирішуємо питання просто переміщенням папки з кастомним ТВ у потрібну папку через додавання інструкції до сервіс-провайдера:
$this->publishes([__DIR__ . '/../assets/tvs/TVName' => public_path('assets/tvs/TVName')]);Далі після запуску команди artisan vendor:publish та вибору вказаного пакету всі файли скопіюються та все буде працювати
Додаємо до сервіс провайдера boot()
$this->loadTranslationsFrom(__DIR__.'/../lang', 'Main');Посилання на те, звідки брати переклади і який у них namespace. Далі в папці створюємо папки з мовами (en, ru, ітд.) і в них уже файли з перекладами
Після цього можемо використовувати в Blade:
@lang('Main::main.welcome')
посилання на ті, звідки брати переклади і який у них namespace. Далі в папці створюємо папки з мовами (en, ru, ітд.) і в них уже файли з перекладами
Після цього можемо використовувати Blade:
$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/11.x/packages#public-assets
Додаємо в сервіс провайдер boot:
$this->loadViewsFrom(__DIR__ . '/../views', 'Main');Після чого ми можемо використовувати шаблони Blade з урахуванням неймспейсів:
return \View::make('Main::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/11.x/packages#views
У цій папці у нас лежить всі файли які потрапляють в автолоад composer-а, в цілому це так само можна змінити якщо потрібно у файлі composer.json
Робота з конфігами така ж як у Laravel:
- https://laravel.com/docs/11.x/packages#configuration
- https://laravel.com/docs/11.x/packages#default-package-configuration
Ми можемо створити для пакета свої налаштування і після них додати в системні, щоб їх можна було змінювати.
Artisan – це інтерфейс командного рядка, включений до Evolutions CMS. Він надає ряд корисних команд, які можуть допомогти вам при створенні програми. Детальнішу інформацію ви можете знайти тут: https://laravel.com/docs/11.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/11.x/routing Також рекомендую ознайомитися з цим прикладом у якому створюємо форму і відправляємо її: https://gist.github.com/Dmi3yy/10e5a004bb77a72a4446ac1ad4c2d9ad
Якщо ви розумієте, що таке Middleware то і знаєте як з ними працювати :) Детальніше читаємо тут: https://laravel.com/docs/11.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/11.x/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
Все тепер можна встановлювати пакет і використовувати його.