README

API-ориентированное решение для создания каталогов товаров с поддержкой вариантов для Evolution CMS CE. Пересборка классических TV под коммерческую составляющую. Включает в себя фильтрацию, импорт, экспорт, UI и CLI. Основная логическая единица - Атрибут, разделённый на общие и вариативные.

Требования: Evolution CMS CE 3.1.30+, PHP 8.1+.

Установка

Установка пакета

php artisan package:installrequire roilafx/product "*"

Публикация стилей и скриптов

php artisan vendor:publish --provider="roilafx\Product\ProductServiceProvider"

Выполните миграции:
```
php artisan migrate
```

Общие характеристики и Вариации

Пакет разделяет атрибуты товара на два типа:

Общие характеристики (product_attributes) - атрибуты, принадлежащие самому товару (Бренд, Страна, Артикул). Выводятся отдельным блоком в админ-панели и участвуют в фильтрации наравне с вариантами.
Вариации (product_variants) - торговые предложения (Цвет, Размер). У каждого варианта свой набор значений, которые хранятся в EAV и кэшируются в JSON-поле attrs_json.

Вывод каталога и фильтрация

Для вывода товаров и формы фильтрации на сайте используйте фасад ProductFilter. Рекомендуется метод getCachedFilteredProducts - тяжёлые запросы кэшируются.

<?php

namespace EvolutionCMS\Shop\Controllers;

use roilafx\Product\Facades\ProductFilter;
use roilafx\Product\Helpers\FilterTypeHelper;

class CatalogController extends BaseController
{
    public function process()
    {
        parent::process();

        $catalogId = evo()->documentIdentifier;
        $depth = 3;    // глубина поиска в подкатегориях
        $perPage = 6;  // товаров на страницу

        $activeFilters = request('filters', []);
        $sort = request('sort', 'menuindex:asc');

        // Атрибуты категории и словарь имён для карточек товаров
        $allAttributes = ProductFilter::getAttributesForCatalog($catalogId, $depth);
        $attrNames = $allAttributes->pluck('name', 'code')->all();

        // Состояние фильтров: счётчики значений и диапазоны
        // пересчитываются с учётом активных фильтров
        $filterState = ProductFilter::getFilterState($catalogId, $activeFilters, $depth)
            ->map(fn ($attr) => [
                'code'   => $attr->code,
                'name'   => $attr->name,
                'type'   => FilterTypeHelper::widgetType($attr->field_type), // select | number | text
                'values' => $attr->filterValues, // списочные: [{value, count, available}]
                'min'    => $attr->filterMin,    // числовые: границы диапазона
                'max'    => $attr->filterMax,
            ]);

        // Товары с кэшированием
        $products = ProductFilter::getCachedFilteredProducts(
            $catalogId,
            $activeFilters,
            $perPage,
            $sort,
            request('page', 1),
            $depth
        );

        // Фильтры не сбрасываются при переходе по страницам
        $products->appends(request()->except('page'));
        $products->appends('depth', $depth);

        $this->addViewData([
            'filterState' => $filterState,
            'products'    => $products,
            'attrNames'   => $attrNames,
            'catalogId'   => $catalogId,
            'depth'       => $depth,
        ]);
    }
}

Для AJAX-обновления без перезагрузки те же данные отдают публичные маршруты GET /api/v1/catalogs/{id}/filter и GET /api/v1/catalogs/{id}/filter-state - без авторизации, с теми же параметрами (filters, sort, per_page, page, depth). Формат ответов - 04-api-reference.md

Работа с вариантами товаров (ProductVariantService)

use roilafx\Product\Services\ProductVariantService;

$variantService = app(ProductVariantService::class);

// Создание варианта для товара ID = 15
$variant = $variantService->createVariant(15, [
    'color' => 'Красный',
    'size'  => 'XL',
]);

// Обновление значений варианта
$variantService->updateVariant($variant, [
    'attrs' => ['color' => 'Синий'],
]);

Сервис автоматически проверит, назначены ли эти атрибуты товару, сохранит значения в EAV и обновит attrs_json.

CLI Инструменты

Генерация тестовых данных (10 категорий, 14 атрибутов, 4 пресета, 5000 товаров):

php artisan product:generate-test-data

Принудительный прогрев кэша фильтров для всех категорий каталога:

php artisan product:warm-cache

Импорт и экспорт каталога (csv/xlsx/xml/json/yml, идемпотентный, с отчётом):

php artisan product:import catalog.csv
php artisan product:export csv --parent_id=2

Документация

Файл	Содержание
docs/01-installation.md	Установка, миграции, публикация ассетов
docs/02-cli-commands.md	Консольные команды: импорт, экспорт, тестовые данные, прогрев кэша
docs/03-exchange-schema.md	Форматы файлов, канонические колонки, профили, режимы синхронизации
docs/04-api-reference.md	HTTP API: атрибуты, категории, варианты, обмен, публичные маршруты фильтра
docs/05-ui-module.md	Менеджер-модуль: пресеты, массовое назначение, профили импорта, запуск обмена
docs/06-ui-plugin-tab.md	Вкладка в документе товара: поля вариаций, вариации, общие характеристики
docs/07-quick-start.md	Быстрый старт: от установки до каталога с фильтром и импортом

roilafx / product

Package info

Security

Statistics