📱 FarazSMS Login Plugin

مستندات فنی جامع افزونه ورود با پیامک وردپرس

📋

نمای کلی فنی

افزونه FarazSMS Login با معماری OOP طراحی شده و شامل کلاس‌های اصلی زیر است.

ساختار فایل‌ها

farazsms-login/
├── admin/ - پنل مدیریتی
├── includes/ - کلاس‌های اصلی
├── templates/ - تمپلت‌های فرم
└── farazsms-login.php - فایل اصلی
🏗️

معماری سیستم

کلاس‌های اصلی سیستم

کلاس مسئولیت namespace وضعیت
Login کلاس اصلی افزونه - نقطه ورود FarazSMS فعال
Main_Settings مدیریت فرم‌های ورود و ثبت‌نام FarazSMS فعال
Admin_Settings مدیریت پنل ادمین FarazSMS\Admin فعال
Helper توابع کمکی و هوک‌های عمومی FarazSMS فعال
Send_SMS ارسال پیامک از طریق API FarazSMS فعال
OTP مدیریت کدهای یکبار مصرف FarazSMS فعال
Wallet مدیریت کیف پول کاربران FarazSMS فعال
Form_Settings مدیریت تمپلت‌های فرم FarazSMS فعال
Wallet مدیریت کیف پول کاربران FarazSMS فعال

متودهای کلاس Main_Settings

شورتکد دکمه ورود: متود login_button_shortcode() برای ایجاد دکمه لینک به صفحه ورود استفاده می‌شود.
/**
 * Login button shortcode
 * @param array $atts Shortcode attributes
 * @return string Button HTML
 */
public function login_button_shortcode($atts) {
    // پارامترهای قابل استفاده:
    // - bg_color: رنگ پس‌زمینه
    // - text_color: رنگ متن
    // - text: متن دکمه
}

هوک‌های وردپرس استفاده شده

هوک کلاس/تابع اولویت توضیح
plugins_loaded Login::load_textdomain() 10 بارگذاری فایل‌های زبان
init Login::init_plugin() 10 راه‌اندازی افزونه
wp_enqueue_scripts Main_Settings::enqueue_frontend_assets() 10 بارگذاری فایل‌های فرانت‌اند
init add_shortcode('farazsms_login_form') 10 ثبت شورتکد فرم ورود
init add_shortcode('farazsms_login_button') 10 ثبت شورتکد دکمه ورود
wp_footer Main_Settings::display_exit_intent_slide() 10 نمایش اسلاید خروج
admin_enqueue_scripts Admin_Settings::enqueue_admin_scripts() 10 بارگذاری فایل‌های ادمین
register_activation_hook Login::activate() - فعال‌سازی افزونه
register_uninstall_hook Login::uninstall() - حذف افزونه

جریان کاری ورود کاربر

  1. کاربر شماره موبایل را وارد می‌کند
  2. سیستم شماره را اعتبارسنجی می‌کند
  3. کد یکبار مصرف تولید و ارسال می‌شود
  4. کد در دیتابیس ذخیره می‌شود
  5. کاربر کد را وارد می‌کند
  6. کد بررسی و کاربر وارد سیستم می‌شود

جریان ثبت‌نام

  1. کاربر شماره موبایل جدید وارد می‌کند
  2. کد تایید ارسال می‌شود
  3. کاربر نام کامل را وارد می‌کند
  4. کد تایید را وارد می‌کند
  5. حساب کاربری ایجاد می‌شود
  6. بونوس ثبت‌نام به کیف پول اضافه می‌شود
⚙️

پیکربندی و تنظیمات

تنظیمات SMS


'farazsms_login_settings' => [
    'sms' => [
        'api_key' => 'your_api_key',
        'sender' => 'your_sender_number',
        'pattern_code' => 'your_pattern_code',
        'code_length' => 6,
        'test_sender' => ''
    ]
]

تنظیمات ظاهری


'appearance' => [
    'theme' => 'style-1', // style-1, style-2, style-3, style-4
    'text_alignment' => 'center', // left, center, right
    'logo' => 'path_to_logo',
    'background_image' => '',
    'primary_color' => '#667eea',
    'background_color' => '',
    'background_color_box' => '',
    'text_color' => '',
    'border_color' => '',
    'custom_css' => ''
]

تنظیمات عمومی


'general' => [
    'terms_link' => '#',
    'redirect_after_login' => '',
    'checkout_redirect_to_login' => '0',
    'woocommerce_login_redirect' => '0'
]

تنظیمات کیف پول


'wallet' => [
    'enable_registration_bonus' => '1',
    'registration_bonus_amount' => '10000', // تومان
    'registration_bonus_description' => 'بونوس ثبت‌نام'
]

تنظیمات اسلاید خروج (Exit Intent Slide)


'slide' => [
    'enable_slide' => '0',
    'slide_position' => 'right', // right or left
    'slide_image' => '',
    'slide_title' => 'Registration Gift',
    'slide_description' => 'Sign up now and get a special gift!',
    'slide_countdown_minutes' => '1',
    'slide_button_text' => 'Sign Up',
    'slide_button_link' => '#',
    'slide_button_color' => '#0BD08B',
    'slide_background_color' => '#ffffff',
    'slide_text_color' => '#333333',
    'slide_title_color' => '#000000'
]

تنظیمات ارسال پیامک سفارشات WooCommerce

این بخش برای برنامه‌نویسانی که می‌خواهند ساختار تنظیمات ارسال پیامک سفارشات را درک کنند، طراحی شده است.

'woo_sms' => [
    'woo_sms_tabs' => [
        'type' => 'tabs',
        'width' => 'w100',
        'tabs' => [
            'customer' => [
                'title' => 'Customer SMS',
                'settings' => [
                    'sms_shortcodes' => [
                        'type' => 'html',
                        'title' => 'Shortcodes SMS',
                        'html' => '...'
                    ],
                    'heading_customer_sms' => [
                        'type' => 'heading',
                        'title' => 'Customer Order SMS'
                    ],
                    'customer_pending_enable' => [
                        'type' => 'switch',
                        'title' => 'Enable Pending SMS',
                        'value' => '0',
                        'width' => 'w20'
                    ],
                    'customer_pending_pattern' => [
                        'type' => 'text',
                        'title' => 'Pattern code for Pending',
                        'value' => '',
                        'width' => 'w30 ltr'
                    ],
                    'customer_pending_attributes' => [
                        'type' => 'textarea',
                        'title' => 'Pattern attributes for Pending',
                        'description' => 'Each parameter should be on one line',
                        'value' => '',
                        'width' => 'w50 ltr'
                    ]
                ]
            ],
            'admin' => [
                'title' => 'Admin SMS',
                'settings' => [
                    'heading_admin_sms' => [
                        'type' => 'heading',
                        'title' => 'Admin Order SMS'
                    ],
                    'admin_phone' => [
                        'type' => 'text',
                        'title' => 'Admin mobile number',
                        'description' => 'Enter admin mobile number',
                        'value' => '',
                        'width' => 'w100'
                    ],
                    'admin_pending_enable' => [
                        'type' => 'switch',
                        'title' => 'Enable Pending SMS',
                        'value' => '0',
                        'width' => 'w20'
                    ],
                    'admin_pending_pattern' => [
                        'type' => 'text',
                        'title' => 'Pattern code for Pending',
                        'value' => '',
                        'width' => 'w30 ltr'
                    ],
                    'admin_pending_attributes' => [
                        'type' => 'textarea',
                        'title' => 'Pattern attributes for Pending',
                        'value' => '',
                        'width' => 'w50 ltr'
                    ]
                ]
            ]
        ]
    ]
]

ساختار تنظیمات ارسال پیامک

تنظیمات ارسال پیامک سفارشات به دو تب تقسیم شده است:
  • تب مشتری (Customer SMS): تنظیمات ارسال پیامک برای مشتریان در هر وضعیت سفارش
  • تب مدیر (Admin SMS): تنظیمات ارسال پیامک برای مدیر سایت در هر وضعیت سفارش

نوع فیلد Tabs


'tabs_field' => [
    'type' => 'tabs',
    'width' => 'w100',
    'tabs' => [
        'tab_key_1' => [
            'title' => 'عنوان تب اول',
            'settings' => [
                'field_id_1' => [
                    'type' => 'text',
                    'title' => 'عنوان فیلد',
                    'value' => '',
                    'width' => 'w50'
                ]
            ]
        ],
        'tab_key_2' => [
            'title' => 'عنوان تب دوم',
            'settings' => [
                'field_id_2' => [
                    'type' => 'switch',
                    'title' => 'فعال/غیرفعال',
                    'value' => '0',
                    'width' => 'w100'
                ]
            ]
        ]
    ]
]

شورتکدهای قابل استفاده در پیامک‌ها

شورتکد توضیح
mobile شماره موبایل مشتری
email ایمیل مشتری
status وضعیت سفارش
all_items محصولات سفارش
price مبلغ سفارش
order_id شماره سفارش
transaction_id شماره تراکنش
date تاریخ سفارش
b_first_name نام مشتری (از بخش فاکتور)
b_last_name نام خانوادگی مشتری
s_first_name نام مشتری (از بخش ارسال)
post_tracking_code کد رهگیری پست

الگوی استفاده از Pattern


// در فایل class-woocommerce-sms.php
// برای هر وضعیت سفارش باید:
1. Pattern Code را از تنظیمات دریافت کنید
2. Pattern Attributes را دریافت و پارس کنید
3. مقادیر را با استفاده از شورتکدها جایگزین کنید
4. از طریق API FarazSMS ارسال کنید

$pattern_code = Farazsms_Get_Setting('woo_sms', 'customer_pending_pattern');
$attributes = Farazsms_Get_Setting('woo_sms', 'customer_pending_attributes');
$attributes_array = explode("\n", $attributes);

$params = [];
foreach ($attributes_array as $attr) {
    $attr = trim($attr);
    if (!empty($attr)) {
        $params[$attr] = $this->replace_shortcode($attr, $order);
    }
}

// ارسال پیامک با Pattern
$sms = new \FarazSMS\Send_SMS();
$sms->send_pattern($phone, $pattern_code, $params);
نکته امنیتی: تنظیمات SMS شامل اطلاعات حساس API است. همیشه از HTTPS استفاده کنید و دسترسی به فایل‌های تنظیمات را محدود کنید.

نحوه ایجاد تنظیمات جدید

برای اضافه کردن فیلد تنظیمات جدید، مراحل زیر را دنبال کنید:

۱. ویرایش کلاس Settings

// فایل: admin/class-main-settings.php
// در متد All_Settings() بخش مورد نظر را ویرایش کنید

'general' => [
    'settings' => [
        // تنظیمات موجود...
        'new_setting' => [
            'type' => 'text', // text, number, select, checkbox, color, file
            'title' => __('عنوان تنظیمات', 'farazsms'),
            'description' => __('توضیح تنظیمات', 'farazsms'),
            'value' => $general['new_setting'] ?? 'default_value',
            'width' => 'w50', // w25, w50, w75, w100
        ],
    ],
],

۲. ذخیره تنظیمات

// فایل: admin/class-main-settings.php
// در متد save_settings() کد ذخیره را اضافه کنید

if (isset($_POST['new_setting'])) {
    $settings['general']['new_setting'] = sanitize_text_field($_POST['new_setting']);
}

۳. استفاده از تنظیمات

// در هر فایل PHP
$value = Farazsms_Get_Setting('general', 'new_setting');

// یا
$settings = get_option('farazsms_login_settings');
$value = $settings['general']['new_setting'] ?? 'default';

انواع فیلدهای پشتیبانی شده

نوع فیلد توضیح مثال
text فیلد متنی ساده 'type' => 'text'
number فیلد عددی 'type' => 'number'
select لیست انتخابی 'type' => 'select', 'options' => ['key' => 'value']
checkbox چک‌باکس 'type' => 'checkbox'
color انتخاب رنگ 'type' => 'color'
file بارگذاری فایل 'type' => 'file', 'format' => 'img'
switch کلید روشن/خاموش 'type' => 'switch', 'value' => '0'
tabs تب‌های تنظیمات 'type' => 'tabs', 'tabs' => [...]
🔌

API و AJAX Endpoints

شورتکدهای موجود

۱. شورتکد فرم ورود

// نمایش فرم کامل ورود و ثبت‌نام
[farazsms_login_form]

// در قالب PHP
<?php echo do_shortcode('[farazsms_login_form]'); ?>

۲. شورتکد دکمه ورود/عضویت

این شورتکد یک دکمه لینک به صفحه ورود ایجاد می‌کند:

// استفاده پایه
[farazsms_login_button]

// با پارامترهای سفارشی
[farazsms_login_button bg_color="#0BD08B" text_color="#ffffff"]
[farazsms_login_button bg_color="#6d50fa" text_color="#ffffff" text="ورود / عضویت"]

// پارامترهای قابل استفاده:
// - bg_color: رنگ پس‌زمینه دکمه (پیش‌فرض: #0BD08B)
// - text_color: رنگ متن دکمه (پیش‌فرض: #ffffff)
// - text: متن دکمه (پیش‌فرض: "ورود / عضویت")

// در قالب PHP
<?php echo do_shortcode('[farazsms_login_button bg_color="#0BD08B"]'); ?>

Endpoints AJAX

Action Method دسترسی توضیح
identifier_ajax_handler POST همه کاربران ارسال کد برای شماره موبایل
login_ajax_handler POST همه کاربران ورود با کد تایید
register_ajax_handler POST همه کاربران ثبت‌نام کاربر جدید
forget_mobile_password_ajax_handler POST همه کاربران فراموشی رمز عبور
reset_password_ajax_handler POST همه کاربران بازنشانی رمز عبور
farazsms_send_test_sms POST مدیران ارسال پیامک تست
farazsms_wallet_transaction POST مدیران مدیریت تراکنش‌های کیف پول

مثال استفاده از AJAX


// ارسال کد برای شماره موبایل
jQuery.ajax({
    url: farazsms_ajax.ajax_url,
    type: 'POST',
    data: {
        action: 'identifier_ajax_handler',
        nonce: farazsms_ajax.nonce,
        data: new URLSearchParams({
            identifier: '09123456789',
            back_url: window.location.href
        }).toString()
    },
    success: function(response) {
        if (response.success) {
            console.log('کد ارسال شد');
        } else {
            console.error(response.data.message);
        }
    }
});

API کلاس Send_SMS

public function send($phone, $message): bool
public function code(): string

API کلاس Wallet

public static function get_balance($user_id): float
public static function add_credit($user_id, $amount, $description): bool
public static function deduct_balance($user_id, $amount, $description): bool
💾

ساختار دیتابیس

جدول farazsms_verification

فیلد نوع توضیح کلید
id BIGINT UNSIGNED شناسه منحصر به فرد PRIMARY KEY
verification VARCHAR(100) شماره موبایل یا ایمیل UNIQUE
code VARCHAR(10) کد یکبار مصرف -
expire_date DATETIME زمان انقضا -

جدول farazsms_wallet

فیلد نوع توضیح کلید
id BIGINT UNSIGNED شناسه تراکنش PRIMARY KEY
user_id BIGINT UNSIGNED شناسه کاربر INDEX
amount DECIMAL(10,2) مبلغ تراکنش -
description TEXT توضیح تراکنش -
transaction_type ENUM('credit', 'debit') نوع تراکنش -
order_id BIGINT UNSIGNED شناسه سفارش (اختیاری) INDEX
created_at DATETIME زمان ایجاد -
created_by BIGINT UNSIGNED ایجاد کننده تراکنش -

Options ذخیره شده


// تنظیمات اصلی افزونه
get_option('farazsms_login_settings');

// تنظیمات اضافی (اگر وجود داشته باشد)
get_option('farazsms_wallet_settings');
get_option('farazsms_sms_settings');
نکته: تمام جداول با پیشوند {$wpdb->prefix} ایجاد می‌شوند تا با تنظیمات دیتابیس وردپرس سازگار باشند.
🚀

توسعه و هوک‌ها

هوک‌های توسعه

هوک پارامترها توضیح
farazsms_before_send_sms $phone, $message قبل از ارسال پیامک
farazsms_after_registration $user_id, $mobile بعد از ثبت‌نام موفق
farazsms_wallet_transaction $user_id, $amount, $type بعد از تراکنش کیف پول

مثال هوک

// اعتبار هدیه بعد از ثبت‌نام
add_action('farazsms_after_registration', 'give_bonus', 10, 2);
function give_bonus($user_id, $mobile) {
    \FarazSMS\Wallet::add_credit($user_id, 10000, 'بونوس');
}

عیب‌یابی

  • تنظیمات API را بررسی کنید
  • لاگ خطاها را چک کنید
  • افزونه‌های تداخل‌کننده را غیرفعال کنید