README

🛡️ Filament Yandex Captcha

Yandex SmartCaptcha Integration for Laravel Filament v4

Protect your Filament forms with Yandex SmartCaptcha - the modern, user-friendly CAPTCHA solution

🚀 Quick Start • 📖 Documentation • 💡 Examples • 🤝 Contributing

✨ Features

🎨 Modern & Beautiful

Seamless Filament v4 integration
Light & dark theme support
Responsive design
Alpine.js powered

🔐 Secure & Reliable

Automatic validation
Server-side verification
Token-based authentication
Rate limiting support

🌍 Multi-language

8 languages supported
Easy localization
Custom translations
RTL support ready

⚙️ Highly Configurable

Invisible mode
Custom callbacks
Test modes
Full API access

🎯 Requirements

Requirement	Version
PHP	^8.1
Laravel	^10.0 \| ^11.0 \| ^12.0
Filament	^4.0
Base Package	tigusigalpa/yandex-smartcaptcha-php ^1.0

📦 Installation

Step 1: Install via Composer

composer require tigusigalpa/yandex-captcha-filament

Step 2: Publish Configuration

php artisan vendor:publish --tag=yandex-captcha-filament-config

This creates config/yandex-captcha-filament.php with all available options.

Step 3: Get Your Yandex SmartCaptcha Keys

3.1. Create Yandex Cloud Account

Visit Yandex Cloud Console
Sign in or create a new account
Ensure you have an active billing account (free tier available)

3.2. Create Your Captcha

Navigate to Yandex SmartCaptcha service
Click Create captcha
Configure your captcha:
- Name: my-app-captcha (or any name you prefer)
- Domains: Add your domain (e.g., example.com)
- Pre-check type: Checkbox or Slider
- Challenge type: Image-text task
- Complexity: Easy, Medium, or Hard
Click Create

3.3. Copy Your Keys

Open your created captcha
Go to Overview tab
Copy both keys:
- Client Key (for frontend widget)
- Server Key (for backend validation)

Step 4: Configure Environment

Add to your .env file:

YANDEX_CAPTCHA_CLIENT_KEY=your-client-key-here
YANDEX_CAPTCHA_SECRET_KEY=your-secret-key-here
YANDEX_CAPTCHA_LANGUAGE=en
YANDEX_CAPTCHA_THEME=light

🚀 Quick Start

Basic Usage

Add the captcha field to any Filament form:

use Tigusigalpa\FilamentYandexCaptcha\Forms\Components\YandexCaptcha;

public static function form(Form $form): Form
{
    return $form
        ->schema([
            TextInput::make('name')
                ->required(),
            
            TextInput::make('email')
                ->email()
                ->required(),
            
            YandexCaptcha::make('captcha')
                ->label('Verification')
                ->required(),
        ]);
}

That's it! 🎉 The captcha will automatically:

✅ Render the widget
✅ Validate user input
✅ Handle errors
✅ Support themes

⚙️ Configuration

Environment Variables

# Required
YANDEX_CAPTCHA_CLIENT_KEY=your-client-key
YANDEX_CAPTCHA_SECRET_KEY=your-secret-key

# Optional
YANDEX_CAPTCHA_LANGUAGE=en        # ru, en, be, kk, tt, uk, uz, tr
YANDEX_CAPTCHA_THEME=light        # light, dark
YANDEX_CAPTCHA_TEST_MODE=prod     # prod, force_pass, force_fail
YANDEX_CAPTCHA_LOGGING=false      # Enable error logging

Configuration File

The config/yandex-captcha-filament.php file provides full control:

return [
    'client_key' => env('YANDEX_CAPTCHA_CLIENT_KEY'),
    'secret_key' => env('YANDEX_CAPTCHA_SECRET_KEY'),
    'language' => env('YANDEX_CAPTCHA_LANGUAGE', 'en'),
    'theme' => env('YANDEX_CAPTCHA_THEME', 'light'),
    'test_mode' => env('YANDEX_CAPTCHA_TEST_MODE', 'prod'),
    'logging' => [
        'enabled' => env('YANDEX_CAPTCHA_LOGGING', false),
        'channel' => env('YANDEX_CAPTCHA_LOG_CHANNEL', 'stack'),
    ],
];

💡 Usage Examples

1️⃣ Contact Form

use Tigusigalpa\FilamentYandexCaptcha\Forms\Components\YandexCaptcha;

public static function form(Form $form): Form
{
    return $form
        ->schema([
            TextInput::make('name')->required(),
            TextInput::make('email')->email()->required(),
            Textarea::make('message')->required()->rows(5),
            
            YandexCaptcha::make('captcha')
                ->label('Security Check'),
        ]);
}

2️⃣ Login Form with Captcha

use App\Filament\Pages\Auth\Login as BaseLogin;
use Tigusigalpa\FilamentYandexCaptcha\Forms\Components\YandexCaptcha;

class Login extends BaseLogin
{
    public function form(Form $form): Form
    {
        return $form
            ->schema([
                $this->getEmailFormComponent(),
                $this->getPasswordFormComponent(),
                $this->getRememberFormComponent(),
                
                YandexCaptcha::make('captcha')
                    ->label('Security Verification'),
            ]);
    }
}

Register in your Panel provider:

->login(Login::class)

3️⃣ Advanced Configuration

YandexCaptcha::make('captcha')
    ->label('Verify you are human')
    ->clientKey('custom-client-key')      // Override config
    ->secretKey('custom-secret-key')      // Override config
    ->language('ru')                       // Set language
    ->theme('dark')                        // Set theme
    ->invisible()                          // Invisible mode
    ->hideAfterValidation()                // Hide after success
    ->callback('onCaptchaSuccess')         // Success callback
    ->errorCallback('onCaptchaError')      // Error callback
    ->testMode('force_pass');              // Test mode

4️⃣ Invisible Captcha

Perfect for newsletter subscriptions and simple forms:

YandexCaptcha::make('captcha')
    ->invisible()                    // No visible widget
    ->hideAfterValidation()          // Clean UI
    ->required();

5️⃣ Custom JavaScript Callbacks

YandexCaptcha::make('captcha')
    ->callback('onSuccess')
    ->errorCallback('onError')
    ->networkErrorCallback('onNetworkError');

Add JavaScript functions:

<script>
    function onSuccess(token) {
        console.log('Captcha verified!', token);
        // Your custom logic
    }

    function onError() {
        console.error('Captcha failed!');
    }

    function onNetworkError() {
        console.error('Network error!');
    }
</script>

🎨 Advanced Features

Supported Languages

Language	Code	Language	Code
🇷🇺 Russian	`ru`	🇺🇦 Ukrainian	`uk`
🇬🇧 English	`en`	🇺🇿 Uzbek	`uz`
🇧🇾 Belarusian	`be`	🇹🇷 Turkish	`tr`
🇰🇿 Kazakh	`kk`	🇷🇺 Tatar	`tt`

Theme Support

// Light theme (default)
YandexCaptcha::make('captcha')->theme('light');

// Dark theme
YandexCaptcha::make('captcha')->theme('dark');

Test Modes

Perfect for development and testing:

// Always pass validation
YandexCaptcha::make('captcha')->testMode('force_pass');

// Always fail validation
YandexCaptcha::make('captcha')->testMode('force_fail');

// Normal operation
YandexCaptcha::make('captcha')->testMode('prod');

Or via environment:

YANDEX_CAPTCHA_TEST_MODE=force_pass

Custom Validation Messages

Publish translations:

php artisan vendor:publish --tag=yandex-captcha-filament-translations

Edit resources/lang/vendor/yandex-captcha-filament/en/validation.php:

return [
    'required' => 'Please complete the captcha.',
    'failed' => 'Captcha verification failed.',
    'error' => 'An error occurred during verification.',
    'config_error' => 'Captcha is not configured properly.',
];

Custom Views

Publish views for full customization:

php artisan vendor:publish --tag=yandex-captcha-filament-views

Edit resources/views/vendor/yandex-captcha-filament/forms/components/yandex-captcha.blade.php

📚 API Reference

YandexCaptcha Component Methods

Method	Description	Example
`clientKey(string)`	Set client key	`->clientKey('key')`
`secretKey(string)`	Set secret key	`->secretKey('key')`
`language(string)`	Set widget language	`->language('ru')`
`theme(string)`	Set theme (light/dark)	`->theme('dark')`
`invisible(bool)`	Enable invisible mode	`->invisible()`
`hideAfterValidation(bool)`	Hide after success	`->hideAfterValidation()`
`callback(string)`	Success callback	`->callback('onSuccess')`
`errorCallback(string)`	Error callback	`->errorCallback('onError')`
`networkErrorCallback(string)`	Network error callback	`->networkErrorCallback('onNetworkError')`
`testMode(string)`	Set test mode	`->testMode('force_pass')`

Validation Rule

Use the validation rule separately in any Laravel form:

use Tigusigalpa\FilamentYandexCaptcha\Rules\YandexCaptchaRule;

$request->validate([
    'captcha' => ['required', new YandexCaptchaRule()],
]);

🔧 Troubleshooting

Captcha Widget Not Showing

Possible causes:

❌ Invalid client key

# Check your .env file
YANDEX_CAPTCHA_CLIENT_KEY=your-correct-key

❌ Domain not whitelisted
- Go to Yandex Cloud Console
- Add your domain to allowed domains
- Or disable domain verification
❌ JavaScript errors
- Open browser console (F12)
- Check for errors
- Ensure no ad blockers are interfering

Validation Always Fails

Possible causes:

❌ Invalid secret key

YANDEX_CAPTCHA_SECRET_KEY=your-correct-secret-key

❌ Token expired
- Tokens expire after 5 minutes
- User must complete captcha before submitting
❌ Network issues
- Enable logging to see detailed errors:
```
YANDEX_CAPTCHA_LOGGING=true
```
- Check Laravel logs: storage/logs/laravel.log

Development Mode

For testing without actual captcha verification:

YANDEX_CAPTCHA_TEST_MODE=force_pass

⚠️ Remember to set back to prod in production!

Getting Help

📁 Project Structure

yandex-captcha-filament/
├── 📂 src/
│   ├── FilamentYandexCaptchaPlugin.php          # Main plugin
│   ├── FilamentYandexCaptchaServiceProvider.php # Service provider
│   ├── 📂 Forms/Components/
│   │   └── YandexCaptcha.php                    # Form field component
│   └── 📂 Rules/
│       └── YandexCaptchaRule.php                # Validation rule
│
├── 📂 resources/
│   ├── 📂 lang/                                 # Translations
│   │   ├── 📂 en/
│   │   │   └── validation.php
│   │   └── 📂 ru/
│   │       └── validation.php
│   └── 📂 views/                                # Blade templates
│       └── forms/components/
│           └── yandex-captcha.blade.php
│
├── 📂 config/
│   └── yandex-captcha-filament.php              # Configuration
│
├── 📂 examples/                                 # Usage examples
│   ├── BasicFormExample.php
│   ├── AdvancedFormExample.php
│   ├── LoginFormExample.php
│   ├── RegistrationFormExample.php
│   ├── InvisibleCaptchaExample.php
│   └── CustomCallbacksExample.php
│
├── 📄 README.md                                 # This file
├── 📄 CHANGELOG.md                              # Version history
├── 📄 CONTRIBUTING.md                           # Contribution guide
├── 📄 LICENSE                                   # MIT License
└── 📄 composer.json                             # Package metadata

🤝 Contributing

We welcome contributions! Here's how you can help:

Ways to Contribute

🐛 Report bugs - Open an issue
💡 Suggest features - Share your ideas
📖 Improve docs - Fix typos, add examples
🔧 Submit PRs - Fix bugs, add features

Development Setup

# Clone repository
git clone https://github.com/tigusigalpa/yandex-captcha-filament.git
cd yandex-captcha-filament

# Install dependencies
composer install

# Run tests
composer test

# Check code style
composer cs-check

# Fix code style
composer cs-fix

# Run static analysis
composer phpstan

Coding Standards

✅ Follow PSR-12
✅ Add tests for new features
✅ Update documentation
✅ Write clear commit messages

Pull Request Process

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

📄 License

This package is open-sourced software licensed under the MIT license.

MIT License

Copyright (c) 2025 Igor Sazonov

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

🙏 Acknowledgments

Yandex Cloud for SmartCaptcha service
Filament for the amazing admin panel
Laravel for the fantastic framework
All contributors and users of this package

🔗 Links

📦 **Package **: tigusigalpa/yandex-captcha-filament
🐙 GitHub: tigusigalpa/yandex-captcha-filament
🔧 Base Package: tigusigalpa/yandex-smartcaptcha-php
📚 Yandex SmartCaptcha: Official Documentation
🎨 Filament: Official Website

👨‍💻 Author

Igor Sazonov

🐙 GitHub: @tigusigalpa
📧 Email: sovletig@gmail.com
🌐 Website: GitHub Profile

💖 Support

If you find this package helpful, please consider:

⭐ Star the repository
🐛 Report bugs and issues
💡 Suggest new features
📖 Improve documentation
🔄 Share with others

Made with ❤️ for the Laravel & Filament community

⬆ Back to Top

tigusigalpa / yandex-captcha-filament

Maintainers

Details