curl_init طلبات POST: دليل قصير

تطبيق البرمجيات cURL، وهو اختصار لـ "Client for URLs"، يقدم مجموعة شاملة من الوظائف للمطورين لإدارة نقل البيانات. يعمل في وضعين متميزين: واجهة سطر أوامر سهلة الاستخدام للتفاعلات الأساسية ومكتبة قوية يمكن دمجها بسلاسة في مشاريع البرمجة.

التعريف الرسمي لـ curl_init()

استنادًا إلى الموقع الرسمي لـ PHP، فإن دالة curl_init تقوم بتهيئة جلسة cURL وتُعيد مقبض cURL للاستخدام مع الدوال curl_setopt() و curl_exec() و curl_close().

المعلمات المعنية

url

إذا قدمت عنوان URL، فسيتم تعيين خيار CURLOPT_URL إلى قيمته. يمكنك أيضًا تعيين هذا الخيار يدويًا باستخدام دالة curl_setopt().

ومع ذلك، يُرجى ملاحظة أن بروتوكول file معطل من قبل cURL نفسه إذا تم تعيين open_basedir.

قيم الإرجاع

تُعيد دالة curl_init() مقبض cURL عند النجاح، وfalse عند حدوث أخطاء.

ما هو طلب POST؟

في سياق التواصل عبر الويب، يُعتبر بروتوكول نقل النص الفائق (HTTP) أساسًا لتبادل البيانات. إحدى الطرق الأساسية المستخدمة ضمن HTTP هي طلب POST، والتي تم تصميمها خصيصًا لنقل البيانات إلى خادم ويب. تتناول هذه الوثيقة تفاصيل طلب POST، موضحة وظيفته ومقارنته مع نظيرته، طلب GET.

الميزات الأساسية لطلبات POST

نقل البيانات

تم تصميم طلبات POST خصيصًا لـ إرسال البيانات إلى خادم الويب. يمكن استخدام هذه البيانات لإنشاء موارد جديدة، أو تحديث معلومات موجودة، أو حذف بيانات.

وضع البيانات

ترسل طلبات POST البيانات في جسم الطلب بدلاً من تضمينها ضمن عنوان URL نفسه. تعزز هذه الفاصلة الأمان، لا سيما للمعلومات الحساسة مثل كلمات المرور أو تفاصيل بطاقات الائتمان، التي لا تُعرض في عنوان URL.

تغيير الحالة

تؤدي طلبات POST عادةً إلى تعديل على جانب الخادم. قد يشمل ذلك إنشاء حساب مستخدم جديد، أو رفع ملف، أو إضافة منتج جديد إلى عربة التسوق، أو حذف تعليق.

غير قابلة للتخزين المؤقت

نظرًا لأن طلبات POST تُعدل البيانات، فإن متصفحات الويب عادةً لا تخزنها مؤقتًا. يضمن ذلك أن أحدث المعلومات تُرسل دائمًا إلى الخادم، مما يمنع استخدام بيانات قديمة.

أمثلة على كود curl_init() لطلبات POST

إليك بعض أمثلة البرمجة بلغة PHP التي يمكنك الرجوع إليها إذا كنت ترغب في عمل طلبات POST باستخدام دالة curl_init().

المثال 1 - إرسال بيانات نصية بسيطة

يرسل هذا المثال اسم مستخدم وكلمة مرور أساسية إلى سكربت تسجيل الدخول.

<?php

$url = "https://www.example.com/login.php";
$username = "your_username";
$password = "your_password";

$data = array(
  "username" => $username,
  "password" => $password
);

$ch = curl_init($url);

curl_setopt($ch, CURLOPT_POST, 1);  // تعيين طريقة الطلب إلى POST
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($data));  // تعيين بيانات POST
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);  // إرجاع الاستجابة

$response = curl_exec($ch);

curl_close($ch);

if($response) {
  echo "تم تسجيل الدخول بنجاح!";
} else {
  echo "خطأ: " . curl_error($ch);
}

?>

تفسير الكود:

1. نحدد عنوان URL المستهدف، واسم المستخدم، وكلمة المرور.
2. ننشئ مصفوفة $data تحتوي على اسم المستخدم وكلمة المرور.
3. نهيئ مقبض curl باستخدام curl_init($url).
4. نقوم بتعيين طريقة الطلب إلى POST باستخدام curl_setopt($ch, CURLOPT_POST, 1).
5. نقوم بتعيين بيانات POST باستخدام curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($data)). http_build_query تحول مصفوفة البيانات إلى سلسلة مشفرة في URL.
6. نقوم بتعيين CURLOPT_RETURNTRANSFER إلى 1 لالتقاط الاستجابة بدلاً من طباعتها مباشرة.
7. ننفيذ الطلب باستخدام curl_exec($ch) ونخزن الاستجابة في $response.
8. نغلق مقبض curl باستخدام curl_close($ch).
9. أخيرًا، نتحقق مما إذا كانت الاستجابة موجودة ونظهر رسالة نجاح أو خطأ.

المثال 2 - إرسال بيانات JSON

يرسل هذا المثال كائن JSON يحتوي على معلومات المستخدم إلى سكربت التسجيل.

<?php

$url = "https://www.example.com/register.php";

$user_data = array(
  "name" => "جون دو",
  "email" => "john.doe@example.com",
  "password" => "your_password"
);

$data_json = json_encode($user_data);

$ch = curl_init($url);

curl_setopt($ch, CURLOPT_POST, 1);  // تعيين طريقة الطلب إلى POST
curl_setopt($ch, CURLOPT_POSTFIELDS, $data_json);  // تعيين بيانات POST كـ JSON
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);  // إرجاع الاستجابة

curl_setopt($ch, CURLOPT_HTTPHEADER, array(
  'Content-Type: application/json',   // تعيين نوع المحتوى إلى JSON
));

$response = curl_exec($ch);

curl_close($ch);

if($response) {
  echo "تم التسجيل بنجاح!";
} else {
  echo "خطأ: " . curl_error($ch);
}

?>

تفسير الكود:

1. نحدد عنوان URL المستهدف ومصفوفة بيانات المستخدم.
2. نحول بيانات المستخدم إلى سلسلة JSON باستخدام json_encode.
3. نهيئ مقبض curl ونقوم بتعيين طريقة الطلب إلى POST.
4. نقوم بتعيين بيانات POST باستخدام curl_setopt($ch, CURLOPT_POSTFIELDS, $data_json).
5. نقوم بتعيين CURLOPT_RETURNTRANSFER إلى 1 لالتقاط الاستجابة.
6. نقوم بتعيين رأس مخصص Content-Type: application/json لإبلاغ الخادم أن البيانات بصيغة JSON.
7. ننفيذ الطلب ونغلق مقبض curl كما في المثال السابق.
8. أخيرًا، نتحقق من وجود استجابة ونظهر رسالة نجاح أو خطأ.

المثال 3 - تعيين رؤوس مخصصة ومتابعة التحويلات

يرسل هذا المثال طلب POST مع رؤوس مخصصة ويتبع التحويلات.

<?php

$url = "https://www.example.com/login.php";

$data = array(
  "username" => "your_username",
  "password" => "your_password"
);

$ch = curl_init($url);

curl_setopt($ch, CURLOPT_POST, 1);  // تعيين طريقة الطلب إلى POST
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($data));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);  // إرجاع الاستجابة

curl_setopt($ch, CURLOPT_HTTPHEADER, array(
  'Authorization: Bearer YOUR_API_KEY',  // تعيين رأس مخصص
));

// متابعة التحويلات حتى 3 مرات
curl_setopt($ch, CURLOPT_FOLLOWLOCATION, 1);
curl_setopt($ch, CURLOPT_MAXREDIRS, 3);

$response = curl_exec($ch);

curl_close($ch);

if($response) {
  echo "تم تسجيل الدخول بنجاح!";
} else {
  echo "خطأ: " . curl_error($ch);
}

?>

تفسير الكود:

1. نحدد عنوان تسجيل الدخول وبيانات المستخدم.
2. نعد مقبض curl وطلب POST كما في السابق.
3. ننشيء رأسًا مخصصًا مع رمز ترخيص باستخدام CURLOPT_HTTPHEADER.
4. نمكن متابعة التحويلات باستخدام CURLOPT_FOLLOWLOCATION ونقيدها إلى 3 باستخدام CURLOPT_MAXREDIRS.

ملاحظة لتذكرها

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

للاطلاع على الوثائق الرسمية، يمكنك التحقق منها على: https://www.php.net/manual/en/book.curl.php

Apidog - استيراد أوامر cURL بسهولة

Apidog هي منصة متطورة لتطوير API توفر للمستخدمين جميع الأدوات اللازمة لدورة حياة API بالكامل. مع Apidog، يمكنك بناء، وتصحيح، ومحاكاة، وتوثيق APIs كلها ضمن تطبيق واحد.

دعنا نتعرف على كيفية استيراد أوامر cURL إلى Apidog!

استيراد أوامر cURL إلى Apidog بسهولة

يدعم Apidog المستخدمين الذين يرغبون في استيراد أوامر cURL إلى Apidog. في مشروع فارغ، انقر على زر + الأرجواني حول الجزء العلوي الأيسر من نافذة Apidog، واختر استيراد cURL.

انسخ والصق أمر cURL في المربع المعروض على الشاشة الخاصة بك.

إذا كان ناجحًا، ينبغي أن تكون الآن قادرًا على رؤية أمر cURL في شكل طلب API.

توليد كود PHP مع Apidog

إذا لم يكن لديك تجربة سابقة في البرمجة بلغة PHP، فلا تقلق! يحتوي Apidog على ميزة توليد الكود التي توفر للمطورين أدوات لعدة لغات!

أولاً، حدد زر </> توليد كود على أي API أو طلب، واختر توليد كود عميل من القائمة المنسدلة.

بعد ذلك، اختر PHP، وابحث عن قسم cURL. يجب أن ترى الآن الكود المُولد لـ cURL. كل ما عليك القيام به هو نسخه ولصقه في IDE (بيئة تطوير متكاملة) الخاصة بك والاستمرار في تطوير تطبيقك.

الخاتمة

تفتح إتقان طلبات POST باستخدام curl_init() أداة قوية للمطورين. تمكّنك من إرسال البيانات إلى خوادم الويب، مما يتيح إجراءات مثل إنشاء حسابات المستخدمين، ورفع الملفات، وإرسال النماذج. من خلال فهم المفاهيم الأساسية لطلبات POST ووظائف curl_init()، يمكنك صياغة حلول مخصصة لمختلف التفاعلات على الويب.

تذكر، curl_init() يقدم نهجًا مرنًا، مما يسمح لك بإرسال البيانات بأشكال مختلفة، وتعيين رؤوس مخصصة، ومعالجة سيناريوهات مثل رفع الملفات والتحويلات. مع هذه المعرفة الجديدة، يمكنك استغلال طلبات POST لتعزيز قدرات تطبيقات الويب الخاصة بك بثقة.