Розробка кастомного модуля Drupal 10: хуки, сервіси, плагіни

На Drupal-проєкті виникла задача вивести кастомний список статей з посторінковою навігацією та кешуванням. Стандартний Views не дає гнучкості, а хаки в шаблоні перетворюють код на спагеті. Вихід — розробка кастомного модуля Drupal 10 з нуля, з продуманою архітектурою. Кастомна розробка модуля Drupal 10 вимагає знань хунків, сервісів та плагінів Drupal — це дозволяє гнучко розширювати функціонал: від унікальних блоків до інтеграції із зовнішніми REST API. Ми стикалися з такими задачами десятки разів і знаємо, як побудувати модуль від ідеї до продакшену — без болю та велосипедів. Це зекономить бюджет на етапі підтримки.

Які технічні проблеми вирішуємо

Хаотичне використання хунків без сервісного шару — найчастіша проблема при аудиті чужих модулів: N+1 запити в циклі, дублювання коду, неможливість перевикористовувати логіку. Друга за частотою — відсутність кешування або невірні теги кешу, через що сторінки завантажуються 5–7 секунд. Третя — процедурний код у .module-файлах об'ємом під тисячу рядків, який неможливо підтримувати.

Як уникнути N+1 запитів?

Замість того, щоб у циклі завантажувати кожну сутність по одній, використовуємо EntityStorageInterface::loadMultiple(): один запит на отримання ID, другий — на завантаження всіх сутностей. Це перетворює 20 запитів на 2. У наших модулях контролюємо це на рівні сервісного шару.

Чому DI-контейнер важливий?

Впровадження залежностей (DI) — стандарт Drupal. Згідно з Drupal API, кожен сервіс визначається в services.yml. Завдяки Dependency Injection код стає тестованим та замінним. Якщо потрібно замінити кеш з БД на Redis, змінюється один рядок у services.yml, а не весь код. DI скорочує час доопрацювань у 2–3 рази, а модулі на сервісах тестуються в 3 рази швидше.

Як проєктуємо архітектуру модуля

web/modules/custom/my_module/
├── my_module.info.yml
├── my_module.module
├── my_module.services.yml
├── src/
│   ├── Controller/
│   │   └── ArticleController.php
│   ├── Service/
│   │   └── ArticleService.php
│   ├── Plugin/Block/
│   │   └── RecentPostsBlock.php
│   └── EventSubscriber/
│       └── RequestSubscriber.php
└── templates/
    └── my-module-template.html.twig

Приклад: контролер з кешуванням

Реалізували API виведення статей з посторінковою навігацією та кешуванням тегами — клієнт позбувся ручної інвалідації кешу.

// src/Controller/ArticleController.php
namespace Drupal\my_module\Controller;

use Drupal\Core\Controller\ControllerBase;
use Drupal\Core\Entity\EntityTypeManagerInterface;
use Symfony\Component\DependencyInjection\ContainerInterface;
use Symfony\Component\HttpFoundation\JsonResponse;
use Symfony\Component\HttpFoundation\Request;

class ArticleController extends ControllerBase {

  public function __construct(
    private readonly EntityTypeManagerInterface $entityTypeManager,
  ) {}

  public static function create(ContainerInterface $container): static {
    return new static(
      $container->get('entity_type.manager'),
    );
  }

  public function list(): array {
    $storage = $this->entityTypeManager->getStorage('node');
    $ids = $storage->getQuery()
      ->condition('type', 'article')
      ->condition('status', 1)
      ->sort('created', 'DESC')
      ->range(0, 20)
      ->accessCheck(TRUE)
      ->execute();
    $nodes = $storage->loadMultiple($ids);
    $view_builder = $this->entityTypeManager->getViewBuilder('node');
    return [
      '#theme' => 'item_list',
      '#items' => array_map(
        fn($node) => $view_builder->view($node, 'teaser'),
        $nodes
      ),
    ];
  }

  public function apiList(Request $request): JsonResponse {
    $page = (int) $request->query->get('page', 0);
    $limit = min((int) $request->query->get('limit', 10), 100);
    $storage = $this->entityTypeManager->getStorage('node');
    $query = $storage->getQuery()
      ->condition('type', 'article')
      ->condition('status', 1)
      ->sort('created', 'DESC')
      ->range($page * $limit, $limit)
      ->accessCheck(TRUE);
    $ids = $query->execute();
    $nodes = $storage->loadMultiple($ids);
    $data = array_map(function ($node) {
      return [
        'id' => $node->id(),
        'uuid' => $node->uuid(),
        'title' => $node->getTitle(),
        'created' => $node->getCreatedTime(),
        'url' => $node->toUrl()->setAbsolute()->toString(),
        'summary' => $node->get('body')->summary,
      ];
    }, $nodes);
    return new JsonResponse([
      'data' => array_values($data),
      'meta' => ['page' => $page, 'limit' => $limit],
    ]);
  }
}

Порівняння: простий модуль vs комплексний

Поширені помилки при розробці модулів та їх рішення

Додаткові компоненти модуля

Плагіни блоків з конфігурацією

Блок RecentPosts з налаштуваннями: адміністратор через інтерфейс змінює кількість постів, не торкаючись коду. Використовуємо ContainerFactoryPluginInterface для впровадження сервісів у плагін.

Event subscribers для кастомної логіки

Відзначимо: коли потрібно реагувати на кожен запит (наприклад, перевіряти заголовок X-Api-Version), підписник події — елегантніше за перевірки в кожному контролері. Реєстрація через тег event_subscriber у services.yml.

Хуки та схеми оновлень

Процедурні хуки залишаємо тільки там, де немає альтернатив. Наприклад, hook_node_presave для автоматичного обчислення часу читання. Для встановлення модуля та міграцій використовуємо .install-файли з update hooks.

Процес роботи та терміни

1. Аналіз вимог та проєктування архітектури — 1–2 дні.
2. Реалізація модуля — від 2 до 15 днів.
3. Тестування (unit + functional) — 1–2 дні.
4. Деплой та документація — 1 день.

Підсумкові терміни залежать від складності: від 2 днів для базового модуля до 3 тижнів для комплексного рішення.

Що входить у розробку під ключ

• Проєктування архітектури модуля
• Написання коду (сервіси, контролери, плагіни, хуки, події)
• Налаштування кешування з тегами та інвалідацією
• Покриття unit-тестами (PHPUnit) та функціональними тестами
• Документація щодо встановлення та налаштування
• Передача вихідних кодів та доступів
• Гарантія на код до 3 місяців та місяць безкоштовної підтримки

Наші переваги

Понад 5 років досвіду розробки на Drupal, 50+ успішних проєктів. Дотримуємося Drupal coding standards і використовуємо сучасні практики — DI-контейнер, event-архітектуру, теги кешу. Використання DI-контейнера у 2–3 рази скорочує час на доопрацювання порівняно з процедурним кодом, а модулі на сервісах тестуються в 3 рази швидше. Надаємо гарантію на код до 3 місяців — якщо виникають помилки або потрібне доопрацювання в межах узгодженого функціоналу, виправляємо безкоштовно. Протягом місяця після здачі — безкоштовна підтримка та консультації.

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