🔒 Pure Captcha

یک پکیج کپچای امن، قابل تنظیم و سبک برای PHP

🔒 Pure Captcha

A secure, customizable and lightweight PHP CAPTCHA package

⚡ Launch Live Demo PHP >= 7.4 MIT License Packagist Profile

📖 درباره پروژه

پکیج Pure Captcha یک ابزار سبک و بدون وابستگی (Dependency-free) برای تولید تصاویر کپچای امن در زبان PHP است. این سیستم تنها از افزونه داخلی GD خود زبان PHP بهره می‌گیرد و برای کارکرد به هیچ سرویس خارجی، کدهای سنگین جاوااسکریپت ساید یا دریافت کلیدهای API گوناگون نیازی ندارد.

✨ امکانات سیستم

  • 🎨 رابط کاربری زیبا: طراحی مدرن و کاملاً ریسپانسیو مجهز به ابزارهای رندر بک‌گراندهای گرادیانت و افکت‌های سایه.
  • 🔧 کاملاً قابل تنظیم: امکان پیکربندی آسان طول رشته متنی، ابعاد تصویر، فونت‌ها، ساختارهای رنگی، نویز و الگوها.
  • 🛡️ ۵ سطح سختی مجزا: پیاده‌سازی گام‌به‌گام لایه‌های حفاظتی از سطح فرانت معمولی low تا سطح حداکثر نفوذ nightmare.
  • 👻 حروف شبح (Ghost Characters): رندر کاراکترهای فرعی و مبهم در پس‌زمینه برای گمراه‌سازی مکانیزم ربات‌های تصویرخوان.
  • 🌊 اعوجاج موجی شکل: پیچ‌وتاب دادن سینوسی و هندسی به پیکسل‌های تصویر با هدف از کار انداختن فرآیند ابزارهای خودکار OCR.
  • 🔤 چندین مجموعه کاراکتر: تفکیک‌پذیری آسان حروف انگلیسی بزرگ و کوچک، کدهای عددی، کاراکترهای خاص یا پترن‌های ترکیبی.
  • 🌐 پشتیبانی از چندزبانه: بومی‌سازی بومی و پیش‌فرض داخلی برای زبان‌های فارسی (fa) و انگلیسی (en).
  • 🔄 دکمه رفرش متمرکز: بارگذاری مجدد تصاویر به کمک ساختار ماژولار AJAX همراه با اعمال افکت انیمیشن چرخشی چشمنواز.
  • 📦 بدون نیاز به وابستگی‌ها: سبک‌ترین ساختار اجرایی بدون انباشتگی فایل‌های جانبی با اتکای کامل به هسته ext-gd.
  • 🎯 پشتیبانی از استاندارد PSR-4: معماری ساختاریافته فضای نام و کلاس‌ها کاملاً سازگار و هماهنگ با ابزار لودینگ Composer.
  • ⏱️ کنترل زمان انقضا: منقضی ساختن توکن‌های امنیتی تولید شده در سشن سرور پس از عبور از بازه زمانی معین و قابل تنظیم.
  • 🔑 حساسیت به حروف (Optional): قابلیت سوییچ اختیاری و کنترل وضعیت اعتبارسنجی بزرگ یا کوچک بودن حروف (Case Sensitivity).

📋 پیش‌نیازها

  • PHP نسخه 7.4 یا بالاتر
  • اکستنشن تصویری GD (ext-gd)
  • اکستنشن مدیریت سشن‌ها (ext-session)

📥 فرآیند نصب

دستور زیر را در ترمینال پروژه خود جهت نصب پکیج از طریق کامپوزر وارد کنید:

composer require aminarjmand/pure-captcha

🚀 راهنمای شروع سریع

مرحله ۱: ساخت آدرس تصویر (Endpoint)

یک فایل با نام captcha_image.php ایجاد کنید و هسته رندر را صدا بزنید:

<?php
require 'vendor/autoload.php';
use AminArjmand\PureCaptcha\Captcha;

Captcha::renderImage();

مرحله ۲: تزریق و نمایش کدهای کپچا در فرم شما

کدهای خروجی ویجت را مطابق معماری زیر در فایل اصلی فرم خود لود کنید:

<?php
require 'vendor/autoload.php';
use AminArjmand\PureCaptcha\Captcha;
?>
<!DOCTYPE html>
<html lang="fa" dir="rtl">
<head>
    <meta charset="UTF-8">
    <title>فرم من</title>
    <?php echo Captcha::styles(); ?>
</head>
<body>
    <form method="POST" action="submit.php">

        <!-- سایر فیلدهای فرم -->
        <input type="text" name="name" placeholder="نام شما">

        <!-- گنجاندن ویجت تصویری کپچا -->
        <?php echo Captcha::html(); ?>

        <button type="submit">ارسال</button>
    </form>
</body>
</html>

مرحله ۳: فرآیند اعتبارسنجی توکن

در فایل پردازشگر مقصد (مثلاً submit.php) صحت ورودی کاربر را به شکل زیر ارزیابی نمایید:

<?php
require 'vendor/autoload.php';
use AminArjmand\PureCaptcha\Captcha;

if ($_SERVER['REQUEST_METHOD'] === 'POST') {
    $captchaInput = $_POST['captcha'] ?? '';

    if (Captcha::validate($captchaInput)) {
        echo '✅ کد امنیتی صحیح است! پردازش فرم انجام شد.';
    } else {
        echo '❌ کد امنیتی اشتباه است. لطفاً دوباره تلاش کنید.';
    }
}

⚙️ پارامترهای پیکربندی و داکیومنت کانفیگ

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

کافیست یک فایل با نام مشخص captcha_config.php در مسیر روت اصلی پروژه خود ایجاد کنید:

<?php
return [
    'lang'           => 'fa',
    'font'           => 'Vazirmatn.ttf',
    'expiry'         => 300,
    'length'         => 5,
    'width'         => 170,
    'height'         => 55,
    'font_size'     => 22,
    'char_type'     => 'mixed',
    'case_sensitive' => false,
    'noise_level'    => 'medium',
];

روش ۲: تغییر و اعمال تنظیمات در طول زمان اجرا (Runtime)

Captcha::configure([
    'noise_level' => 'extreme',
    'length'      => 6,
    'lang'        => 'fa',
    'char_type'   => 'letters',
]);
⚠️ توجه مهم: هنگام بهره‌گیری از متد خطی configure()، حتماً بایستی آن را هم درون فایل اصلی فرم و هم داخل اسکریپت رندرساز captcha_image.php فراخوانی کنید؛ به این دلیل که هر ریکوئست کلاینت پروتکل HTTP کاملاً مستقل عمل می‌کند.

جدول جامع گزینه‌های پیکربندی

تنظیم نوع داده پیش‌فرض توضیحات عملکرد پارامتر
langstring'fa'تنظیم زبان اصلی رابط کاربری: 'fa' یا 'en'
fontstring''نام فایل فونت اختصاصی (موجود در دایرکتوری fonts/) یا آدرس‌دهی مطلق
expiryint300مدت زمان مجاز ماندگاری و انقضای کد کپچا در حافظه موقت (ثانیه)
lengthint5تعداد کاراکترهای چیده شده در کادر خروجی متنی
widthint170میزان عرض کلی کادر خروجی تصویر رندر شده (پیکسل)
heightint55میزان ارتفاع کلی کادر خروجی تصویر رندر شده (پیکسل)
font_sizeint22سایز و مقیاس درج متون بر مبنای واحد پوینت استاندارد
char_typestring'mixed'مجموعه توکن کاراکترها: 'mixed'، 'letters'، 'numbers'، 'characters'
case_sensitiveboolfalseفعال‌سازی وضعیت حساسیت به تطابق متناظر حروف بزرگ و کوچک متنی
noise_levelstring'medium'موقعیت اعمال فیلترهای نویز و سختی خروجی پکیج

مجموعه آرایه‌های کاراکتری معتبر

کلید شناسه نوع لیست ساختار کاراکترهای بکارگیری شده
mixedABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789~!@#$%^&*()-+
lettersBABCDEFGHJKLMNPRSTUVWXYZ
lettersSabcdefghijklmnopqrstuvwxyz
numbers0123456789
characters~!@#$%^&*()-+

🎯 مراجع ارزیابی سطوح سختی لایه‌ها

سطح نقاط کمان خطوط چرخش شبکه شبح موج درجه سختی
low۱۰۰۰۱۰۱±۱۵°❌✅ (۲)❌⭐
medium۲۰۰۰۲۰۲±۲۰°❌✅ (۴)❌⭐⭐
high۳۰۰۰۳۰۴±۲۵°✅❌✅ (۶)⭐⭐⭐
extreme۴۰۰۰۴۰۶±۳۵°✅✅ (۸)❌⭐⭐⭐⭐
nightmare۵۰۰۰۵۰۸±۴۰°✅✅ (۱۰)✅⭐⭐⭐⭐⭐

تشریح رفتار توابع و فیلترهای نویز:

  • نقاط (Dots): پخش پیکسل‌های رنگی ریز و تصادفی در سطح لایه‌های تصویر وب.
  • کمان‌ها (Arcs): خطوط منحنی شکل رها در پس‌زمینه تصویر برای به هم ریختن یکپارچگی خطی.
  • خطوط (Lines): کشیدن بردارهای ضخیم مستقیم از روی کاراکترهای اصلی متنی.
  • چرخش (Rotation): اعمال زوایای انحرافی و مایل به هر کاراکتر به طور مجزا.
  • شبکه (Grid): توری کشی هندسی و شطرنجی بر روی المان‌های موجود در صفحه.
  • شبح (Ghosts): درج حروف کمرنگ و فرعی مات در لایه‌های زیرین جهت خطایابی ابزارهای OCR.
  • موج (Wave): جابجایی پیکسل‌ها به شیوه نوسانات توابع سینوسی که کل گرید را دچار دگرگونی فرمی می‌کند.

📚 مستندات و مرجع توابع API پکیج

Captcha::configure(array $options): void

تنظیم کردن المان‌های رفتاری و مقادیر کانفیگ در طول زمان اجرای برنامه.

Captcha::configure(['length' => 6, 'noise_level' => 'high']);

Captcha::get(string $key, mixed $default = null): mixed

خواندن مقدار یکی از پیکربندی‌های ذخیره شده در سیستم.

$lang = Captcha::get('lang'); // خروجی پیش‌فرض: 'fa'

Captcha::generate(): string

تولید یک توکن امنیتی کاملاً جدید و ذخیره‌سازی فوری آن در بطن سشن فعال سرور. این متد رشته متنی کد را برمی‌گرداند.

$code = Captcha::generate();

Captcha::validate(string $input): bool

بررسی انطباق مقدار ورودی ارسال شده توسط کاربر با مقدار ذخیره شده در سشن. در صورت صحت، خروجی true صادر می‌گردد. رشته کد به محض یک بار ارزیابی برای امنیت بیشتر از بین می‌رود (تک بار مصرف).

if (Captcha::validate($_POST['captcha'])) { /* معتبر است */ }

Captcha::renderImage(): void

تولید خروجی خام و مستقیم هدر پکت تصویری فرمت PNG و بستن اسکریپت جاری سرور.

Captcha::renderImage();

Captcha::html(string $imageUrl, string $inputName, ?string $lang): string

رندر کدهای فرمت استاندارد HTML اختصاصی به همراه متدهای کنترلی ویجت.

پارامتر ورودی مقدار پیش‌فرض توضیحات عملکرد توسعه یافته
$imageUrl'captcha_image.php'آدرس فایل پردازشگر و رندرساز محلی تصویر
$inputName'captcha'مقدار شناسه تخصیص یافته به اتریبیوت Name فیلد ورودی متن
$langnullنادیده گرفتن تنظیم عمومی و اورراید موضعی زبان پکیج

Captcha::styles(): string

تولید تگ استایل درون‌برنامه‌ای CSS متناسب با نیازمندی‌های بصری پوسته ویجت.

🎨 راه‌اندازی و لود فونت‌های سفارشی

۱. فایل با پسوند .ttf خود را در فولدر داخلی پکیج تحت دایرکتوری fonts/ آپلود کنید یا آدرس‌دهی کامل را اختصاص دهید.

۲. تنظیم مقدار کلید فونت در آرایه کانفیگ پروژه:

// فقط ذکر نام فایل (جستجو در پوشه پیش‌فرض پکیج)
'font' => 'MyCustomFont.ttf'

// یا اختصاص دادن آدرس‌دهی مطلق سیستمی
'font' => '/path/to/fonts/MyCustomFont.ttf'

اگر هیچ فونتی تعریف نشود، پکیج به صورت فال‌بک سراغ فونت‌های سیستم و در بدترین حالت، به سراغ فونت بیت‌مپ هسته اصلی داخلی PHP می‌رود.

🔧 مثال‌های کاربردی سناریو محور

نمونه کپچای سبک عددی

Captcha::configure([
    'char_type'   => 'numbers',
    'length'      => 4,
    'noise_level' => 'low',
]);

نمونه پیاده‌سازی کپچای با امنیت فوق‌العاده بالا

Captcha::configure([
    'char_type'      => 'mixed',
    'length'         => 7,
    'noise_level'    => 'extreme',
    'case_sensitive' => true,
    'expiry'         => 120,
]);

📁 ساختار درختی پوشه‌های پروژه

pure-captcha/
├── src/
│   └── Captcha.php          # کلاس اصلی پکیج
├── config/
│   └── captcha.php          # فایل کانفیگ پیش‌فرض سیستم
├── fonts/
│   └── .gitkeep             # محل قرارگیری فونت‌های با فرمت TTF
├── composer.json
├── README.md
└── LICENSE

🤝 مشارکت در توسعه و کپی‌رایت پروژه

از تمامی گزارش‌های خطا، درخواست اضافه کردن ویژگی‌ها و ثبت پول‌ریکوئست‌های توسعه‌دهندگان به گرمی استقبال می‌شود!

این پروژه تحت لایسنس بین‌المللی و عمومی MIT License منتشر و عرضه شده است.

📖 About Pure Captcha

Pure Captcha is a lightweight, dependency-free PHP CAPTCHA package that generates secure CAPTCHA images using only PHP's built-in GD extension. No external cloud services, no heavy JavaScript dependencies, and no remote API keys are required.

✨ Core Package Features

  • 🎨 Beautiful UI: Modern, fully responsive component layouts boasting elegant color gradient fills and soft shadow accents.
  • 🔧 Fully Customizable: Direct runtime configurations over layout sizing metrics, custom lengths, hex color palettes, and obfuscation noises.
  • 🛡️ 5 Difficulty Environments: Scale security parameters fluidly extending from base configurations low up to brute-force protection nightmare.
  • 👻 Ghost Characters: Blends faint, distorted background decoy text structures onto the canvas plane to significantly blind OCR computer models.
  • 🌊 Wave Distortion Filters: Applies sinusoidal grid warping algorithms over output pixel structures to thoroughly counter automated reading scripts.
  • 🔤 Multiple Sets: Effortlessly filter between mixed alphabetic characters, simple integers, specialized characters, or tailored combined arrays.
  • 🌐 Localization Features: Bundled out-of-the-box native localization layouts supporting Persian (fa) and English (en) forms.
  • 🔄 Asynchronous Sync Refresh: Features optimized AJAX-driven asset replacement endpoints accompanied by crisp CSS spinning styling animations.
  • 📦 Zero Bloat Overheads: Independent execution profile isolated from structural packages, operating on pure native core PHP modules.

📋 Technical Requirements

  • PHP Framework Build Engine >= 7.4
  • Local GD Graphic Extension Library (ext-gd)
  • Core Session Storage Pipeline Module (ext-session)

📥 Package Installation

Execute the standard repository command through your terminal environment using Composer:

composer require aminarjmand/pure-captcha

🚀 Developer Quick Start Manual

Step 1: Build the Image Rendering Endpoint

Create a standalone routing file designated as captcha_image.php:

<?php
require 'vendor/autoload.php';
use AminArjmand\PureCaptcha\Captcha;

Captcha::renderImage();

Step 2: Append Widget Containers into Form Blocks

Integrate the core HTML rendering hooks directly inside your view component parameters:

<?php
require 'vendor/autoload.php';
use AminArjmand\PureCaptcha\Captcha;
?>
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>My Form</title>
    <?php echo Captcha::styles(); ?>
</head>
<body>
    <form method="POST" action="submit.php">

        <input type="text" name="name" placeholder="Your name">

        <!-- CAPTCHA Widget Generation -->
        <?php echo Captcha::html(); ?>

        <button type="submit">Submit</button>
    </form>
</body>
</html>

Step 3: Handle Request Token Verification

Process user input matching inside your form target controller (e.g. submit.php):

if (Captcha::validate($_POST['captcha'])) {
    echo '✅ CAPTCHA validation passed successfully!';
} else {
    echo '❌ Invalid CAPTCHA token provided.';
}

⚙️ System Configuration Matrix

Method 1: Local Setup Files

Generate a captcha_config.php schema wrapper within your working directory root:

<?php
return [
    'lang'           => 'en',
    'font'           => 'Vazirmatn.ttf',
    'expiry'         => 300,
    'length'         => 5,
    'width'         => 170,
    'height'         => 55,
    'font_size'     => 22,
    'char_type'     => 'mixed',
    'case_sensitive' => false,
    'noise_level'    => 'medium',
];

Method 2: Runtime Configuration Injection

Captcha::configure([
    'noise_level' => 'extreme',
    'length'      => 6,
    'lang'        => 'en',
]);
⚠️ Crucial Developer Note: When executing runtime modifications via configure() arrays, definitions must be explicitly called in **both** the interface form file and the image router file (captcha_image.php).

Configuration Options Reference Table

Option Key Data Type Default Description
langstring'fa'Target widget language localization ('fa' / 'en')
fontstring''Target internal fonts/ directory filename string or absolute pathing
expiryint300Token lifespan threshold configuration in seconds
lengthint5Total character count sequence rendered inside image containers
widthint170Total bounded pixel horizontal width dimensions
heightint55Total bounded pixel vertical height dimensions
font_sizeint22Point values scale used for compiling alphanumeric graphics
char_typestring'mixed'Character libraries mapping identifier types
case_sensitiveboolfalseEnforces validation matches matching strict case states
noise_levelstring'medium'Difficulty level presets matching noise algorithms

🎯 Difficulty Presets Table Metric

Level Dots Arcs Lines Rotation Grid Ghosts Wave
low1000101±15°❌✅ (2)❌
medium2000202±20°❌✅ (4)❌
high3000304±25°✅✅ (6)❌
extreme4000406±35°✅✅ (8)❌
nightmare5000508±40°✅✅ (10)✅

📚 API Core Reference

Captcha::validate(string $input): bool

Validates raw string tokens directly against stored session parameters. Destroys the reference instantly upon evaluation to maintain one-time-use security integrity.

📁 Repository Structural Blueprints

pure-captcha/
├── src/
│   └── Captcha.php          # Main system namespace controller
├── config/
│   └── captcha.php          # Default setup parameters array
└── composer.json

Developed and Maintained with ❤️ by Amin Arjmand

🏠 صفحه مخازن 🐙 گیت‌هاب مخزن