PHP setrawcookie() Function: Everything You Need to Know

As a PHP developer, you may need to set raw cookies for your web application to store information on the client side. The setrawcookie() function is a built-in PHP function that allows you to set a raw cookie. Unlike the standard setcookie() function, setrawcookie() does not URL-encode the cookie value, making it useful when you need to store pre-encoded data or binary strings. In this article, we will take an in-depth look at the setrawcookie() function — its syntax, parameters, the modern options-array form, common pitfalls, and how it differs from setcookie().

This page assumes you already understand the basics of PHP cookies. If you simply want to store ordinary text, setcookie() is usually the better choice — reach for setrawcookie() only when you must send the value exactly as-is.

What is the setrawcookie() Function?

The setrawcookie() function is a PHP built-in function (available since PHP 5.2.0) that allows you to set a raw cookie on the client side. It works by adding a Set-Cookie HTTP response header, so — like every header-emitting function — it must be called before any output is sent to the browser (no echoed HTML, no blank lines before <?php, no BOM). If output has already started, the header is silently dropped. See headers_sent() for how to detect this.

The function returns true if the header was successfully queued and false on failure. Note that a true return does not guarantee the browser accepted or will send back the cookie — it only means the header was emitted.

How to Use the setrawcookie() Function

Using the setrawcookie() function is straightforward. Here is the syntax:

PHP Syntax

setrawcookie($name, $value, $expire, $path, $domain, $secure, $httponly);

The function accepts seven parameters:

• $name: The name of the cookie.
• $value: The raw value of the cookie (not URL-encoded).
• $expire: The expiration time as a Unix timestamp.
• $path: The server path where the cookie will be available.
• $domain: The domain where the cookie will be available.
• $secure: Whether the cookie should only be transmitted over HTTPS.
• $httponly: Whether the cookie should be inaccessible to client-side JavaScript.

Here is an example of how to use the setrawcookie() function to set a raw cookie:

Example

<?php

$name = "username";
$value = "john";
$expire = time() + (86400 * 30); // 30 days
$path = "/";
$domain = ".example.com";
$secure = true;
$httponly = true;
setrawcookie($name, $value, $expire, $path, $domain, $secure, $httponly);

In this example, we use the setrawcookie() function to set a raw cookie named username with the value john. We specify the expiration time as 30 days from the current time (using time() as the base), the server path as /, and the domain as .example.com. The secure and httponly flags are set to true to ensure the cookie is only transmitted over HTTPS and is inaccessible to client-side JavaScript.

The options-array signature (PHP 7.3+)

Since PHP 7.3 you can pass a single $options array instead of positional arguments. This is the recommended form because it is the only way to set the SameSite attribute, which controls whether the cookie is sent on cross-site requests:

<?php

setrawcookie("username", "john", [
    "expires"  => time() + (86400 * 30), // 30 days
    "path"     => "/",
    "domain"   => ".example.com",
    "secure"   => true,
    "httponly" => true,
    "samesite" => "Strict", // "Strict", "Lax", or "None"
]);

When using the array form, the $expire key is named expires (with an s), and samesite has no equivalent in the positional signature.

Reading the cookie back

A cookie set on one request is not available in $_COOKIE until the browser sends it back on a subsequent request. On that later request you read it like any other cookie:

<?php

if (isset($_COOKIE["username"])) {
    echo "Welcome back, " . $_COOKIE["username"];
} else {
    echo "Cookie not set yet.";
}

Because setrawcookie() does not encode the value, whatever bytes you stored are returned exactly as-is — there is no automatic urldecode() step on the way back in.

Deleting a raw cookie

To remove a cookie, set it again with an expiration time in the past. The name, path, and domain must match the original cookie:

<?php

setrawcookie("username", "", time() - 3600, "/", ".example.com");

setrawcookie() vs setcookie()

The main difference between setcookie() and setrawcookie() is how they handle the cookie value. setcookie() automatically URL-encodes the value using rawurlencode(), which is safe for standard text but can cause issues if you need to store pre-encoded data or binary strings. setrawcookie() skips this encoding step, giving you full control over the raw value. For most standard use cases, setcookie() is preferred, but setrawcookie() is essential when working with already-encoded data.

A practical consequence: with setrawcookie() you are responsible for keeping the value cookie-safe. A raw cookie value must not contain certain characters — control characters, whitespace, commas, semicolons, or equals signs — because they have special meaning in the Set-Cookie header. If your value might contain those, encode it yourself (for example with rawurlencode()) before passing it in:

<?php

$raw = rawurlencode("john doe; admin=1"); // pre-encode unsafe bytes
setrawcookie("username", $raw, time() + 3600, "/");

Conclusion

The setrawcookie() function is a useful tool for setting raw cookies in your PHP web application. By understanding its syntax, parameters, the options-array form, and how it differs from setcookie(), you can safely store pre-encoded data on the client side. Remember to call it before any output, prefer the options array so you can set SameSite, and only reach for it when you genuinely need to bypass URL-encoding.

Related topics

• PHP Cookies — the bigger picture of how cookies work in PHP.
• setcookie() — the standard, URL-encoding cookie setter.
• PHP Sessions — server-side state, an alternative to cookies.
• header() — send arbitrary HTTP headers manually.
• headers_sent() — check whether headers have already been sent.

Practice