تابع http_response_code() در PHP

تابع http_response_code() در PHP برای خواندن یا تعیین کد وضعیت (HTTP status code) پاسخ سرور استفاده می‌شود. این تابع از PHP 5.4 معرفی شده و ساده، اما کاربردی است؛ به‌ویژه در توسعه APIها، مدیریت خطاها و هدایت (redirect) کاربر. در ادامه به جزئیات، مثال‌های عملی، نکات سازگاری و بهترین شیوه‌ها می‌پردازیم.

نحوه استفاده پایه

دو حالت کلی برای این تابع وجود دارد:

• بدون آرگومان: مقدار فعلی کد وضعیت HTTP را برمی‌گرداند.
• با آرگومان عددی: کد وضعیت را تنظیم می‌کند و مقدار قبلی را برمی‌گرداند.

// گرفتن کد وضعیت فعلی
$current = http_response_code();

// تنظیم کد وضعیت به 404
$prev = http_response_code(404);

در قطعه بالا، ابتدا مقدار فعلی با فراخوانی بدون پارامتر خوانده می‌شود. سپس با ارسال 404 کد وضعیت تغییر کرده و مقدار قبلی در متغیر $prev ذخیره می‌شود.

مثال عملی: پاسخ JSON برای API

header('Content-Type: application/json; charset=utf-8');

$data = ['error' => 'Resource not found'];
http_response_code(404);

echo json_encode($data);

این کد یک پاسخ JSON با کد وضعیت 404 ارسال می‌کند. ابتدا هدر Content-Type تنظیم شده تا کلاینت بداند پاسخ JSON است، سپس کد وضعیت 404 و در نهایت بدنه JSON ارسال می‌شود. توجه داشته باشید که هدرها باید قبل از خروجی تولید شوند.

نمونه: استفاده در ریدایرکت

// ریدایرکت دائمی
http_response_code(301);
header('Location: https://example.com/new-page');
exit;

برای ریدایرکت بهتر است ابتدا کد 301 یا 302 را تنظیم کرده و سپس هدر Location را ارسال کنید. سپس با exit از ادامه اجرای اسکریپت جلوگیری کنید تا تنها ریدایرکت اعمال شود.

وقتی هدرها قبلاً ارسال شده‌اند

اگر خروجی (هر محتوایی) قبل از فراخوانی http_response_code() ارسال شده باشد، PHP قادر به تغییر هدرها نخواهد بود. برای جلوگیری از این مشکل از ob_start() یا چک کردن headers_sent() استفاده کنید:

if (!headers_sent()) {
    http_response_code(500);
} else {
    // fallback: ممکن است نتوانیم کد را تغییر دهیم
    error_log('Cannot change HTTP response code: headers already sent.');
}

در صورت ارسال قبلی هدرها، بهتر است از لاگ یا متدهای جایگزین برای گزارش خطا استفاده کنید؛ چون مرورگر ممکن است کد وضعیت دلخواه را دریافت نکند.

نسخه‌های PHP و سازگاری

تابع http_response_code() از PHP 5.4 در دسترس است. در نسخه‌های قدیمی‌تر باید از تابع header() به‌صورت دستی استفاده می‌شد:

// معادل برای PHP < 5.4
header('HTTP/1.1 404 Not Found');

همچنین می‌توانید متن وضعیت دلخواه را با header ارسال کنید، اگرچه اکثر کلاینت‌ها تنها روی عدد وضعیت تکیه می‌کنند.

ارسال متن وضعیت سفارشی

http_response_code() فقط عدد وضعیت را تنظیم می‌کند؛ برای تعیین متن وضعیت (status text) باید از header استفاده کنید:

header("HTTP/1.1 418 I'm a teapot");

این روش امکان ارسال متن سفارشی را می‌دهد اما بهتر است از استانداردهای HTTP پیروی کنید و متن‌های غیرمعمول را به کار نبرید مگر در موارد خاص (مثلاً برای توسعه و دیباگ).

جدول کدهای متداول HTTP

بهترین شیوه‌ها و نکات امنیتی

• همیشه قبل از ارسال body، هدرها و کد وضعیت را تنظیم کنید.
• در APIها از کدهای مناسب (مانند 201 برای POST موفق) استفاده کنید تا کلاینت‌ها رفتار درست را تشخیص دهند.
• اطلاعات داخلی یا پیام‌های خطای کامل را به کلاینت نفرستید؛ برای لاگ کردن از error_log استفاده کنید و برای کاربر پیام کلی بفرستید.
• برای تست و توسعه می‌توانید از کدهای موقتی استفاده کنید، اما در محیط تولید از استانداردها پیروی کنید.
• اگر از فریم‌ورک استفاده می‌کنید، اغلب فریم‌ورک‌ها متدهایی برای تنظیم وضعیت دارند — از آن‌ها استفاده کنید تا هماهنگی حفظ شود.

مثال پیشرفته: هندلر خطا برای API با خروجی JSON

function api_response($data, $status = 200) {
    if (!headers_sent()) {
        header('Content-Type: application/json; charset=utf-8');
        http_response_code($status);
    }
    echo json_encode($data);
    exit;
}

// استفاده
if (!$resourceFound) {
    api_response(['error' => 'Not found'], 404);
}

در این مثال یک تابع کمکی ساخته‌ایم که هدر Content-Type را تنظیم، کد وضعیت را تعیین و خروجی JSON را چاپ می‌کند. اگر هدرها قبلاً ارسال شده باشند، تابع صرفاً خروجی را می‌فرستد ولی تلاش برای تغییر هدرها نخواهد کرد.

جمع‌بندی

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

لطفاً از کمبود ها و مشکلات این محتوا برای ما بنویسید

ارسال