This is a PHP tutorial on how to send a “503 Service Temporarily Unavailable” status code. This header can be useful to use if you are carrying out maintenance or a technical issue is currently preventing your app from working correctly.
By sending a 503 HTTP response code, we are letting the client know that something is “wrong” at the moment and that they should retry at a later stage. This header also helps prevent search engines from indexing broken web apps, etc.
Using PHP’s header function to respond with a 503 HTTP status code.
In this example, I will use PHP’s inbuilt header function to respond with a 503 HTTP status code:
//Using PHP's header function to send a 503 //Service Temporarily Unavailable status code to the client. header($_SERVER["SERVER_PROTOCOL"]." 503 Service Temporarily Unavailable", true, 503); //The number of seconds that the client should //wait before retrying. $retryAfterSeconds = 240; //Send a Retry-After header to the client. header('Retry-After: ' . $retryAfterSeconds); //Send a message to the browser so that the user //knows what is going on. echo '<h1>503 Service Temporarily Unavailable</h1>'; echo '<p>Our site is currently under maintenance.</p>'; //Kill the PHP script. exit;
In the PHP code above:
- We sent a “503 Service Temporarily Unavailable” status code to the client using PHP’s header function. Note that we used $_SERVER[“SERVER_PROTOCOL”] because we cannot assume that the client will be using HTTP/1.1. For all we know, they could be using HTTP/1.0
- We sent a Retry-After header to the client. This header tells the client how many seconds they should wait before trying again. Note that I emphasized the word “should” there because the client can simply ignore this header if they want to. Thankfully, bots and crawlers such as Googlebot will honor this header.
- Finally, we outputted a basic “under maintenance” message and exited the PHP script.
Note that if you do not provide a custom message, browsers such as Chrome will display the following message:
Personally, I think that the 503 error message above is too uninformative.
Using the http_response_code function to return a 503 error.
If you are using PHP version 5.4.0 or above, then you can send a 503 response code using the aptly-named http_response_code function:
//Use PHP's http_response_code function to send a 503 //Service Temporarily Unavailable status code to the client. http_response_code(503); //Seconds until the client should retry. $retryAfterSeconds = 240; //Retry-After header. header('Retry-After: ' . $retryAfterSeconds); //Custom message. echo '<h1>503 Service Temporarily Unavailable</h1>'; echo '<p>Our site is currently under maintenance.</p>'; //Exit the script. exit;
The code above works the exact same way as the PHP code in our first example. The only difference is that you don’t have to manually write out the full header details.
For other useful HTTP response codes, see:
- Sending a 404 Not Found header with PHP.
- 405 Method Not Allowed.
- PHP: Send a 500 Internal Server Error response.
Hopefully, you found this guide useful!