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

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

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

الميزات​

قالب كامل

هيكل بوابة جاهز للاستخدام مع جميع الطرق المطلوبة

تكامل POS

مُعد مسبقًا للتوافق مع WooCommerce POS

إعداد تلقائي

تخصيص القالب بناءً على السكربت

قابل للتوسيع

سهل التعديل والتوسيع لمزودي الدفع المحددين

بدء الاستخدام​

الخيار 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 للحصول على إرشادات عامة

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

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