Shielda Captcha for Laravel (پکیج رسمی شیلدا برای لاراول)

پکیج رسمی و متن‌باز سامانه شیلدا (Shielda) برای فریم‌ورک محبوب لاراول (Laravel). این پکیج امکان اعتبارسنجی چالش‌های امنیتی و محافظت از فرم‌ها در برابر ربات‌ها و حملات Brute-Force را با چند خط کد ساده فراهم می‌سازد.

🚀 ویژگی‌ها

• ⚡️ نصب فوق‌العاده آسان با پشتیبانی کامل از Package Auto-Discovery لاراول
• 🎨 دایرکتیوهای اختصاصی Blade جهت لود اسکریپت و قرار دادن کانتینر ویجت
• 🛡️ ولیدیشن رول اختصاصی (shielda) برای استفاده در کنترلرها و FormRequest
• 🎛️ فاساد اختصاصی (Shielda::verify()) برای اعتبارسنجی دستی و دسترسی به جزییات پاسخ
• 🌐 سازگاری کامل با نسخه‌های PHP 8.1 به بالا و Laravel 10، 11 و 12

📦 نصب و راه‌اندازی

ابتدا پکیج را با دستور زیر از طریق Composer نصب کنید:

composer require shielda/laravel

(در لاراول ۱۰ و بالاتر، پکیج به صورت خودکار شناسایی و لود می‌شود).

⚙️ تنظیمات (Configuration)

۱. تنظیم متغیرهای محیطی (.env)

کلیدهای دریافت شده از پنل کاربری شیلدا را در فایل .env پروژه خود قرار دهید:

SHIELDA_SITE_KEY=your_site_key_here
SHIELDA_SECRET_KEY=your_secret_key_here

۲. انتشار فایل کانفیگ (اختیاری)

در صورت تمایل به تغییر تنظیمات پیش‌فرض (مانند زبان، تم یا پیام‌های خطا)، فایل کانفیگ را منتشر کنید:

php artisan vendor:publish --tag=shielda-config

فایل تنظیمات در مسیر config/shielda.php قرار خواهد گرفت:

return [
    'site_key'      => env('SHIELDA_SITE_KEY', ''),
    'secret_key'    => env('SHIELDA_SECRET_KEY', ''),
    'verify_url'    => env('SHIELDA_VERIFY_URL', 'https://shielda.ir/api/v1/siteverify'),
    'widget_url'    => env('SHIELDA_WIDGET_URL', 'https://shielda.ir/widget/api.js'),
    'input_name'    => env('SHIELDA_INPUT_NAME', 'darban-captcha-response'),
    'timeout'       => env('SHIELDA_TIMEOUT', 10.0),
    'theme'         => env('SHIELDA_THEME', 'auto'), // auto, light, dark
    'lang'          => env('SHIELDA_LANG', 'fa'),   // fa, en
    'error_message' => 'کد امنیتی (کپچا) تایید نشد یا منقضی شده است.',
];

💻 نحوه استفاده

۱. نمایش کپچا در صفحات Blade

در فرم مورد نظر (مثلاً فرم لاگین یا ثبت‌نام):

<form method="POST" action="{{ route('login') }}">
    @csrf

    <input type="email" name="email" placeholder="ایمیل" required>
    <input type="password" name="password" placeholder="کلمه عبور" required>

    <!-- ویجت شیلدا کپچا -->
    @shieldaWidget

    @error('darban-captcha-response')
        <span class="text-danger">{{ $message }}</span>
    @enderror

    <button type="submit">ورود به حساب</button>
</form>

<!-- اسکریپت شیلدا (در تگ head یا انتهای body) -->
@shieldaScripts

نکته: همچنین می‌توانید از دایرکتیو یکپارچه @shielda برای اضافه کردن همزمان اسکریپت و کانتینر استفاده کنید.

۲. اعتبارسنجی در کنترلر یا FormRequest

شما می‌توانید به سادگی از رول اعتبارسنجی shielda استفاده کنید:

روش اول: اعتبارسنجی با Validator یا FormRequest (روش پیشنهادی)

namespace App\Http\Controllers;

use Illuminate\Http\Request;

class AuthController extends Controller
{
    public function login(Request $request)
    {
        $request->validate([
            'email'                   => 'required|email',
            'password'                => 'required|string',
            'darban-captcha-response' => 'required|shielda',
        ]);

        // فرآیند ورود کاربر پس از اعتبارسنجی موفق...
    }
}

یا با استفاده از شیء کلاس Rule:

use Shielda\Laravel\Rules\ShieldaRule;

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

۳. اعتبارسنجی دستی با استفاده از فاساد (Facade)

اگر می‌خواهید در سناریوهای خاص به صورت دستی توکن را بررسی کنید یا جزییات کامل پاسخ سرور شیلدا را دریافت نمایید:

use Shielda\Laravel\Facades\Shielda;

// بررسی وضعیت بولین (true / false)
$isValid = Shielda::verify($request->input('darban-captcha-response'));

if ($isValid) {
    // کپچا تایید شد
}

// یا دریافت جزییات کامل ارزیابی:
$details = Shielda::verifyResponse($request->input('darban-captcha-response'));
/*
خروجی نمونه:
[
    'success' => true,
    'challenge_ts' => '2026-10-13T10:00:00Z',
    'hostname' => 'yourdomain.com',
    'error_codes' => []
]
*/

🧪 تست و عیب‌یابی

اگر نیاز به شبیه‌سازی یا تست اعتبارسنجی دارید، می‌توانید با متد فیک لاراول یا تزریق پاسخ مورد نظر آن را شبیه‌سازی کنید:

use Shielda\Laravel\Facades\Shielda;

Shielda::shouldReceive('verify')->once()->andReturn(true);

📄 لایسنس

این پکیج تحت مجوز MIT License منتشر شده است و استفاده از آن در پروژه‌های تجاری و شخصی کاملاً آزاد است.

• وب‌سایت رسمی: https://shielda.ir
• مستندات و پشتیبانی: support@shielda.ir