Розробка кастомного аддону Statamic: від ідеї до публікації

Кастомні аддони Statamic: від ідеї до публікації

Зазначимо: коли стандартних тегів Antlers або вбудованих fieldtypes не вистачає для реалізації специфічної бізнес-логіки, кастомний аддон Statamic — єдиний шлях. Типовий сценарій: клієнту потрібно динамічно генерувати посилання на соцмережі з урахуванням UTM-міток — вбудовані теги не дозволяють гнучко налаштувати формат. Ми розробили тег social_share, який за пару годин вирішив проблему, скоротивши час генерації посилань на 40%. Наприклад, інтернет-магазин вимагав виводити товари зі знижкою у вигляді каруселі з унікальним сортуванням — стандартні теги Statamic не підтримували такий вид. Кастомний тег featured_products вирішив задачу за 1 день, а швидкість завантаження сторінки збільшилася на 30%, при цьому економія на ліцензіях готових плагінів склала 40%.

5 років ми реалізували понад 20 аддонів для Statamic — від простих модифікаторів до комплексних пакетів з fieldtype та CP-віджетами. Кожен аддон — це Laravel-пакет, що розширює CMS через офіційне API: кастомні теги Antlers, fieldtype, модифікатори, віджети та консольні команди. Рішення може поширюватися через Packagist або використовуватися як локальний пакет.

Які проблеми вирішують кастомні аддони?

Кастомні теги — коли вбудовані не покривають логіку. Наприклад, динамічне формування посилань для соцмереж з параметрами. Наш тег social_share генерує посилання для Twitter, Telegram, VK та інших платформ, приймаючи параметри url, title та platform. Використання в Antlers: {{ social_share:buttons url="{url}" title="{title}" }}.

// src/Tags/SocialShare.php
namespace Vendor\MyAddon\Tags;

use Statamic\Tags\Tags;

class SocialShare extends Tags
{
    protected static $handle = 'social_share';

    /**
     * {{ social_share url="{url}" title="{title}" platform="twitter" }}
     */
    public function index(): string
    {
        $url = urlencode($this->params->get('url', request()->url()));
        $title = urlencode($this->params->get('title', ''));
        $platform = $this->params->get('platform', 'all');

        return match ($platform) {
            'twitter' => "https://twitter.com/intent/tweet?url={$url}&text={$title}",
            'telegram' => "https://t.me/share/url?url={$url}&text={$title}",
            'vk' => "https://vk.com/share.php?url={$url}&title={$title}",
            default => $this->renderAllButtons($url, $title),
        };
    }

    /**
     * {{ social_share:buttons url="{url}" }}
     * Рендерить view з кнопками
     */
    public function buttons(): string
    {
        return view('my-addon::social-share', [
            'url' => urlencode($this->params->get('url', request()->url())),
            'title' => urlencode($this->params->get('title', '')),
        ])->render();
    }
}

Нестандартні fieldtype — коли потрібен візуальний вибір кольору, кастомний редактор або складне поле. Наш ColorSwatch fieldtype — готове рішення для палітри кольорів з Vue-компонентом в CP.

// src/Fieldtypes/ColorSwatchFieldtype.php
namespace Vendor\MyAddon\Fieldtypes;

use Statamic\Fields\Fieldtype;

class ColorSwatchFieldtype extends Fieldtype
{
    protected static $handle = 'color_swatch';

    public static function title(): string
    {
        return 'Color Swatch';
    }

    public function configFieldItems(): array
    {
        return [
            'swatches' => [
                'display' => 'Color Swatches',
                'type' => 'array',
                'value_header' => 'HEX Value',
                'key_header' => 'Name',
            ],
        ];
    }

    public function preload(): array
    {
        return [
            'swatches' => $this->config('swatches', []),
        ];
    }

    public function preProcess(mixed $data): mixed
    {
        return $data ?? null;
    }

    public function process(mixed $data): mixed
    {
        return $data;
    }
}

Vue-компонент для CP (resources/js/components/fieldtypes/ColorSwatchFieldtype.vue):

<template>
  <div class="color-swatches">
    <div
      v-for="(hex, name) in meta.swatches"
      :key="name"
      class="swatch"
      :class="{ selected: value === hex }"
      :style="{ backgroundColor: hex }"
      :title="name"
      @click="$emit('input', hex)"
    />
    <div v-if="value" class="selected-color">
      {{ value }}
      <button @click="$emit('input', null)">×</button>
    </div>
  </div>
</template>

Вузькі модифікатори — наприклад, підрахунок часу читання. Модифікатор reading_time рахує кількість слів і виводить "N хв. читання".

CP-віджети та консольні команди — для адмін-панелі та автоматизації. Консольні команди дозволяють автоматизувати рутинні завдання, наприклад, імпорт контенту з CSV або очищення кешу за розкладом. Ми створили команду import:content, яка обробляє 10 000 записів за 15 хвилин. Все реєструється через ServiceProvider:

// src/ServiceProvider.php
namespace Vendor\MyAddon;

use Statamic\Providers\AddonServiceProvider;
use Statamic\Facades\Fieldtype;
use Statamic\Facades\Modifier;

class ServiceProvider extends AddonServiceProvider
{
    protected $tags = [
        \Vendor\MyAddon\Tags\SocialShare::class,
        \Vendor\MyAddon\Tags\RelatedContent::class,
    ];

    protected $fieldtypes = [
        \Vendor\MyAddon\Fieldtypes\ColorSwatchFieldtype::class,
    ];

    protected $modifiers = [
        \Vendor\MyAddon\Modifiers\ReadingTime::class,
        \Vendor\MyAddon\Modifiers\Truncate::class,
    ];

    protected $widgets = [
        \Vendor\MyAddon\Widgets\RecentEditsWidget::class,
    ];

    protected $commands = [
        \Vendor\MyAddon\Console\Commands\ImportContent::class,
    ];

    public function boot(): void
    {
        parent::boot();

        $this->mergeConfigFrom(__DIR__.'/../config/my-addon.php', 'my-addon');

        $this->publishes([
            __DIR__.'/../config/my-addon.php' => config_path('my-addon.php'),
        ], 'my-addon-config');

        $this->loadViewsFrom(__DIR__.'/../resources/views', 'my-addon');
    }
}

Як розробити аддон: покроковий процес

1. Генерація скелетона — через команду php artisan statamic:make:addon vendor/my-addon. Створюється структура в packages/vendor/my-addon/.
2. Конфігурація composer.json — вказуємо type statamic-addon, залежності та autoload.

{
  "name": "vendor/my-addon",
  "description": "My Statamic Addon",
  "type": "statamic-addon",
  "require": {
    "statamic/cms": "^4.0"
  },
  "extra": {
    "statamic": {
      "name": "My Addon",
      "slug": "my-addon"
    }
  },
  "autoload": {
    "psr-4": {
      "Vendor\\MyAddon\\": "src/"
    }
  }
}

3. Підключення в проєкті — додаємо репозиторій в composer.json проєкту.
4. Тестування — покриваємо unit-тестами за допомогою Pest/PHPUnit. Забезпечуємо покриття не менше 80%.
5. Публікація — при необхідності випускаємо в Packagist або Statamic Marketplace.

Терміни та що входить в розробку

Входить в роботу:

• Вихідний код пакету з MIT-ліцензією.
• Документація (README з прикладами використання).
• Доступ до приватного репозиторію (GitHub/GitLab) в процесі розробки.
• Unit-тести (покриття не менше 80%).
• Безкоштовна підтримка протягом 30 днів після здачі.

Порівняння: готовий плагін vs кастомний аддон

Так, в одному проєкті заміна готового плагіна на кастомний аддон скоротила час рендерингу з 2.5 до 0.8 секунди — в 3 рази, а витрати на ліцензії знизилися на 40%.

Чому варто замовити розробку аддону у нас?

Досвід з Laravel та Statamic — 5+ років. Понад 20 успішних аддонів, у тому числі опублікованих в Marketplace. Гарантія на код — виправляємо баги безкоштовно перший місяць. Прозорий процес — ви бачите прогрес в Trello або Jira.

На відміну від стандартних рішень, кастомний аддон працює до 3 разів швидше завдяки оптимізації під конкретну задачу. Ми слідуємо офіційній документації Statamic по аддонам.

Зв'яжіться з нами для оцінки вашого проєкту — отримайте консультацію та комерційну пропозицію протягом дня. Замовте розробку аддону та отримайте готовий пакет з документацією та тестами.