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

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

يقدم لك قالب بوابة الدفع نقطة انطلاق لبناء بوابة دفع خاصة فقط بنظام نقاط البيع. ينتج مكون WordPress عملي مع ملف PHP واحد يمكنك تثبيته وتخصيصه ليناسب احتياجاتك.

الميزات​

رمز بسيط

ملف PHP واحد يحتوي فقط على الأساسيات - سهل القراءة والتعديل

خاص بنقاط البيع

معطل على الخروج عبر الويب بشكل افتراضي، مفعل من خلال إعدادات WCPOS

إعداد تلقائي

برنامج نصي يتولى جميع استبدالات العناصر النائبة لك

إصدارات GitHub

ادفع زيادة في الإصدار ويقوم GitHub Actions ببناء ملف ZIP قابل للتنزيل

البدء​

1

استنساخ مستودع القالب

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

أو انقر على زر استخدم هذا القالب في مستودع GitHub لإنشاء نسخة خاصة بك.

2

تشغيل برنامج الإعداد

./create-gateway.sh

يسأل البرنامج النصي عن بعض التفاصيل - اسم بوابتك، وصف مختصر، واسم مستخدم GitHub الخاص بك - ثم يقوم بإنشاء مكون جاهز للاستخدام في دليل من اختيارك.

3

تثبيت المكون

لديك خياران:

الخيار أ - نسخ المجلد مباشرة (إذا كان لديك وصول للخادم): انسخ مجلد البوابة الذي تم إنشاؤه إلى دليل موقعك wp-content/plugins/.

الخيار ب - ضغط وتحميل (أسهل لمعظم الأشخاص):

  1. قم بضغط المجلد الذي تم إنشاؤه إلى ملف .zip
  2. في WordPress، انتقل إلى المكونات > إضافة جديدة > تحميل البرنامج
  3. اختر ملف zip واضغط تثبيت الآن
4

تفعيل في WCPOS

  1. انتقل إلى WP Admin > WCPOS > الإعدادات > الخروج
  2. ابحث عن بوابتك الجديدة في القائمة وقم بتفعيلها
ملاحظة

البوابة معطلة على الخروج العادي عبر الويب بشكل افتراضي. تتحكم WCPOS في البوابات التي تظهر في نقاط البيع من خلال إعداداتها الخاصة.

الإعداد اليدوي​

إذا كنت تفضل عدم استخدام البرنامج النصي، يمكنك استبدال العناصر النائبة بنفسك. افتح كل ملف في محرر نصوص وابحث واستبدل ما يلي:

العنصر النائبما يجب إدخالهمثال
{{GATEWAY_NAME}}اسم عرض بوابتكدفع نقدي
{{GATEWAY_SLUG}}مُعرف صالح لعنوان URL (حروف صغيرة، شرطات)cash-payment
{{GATEWAY_DESCRIPTION}}وصف قصير للبوابةقبول المدفوعات النقدية في WCPOS
{{GATEWAY_DEFAULT_DESCRIPTION}}نص يظهر للصراف عند الخروجالدفع نقدًا عند نقطة البيع
{{GITHUB_USERNAME}}اسم مستخدم GitHub الخاص بكkilbot
{{REPO_NAME}}اسم المستودع الخاص بكcash-payment-gateway
{{AUTHOR_NAME}}اسمكkilbot
{{GATEWAY_ID}}شريحة مع شرطات سفلية بدلاً من الشرطاتcash_payment
{{GATEWAY_CLASS_NAME}}كل كلمة بحرف كبير، مفصولة بشرطات سفليةCash_Payment
{{GATEWAY_FUNCTION_PREFIX}}نفس معرف البوابةcash_payment

ثم قم بإعادة تسمية wcpos-{{GATEWAY_SLUG}}.php لتتناسب مع شريحتك (على سبيل المثال، wcpos-cash-payment.php).

نصيحة

يشتق برنامج الإعداد GATEWAY_ID و GATEWAY_CLASS_NAME و GATEWAY_FUNCTION_PREFIX تلقائيًا من الاسم والشريحة، لذا تحتاج فقط إلى التفكير في هذه الأمور عند القيام بالإعداد اليدوي.

كيف يعمل​

يقوم المكون الذي تم إنشاؤه بتسجيل فئة بوابة دفع WooCommerce. إليك الأشياء الرئيسية التي تحتاج لمعرفتها:

  • $this->enabled = 'no' - يتم إخفاء البوابة من الخروج عبر الويب. تقوم WCPOS بتفعيلها في نظام نقاط البيع بناءً على إعدادات نقاط البيع الخاصة بك.
  • process_payment() - يستدعي $order->payment_complete()، والذي يحدد الطلب كمدفوع ويتعامل مع تقليل المخزون تلقائيًا.
  • init_form_fields() - يحدد حقول العنوان والوصف التي تظهر في إعدادات WooCommerce.

تخصيص بوابتك​

إضافة حقول الدفع​

إذا كانت بوابتك تحتاج إلى إدخال من أمين الصندوق (على سبيل المثال، رقم مرجعي)، قم بتجاوز طريقة payment_fields():

public function payment_fields() {
    if ( $this->description ) {
        echo wpautop( wptexturize( $this->description ) );
    }

    woocommerce_form_field( 'my_gateway_reference', array(
        'type'        => 'text',
        'label'       => __( 'Reference Number', 'your-text-domain' ),
        'required'    => true,
    ) );
}

يمكنك بعد ذلك قراءة القيمة المقدمة في process_payment() عبر $_POST['my_gateway_reference']. تذكر أن تقوم بتطهير أي إدخال باستخدام sanitize_text_field().

تغيير سلوك الدفع​

يحدد القالب الافتراضي الطلبات كمدفوعة على الفور. إذا كانت سيرتك الذاتية تتطلب الدفع لاحقًا (مثل فاتورة)، استبدل payment_complete() بتحديث الحالة:

public function process_payment( $order_id ) {
    $order = wc_get_order( $order_id );

    // Set to pending — the customer will pay later.
    $order->update_status( 'pending', __( 'Awaiting payment', 'your-text-domain' ) );

    // Stock must be reduced manually when not using payment_complete().
    wc_reduce_stock_levels( $order_id );

    return array(
        'result'   => 'success',
        'redirect' => $this->get_return_url( $order ),
    );
}

إجراء التغييرات والتحديثات​

بعد تثبيت بوابتك، يمكنك الاستمرار في تعديل ملف المكون لضبط منطق الدفع. لتثبيت إصدار محدث:

  1. حرر wcpos-your-slug.php في المجلد الذي تم إنشاؤه
  2. قم بتحديث رقم Version: في رأس المكون (على سبيل المثال، من 0.1.0 إلى 0.2.0)
  3. قم بضغط المجلد وتحميله مرة أخرى من خلال المكونات > إضافة جديدة > تحميل البرنامج، أو استبدل المجلد مباشرة في wp-content/plugins/
نصيحة

سيسأل WordPress إذا كنت تريد استبدال المكون الحالي عند تحميل ملف zip بنفس اسم المكون - انقر على استبدال الحالي بالملف المرفوع للتحديث.

إصدارات تلقائية مع GitHub​

إذا قمت بدفع بوابتك إلى مستودع GitHub، يتضمن القالب تدفق عمل GitHub Actions الذي ينشئ إصدارات تلقائيًا:

  1. قم بتحديث رقم Version: في رأس المكون
  2. قم بالتزام الدفع والدفع إلى فرع main
  3. يكتشف GitHub Actions تغيير الإصدار وينشئ إصدارًا جديدًا مع ملف ZIP قابل للتنزيل

يمكن للمستخدمين الآخرين بعد ذلك تحميل ملف ZIP من صفحة الإصدارات في مستودعك وتثبيته كما في أي مكون WordPress.

استكشاف الأخطاء وإصلاحها​

البوابة لا تظهر في نظام نقاط البيع
  • تحقق من أن المكون مفعل في WP Admin > المكونات
  • انتقل إلى WP Admin > WCPOS > الإعدادات > الخروج وتأكد من تفعيل البوابة
  • تحقق من أن WooCommerce مثبت ومفعل
البوابة تظهر على الخروج عبر الويب
  • تأكد من تعيين $this->enabled = 'no'; في مُنشئ البوابة
  • تقوم WCPOS بتجاوز هذا الإعداد لطلبات نقاط البيع، لذلك يجب أن تظهر البوابة فقط في نقاط البيع
تبقى الطلبات في حالة 'المعالجة' بدلاً من 'الإنهاء'
  • تقوم WooCommerce بتعيين حالة الطلب بناءً على أنواع المنتجات. تبقى الطلبات التي تحتوي على منتجات مادية في "المعالجة" - هذا سلوك عادي في WooCommerce. فقط الطلبات التي تحتوي على منتجات افتراضية أو قابلة للتنزيل يتم وضع علامة "مكتمل" تلقائيًا.

الموارد​

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

تلك البوابات الموجودة تم بناؤها بنفس النهج وهي مراجع جيدة: