نمای کلی فنی
افزونه FarazSMS Login با معماری OOP طراحی شده و شامل کلاسهای اصلی زیر است.
ساختار فایلها
farazsms-login/
├── admin/ - پنل مدیریتی
├── includes/ - کلاسهای اصلی
├── templates/ - تمپلتهای فرم
└── farazsms-login.php - فایل اصلی
├── 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() |
- | حذف افزونه |
جریان کاری ورود کاربر
- کاربر شماره موبایل را وارد میکند
- سیستم شماره را اعتبارسنجی میکند
- کد یکبار مصرف تولید و ارسال میشود
- کد در دیتابیس ذخیره میشود
- کاربر کد را وارد میکند
- کد بررسی و کاربر وارد سیستم میشود
جریان ثبتنام
- کاربر شماره موبایل جدید وارد میکند
- کد تایید ارسال میشود
- کاربر نام کامل را وارد میکند
- کد تایید را وارد میکند
- حساب کاربری ایجاد میشود
- بونوس ثبتنام به کیف پول اضافه میشود
پیکربندی و تنظیمات
تنظیمات 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 را بررسی کنید
- لاگ خطاها را چک کنید
- افزونههای تداخلکننده را غیرفعال کنید