✨ Основные функции

📋 Содержание

• Требования
• Установка
• Быстрый старт
• Конфигурация
• Примеры использования
• Расширенные возможности
• Справочник API
• Решение проблем
• Участие в проекте
• Лицензия

🎯 Требования

📦 Руководство по установке

Шаг 1: Добавление пакета через Composer

Шаг 2: Экспорт файла конфигурации

Это сгенерирует

Шаг 3: Получение учётных данных Yandex SmartCaptcha

3.1. Настройка Yandex Cloud

1. Перейдите в Консоль Yandex Cloud
2. Авторизуйтесь или зарегистрируйте профиль
3. Проверьте активность платёжного аккаунта (бесплатный план доступен)

3.2. Создание экземпляра капчи

1. Откройте панель Yandex SmartCaptcha
2. Выберите Создать капчу
3. Укажите параметры:
   • Метка:
     my-app-captcha
     (настраиваемо)
   • Разрешённые домены: Домен вашего сайта (например,
     example.com
     )
   • Метод проверки: Флажок или Слайдер
   • Формат задания: Текстовая головоломка
   • Уровень сложности: Лёгкий, Средний или Сложный
4. Подтвердите создание

3.3. Получение API-ключей

1. Откройте настройки капчи
2. Перейдите в раздел Обзор
3. Извлеките оба ключа:
   • Ключ клиента (фронтенд-интеграция)
   • Ключ сервера (бэкенд-валидация)

Шаг 4: Настройка окружения

Добавьте в файл

🚀 Быстрый старт

Простая реализация

Интегрируйте проверку капчи в формы Filament:

Готово! 🎉 Компонент обрабатывает:

• ✅ Отрисовку виджета
• ✅ Проверку ввода пользователя
• ✅ Управление ошибками
• ✅ Адаптацию тем

⚙️ Конфигурация

Настройка окружения

Файл конфигурации

Файл

💡 Примеры использования

1️⃣ Форма обратной связи

2️⃣ Защита страницы аутентификации

Активируйте в конфигурации панели:

3️⃣ Расширенная конфигурация

4️⃣ Реализация скрытого режима

Подходит для форм подписки и минималистичных интерфейсов:

5️⃣ Обработчики событий

Добавьте JavaScript функции:

🎨 Расширенные возможности

Поддерживаемые языки

Поддержка тем

Тестовые режимы

Идеально для разработки и тестирования:

Или через окружение:

Кастомные сообщения валидации

Опубликуйте переводы:

Отредактируйте

Кастомные представления

Опубликуйте представления для полной кастомизации:

Отредактируйте

📚 Справочник API

Методы компонента YandexCaptcha

Правило валидации

Используйте правило валидации отдельно в любой форме Laravel:

🔧 Решение проблем

Виджет капчи не отображается

Возможные причины:

1. ❌ Неверный клиентский ключ

2. ❌ Домен не в белом списке

   • Перейдите в Консоль Yandex Cloud
   • Добавьте ваш домен в разрешённые
   • Или отключите проверку домена

3. ❌ Ошибки JavaScript

   • Откройте консоль браузера (F12)
   • Проверьте наличие ошибок
   • Убедитесь, что блокировщики рекламы не мешают

Валидация всегда проваливается

Возможные причины:

1. ❌ Неверный секретный ключ

2. ❌ Токен истёк

   • Токены истекают через 5 минут
   • Пользователь должен пройти капчу перед отправкой

3. ❌ Проблемы с сетью

   • Включите логирование для просмотра детальных ошибок:
   • Проверьте логи Laravel:
     storage/logs/laravel.log

Режим разработки

Для тестирования без реальной проверки капчи:

⚠️ Не забудьте вернуть

Получение помощи

• 📖 Документация Yandex SmartCaptcha
• 🐛 Сообщить о проблеме
• 💬 Обсуждения
• 📧 Email: sovletig@gmail.com

📁 Структура проекта

yandex-captcha-filament/
├── 📂 src/
│   ├── FilamentYandexCaptchaPlugin.php          # Основной плагин
│   ├── FilamentYandexCaptchaServiceProvider.php # Сервис-провайдер
│   ├── 📂 Forms/Components/
│   │   └── YandexCaptcha.php                    # Компонент формы
│   └── 📂 Rules/
│       └── YandexCaptchaRule.php                # Правило валидации
│
├── 📂 resources/
│   ├── 📂 lang/                                 # Переводы
│   │   ├── 📂 en/
│   │   │   └── validation.php
│   │   └── 📂 ru/
│   │       └── validation.php
│   └── 📂 views/                                # Blade шаблоны
│       └── forms/components/
│           └── yandex-captcha.blade.php
│
├── 📂 config/
│   └── yandex-captcha-filament.php              # Конфигурация
│
├── 📂 examples/                                 # Примеры использования
│   ├── BasicFormExample.php
│   ├── AdvancedFormExample.php
│   ├── LoginFormExample.php
│   ├── RegistrationFormExample.php
│   ├── InvisibleCaptchaExample.php
│   └── CustomCallbacksExample.php
│
├── 📄 README.md                                 # Документация (RU)
├── 📄 README-en.md                              # Документация (EN)
├── 📄 CHANGELOG.md                              # История версий
├── 📄 CONTRIBUTING.md                           # Руководство по участию
├── 📄 LICENSE                                   # Лицензия MIT
└── 📄 composer.json                             # Метаданные пакета

🤝 Участие в проекте

Мы приветствуем вклад в проект! Вот как вы можете помочь:

Способы участия

• 🐛 Сообщайте об ошибках - Открывайте issue
• 💡 Предлагайте функции - Делитесь идеями
• 📖 Улучшайте документацию - Исправляйте опечатки, добавляйте примеры
• 🔧 Отправляйте PR - Исправляйте баги, добавляйте функции

Настройка для разработки

Стандарты кодирования

• ✅ Следуйте PSR-12
• ✅ Добавляйте тесты для новых функций
• ✅ Обновляйте документацию
• ✅ Пишите понятные commit-сообщения

Процесс Pull Request

1. Сделайте fork репозитория
2. Создайте ветку функции (
   git checkout -b feature/amazing-feature
   )
3. Закоммитьте изменения (
   git commit -m 'Add amazing feature'
   )
4. Отправьте в ветку (
   git push origin feature/amazing-feature
   )
5. Откройте Pull Request

📄 Лицензия

Этот пакет является программным обеспечением с открытым исходным кодом, лицензированным по лицензии MIT.

MIT License

Copyright (c) 2025 Igor Sazonov

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

🙏 Благодарности

• Yandex Cloud за сервис SmartCaptcha
• Filament за потрясающую админ-панель
• Laravel за фантастический фреймворк
• Всем участникам и пользователям этого пакета

🔗 Ссылки

• 📦 Пакет: tigusigalpa/yandex-captcha-filament
• 🐙 GitHub: tigusigalpa/yandex-captcha-filament
• 🔧 Базовый пакет: tigusigalpa/yandex-smartcaptcha-php
• 📚 Yandex SmartCaptcha: Официальная документация
• 🎨 Filament: Официальный сайт

👨‍💻 Автор

Игорь Сазонов

• 🐙 GitHub: @tigusigalpa
• 📧 Email: sovletig@gmail.com
• 🌐 Сайт: GitHub Profile

💖 Поддержка

Если этот пакет оказался полезным, пожалуйста:

• ⭐ Поставьте звезду репозиторию
• 🐛 Сообщайте об ошибках и проблемах
• 💡 Предлагайте новые функции
• 📖 Улучшайте документацию
• 🔄 Делитесь с другими