> ## Documentation Index
> Fetch the complete documentation index at: https://docs.oneclickdz.com/llms.txt
> Use this file to discover all available pages before exploring further.

# تكامل SDK PHP

> دليل الإعداد السريع لـ SDK Navio PHP

<div dir="rtl">
  ## نظرة عامة

  يوفر SDK Navio PHP واجهة حديثة وآمنة من حيث الأنواع لدمج مدفوعات Navio في تطبيقات PHP الخاصة بك. مبني باستخدام ميزات PHP 8.1+ وأفضل الممارسات.

  <CardGroup cols={2}>
    <Card title="آمن من حيث الأنواع" icon="shield-check" color="#0D9373">
      تلميحات أنواع PHP 8.1+ الكاملة وأنواع الإرجاع
    </Card>

    <Card title="متوافق مع Composer" icon="box" color="#0D9373">
      التحميل التلقائي PSR-4 والتثبيت السهل
    </Card>

    <Card title="API بسيط" icon="code" color="#0D9373">
      واجهة نظيفة وبديهية
    </Card>

    <Card title="معالجة الأخطاء" icon="circle-exclamation" color="#0D9373">
      استثناءات مخصصة لأنواع الأخطاء المختلفة
    </Card>
  </CardGroup>

  ## المتطلبات

  * PHP 8.1 أو أحدث
  * Composer
  * امتداد `ext-json`
  * امتداد `ext-curl`

  ## التثبيت

  قم بالتثبيت عبر Composer:

  ```bash theme={null}
  composer require oneclickdz/ocpay-php-sdk
  ```

  أو أضف إلى `composer.json` الخاص بك:

  ```json theme={null}
  {
      "require": {
          "oneclickdz/ocpay-php-sdk": "^1.0"
      }
  }
  ```

  ## البدء السريع

  ### 1. تهيئة SDK

  ```php theme={null}
  <?php

  require 'vendor/autoload.php';

  use OneClickDz\OCPay\OCPay;

  // Initialize with your API access token
  $ocpay = new OCPay('your-api-access-token');
  ```

  <Warning>
    خزّن مفتاح API الخاص بك في متغيرات البيئة، وليس في الكود مباشرة
  </Warning>

  ```bash theme={null}
  # .env file
  ONECLICK_API_KEY=your_api_key_here
  ```

  ```php theme={null}
  // Load from environment
  $ocpay = new OCPay(getenv('ONECLICK_API_KEY'));
  ```

  ### 2. إنشاء رابط دفع

  ```php theme={null}
  use OneClickDz\OCPay\DTO\CreateLinkRequest;
  use OneClickDz\OCPay\DTO\ProductInfo;

  // Create product information
  $productInfo = new ProductInfo(
      title: 'Premium Subscription',
      amount: 5000, // Amount in DZD (500 - 500,000)
      description: 'Monthly access to premium features'
  );

  // Create payment link request
  $request = new CreateLinkRequest(
      productInfo: $productInfo,
      feeMode: CreateLinkRequest::FEE_MODE_NO_FEE,
      successMessage: 'Thank you for your purchase!',
      redirectUrl: 'https://yourstore.com/success?order=12345'
  );

  // Create the payment link
  try {
      $response = $ocpay->createLink($request);
      
      // Redirect customer to payment page
      echo "Payment URL: " . $response->paymentUrl . "\n";
      
      // IMPORTANT: Save this reference!
      echo "Payment Reference: " . $response->paymentRef . "\n";
      saveOrderPaymentRef($orderId, $response->paymentRef);
      
  } catch (\OneClickDz\OCPay\Exception\ValidationException $e) {
      echo "Validation error: " . $e->getMessage() . "\n";
  } catch (\OneClickDz\OCPay\Exception\UnauthorizedException $e) {
      echo "Auth error: " . $e->getMessage() . "\n";
  } catch (\OneClickDz\OCPay\Exception\ApiException $e) {
      echo "API error: " . $e->getMessage() . "\n";
  }
  ```

  ### 3. التحقق من حالة الدفع

  ```php theme={null}
  // Check payment status using the payment reference
  try {
      $status = $ocpay->checkPayment('OCPL-A1B2C3-D4E5');
      
      if ($status->isConfirmed()) {
          // Payment successful - fulfill the order
          echo "Payment confirmed!\n";
          echo "Amount: " . $status->transactionDetails->amount . " DZD\n";
          fulfillOrder($orderId);
          
      } elseif ($status->isFailed()) {
          // Payment failed or expired
          echo "Payment failed: " . $status->message . "\n";
          markOrderFailed($orderId);
          
      } else {
          // Still pending - check again later
          echo "Payment pending...\n";
      }
      
  } catch (\OneClickDz\OCPay\Exception\NotFoundException $e) {
      echo "Payment not found\n";
  } catch (\OneClickDz\OCPay\Exception\PaymentExpiredException $e) {
      echo "Payment link expired\n";
  } catch (\OneClickDz\OCPay\Exception\ApiException $e) {
      echo "API error: " . $e->getMessage() . "\n";
  }
  ```

  ## مثال تجارة إلكترونية كامل

  إليك تدفقاً كاملاً لعملية دفع في التجارة الإلكترونية:

  ```php theme={null}
  <?php

  require 'vendor/autoload.php';

  use OneClickDz\OCPay\OCPay;
  use OneClickDz\OCPay\DTO\CreateLinkRequest;
  use OneClickDz\OCPay\DTO\ProductInfo;

  // Initialize SDK
  $ocpay = new OCPay(getenv('ONECLICK_API_KEY'));

  // Step 1: Create order in your system
  $orderId = createOrder([
      'customer_id' => 123,
      'items' => [
          ['name' => 'Product A', 'price' => 5000],
          ['name' => 'Product B', 'price' => 3000],
      ],
      'total' => 8000,
  ]);

  // Step 2: Create payment link
  try {
      $productInfo = new ProductInfo(
          title: "Order #{$orderId}",
          amount: 8000,
          description: "Payment for order #{$orderId}"
      );
      
      $request = new CreateLinkRequest(
          productInfo: $productInfo,
          feeMode: CreateLinkRequest::FEE_MODE_NO_FEE,
          successMessage: "Thank you! Order #{$orderId} confirmed.",
          redirectUrl: "https://yourstore.com/orders/{$orderId}/success"
      );
      
      $response = $ocpay->createLink($request);
      
      // Step 3: Save payment reference
      updateOrder($orderId, [
          'payment_ref' => $response->paymentRef,
          'payment_url' => $response->paymentUrl,
          'status' => 'pending_payment',
      ]);
      
      // Step 4: Redirect customer
      header("Location: " . $response->paymentUrl);
      exit;
      
  } catch (ApiException $e) {
      error_log("Payment creation failed: " . $e->getMessage());
      showErrorPage("Failed to create payment. Please try again.");
  }
  ```

  ### مهمة خلفية للتحقق من الحالة

  قم بإعداد مهمة cron أو عامل خلفي:

  ```php theme={null}
  <?php

  // check_payments.php - Run every 20 minutes

  require 'vendor/autoload.php';

  use OneClickDz\OCPay\OCPay;

  $ocpay = new OCPay(getenv('ONECLICK_API_KEY'));

  // Get all pending orders
  $pendingOrders = getPendingOrders();

  foreach ($pendingOrders as $order) {
      if (!$order['payment_ref']) {
          continue;
      }
      
      try {
          $status = $ocpay->checkPayment($order['payment_ref']);
          
          if ($status->isConfirmed()) {
              // Mark as paid and fulfill
              updateOrder($order['id'], [
                  'status' => 'paid',
                  'paid_at' => date('Y-m-d H:i:s'),
              ]);
              fulfillOrder($order['id']);
              
          } elseif ($status->isFailed()) {
              // Mark as failed
              updateOrder($order['id'], [
                  'status' => 'payment_failed',
              ]);
          }
          
      } catch (ApiException $e) {
          error_log("Status check failed: " . $e->getMessage());
      }
  }
  ```

  أضف إلى crontab:

  ```bash theme={null}
  */20 * * * * php /path/to/check_payments.php
  ```

  ## مرجع API

  ### فئة Navio

  نقطة الدخول الرئيسية لـ SDK.

  #### المنشئ

  ```php theme={null}
  public function __construct(
      string $accessToken,
      array $options = []
  )
  ```

  **المعاملات:**

  * `$accessToken`: رمز الوصول إلى API الخاص بك
  * `$options`: إعداد اختياري لعميل Guzzle
    * `timeout`: مهلة الطلب بالثواني (الافتراضي: 30)

  #### الطرق

  **createLink(CreateLinkRequest \$request): CreateLinkResponse**

  ينشئ رابط دفع.

  **checkPayment(string \$paymentRef): CheckPaymentResponse**

  يتحقق من حالة الدفع.

  ### كائنات نقل البيانات (DTOs)

  #### ProductInfo

  ```php theme={null}
  new ProductInfo(
      title: string,        // Product name (1-200 chars)
      amount: int,          // Amount in DZD (500 - 500,000)
      description?: string  // Optional (max 1000 chars)
  )
  ```

  #### CreateLinkRequest

  ```php theme={null}
  new CreateLinkRequest(
      productInfo: ProductInfo,
      feeMode?: string,        // NO_FEE (default), SPLIT_FEE, CUSTOMER_FEE
      successMessage?: string, // Optional success message
      redirectUrl?: string     // Optional redirect URL
  )
  ```

  **ثوابت وضع الرسوم:**

  * `CreateLinkRequest::FEE_MODE_NO_FEE` - التاجر يدفع (الافتراضي)
  * `CreateLinkRequest::FEE_MODE_SPLIT_FEE` - تقسيم 50/50
  * `CreateLinkRequest::FEE_MODE_CUSTOMER_FEE` - العميل يدفع

  #### CreateLinkResponse

  ```php theme={null}
  $response->paymentUrl     // URL to redirect customer
  $response->paymentRef     // Payment reference (SAVE THIS!)
  $response->paymentLink    // Full payment link object
  ```

  #### CheckPaymentResponse

  ```php theme={null}
  $response->status                // PaymentStatus enum
  $response->message               // Status message
  $response->paymentRef           // Payment reference
  $response->transactionDetails   // Transaction details (if confirmed)

  // Helper methods
  $response->isConfirmed()        // true if payment confirmed
  $response->isPending()          // true if still pending
  $response->isFailed()           // true if failed
  ```

  ### معالجة الاستثناءات

  جميع الاستثناءات ترث من `NavioException`:

  | الاستثناء                 | كود HTTP | عند الإطلاق                       |
  | ------------------------- | -------- | --------------------------------- |
  | `ValidationException`     | 400      | بيانات طلب غير صالحة              |
  | `UnauthorizedException`   | 403      | مفتاح API غير صالح                |
  | `NotFoundException`       | 404      | الدفع غير موجود                   |
  | `PaymentExpiredException` | 410      | الرابط منتهي الصلاحية (>20 دقيقة) |
  | `ApiException`            | متنوعة   | أخطاء API أخرى                    |

  جميع الاستثناءات توفر:

  ```php theme={null}
  try {
      $response = $ocpay->createLink($request);
  } catch (ApiException $e) {
      echo $e->getMessage();       // Error message
      echo $e->getStatusCode();    // HTTP status code
      echo $e->getRequestId();     // Request ID for support
      var_dump($e->getErrorData()); // Full error data
  }
  ```

  ## ملاحظات مهمة

  ### التحقق من التاجر مطلوب

  <Warning>
    أكمل التحقق من التاجر على [app.oneclickdz.com](https://app.oneclickdz.com/profile) قبل استخدام API
  </Warning>

  ### حدود المبلغ

  * **الحد الأدنى**: 500 دج
  * **الحد الأقصى**: 500,000 دج
  * يجب أن يكون عدداً صحيحاً

  ### هيكل الرسوم

  <Info>
    **رسوم منخفضة**: 0% على الرصيد، رسوم سحب 1% فقط
  </Info>

  ### انتهاء صلاحية رابط الدفع

  تنتهي صلاحية الروابط بعد **20 دقيقة** من الإنشاء إذا لم يُبدأ الدفع.

  ### تدفق حالة الدفع

  1. **PENDING** - الدفع قيد التنفيذ → أعد التحقق لاحقاً
  2. **CONFIRMED** - الدفع ناجح → نفّذ الطلب
  3. **FAILED** - الدفع مرفوض/منتهي الصلاحية → علّم الطلب كفاشل

  ## تكامل Laravel

  لمشاريع Laravel، راجع مثال التكامل الكامل في [مستودع GitHub](https://github.com/oneclickdz/ocpay-php-sdk/tree/main/examples/laravel).

  يشمل:

  * إعداد مزود الخدمة
  * فئة خدمة الدفع
  * أمثلة على المتحكمات
  * ترحيلات قاعدة البيانات
  * مهمة خلفية للتحقق
  * معالجة الأخطاء

  ## الاختبار

  ### استخدام Sandbox

  يستخدم API تلقائياً وضع sandbox لحسابات الاختبار:

  ```php theme={null}
  $response = $ocpay->createLink($request);

  if ($response->paymentLink->isSandbox) {
      echo "This is a test payment\n";
  }
  ```

  ### اختبارات الوحدة

  ```bash theme={null}
  composer install --dev
  vendor/bin/phpunit
  ```

  ## أفضل الممارسات

  <AccordionGroup>
    <Accordion title="احفظ دائماً مرجع الدفع" icon="database">
      خزّن `paymentRef` فوراً بعد إنشاء الرابط. ستحتاجه للتحقق من حالة الدفع.
    </Accordion>

    <Accordion title="تحقق من حالة الدفع" icon="clock">
      قم بإعداد مهمة خلفية للتحقق من حالة الدفع كل 20 دقيقة للطلبات المعلقة.
    </Accordion>

    <Accordion title="تعامل مع جميع الاستثناءات" icon="shield-halved">
      التقط جميع أنواع الاستثناءات وتعامل معها بشكل مناسب. سجّل الأخطاء لأغراض التصحيح.
    </Accordion>

    <Accordion title="أمّن مفتاح API الخاص بك" icon="key">
      خزّن مفاتيح API في متغيرات البيئة، ولا تلتزم بها أبداً في نظام التحكم بالإصدار.
    </Accordion>

    <Accordion title="استخدم HTTPS فقط" icon="lock">
      استخدم دائماً HTTPS لعناوين URL لإعادة التوجيه ونقاط النهاية في تطبيقك.
    </Accordion>
  </AccordionGroup>

  ## الدعم والموارد

  <CardGroup cols={2}>
    <Card title="مستودع GitHub" icon="github" href="https://github.com/oneclickdz/ocpay-php-sdk">
      الكود المصدري والأمثلة والمشاكل
    </Card>

    <Card title="توثيق API" icon="book" href="/ar/api-reference/ocpay/create-link">
      مرجع API مفصل
    </Card>

    <Card title="مثال Laravel" icon="code" href="https://github.com/oneclickdz/ocpay-php-sdk/tree/main/examples/laravel">
      تكامل Laravel كامل
    </Card>

    <Card title="اتصل بالدعم" icon="headset" href="/ar/contact">
      احصل على المساعدة من فريقنا
    </Card>
  </CardGroup>

  ## الخطوات التالية

  <Card title="أفضل ممارسات Navio" icon="star" href="/ar/ocpay-guides/4-best-practices">
    تعلم نصائح الإنتاج وأفضل ممارسات الأمان
  </Card>
</div>