Розробка кастомного плагіна Sylius: досвід та гарантії

Розробка кастомного плагіна Sylius

При розробці кастомного плагіна Sylius ми використовуємо Resource System. Стандартний Sylius покриває 80% завдань, але бізнес-логіка часто потребує унікальних механік: програма лояльності, інтеграція з ERP, кастомні знижки. Розробники часто копіюють код у ядро, що перетворює оновлення на кошмар — кожен реліз Sylius може зламати логіку. Ми створюємо ізольовані плагіни-базли на основі Resource System. Це гарантує сумісність з оновленнями і скорочує час на підтримку в 2-3 рази порівняно з ручним форком.

В одному проекті ми впроваджували лояльність для інтернет-магазину з 50 000 замовлень на місяць. Плагін на Resource System обробляв нарахування балів без N+1 запитів і працював стабільно після трьох мажорних оновлень Sylius. Економія на підтримці склала 60%.

Які проблеми вирішуємо

N+1 запити при роботі з кастомними зв'язками — стандарт Sylius оптимізовано під свої сутності, але додані відношення без join у репозиторіях призводять до лавини запитів. Плагін включає оптимізовані репозиторії з eager loading. Наприклад, при завантаженні 1000 замовлень з балами лояльності — всього 2 запити замість 1001.

Дублювання коду між проектами — часто одну й ту саму логіку пишуть заново. Ми пакуємо її в Composer-пакет, який можна перевикористовувати. Це скорочує час на наступний проект на 40%.

Конфлікти при оновленні Sylius — патчі ядра замінюються декларативними конфігураціями через sylius_*.yaml. При оновленні достатньо перезібрати плагін з новими залежностями.

Некоректна робота з транзакціями — плагін гарантує атомарність операцій через Doctrine ORM, що виключає часткове нарахування балів або втрату даних при збоях.

Чому Sylius Resource System — найкращий спосіб розширення?

Resource System автоматично генерує CRUD, API-ендпоінти, форми та Grid-таблиці. Ви описуєте лише сутність та її відображення — інше Sylius робить за вас. Це скорочує обсяг коду на 40% порівняно з ручною реалізацією. Для порівняння: створення програми лояльності вручну займає 3-4 тижні, з Resource System — 1-2 тижні. У порівнянні з кастомними Bundle, Resource System забезпечує єдність коду і прискорює розробку в 2 рази.

Як ми це робимо: приклад програми лояльності

Розглянемо програму лояльності: потрібно зберігати бали, історію нарахувань і списань, відображати баланс в особистому кабінеті та адмінці. Плагін будується на Resource System, а код виглядає так:

// src/SyliusLoyaltyPlugin/SyliusLoyaltyPlugin.php
namespace Acme\SyliusLoyaltyPlugin;

use Sylius\Bundle\CoreBundle\Application\SyliusPluginTrait;
use Symfony\Component\HttpKernel\Bundle\Bundle;

final class SyliusLoyaltyPlugin extends Bundle
{
    use SyliusPluginTrait;
}

// src/SyliusLoyaltyPlugin/Entity/LoyaltyAccount.php
namespace Acme\SyliusLoyaltyPlugin\Entity;

use Doctrine\ORM\Mapping as ORM;
use Sylius\Component\Customer\Model\CustomerInterface;

#[ORM\Entity(repositoryClass: LoyaltyAccountRepository::class)]
#[ORM\Table(name: 'acme_loyalty_account')]
class LoyaltyAccount
{
    #[ORM\Id]
    #[ORM\GeneratedValue]
    #[ORM\Column(type: 'integer')]
    private ?int $id = null;

    #[ORM\OneToOne(targetEntity: CustomerInterface::class)]
    #[ORM\JoinColumn(nullable: false, onDelete: 'CASCADE')]
    private CustomerInterface $customer;

    #[ORM\Column(type: 'integer', options: ['default' => 0])]
    private int $points = 0;

    #[ORM\Column(type: 'json')]
    private array $transactions = [];

    #[ORM\Column(type: 'datetime_immutable')]
    private \DateTimeImmutable $createdAt;

    public function __construct()
    {
        $this->createdAt = new \DateTimeImmutable();
    }

    public function addPoints(int $points, string $reason, ?string $orderId = null): void
    {
        $this->points += $points;
        $this->transactions[] = [
            'type' => 'earn',
            'points' => $points,
            'reason' => $reason,
            'order_id' => $orderId,
            'date' => (new \DateTimeImmutable())->format(\DateTimeInterface::ATOM),
        ];
    }

    public function spendPoints(int $points, string $reason): void
    {
        if ($this->points < $points) {
            throw new \DomainException('Недостатньо балів');
        }
        $this->points -= $points;
        $this->transactions[] = [
            'type' => 'spend',
            'points' => $points,
            'reason' => $reason,
            'date' => (new \DateTimeImmutable())->format(\DateTimeInterface::ATOM),
        ];
    }

    public function getId(): ?int
    {
        return $this->id;
    }

    public function getPoints(): int
    {
        return $this->points;
    }

    public function getTransactions(): array
    {
        return $this->transactions;
    }
}

// src/SyliusLoyaltyPlugin/EventListener/OrderPlacedListener.php
namespace Acme\SyliusLoyaltyPlugin\EventListener;

use Acme\SyliusLoyaltyPlugin\Repository\LoyaltyAccountRepository;
use Doctrine\ORM\EntityManagerInterface;
use Sylius\Bundle\ResourceBundle\Event\ResourceControllerEvent;
use Sylius\Component\Core\Model\OrderInterface;

final class OrderPlacedListener
{
    public function __construct(
        private LoyaltyAccountRepository $accountRepository,
        private EntityManagerInterface $em,
    ) {}

    public function onOrderComplete(ResourceControllerEvent $event): void
    {
        /** @var OrderInterface $order */
        $order = $event->getSubject();
        $customer = $order->getCustomer();

        if (!$customer) {
            return; // гостьове замовлення
        }

        $pointsToAward = (int) floor($order->getTotal() / 10000); // 1 бал = 100 грн

        $account = $this->accountRepository->findOneByCustomer($customer);
        if (!$account) {
            $account = new LoyaltyAccount();
            $account->setCustomer($customer);
        }

        $account->addPoints(
            $pointsToAward,
            sprintf('Замовлення #%s', $order->getNumber()),
            $order->getId()
        );

        $this->em->persist($account);
        $this->em->flush();
    }
}

<!-- src/SyliusLoyaltyPlugin/Resources/config/services.xml -->
<service id="acme.loyalty.event_listener.order_placed" class="Acme\SyliusLoyaltyPlugin\EventListener\OrderPlacedListener">
    <argument type="service" id="acme.loyalty.repository.loyalty_account"/>
    <argument type="service" id="doctrine.orm.entity_manager"/>
    <tag name="kernel.event_listener" event="sylius.order.post_complete" method="onOrderComplete"/>
</service>
<service id="acme.loyalty.menu.admin_menu_listener" class="Acme\SyliusLoyaltyPlugin\Menu\AdminMenuListener">
    <tag name="kernel.event_listener" event="sylius.menu.admin.main" method="addAdminMenuItems"/>
</service>

// src/SyliusLoyaltyPlugin/Api/Resource/LoyaltyAccountResource.php
namespace Acme\SyliusLoyaltyPlugin\Api\Resource;

use ApiPlatform\Metadata\ApiResource;
use ApiPlatform\Metadata\Get;
use Acme\SyliusLoyaltyPlugin\Api\Provider\LoyaltyAccountProvider;

#[ApiResource(
    shortName: 'LoyaltyAccount',
    operations: [
        new Get(
            uriTemplate: '/shop/loyalty-account',
            provider: LoyaltyAccountProvider::class,
        ),
    ],
    normalizationContext: ['groups' => ['loyalty:read']],
)]
final class LoyaltyAccountResource
{
    public int $points = 0;
    public array $transactions = [];
}

Реєстрація плагіна в config/bundles.php та міграція структури БД через doctrine:migrations:diff && doctrine:migrations:migrate.

Як уникнути конфліктів при оновленні Sylius?

Ми використовуємо події та декоратори замість наслідування. Плагін реагує на події ядра (наприклад, sylius.order.post_complete) і розширює функціональність через сервісні теги. Жодних змін у vendor-коді — тільки власні Bundle та конфігурації. При оновленні Sylius плагін просто адаптується під нову версію через залежності Composer.

Терміни та гарантії

Вартість фіксується після аудиту. На всі плагіни даємо гарантію сумісності з поточною мажорною версією Sylius. Досвід команди — 5+ років у Symfony-екосистемі, понад 20 успішних інтеграцій з Sylius.

Процес роботи

1. Аудит поточного Sylius-застосунку: версія, встановлені плагіни, кастомізації.
2. Проектування структури: визначення ресурсів, подій, API.
3. Реалізація: написання сутностей, ліснерів, конфігурацій.
4. Тестування: юніт-тести на PHPUnit + Behat-сценарії для acceptance.
5. Інтеграція та деплой: merge в репозиторій, міграції, налаштування CI/CD.

Що входить у розробку

• Повний код плагіна з сутностями, сервісами, конфігураціями.
• Документація з встановлення, налаштування та адміністрування.
• Міграції для оновлення структури БД.
• Тести (PHPUnit + Behat).
• Навчання команди замовника (2–4 години).
• Гарантійна підтримка 3 місяці.

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

Докладніше про Sylius можна прочитати в Wikipedia.