README

Что это и для чего?

Пакет предоставляет два типа словарей для валидации пользовательского контента:

1. StopWordsValidator - проверяет на наличие стоп-слов, которые могут привести к блокировке Роскомнадзором:

   • Запрещённые товары (электроудочки, наркотические вещества)
   • Нежелательные услуги (гадания, эскорт-услуги, кредиты)
   • Другие проблемные категории

2. ProfanityWordsValidator - проверяет на ненормативную лексику (матерные слова)

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

Особенности:

• Структурированные PHP-массивы для удобного редактирования
• Регулярно обновляется на основе реальных случаев блокировок
• Поддержка расширения и модификации

Установка

1. Добавьте/измените данные в секции scripts и autoload в composer.json вашего проекта:

{
    "scripts": {
        "post-install-cmd": [
            "Krugozor\\RussianBadWords\\Installer::postInstall"
        ],
        "post-update-cmd": [
            "Krugozor\\RussianBadWords\\Installer::postInstall"
        ],
        "pre-package-uninstall": [
            "Krugozor\\RussianBadWords\\Installer::preUninstall"
        ]
    },

    "autoload": {
        "psr-4": {
            "Krugozor\\RussianBadWords\\Items\\": "dictionaries"
        }
    }
}

2. Установите пакет

composer require krugozor/russian-bad-words

3. Проверьте установку

После установки в корне вашего проекта появится папка dictionaries с файлами:

• ProfanityWordsValidator.php - Словарь ненормативной лексики
• StopWordsValidator.php - Словарь стоп-слов

ВАЖНО: Редактор PhpStorm иногда не видит только что созданную директорию dictionaries. Смотрите факт её создания в проводнике.

Использование

Пример валидации текста:

<?php
// Подключите '/vendor/autoload.php'

use Krugozor\RussianBadWords\Items\ProfanityWordsValidator;
use Krugozor\RussianBadWords\Items\StopWordsValidator;

// Проверка сообщения от пользователя.
// В слове "электрo-фишер" кириллическая буква "о" заменена на латинскую,
// а слова умышленно соединены различными символами с целью обмана программы.
// В слове "сукa" кириллическая буква "a" заменена на латинскую.
$message = 'Продам_электрo-фишер.fisher-f-3500 не дорого! Ну и немного нембутала, сукa';

$validator = new StopWordsValidator($message);
if (!$validator->validate()) {
    echo "Текст не проходит валидацию! Плохие слова:\n";
    print_r($validator->getFailedWords());
}

$validator = new ProfanityWordsValidator($message);
if (!$validator->validate()) {
    echo "Текст не проходит валидацию! Ненормативная лексика:\n";
    print_r($validator->getFailedWords());
}

Результат:

Текст не проходит валидацию! Плохие слова:
Array
(
    [1] => электрo-фишер
    [2] => fisher-f-3500
    [9] => нембутала
)

Текст не проходит валидацию! Ненормативная лексика:
Array
(
    [11] => сукa
)

Класс определяет слова, в которых русские буквы заменены на визуально похожие английские (например: «с» → «c», «а» → «a», «к» → «k»).

Пример работы для проверки слова "сок" - будут сгенерированы следующие варианты слов для проверки:

• сoк (английская o вместо русской о)
• cок (английская c вместо русской с)
• соk (английская k вместо русской к)
• cok (все буквы английского алфавита)

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

Обновление словарей и пакета

composer update krugozor/russian-bad-words

Принцип работы резервных копий

При обновлении пакета система автоматически создает резервные копии измененных файлов словарей по следующему алгоритму:

graph TD
A[Начало обновления пакета] --> B{Файл словаря изменился?}
B -->|Да| C[Создать резервную копию]
B -->|Нет| D[Пропустить файл]
C --> E[Обновить файл словаря]
D --> F[Завершение обработки]
E --> F

Основные правила

1. Создание резервных копий происходит ТОЛЬКО при:
   • Наличии существующего файла словаря
   • Отличии содержимого нового файла от текущег
2. Формат имени резервного файла ГГГГ-ММ-ДД_ЧЧММСС_ИмяФайла.php
   • Пример: 2025-08-08_153045_StopWordsValidator.php
3. Расположение
   • Все резервные копии сохраняются в папке dictionaries

Пример сценария

До обновления:

dictionaries/
├── StopWordsValidator.php (ваша версия)
└── ProfanityWordsValidator.php (версия из репозитория)

После обновления:

dictionaries/
├── StopWordsValidator.php (версия из репозитория)
├── 2025-08-08_153045_StopWordsValidator.php (ваша старая версия)
└── ProfanityWordsValidator.php (версия из репозитория)

Управление резервными копиями

# Просмотр резервных копий
ls dictionaries/*_*.php

# Восстановление из резервной копии
cp dictionaries/2025-08-08_153045_StopWordsValidator.php dictionaries/StopWordsValidator.php

Важно: Система никогда не удаляет резервные копии автоматически

Добавление своих слов

Откройте нужный файл словаря и добавьте слова в массив:

// dictionaries/StopWordsValidator.php
return [
    // ...
    'электроудочка',
    'наркотик',
    'гадалка',
    // Добавьте свои слова здесь
    'новоезапрещенноеслово',
    'другоенедопустимоеслово',
];

Но лучше сделайте Merge request, если добавляете общеизвестные и частоупотребимые слова.

Удаление пакета

composer remove krugozor/russian-bad-words

При удалении файлы словарей остаются в вашем проекте.