【PHP8.x】setrawcookie関数の使い方
setrawcookie関数は、HTTPレスポンスヘッダーを通じてクライアント（ブラウザ）にクッキーを送信するために使用される関数です。この関数は、ウェブサーバーからブラウザへ少量の情報を保存し、次回以降のアクセスでその情報を利用できるようにします。PHPのsetcookie関数と非常に似ていますが、setrawcookie関数では、クッキーの値がURLエンコードされずにそのまま送信される点が大きな特徴です。このため、値を事前に開発者がURLエンコードしておく必要がある場合や、特殊な文字を含む値を加工せずにそのまま送信したい場合に利用されます。
引数としては、クッキーの名前、値、有効期限、パス、ドメイン、セキュア属性、HTTPオンリー属性などを指定できます。有効期限はUnixタイムスタンプ形式で指定し、これを未来の時間に設定しないと、ブラウザを閉じると同時にクッキーが削除されます。パスはクッキーが有効となるサーバー上のパスを指定し、ドメインはクッキーが有効となるドメインを限定します。セキュア属性をtrueに設定するとHTTPS接続でのみクッキーが送信されるようになり、HTTPオンリー属性をtrueに設定するとJavaScriptからのクッキーアクセスを防ぎ、セキュリティを向上させます。
この関数は、他のHTTPヘッダーが既に送信されている場合には正しく動作しません。したがって、setrawcookie関数を呼び出す前に、いかなるHTML出力や空白行なども行われていないことを確認することが重要です。主に、ユーザー認証情報やセッションID、ユーザー設定などの一時的な情報をブラウザに保存し、ウェブアプリケーションにおいてユーザーの状態を管理する際に利用されます。これは、ユーザー体験を向上させる上で重要な機能の一つです。
基本的な使い方
構文(syntax)
setrawcookie(string $name, string $value = '', int $expires = 0, string $path = '', string $domain = '', bool $secure = false, bool $httponly = false): bool
引数(parameters)
string $name, string $value = '', int $expires = 0, string $path = '', string $domain = '', bool $secure = false, bool $httponly = false
- string $name: 設定するクッキーの名前
- string $value = '': クッキーに保存する値。デフォルトは空文字列
- int $expires = 0: クッキーの有効期限（UNIXタイムスタンプ）。0を指定するとセッションクッキーとなる
- string $path = '': クッキーが有効なサーバー上のパス。デフォルトはルートディレクトリ('/')
- string $domain = '': クッキーが有効なドメイン。デフォルトは現在のホスト
- bool $secure = false: trueを指定すると、HTTPS接続時のみクッキーが送信される
- bool $httponly = false: trueを指定すると、HTTPプロトコル経由でのみクッキーにアクセス可能となり、JavaScriptからのアクセスが制限される
戻り値(return)
bool
setrawcookie関数は、HTTPヘッダーとしてクライアントにクッキーを設定したかどうかを示す真偽値（bool）を返します。成功した場合は true、失敗した場合は false を返します。
サンプルコード
PHPで生のクッキーを設定する
<?php
// setrawcookie関数はHTTPヘッダーが送信される前に呼び出す必要があります。
// そのため、HTML出力より前にこのコードを配置します。
// クッキーの名前を定義します。
$cookieName = 'my_raw_cookie';
// クッキーの値を定義します。setrawcookieは値をURLエンコードしないため、
// 特殊文字を含む場合でもそのままブラウザに送信されます。
$cookieValue = 'Hello Raw World! This value is NOT URL encoded.';
// クッキーの有効期限を定義します。現在の時刻に3600秒（1時間）を加算しています。
$expires = time() + (3600); // 1時間後
// setrawcookie関数を呼び出してクッキーを設定します。
// 引数:
// 1. $name: クッキーの名前
// 2. $value: クッキーの値 (URLエンコードされない)
// 3. $expires: 有効期限のUNIXタイムスタンプ (0はブラウザを閉じると削除)
// 4. $path: クッキーが有効なパス ( '/' はサイト全体を意味します)
// 5. $domain: クッキーが有効なドメイン (空文字列は現在のドメイン)
// 6. $secure: HTTPS接続でのみクッキーを送信するか (true/false)
// 7. $httponly: JavaScriptからクッキーにアクセスできるか (true/false, セキュリティ推奨)
$cookieSet = setrawcookie(
$cookieName, // クッキーの名前
$cookieValue, // クッキーの値 (URLエンコードされないため、生のままのデータが送信されます)
$expires, // 有効期限 (UNIXタイムスタンプ形式)
'/', // クッキーが有効なパス
'', // クッキーが有効なドメイン
false, // HTTPSでのみ送信するか (ここではHTTPでも動作させるためfalse)
true // JavaScriptからのアクセスを禁止するか (セキュリティのためtrueを推奨)
);
?>
<!DOCTYPE html>
<html lang="ja">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>setrawcookieサンプル</title>
</head>
<body>
<h1>setrawcookie関数を使ったクッキー設定のサンプル</h1>
<?php if ($cookieSet): ?>
<p>「<?php echo htmlspecialchars($cookieName); ?>」クッキーが設定されました。</p>
<p>このページを<strong>リロード（再読み込み）</strong>すると、ブラウザから送信されたクッキーの値が表示されます。</p>
<?php else: ?>
<p>クッキーの設定に失敗しました。ヘッダーが既に送信されている可能性があります。</p>
<?php endif; ?>
<h2>現在のクッキー値:</h2>
<?php
// クッキーはブラウザから次のリクエストで送信されるため、
// setrawcookieを呼び出した直後の$_COOKIEには反映されません。
// ページをリロードすると、ブラウザから送信されたクッキーの値にアクセスできます。
if (isset($_COOKIE[$cookieName])) {
echo '<p>クッキー名: ' . htmlspecialchars($cookieName) . '</p>';
echo '<p>クッキー値: ' . htmlspecialchars($_COOKIE[$cookieName]) . '</p>';
echo '<p>この値はsetrawcookieで設定されたため、URLエンコードされていないそのままの文字列です。</p>';
} else {
echo '<p>「' . htmlspecialchars($cookieName) . '」クッキーはまだ設定されていないか、ブラウザから送信されていません。</p>';
}
?>
<hr>
<p><strong>ポイント:</strong> クッキーはサーバーがブラウザに「保存してね」と依頼するデータです。</p>
<p>ブラウザはその依頼を受け取った後、次回同じサイトにアクセスする際にそのクッキーをサーバーに送り返します。</p>
<p>そのため、<code>setrawcookie()</code>を呼び出した直後の同じページリクエストでは、<code>$_COOKIE</code>スーパーグローバル変数には設定されたばかりの値は含まれません。ページを再読み込みすることで、ブラウザから新しいクッキーがサーバーに送られ、<code>$_COOKIE</code>から利用可能になります。</p>
</body>
</html>
PHPのsetrawcookie関数は、ウェブブラウザにクッキー（一時的なデータ）を保存するよう指示するために使用されます。この関数は、設定する値（$value引数）をURLエンコードせずに、そのままの文字列でブラウザに送信する点が、一般的なsetcookie関数との大きな違いです。これにより、特殊文字を含む値でも意図した通りの「生」のデータとして扱うことができます。
setrawcookie関数は、HTMLなどのコンテンツがブラウザに送信される「HTTPヘッダー」が送られる前に呼び出す必要があります。もしヘッダー送信後に呼び出すと、クッキー設定に失敗し、戻り値としてfalseを返します。クッキーが正常に設定されるとtrueを返します。
引数には、クッキーを識別する$name（名前）と$value（値）を指定します。$expiresにはクッキーの有効期限をUNIXタイムスタンプ形式で設定し、0を指定するとブラウザを閉じると削除されます。$pathでクッキーが有効なウェブサイトのパスを、$domainで有効なドメインを指定できます。$secureをtrueに設定するとHTTPS接続でのみクッキーが送信され、$httponlyをtrueにするとJavaScriptからのクッキーアクセスを禁止し、セキュリティを高めることが推奨されます。
setrawcookie関数を呼び出した直後のページリクエストでは、ブラウザからサーバーに送り返される$_COOKIEスーパーグローバル変数には、設定されたばかりの新しいクッキーは含まれません。設定したクッキーの値は、ページをリロードするなど、次のリクエストがブラウザからサーバーに送信された際に$_COOKIEで利用可能になります。
setrawcookie関数は、HTTPヘッダーが送信される前に呼び出す必要がありますので、HTML出力より前に記述してください。この関数は、クッキーの値をURLエンコードせずにそのままブラウザに送信します。そのため、値に特殊文字が含まれる場合は、ブラウザでの扱いに注意が必要です。クッキーを設定した直後の同じリクエストでは、$_COOKIEスーパーグローバル変数に値は反映されません。値を確認するには、ページを再読み込みするなどしてブラウザからの次のリクエストを待つ必要があります。セキュリティ向上のため、httponly引数はtrueに設定し、JavaScriptからのクッキーアクセスを禁止することを強く推奨します。また、HTTPS環境ではsecure引数をtrueに設定し、安全な接続でのみクッキーを送信するようにしてください。有効期限はUNIXタイムスタンプで指定します。