آموزش جامع کار با API در PHP (ارسال و دریافت داده‌ها به صورت استاندارد)

مقدمه؛ API چیست و چرا در PHP به آن نیاز داریم؟

امروزه تقریباً تمام وب‌سایت‌ها و اپلیکیشن‌های مدرن برای تعامل با خدمات دیگر از API (رابط برنامه‌نویسی اپلیکیشن) استفاده می‌کنند. به عنوان مثال، برای اتصال به درگاه پرداخت، ارسال پیامک، دریافت آب و هوا یا احراز هویت کاربران از طریق شبکه‌های اجتماعی، شما باید بتوانید از داخل کدهای PHP خود به یک سرور خارجی درخواست (Request) ارسال کرده و پاسخ (Response) مناسب را دریافت کنید.

در این مقاله آموزشی، استانداردترین روش‌های برقراری ارتباط با وب‌سرویس‌ها در PHP را با تمرکز بر ابزار قدرتمند cURL بررسی می‌کنیم.

روش‌های کار با API در PHP

در PHP به طور کلی دو روش اصلی برای ارسال درخواست‌های HTTP وجود دارد:

• تابع file_get_contents: ساده‌ترین روش برای درخواست‌های GET معمولی، اما فاقد انعطاف‌پذیری لازم برای پروژه‌های بزرگ.
• کتابخانه cURL (Client URL Library): استانداردترین، سریع‌ترین و منعطف‌ترین ابزار برای انواع درخواست‌های GET، POST، PUT و DELETE همراه با مدیریت هدرها و امنیت بالا.

روش اول: استفاده از file_get_contents (ساده و سریع)

اگر فقط می‌خواهید یک درخواست GET ساده به یک API عمومی ارسال کنید و نیازی به هدرهای پیشرفته ندارید، این روش بسیار سریع است:

$apiUrl = "https://jsonplaceholder.typicode.com/posts/1";
$response = file_get_contents($apiUrl);

if ($response === FALSE) {
    die("خطا در دریافت داده‌ها");
}

// تبدیل رشته JSON به آرایه تعاملی PHP
$data = json_decode($response, true);
echo "عنوان پست: " . $data['title'];

روش دوم: استفاده از cURL (استاندارد و حرفه‌ای)

کتابخانه cURL به طور پیش‌فرض در بیشتر سرورهای PHP فعال است. فرآیند کار با cURL شامل ۴ مرحله اصلی است: ایجاد نشست، تنظیم پیکربندی، اجرای درخواست و بستن نشست.

۱. ارسال درخواست GET با cURL

در درخواست GET، ما داده‌ها را از وب‌سرویس دریافت می‌کنیم. کد زیر نمونه‌ای استاندارد از این متد است:

$url = "https://api.github.com/users/octocat";

// ۱. مقداردهی اولیه cURL
$ch = curl_init();

// ۲. تنظیم تنظیمات مربوطه
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); // دریافت پاسخ به صورت رشته
curl_setopt($ch, CURLOPT_USERAGENT, 'MyPHPApp'); // هدر User-Agent برای امنیت برخی APIها

// ۳. اجرای درخواست و دریافت پاسخ
$response = curl_exec($ch);

// بررسی خطاهای احتمالی
if (curl_errno($ch)) {
    echo 'خطای cURL: ' . curl_error($ch);
} else {
    // تبدیل پاسخ JSON به آرایه
    $result = json_decode($response, true);
    echo "نام کاربر گیت‌هاب: " . $result['name'];
}

// ۴. بستن اتصال
curl_close($ch);

۲. ارسال درخواست POST با cURL

زمانی که می‌خواهید داده‌ای را به سرور مقصد ارسال کنید (مثلاً ثبت نام یک کاربر یا ارسال تراکنش مالی)، باید از متد POST استفاده کنید. در زیر هدرهای ارسال داده به صورت JSON نیز تنظیم شده است:

$url = "https://reqres.in/api/users";

// داده‌هایی که می‌خواهیم ارسال کنیم
$postData = [
    'name' => 'محمد رضایی',
    'job' => 'توسعه‌دهنده وب'
];

$ch = curl_init($url);

// تبدیل آرایه به JSON
$jsonData = json_encode($postData);

// تنظیمات ارسال POST و هدرها
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $jsonData);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json',
    'Content-Length: ' . strlen($jsonData),
    'Authorization: Bearer YOUR_API_TOKEN' // در صورت نیاز به احراز هویت
]);

$response = curl_exec($ch);

if (!curl_errno($ch)) {
    $statusCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    if ($statusCode === 201) {
        echo "کاربر با موفقیت ایجاد شد!\n";
        $responseData = json_decode($response, true);
        echo "شناسه کاربر: " . $responseData['id'];
    } else {
        echo "خطا در سرور با کد وضعیت: " . $statusCode;
    }
}

curl_close($ch);

نکات مهم و امنیتی در اتصال به APIها

برای توسعه کد امن و پایدار، موارد زیر را همیشه رعایت کنید:

• بررسی کدهای وضعیت HTTP (HTTP Status Codes): پاسخ‌های موفق معمولاً رنج 200 دارند. خطاهای کاربر رنج 400 و خطاهای سرور رنج 500 هستند.
• تایم‌اوت (Timeout): همیشه برای درخواست‌های خود زمان انتظار مشخص کنید تا اسکریپت شما در صورت قطع بودن سرور مقصد معلق نماند (مثلاً با تنظیم CURLOPT_TIMEOUT).
• امنیت اطلاعات حساس: هرگز توکن‌ها و کلیدهای امنیتی (API Keys) خود را هاردکد نکنید؛ بلکه آن‌ها را در فایل‌های پیکربندی یا .env ذخیره کنید.

پیشنمایش