CakePHP 4 で HTTP ステータスコードを変更する方法

はじめに

HTTP ステータスコードとは、クライアントからサーバへのリクエストの結果を表すものです。

Web ページを閲覧するときには、ブラウザが HTTP ステータスコードを受けているのですが、画面に表示されないので、あまり意識しないですよね。

ページが正常に表示されているときには 200 などが返っているのですが、それよりも 404 (Not Found) や 500 (Internal Server Error) などのほうが、馴染みがあるでしょうか。

さて、Web サイトを作っているときには、意識的に HTTP ステータスコードを指定することはないと思いますが、API をつくる時には大切になってきます。

例えば「API が PUT リクエストを受けた時に、正常終了したら 201 (Created) を返す」というような使い方ができます。

今日はそのような CakePHP 4 で任意の HTTP ステータスコードを出力する方法 をご紹介します。

今回使用したのは CakePHP 4.0.5 です。

目次
  1. HTTP ステータスコードの変更方法
  2. 注意(うまくいかない例)
  3. おわりに

1. HTTP ステータスコードの変更方法

コントローラで下記のようにすることで、任意の HTTP ステータスコードを出力できます。

/src/Controller/SampleController.php
class SampleController extends AppController
{
    public function index()
    {
        $this->set('message', 'Down for maintenance');
        $this->viewBuilder()
            ->setClassName('Json')
            ->setOption('serialize', ['message'])
            ->setOption('jsonOptions', JSON_FORCE_OBJECT);

        // ▼ HTTP ステータスコード 503 で出力
        $this->response = $this->response->withStatus(503);
    }
}

ステータスコードの確認はブラウザのコンソールで可能です。詳細は割愛しますが、ブラウザのコンソールを開いて「Network」や「ネットワーク」のタブで確認できます。

2. 注意(うまくいかない例)

下記のようにするとうまく動作しないのでご注意ください。

/src/Controller/SampleController.php
public function index()
{
    ...
    // 【ダメ】ステータスコードが 200 になります
    $this->response->withStatus(503);
}
/src/Controller/SampleController.php
public function index()
{
    ...
    // 【ダメ】503 にはなりますが JSON データが出力されなくなります
    return $this->response->withStatus(503);
}

3. おわりに

ステータスコードの種類につきましては、それを管理している IANA のサイトで確認できます。

また、今回紹介した HTTP ステータスを変更する方法は、CakePHP 3.8 の公式ドキュメントを参考にして実装したものです。

CakePHP 4.x Cookbook ではみつけることができませんでした。