تجاوز إلى المحتوى الرئيسي
الإصدار: 1.x

قالب بوابة الدفع

يوفر قالب بوابة WooCommerce نقطة انطلاق لإنشاء بوابات الدفع المخصصة الخاصة بك لـ WooCommerce POS. يتضمن هذا القالب جميع الكود الهيكلي اللازم لبناء بوابة دفع تعمل بالكامل.

الميزات​

  • قالب كامل: هيكل بوابة جاهز للاستخدام مع جميع الطرق المطلوبة
  • تكامل POS: مُعَد مسبقًا للتوافق مع WooCommerce POS
  • إعداد تلقائي: تخصيص قالب قائم على السكريبت
  • أفضل الممارسات: يتبع معايير ترميز WordPress وWooCommerce
  • قابل للتوسيع: سهل التعديل والتوسيع لمقدمي الدفع المحددين

البداية​

الخيار 1: توليد القالب تلقائيًا​

يتضمن القالب سكريبت يقوم تلقائيًا بتخصيص القالب من أجل بوابتك المحددة:

  1. استنساخ المستودع:

    git clone https://github.com/wcpos/woocommerce-gateway-template.git
    cd woocommerce-gateway-template

  2. تشغيل سكريبت الإعداد:

    ./create-gateway.sh

  3. اتباع التعليمات:

    • أدخل اسم بوابتك (على سبيل المثال، "بوابة الدفع الخاصة بي")
    • أدخل شريحة بوابة (على سبيل المثال، "my-payment")
    • قدم وصفًا
    • سيولد السكريبت مكونًا مخصصًا

الخيار 2: استخدام القالب يدويًا​

إذا كنت تفضل التخصيص اليدوي:

  1. تنزيل القالب:

  2. تخصيص القالب:

    • استبدل {{GATEWAY_NAME}} باسم عرض بوابتك
    • استبدل {{GATEWAY_SLUG}} بمعرف بوابتك الفريد
    • استبدل {{GATEWAY_DESCRIPTION}} بوصف بوابتك

  3. إعادة تسمية الملفات:

    • أعد تسمية wcpos-{{GATEWAY_SLUG}}.php لتتناسب مع شريحة بوابتك
    • تحديث رؤوس الملفات ومعلومات المكون

هيكل القالب​

الملف الرئيسي للمكون​

يحتوي الملف الرئيسي للمكون (wcpos-{{GATEWAY_SLUG}}.php) على:

  • رأس المكون: معلومات مكون WordPress
  • فئة البوابة: الفئة الرئيسية لبوابة الدفع
  • التهيئة: إعداد المكون والخطافات
  • التكامل: توافق WooCommerce POS

المكونات الرئيسية​

هيكل فئة البوابة:

class WCPOS_Gateway_{{GATEWAY_CLASS}} extends WC_Payment_Gateway {
    // Gateway configuration
    public function __construct() { }
    
    // Admin settings form
    public function init_form_fields() { }
    
    // Process payment (main logic goes here)
    public function process_payment( $order_id ) { }
    
    // POS-specific methods
    public function payment_fields() { }
}

دليل التخصيص​

التهيئة الأساسية​

  1. معلومات البوابة:

    $this->id = 'your_gateway_id';
    $this->title = 'Your Gateway Name';
    $this->description = 'Gateway description for customers';
    $this->method_title = 'Admin title';
    $this->method_description = 'Admin description';

  2. الميزات المدعومة:

    $this->supports = array(
        'products',
        'refunds',
        'subscriptions', // if applicable
    );

معالجة الدفع​

يذهب منطق الدفع الأساسي في الطريقة process_payment():

public function process_payment( $order_id ) {
    $order = wc_get_order( $order_id );
    
    // Your payment processing logic here
    // Example: API calls, validation, etc.
    
    if ( $payment_successful ) {
        $order->payment_complete();
        return array(
            'result' => 'success',
            'redirect' => $this->get_return_url( $order )
        );
    } else {
        wc_add_notice( 'Payment failed', 'error' );
        return array(
            'result' => 'failure'
        );
    }
}

إعدادات الإدارة​

قم بتكوين إعدادات الإدارة في init_form_fields():

public function init_form_fields() {
    $this->form_fields = array(
        'enabled' => array(
            'title' => 'Enable/Disable',
            'type' => 'checkbox',
            'label' => 'Enable Your Gateway',
            'default' => 'yes'
        ),
        'api_key' => array(
            'title' => 'API Key',
            'type' => 'text',
            'description' => 'Enter your API key',
            'default' => '',
            'desc_tip' => true,
        ),
        // Add more settings as needed
    );
}

تكامل POS​

للوظائف المحددة لـ POS، نفذ:

public function payment_fields() {
    // Custom payment form for POS
    if ( is_admin() && isset( $_GET['page'] ) && $_GET['page'] === 'wc-pos' ) {
        // POS-specific payment fields
        echo '<div class="pos-payment-fields">';
        // Your custom POS interface
        echo '</div>';
    } else {
        // Standard web checkout fields
        parent::payment_fields();
    }
}

أفضل الممارسات في التطوير​

معايير الكود​

  • معايير ترميز WordPress: اتبع معايير ترميز PHP الخاصة بـ WordPress
  • إرشادات WooCommerce: الالتزام بممارسات تطوير WooCommerce
  • الأمان: تعقيم المدخلات، التحقق من البيانات، استخدام النونات
  • التدويل: جعل السلاسل قابلة للترجمة باستخدام __() و_e()

معالجة الأخطاء​

// Proper error handling
try {
    $result = $this->process_api_call( $data );
    if ( is_wp_error( $result ) ) {
        throw new Exception( $result->get_error_message() );
    }
} catch ( Exception $e ) {
    $order->add_order_note( 'Payment failed: ' . $e->getMessage() );
    wc_add_notice( 'Payment processing error', 'error' );
    return array( 'result' => 'failure' );
}

التسجيل​

// Add logging for debugging
if ( $this->debug ) {
    $this->log( 'Payment processing started for order ' . $order_id );
}

private function log( $message ) {
    if ( empty( $this->logger ) ) {
        $this->logger = wc_get_logger();
    }
    $this->logger->info( $message, array( 'source' => $this->id ) );
}

اختبار بوابتك​

بيئة التطوير​

  1. وضع الاختبار: دائماً قم بتنفيذ وضع اختبار/صندوق الرمل
  2. تسجيل الأخطاء: تضمين تسجيل شامل لاستكشاف الأخطاء وإصلاحها
  3. سيناريوهات الأخطاء: اختبار حالات الفشل المختلفة
  4. اختبار POS: اختبر بشكل محدد في بيئة POS

حالات الاختبار​

  • المدفوعات الناجحة: التحقق من أن الطلبات تكتمل بشكل صحيح
  • المدفوعات الفاشلة: ضمان معالجة الأخطاء بشكل صحيح
  • الاستردادات: اختبار وظيفة الاسترداد إذا كانت مدعومة
  • حالات الحافة: اختبار مع كميات الطلب المختلفة والتكوينات

النشر​

تعبئة المكون​

  1. إزالة ملفات التطوير: تنظيف الملفات التجريبية وأدوات التطوير
  2. التحكم في النسخ: تحديث أرقام النسخ في رأس المكون
  3. التوثيق: تضمين README مع تعليمات التثبيت
  4. حزمة ZIP: إنشاء ملف ZIP قابل للتثبيت

التوزيع​

  • إصدارات GitHub: استخدام إصدارات GitHub لإدارة النسخ
  • دليل إضافات WordPress: النظر في تقديمه لـ WordPress.org
  • التوزيع الخاص: استضافته على خوادمك الخاصة إذا لزم الأمر

ميزات متقدمة​

Webhooks​

للحصول على تحديثات الدفع في الوقت الفعلي:

public function handle_webhook() {
    $payload = file_get_contents( 'php://input' );
    $data = json_decode( $payload, true );
    
    // Verify webhook signature
    if ( $this->verify_webhook_signature( $payload ) ) {
        $this->process_webhook_data( $data );
    }
}

دعم الاشتراكات​

لدفعات متكررة:

// Add subscription support
$this->supports[] = 'subscriptions';
$this->supports[] = 'subscription_cancellation';
$this->supports[] = 'subscription_suspension';

العملات متعددة​

للمدفوعات الدولية:

public function get_supported_currencies() {
    return array( 'USD', 'EUR', 'GBP', 'CAD' );
}

الموارد​

التوثيق​

مستودع القالب​

  • GitHub: woocommerce-gateway-template
  • المشاكل: الإبلاغ عن مشاكل القالب أو طلب ميزات
  • المساهمات: تقديم تحسينات عبر طلبات السحب

الحصول على المساعدة​

للحصول على دعم التطوير:

  • قم بزيارة مستودع GitHub لمشاكل القالب المحددة
  • تحقق من توثيق مطور WooCommerce لأسئلة API
  • انضم إلى مجتمع مطوري WooCommerce للحصول على إرشادات عامة

بوابات أمثلة​

ادرس هذه البوابات المخصصة الموجودة للحصول على أمثلة للتنفيذ: