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

📋 Table of Contents

• Requirements
• Installation
• Quick Start
• Configuration
• Usage Examples
• Advanced Features
• API Reference
• Troubleshooting
• Contributing
• License

🎯 Requirements

📦 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

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

3.2. Create Your Captcha

1. Navigate to Yandex SmartCaptcha service
2. Click Create captcha
3. 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
4. Click Create

3.3. Copy Your Keys

1. Open your created captcha
2. Go to Overview tab
3. 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

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

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:

1. ❌ Invalid client key

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

2. ❌ Domain not whitelisted

   • Go to Yandex Cloud Console
   • Add your domain to allowed domains
   • Or disable domain verification

3. ❌ JavaScript errors

   • Open browser console (F12)
   • Check for errors
   • Ensure no ad blockers are interfering

Validation Always Fails

Possible causes:

1. ❌ Invalid secret key

   YANDEX_CAPTCHA_SECRET_KEY=your-correct-secret-key

2. ❌ Token expired

   • Tokens expire after 5 minutes
   • User must complete captcha before submitting

3. ❌ 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

• 📖 Yandex SmartCaptcha Documentation
• 🐛 Report an Issue
• 💬 Discussions
• 📧 Email: sovletig@gmail.com

📁 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

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. 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