Перейти к содержимому
Поиск
Разработка

Symfony ExpressionLanguage: бизнес-правила PHP — мастерская и 9 опытов

Выносим изменяемые условия в понятные правила: девять опытов настоящего PHP, скидки, доставка, маршруты, собственная функция, кеш и версии. Мастерская и исходники.

Александр Некрасов
Symfony ExpressionLanguage: бизнес-правила PHP — мастерская и 9 опытов — обложка

Symfony ExpressionLanguage: правила, которые можно объяснить

В небольшом приложении условия скидки, доставки и маршрутизации обычно находятся внутри PHP-кода. Со временем условия начинают меняться независимо от остальной логики: акция получила новый порог, критические обращения должны идти дежурному, редактирование доступно только для незаблокированного черновика. Такие решения важно не просто выполнить, но и объяснить человеку.

Symfony ExpressionLanguage позволяет записать короткое выражение, передать ему данные и получить значение. Результат может быть логическим решением, суммой или названием маршрута. Компонент работает отдельно от полного Symfony-приложения и устанавливается через Composer. Вокруг него можно построить управляемый реестр бизнес-правил с проверками, версиями и журналом решений.

В этом материале соберём именно такой небольшой проект: девять практических сценариев, реальные результаты PHP, собственная чистая функция, ошибки типов и синтаксиса, кеш разбора и сравнение версий. В мастерской можно выбирать подготовленные варианты и изучать входные данные, ответ и исходники. Для собственных вычислений предусмотрен скачиваемый стенд Windows и Linux.

Где применять: CRM, тарифы, маршрутизация и внутренние кабинеты

В CRM правило помогает определить предложение для конкретного клиента: подходит ли уровень обслуживания, достигнут ли порог заказа, нет ли блокировки. В службе поддержки похожий механизм выбирает очередь обращения по важности и категории. В кабинете он может объяснить доступность действия: запись уже опубликована, поэтому обычное редактирование закрыто.

Такие решения удобны, когда их нужно тестировать на наборах примеров и постепенно менять. Менеджер продукта может увидеть таблицу входов и результатов, а разработчик — проверить границу суммы и приоритет условий. При этом сама отправка уведомления, списание денег или изменение статуса остаются в обычном прикладном коде после подтверждённого решения.

ExpressionLanguage не является готовой системой управления бизнесом. Он вычисляет выражения, а интерфейс редактирования, права авторов, согласование публикации и аудит вы строите вокруг. Для первого внедрения выберите одно часто меняющееся условие и ясный контракт данных. Это позволит оценить пользу без превращения всей программы в строки выражений.

Когда оставить обычный if, а когда выделить правило

Обычный if отлично подходит для стабильного условия, которое меняется вместе с кодом приложения. Он привычен команде, проверяется анализаторами и не требует отдельного формата хранения. Если ветвление небольшое и читателю программы сразу понятен смысл, отдельный движок может только усложнить сопровождение.

Выделенное правило полезно, когда условие нужно показывать отдельно, версионировать и сравнивать на одном наборе данных. В нашем проекте discount-v1 и discount-v2 отличаются порогом. Один и тот же заказ можно пропустить через обе версии и заранее увидеть изменение поведения. Это удобнее, чем искать нужную ветку среди контроллеров.

Не переносите в выражения длинные процедуры, циклы интеграции, запросы к базе и сетевые вызовы. Подготовьте контекст обычным PHP, вычислите короткое решение и обработайте результат в понятном сервисе. Если задача описывает переходы процесса и допустимые состояния, дополнительно посмотрите Symfony Workflow: выражение может стать условием перехода, а сам процесс останется явной моделью.

Потребность Подход
Стабильное условие рядом с кодом Обычный if
Версии короткого бизнес-решения ExpressionLanguage и реестр правил
Проверка формы или DTO Validator перед вычислением
Статусы и согласование Workflow и явно заданные переходы

Мини-мастерская: девять опытов настоящего PHP

На странице находится интерактивный просмотрщик записей реального выполнения. Выберите задачу, платформу Windows или Linux, затем вариант и нажмите «Показать результат». Мастерская покажет данные, тип ответа, результат либо подтверждённую ошибку. Можно скачать выбранную запись в JSON и открыть соответствующий исходник.

В браузере не запускается PHP и не исполняется введённая посетителем строка. Предложенные варианты рассчитаны настоящим компонентом в проверяемом стенде; публичная страница позволяет сравнить их. Такая граница прямо подписана в интерфейсе. Чтобы изменить выражение или данные произвольно, скачайте проект и выполните CLI либо локальный HTTP-запрос.

Сценарии охватывают скидку, доставку, маршрутизацию, доступность действия, время и null, собственную функцию, lint и compile, кеш и новую версию правила. Начните с двух соседних сумм в скидке, затем сравните ошибку типа с обычным false. Это быстро показывает, почему корректный отрицательный результат и некорректный запрос должны отображаться по-разному.

Версия 7.4 LTS, Composer и состав проекта

В скачиваемом проекте закреплён symfony/expression-language 7.4.21, используется совместимая ветка symfony/cache 7.4, а точные зависимости находятся в composer.lock. Это версия воспроизводимого примера, а не обещание, что номер всегда будет последним. Ветка Symfony 7.4 относится к LTS; сроки поддержки следует проверять на официальной странице выпуска.

Для стенда выбран PHP 8.3 или новее в 64-битной сборке. Сам компонент ветки 7.4 допускает PHP 8.2, но контракт нашего проекта строже. Node 24 используется только для сборки и локального просмотра HTML-оболочки на Bootstrap 5.3.9; вычисление бизнес-правил выполняется PHP.

Установку начинайте с composer install, чтобы восстановить lock-файл. Команда update имеет другой смысл и может изменить набор зависимостей. Автозагрузку подключает vendor/autoload.php. Если Composer пока непривычен, пригодится подробное руководство по Composer. Не нужно устанавливать полный Symfony Framework ради одного компонента.

{
  "name": "aen/expression-language-workshop",
  "description": "Standalone PHP business rules with Symfony ExpressionLanguage",
  "type": "project",
  "license": "MIT",
  "require": {"php": "^8.3", "symfony/expression-language": "7.4.21", "symfony/cache": "7.4.*"},
  "autoload": {"psr-4": {"Workshop\\": "src/"}},
  "config": {"sort-packages": true, "allow-plugins": false},
  "scripts": {"test": "php tests/run.php", "record": "php tools/record.php"}
}

Windows: установка и первый запуск из PowerShell

Откройте PowerShell в распакованном каталоге и проверьте php -v и composer –version. Установите зависимости, выполните тесты, затем запустите bin/rule.php с готовым JSON. Вы получите реальный ответ движка с идентификатором, версией, результатом и типом. Входной файл удобно изменить в редакторе и повторить команду.

Для просмотра мастерской установите npm-зависимости, соберите public и запустите npm start. Это отдельная оболочка для записей и исходников. Она не превращается в вычислительный API от одного запуска Node. Настоящий локальный PHP endpoint запускается другой командой, приведённой ниже в разделе HTTP.

Если в Windows установлено несколько PHP, проверьте путь исполняемого файла и composer check-platform-reqs. Неисправность расширения или версия интерпретатора должны обнаруживаться до эксперимента с правилами. Встроенный PHP-сервер используйте на loopback для разработки, завершайте его Ctrl+C в собственной консоли и не публикуйте случайно в локальную сеть.

php -v
composer --version
composer install --no-interaction
composer check-platform-reqs
composer test
php bin/rule.php fixtures/request.json
npm ci
npm run build
npm start

Linux: CLI, воспроизводимая запись и контейнер

В Linux используется тот же composer.lock и JSON-контракт. Установите поддерживаемый PHP CLI и Composer из доверенного источника вашей ОС, затем проверьте фактическую версию. Пакет php в репозитории зависит от дистрибутива и выпуска. Не заменяйте системный PHP рабочего сервера без проверки других приложений.

Команда tools/record.php последовательно вычисляет подготовленные варианты и пишет JSON с платформой, версией PHP и компонента. Это удобный артефакт для сравнения окружений. Собственную запись можно сохранить рядом с проектом; она не подменяет автоматически опубликованные данные статьи. Так сохраняется ясное происхождение каждого результата.

Dockerfile даёт изолированный способ повторить Linux-опыты. Контейнер не требуется публичному просмотрщику. Он полезен для проверки чистой установки и HTTP-контракта, пока вы не готовы подключать модуль к реальному приложению. Для использования на VPS дальше потребуется обычная интеграция с PHP-FPM, а не бесконечно работающий development server.

composer install --no-interaction
composer test
php bin/rule.php fixtures/request.json
php tools/record.php > records-local.json
docker build -t aen-expression-lab .
docker run --rm aen-expression-lab
docker run --rm aen-expression-lab php tools/record.php

Архитектура: реестр, контракт, движок и ответ

Rules.php хранит доверенные выражения вместе с версией и схемой контекста. Engine получает ruleId, находит запись, проверяет переданные данные, разбирает выражение и вычисляет результат. Клиент не присылает произвольный PHP-код или свободное expression-поле. Это делает границу входа небольшой и проверяемой.

Scenarios.php содержит практические наборы данных и ожидаемые ответы. RuleProvider добавляет одну чистую функцию. CountingCache показывает работу кеша разбора. CLI и HTTP используют один Engine, поэтому формат ответа и ошибки не расходятся в двух независимых реализациях. Публичный просмотрщик читает заранее подготовленные записи.

В рабочем приложении подготовка контекста обычно находится в отдельном сервисе: он извлекает сведения из базы, нормализует суммы и передаёт минимальный массив. Затем результат преобразуется в конкретное действие. Если нужно аккуратно собрать зависимости такого сервиса, посмотрите PHP-DI без фреймворка. Выражение остаётся короткой частью системы, а не её единственным уровнем логики.

require __DIR__ . '/vendor/autoload.php';
$engine = new Workshop\Engine();
$result = $engine->evaluate('discount-v1', [
  'customer' => ['tier' => 'gold'],
  'order' => ['total' => 120000, 'blocked' => false],
]);
// $result['result'] === true

Синтаксис выражений: переменные, массивы и условия

В наших правилах данные передаются массивами: customer[“tier”], order[“total”], ticket[“severity”]. Принадлежность к списку проверяется через in, логические части связываются and, or и not, а тернарный оператор выбирает значение. Скобки помогают показать приоритет и избежать неясной длинной строки.

Не считайте выражение произвольным фрагментом PHP. У языка собственный синтаксис и набор возможностей, описанный в официальном справочнике Expression Syntax. Для примера выбран небольшой понятный поднабор, достаточный для бизнес-условий. Это облегчает чтение и обсуждение правил с людьми, которые не поддерживают весь код приложения.

При проектировании важнее единообразие, чем максимальное количество операторов. Определите, что означает сумма, какой тип у статуса и какие имена доступны. Подготовьте несколько характерных входов и ожидаемый результат. Если условие стало настолько сложным, что его невозможно объяснить рядом с таблицей примеров, разделите решение на несколько именованных шагов.

customer["tier"] in ["gold", "partner"]
and order["total"] >= 100000
and not order["blocked"]

Пример 1. Право на скидку и проверка границы

Первый сценарий определяет, подходит ли заказ под акцию. У клиента должен быть уровень gold или partner, сумма — не меньше 100 000 копеек, а заказ не должен быть заблокирован. Выберите gold с 1 200 рублями: результат true. Вариант 999,99 рубля возвращает false, хотя остальные условия выполнены.

Затем откройте заблокированный заказ партнёра на 3 000 рублей. Высокая сумма не отменяет запрет, поскольку логические условия объединены через and. Это полезный опыт для реального интерфейса: менеджеру нужно видеть причину отказа, а не только серую кнопку. В нашем ответе сохраняются выражение и вход, из которых можно восстановить решение.

Граница суммы заслуживает отдельных тестов: чуть ниже, ровно порог и чуть выше. Дополнительно проверьте каждый разрешённый уровень, неизвестный уровень и блокировку. При переносе правила в продукт не вычисляйте право на скидку из произвольного клиентского JSON: сведения об уровне и блокировке должны приходить из доверенной серверной модели.

'discount-v1' => [
  'version' => 1,
  'expression' => 'customer["tier"] in ["gold", "partner"] and order["total"] >= 100000 and not order["blocked"]',
]

Пример 2. Стоимость доставки как числовой результат

Выражение не обязано возвращать только true или false. В сценарии доставки ответом является целое количество копеек. Если заказ достиг 500 000 копеек, доставка бесплатна. Иначе local получает 49 000 копеек, а другая зона — 89 000. В мастерской это 490 и 890 рублей соответственно.

Выберите региональный заказ ровно на 5 000 рублей. Результат равен нулю; это полноценное успешное вычисление, а не отсутствие ответа. В PHP и JavaScript ноль легко потерять при неосторожной проверке истинности, поэтому интерфейс должен отдельно учитывать ok и само значение результата.

В реальном сервисе заранее определите список допустимых зон и порядок применения льгот. Учебная схема проверяет строковый тип, но выражение направляет любую зону, отличную от local, в региональный тариф. Если опечатка зоны должна быть ошибкой, добавьте перечисление допустимых значений в валидацию. Пример намеренно позволяет увидеть, где заканчивается тип и начинается бизнес-смысл.

order["total"] >= 500000
  ? 0
  : (address["zone"] == "local" ? 49000 : 89000)

Пример 3. Маршрут обращения и приоритет условий

В службе поддержки срочность может оказаться важнее категории. Наше правило сначала проверяет critical и направляет обращение в oncall. Только после этого категория billing или refund выбирает finance; остальные обращения идут в support. Критический платёж поэтому попадёт дежурному, хотя относится к финансовому вопросу.

Такая последовательность должна быть понятна команде. Если сначала проверить категорию, получится другое поведение: срочный запрос может застрять в обычной очереди. В мастерской рядом представлены критический платёж, обычный возврат и вопрос об аккаунте. Сравнение помогает обсуждать бизнес-приоритет на конкретных данных.

Само выражение лишь возвращает название маршрута. Создание задания, назначение сотрудника и отправка сообщения выполняются после него обычным кодом. Это позволяет повторить расчёт без побочных эффектов и проверить правило на исторической выборке. В рабочем сервисе итоговый маршрут ещё нужно сопоставить с существующей очередью и обработать ситуацию, когда она временно недоступна.

ticket["severity"] == "critical"
  ? "oncall"
  : (ticket["category"] in ["billing", "refund"] ? "finance" : "support")

Пример 4. Доступность действия в кабинете

Четвёртый сценарий показывает редактирование записи. Роль должна быть manager или admin, статус — draft, блокировка — выключена. Менеджер с черновиком получает true, опубликованная запись и наблюдатель — false. Такое решение удобно использовать для объяснения состояния кнопки в интерфейсе.

Однако доступность кнопки не равна полноценной авторизации. Серверу нужно отдельно проверить реальную личность, принадлежность записи, организацию и актуальное состояние. Если клиент передал role=admin, это не делает его администратором. Для вычисления производственного правила роль берётся из проверенной серверной сессии или другого доверенного источника.

Кроме того, между показом формы и сохранением запись может измениться. Поэтому перед изменением сервер повторяет проверку внутри своего согласованного процесса, а при необходимости использует версию объекта. Пользователю стоит объяснить причину отказа: запись уже опубликована или заблокирована другим действием. Простого скрытия кнопки для такой ситуации недостаточно.

user["role"] in ["manager", "admin"]
and record["status"] == "draft"
and not record["locked"]

Пример 5. Явное время, null и неверный тип

Пятый опыт проверяет неактивность клиента за тридцать дней. В контекст передаются now и lastSeen, поэтому один и тот же тест даёт одинаковый результат независимо от часов машины. При наличии даты разница сравнивается с 2 592 000 секундами. Для учебного сценария это фиксированная длительность, а не календарный месяц.

Если lastSeen равен null, правило возвращает false. Отсутствие даты имеет определённый смысл и не превращается автоматически в очень старое посещение. Вариант со строкой вместо числового now отклоняется проверкой контракта ещё до вычисления. Ошибка типа и корректный false отображаются раздельно.

В проекте целые значения ограничены диапазоном до 2 147 483 647. Это выбранный учебный контракт, который ограничивает и передаваемые timestamp. Для более дальних дат его нужно пересмотреть явно. В производственной системе также определите источник времени, часовую зону для календарных правил и поведение при будущей lastSeen, а не полагайтесь на неявные преобразования.

context["lastSeen"] != null
and context["now"] - context["lastSeen"] >= 2592000

Пример 6. Собственная функция и округление денег

Вычисление итоговой цены вынесено в функцию discounted. Она принимает целую сумму в копейках и целый процент, проверяет диапазоны и возвращает целое значение. Вариант 1 999,99 рубля со скидкой 15 процентов даёт 1 699,99 рубля. Одна копейка со скидкой 50 процентов после принятого округления остаётся одной копейкой.

Формула использует округление половины вверх для неотрицательных значений. Это явное правило примера, а не универсальное требование бухгалтерии. Максимальная сумма ограничена, а вычисление рассчитано на 64-битный PHP: промежуточное произведение может превышать диапазон 32-битного целого. Вариант со скидкой 70 процентов отклоняется.

Важная граница функции — чистота. Она не читает файлы, не отправляет запросы и не меняет базу. Поэтому её можно повторно вызвать в тесте или сравнении версий. Для нескольких валют, сложных округлений и распределения сумм полезен отдельный инструмент; на сайте есть подробный материал про Brick\Money.

public static function discounted(int $amount, int $percent): int
    {
        if ($amount < 0 || $amount > 100000000 || $percent < 0 || $percent > 50) {
            throw new \InvalidArgumentException('Сумма или процент вне допустимого диапазона.');
        }
        return intdiv($amount * (100 - $percent) + 50, 100);
    }

Provider: две стороны пользовательской функции

RuleProvider регистрирует имя discounted и описывает две операции: как получить значение при evaluate и как представить вызов при compile. В проекте обе стороны указывают на одну проверенную арифметическую функцию. Это уменьшает риск расхождения поведения между интерпретацией и сгенерированным представлением.

Первый аргумент evaluator содержит контекст переменных, а следующие — значения аргументов выражения. Compiler работает с представлениями аргументов и формирует PHP-строку. В нашем приложении эта строка нужна только для просмотра; она не передаётся eval. Полный provider показан в исходниках, поэтому можно проверить конкретную регистрацию.

Не давайте выражению универсальную функцию call, file или request только ради гибкости. Каждая добавленная возможность расширяет доступный набор действий и усложняет контроль. Для бизнес-правила лучше маленькая именованная функция с понятными типами, ограничениями и тестами. Если функцию меняют, учитывайте это при версионировании правила и кеша, даже когда текст самого выражения остался прежним.

new ExpressionFunction(
  'discounted',
  static fn($amount, $percent) => sprintf(
    '\\Workshop\\RuleProvider::discounted(%s, %s)', $amount, $percent
  ),
  static fn(array $variables, int $amount, int $percent) =>
    self::discounted($amount, $percent)
);

Пример 7. lint, parse и compile без исполнения строки PHP

В седьмой задаче сравните правильное выражение с опечаткой orderr и незакрытой скобкой. lint проверяет выражение относительно известных имён и сообщает ошибку до публикации правила. parse строит разобранное представление, которое затем можно использовать для вычисления. Это помогает обнаружить техническую проблему раньше запроса клиента.

compile возвращает строковое PHP-представление выражения. В нашей мастерской она подписана compiledForInspection и показывается как данные. Проект не вызывает eval и не превращает полученный текст в отдельный исполняемый файл. Такой просмотр полезен для понимания механизма, но не требуется обычному менеджеру, принимающему решение по акции.

Успешный lint не доказывает, что правило правильно описывает бизнес. Синтаксически корректное условие с неверным порогом тоже пройдёт проверку. Поэтому техническую проверку дополняют ожидаемые результаты на границах и обсуждение изменения. Различия API разобраны в документации компонента.

$language->lint('order["total"] >= 100000', ['order']);
$parsed = $language->parse('order["total"] >= 100000', ['order']);
$value = $language->evaluate($parsed, ['order' => ['total' => 120000]]);
$phpForInspection = $language->compile($parsed, ['order']);

Пример 8. Кеш разбора не хранит решение клиента

В восьмом опыте одно выражение вычисляется дважды с разными суммами. Для 1 200 рублей результат true, для 900 рублей — false. Второй вариант меняет порядок сумм и получает обратную последовательность. При этом журнал кеша показывает первый miss и последующий hit: разобранное дерево используется повторно.

Если бы кеш хранил готовое решение без учёта данных, второй заказ получил бы чужой ответ. Именно поэтому в мастерской рядом показаны results и cacheLookups. Кеширование разбора экономит повторную техническую работу, но каждое новое значение контекста всё равно участвует в вычислении. Это принципиально отличается от прикладного кеша итоговой стоимости.

CountingCache наследует ArrayAdapter и живёт в текущем процессе. Новый CLI-запуск начинает с пустого состояния. Для общего хранилища нескольких процессов можно передать совместимый PSR-6 адаптер: Engine принимает CacheItemPoolInterface, а ArrayAdapter остаётся удобным вариантом по умолчанию. При подключении общего кеша определите namespace, права доступа и сброс после изменения набора функций.

$cache = new CountingCache();
$engine = new Engine($cache);
// Один и тот же движок, разные проверенные данные:
$first = $engine->evaluate('discount-v1', $context1200);
$second = $engine->evaluate('discount-v1', $context900);
// results: [true, false], cache hit: [false, true]

Пример 9. Новая версия правила и объяснимый откат

В девятом сценарии сравниваются discount-v1 и discount-v2. Первая версия требует 1 000 рублей, вторая — 1 500. Заказ gold на 1 200 рублей подходит только старой версии; заказ на 1 800 проходит обе. Такой опыт показывает влияние изменения до включения его для всех пользователей.

Ответ Engine содержит ruleId, version, выражение и его SHA256. Вместе с минимальным снимком входных данных это помогает восстановить, почему было принято решение. Хеш позволяет обнаружить изменение текста, однако не заменяет полную версию окружения: реализация пользовательской функции тоже влияет на ответ.

В продукте полезен порядок «подготовка, тестовые примеры, сравнение, согласование, включение». Откат означает выбор предыдущей проверенной версии для новых вычислений. Он не отменяет уже выданную скидку или выполненное действие. Такие последствия должны обрабатываться отдельным бизнес-процессом, а история решений — оставаться доступной для поддержки.

foreach (['discount-v1', 'discount-v2'] as $id) {
    $audit[] = $engine->evaluate($id, $sameContext);
}
// Заказ 1200 рублей: [true, false]

Контракт JSON: проверить данные до вычисления

HTTP и CLI принимают объект ровно с двумя полями: ruleId и context. Engine ограничивает размер JSON восемью KiB и глубину двенадцатью уровнями, затем проверяет структуру и схему выбранного правила. Лишние поля, неизвестный идентификатор и неподходящие типы отклоняются. Порядок ключей JSON не влияет на результат.

Вложенный объект проверяется рекурсивно. Строка имеет ограниченную длину, булевы значения должны быть настоящими boolean, целые числа — попадать в диапазон. Это защищает вычисление от случайных строковых сумм и неполного контекста. При этом схема примера не заменяет все семантические ограничения конкретного бизнеса.

В большом приложении удобно подключить Symfony Validator и Serializer с DTO. Тогда преобразование транспорта, проверка формы и вычисление правила остаются отдельными шагами. Не позволяйте выражению разбираться с повреждённым JSON самостоятельно: качественная ошибка контракта понятнее, чем исключение глубоко внутри вычислителя.

{"ruleId":"discount-v1","context":{"customer":{"tier":"gold"},"order":{"total":120000,"blocked":false}}}

Локальный HTTP API: запрос, ответ и коды ошибок

Запустите встроенный PHP-сервер на 127.0.0.1:8577 и отправьте fixtures/request.json. Обработчик разрешает POST с Content-Type application/json, читает ограниченный объём тела и вызывает тот же Engine, что CLI. Успех возвращает JSON с результатом; повреждённый контракт получает 422.

Метод GET получает 405 с Allow: POST, а неподходящий тип содержимого — 415. Непредвиденная внутренняя ошибка превращается в нейтральный 500; подробный класс уходит в серверный журнал. Такой контракт позволяет интерфейсу отличить ошибку пользователя от недоступности вычисления и не показывать успешный результат после неудачного запроса.

Лабораторный API не содержит входа пользователей и готовой авторизации. Он запускается локально для проверки, а при интеграции в приложение должен находиться за вашим обычным контролем доступа. Особенно важно не принимать из браузера доверенные роли, цены и признаки блокировки без серверной проверки. Сам размер JSON эту проблему не решает.

php -S 127.0.0.1:8577 -t api
# PowerShell, другая консоль:
curl.exe -i -H "Content-Type: application/json" --data-binary "@fixtures/request.json" http://127.0.0.1:8577/
# Linux:
curl -i -H 'Content-Type: application/json' --data-binary @fixtures/request.json http://127.0.0.1:8577/

Доверенные выражения и граница безопасности

В этой реализации тексты правил находятся в доверенном Rules.php. Посетитель выбирает только известный ruleId и передаёт проверяемые данные. Это важное ограничение проекта. ExpressionLanguage нельзя автоматически считать универсальной песочницей для любых анонимных выражений: доступные возможности зависят от функций и переданных объектов.

Язык умеет обращаться к свойствам и методам объектов, а встроенная constant может читать PHP-константы. Поэтому в контекст не передаются контейнер приложения, ORM-сущности с методами загрузки, HTTP-клиент или другие сервисы. Используются небольшие массивы со скалярами. Добавленная discounted ограничена арифметикой и не выполняет побочных действий.

Если нужно дать сотрудникам редактор правил, проектируйте отдельный доверенный процесс: права на изменение, ограниченный словарь, тестовые данные, рецензию и публикацию версии. Для недоверенного публичного ввода потребуется значительно более строгая модель допустимого языка и ресурсов. Отсутствие eval само по себе ещё не означает, что любое выражение безопасно для вашего приложения.

Журнал решений: причина, версия и минимум данных

Когда клиент спрашивает о скидке или маршруте заявки, одной строки «правило выполнено» мало. Полезно сохранить идентификатор операции, ruleId, версию, хеш выражения, результат и необходимые факты контекста. Это позволяет сопоставить событие с конкретным выпуском правил и повторить вычисление на тестовом стенде.

При этом полный клиентский объект обычно избыточен. Пароли, токены, адреса и лишние персональные данные не нужны для объяснения порога суммы. Выберите минимальный снимок, установите срок хранения и права чтения журнала. Записи мастерской используют синтетические сведения, поэтому их можно свободно изучать и скачивать.

Для прикладных логов пригодится Monolog. Разделяйте техническую ошибку выполнения и обычное бизнес-решение false. Отрицательный результат акции не является аварией сервиса. Полезные метрики — частота ошибок контрактов, время вычисления и изменение доли положительных решений после выпуска новой версии.

Linux/VPS: интеграция с PHP-FPM и существующим приложением

Разместите код проекта вне document root, например в /opt/aen-rules, установите зависимости из lock-файла и проверьте требования платформы. Публичным должен быть только нужный маршрут приложения, а не весь каталог с тестами, конфигурацией и vendor. Для статического просмотрщика отдельно публикуется public.

В deploy/nginx.conf приведён фрагмент подключения PHP-FPM. Сокет нужно заменить на фактический путь вашей системы, а маршрут включить в существующий HTTPS server block. Перед открытием добавьте аутентификацию и проверку прав в вашем приложении. Встроенный php -S предназначен для локального стенда, а не для обслуживания публичных запросов.

Разделите владельца кода и права процесса: FPM достаточно чтения исходников, а запись требуется только явно выделенным каталогам журнала или кеша. Перед reload выполните nginx -t. Затем проверьте успешный запрос, неправильный JSON, неподходящий метод и отказ без доступа. Практику настройки дополняет статья о Nginx.

# Include in an existing HTTPS server block; adjust PHP-FPM socket for your OS.
location = /rules/evaluate {
    client_max_body_size 8k;
    include fastcgi_params;
    fastcgi_param SCRIPT_FILENAME /opt/aen-rules/api/index.php;
    fastcgi_pass unix:/run/php/php8.3-fpm.sock;
}
# Do not expose /opt/aen-rules as the web root. Add application authentication
# before publishing the route; the tutorial handler is an isolated lab API.

Тесты и проверка изменений до выпуска

tests/run.php выполняет 35 проверок: ожидаемые результаты сценариев, ошибки типов и синтаксиса, округление, null, кеш и сравнение версий. Отдельно проверяются строгий JSON-контракт, независимость от порядка полей, неизвестные данные и превышение лимита. Ещё семь HTTP-проверок дополняют вызов класса настоящими запросами к обработчику и проверкой его статусов. Эти наборы выполнены в Windows и Linux.

Смысл такого набора — защитить поведение, понятное пользователю. Если изменить порог акции, сравнение покажет, какие примеры теперь должны дать другой ответ. Если случайно начать преобразовывать строку в число, отрицательный тест обнаружит нарушение контракта. Это полезнее, чем тест, который просто повторяет текст формулы без независимого ожидаемого значения.

После изменения правила обновляйте версию и набор ожидаемых решений, выполняйте проверки в поддерживаемых средах и создавайте новую запись. Затем пересобирайте public/sources.json, чтобы просмотрщик не показывал устаревший код. Проверка PHP не заменяет отдельную приёмку интерфейса и скачивания опубликованного архива.

composer test
php tools/record.php > records-local.json
npm run build
# При запущенном локальном API:
# Linux: RULES_URL=http://127.0.0.1:8577 node tests/http.mjs
# PowerShell: $env:RULES_URL='http://127.0.0.1:8577'; node tests/http.mjs

Мобильная мастерская, исходники и дальнейшее внедрение

Просмотрщик построен на HTML5 и Bootstrap: выбор задачи, платформы и варианта остаётся доступным на узком экране, а длинные выражения и JSON прокручиваются внутри своих блоков. Результат показывается текстом с типом и статусом. Смена варианта требует нового осознанного просмотра, чтобы не смешивать ответ одного опыта с входом другого.

Полный архив содержит PHP-классы, CLI, HTTP-обработчик, фикстуры, тесты, lock-файлы, инструкции Windows и Linux и готовую оболочку. Авторский код распространяется по MIT; зависимости сохраняют собственные лицензии. Начните с запуска неизменённого примера, затем добавьте одно правило в реестр вместе со схемой и ожидаемыми результатами.

При переносе в сервис сохраняйте три границы: проверенные данные до вычисления, короткое чистое решение внутри выражения и контролируемое действие после него. Официальные источники — документация компонента, синтаксис и ветка 7.4 LTS. Тогда правило становится частью понятного и проверяемого поведения приложения.