Language
Text and bytes
string is UTF-8 text and bytes is binary data; both are PHP strings at run time, and the checker keeps them apart.
PHP has one string type for two different things: text, such as a name or a JSON document, and
binary data, such as a hash, a random token or a packed frame. Phaenon gives the second its own
type, bytes, so that a random token is not echoed into HTML or compared with a password by
accident. At run time both are PHP strings, and bytes compiles to string.
At a glance
namespace App;
final class Token
{
__construct(private bytes $raw) {}
static generate(): self => new self(random_bytes(16));
static fromHeader(string $header): ?self {
$raw = base64_decode($header, true);
return $raw === false ? null : new self((bytes) $raw);
}
hex(): string => bin2hex($this->raw);
}<?php
/* @generated by phaenon from Example.phn */
declare(strict_types=1);
namespace App;
final class Token
{
public function __construct(private string $raw) {}
public static function generate(): self
{
return new self(random_bytes(16));
}
public static function fromHeader(string $header): ?self
{
$raw = base64_decode($header, true);
return $raw === false ? null : new self($raw);
}
public function hex(): string
{
return bin2hex($this->raw);
}
}random_bytes() returns bytes, bin2hex() takes it and returns text, and (bytes) says that
what base64_decode() returned is binary. The cast leaves nothing in the PHP.
Two types, neither a subtype of the other
string is text, UTF-8. bytes is binary data of any length. A bytes value does not go where
a string is expected, nor the other way, and the checker reports what would mix them:
.joins two values of the same kind:string . stringis text,bytes . bytesis binary. Joining one with the other isP2530.- Interpolation,
"id: $raw", andechotake text only: abytesoperand isP2530. ===between astringand abytesisP2305. Both are PHP strings and may compare equal, but comparing text with binary is a mistake in the code.- A string literal is
string. There is no bytes literal: a binary buffer starts from(bytes) '', and$buffer .= $chunkkeeps itbytes.
namespace App;
function header(bytes $frame, string $name): string {
$line = "frame for $name: " . $frame;
return $frame === $name ? $line : '';
}src/Example.phn:4:13: error P2530:
4 | $line = "frame for $name: " . $frame;
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
src/Example.phn:6:12: error P2305:
6 | return $frame === $name ? $line : '';
| ^^^^^^^^^^^^^^^^
1 files checked: 2 errors, 0 warningsConverting
| From | To | Write | At run time |
|---|---|---|---|
string | bytes | (bytes) $text | nothing: the cast is erased |
bytes | string, unchecked | (string) $raw | nothing |
bytes | string, checked | mb_check_encoding($raw, 'UTF-8') | the test, which PHP runs |
bytes | string, lossy | mb_scrub($raw) | invalid sequences replaced |
bytes | hex or base64 text | bin2hex($raw), base64_encode($raw) | the encoding |
(bytes) retypes text, or a string that a PHP function returned with binary in it, as binary
data. (string) is the way back for an API that takes binary in a string parameter, such as a
UUID library's fromBinary(string $bytes): the cast shows in the code where binary crosses into
a string.
The checked way is PHP's own test. Where mb_check_encoding($raw, 'UTF-8') holds, the checker
narrows $raw to string&bytes, a value that is both, accepted wherever either is:
namespace App;
function text(bytes $raw): string {
return mb_check_encoding($raw, 'UTF-8') ? $raw : throw new \ValueError('not valid UTF-8');
}
function textOrNull(bytes $raw): ?string => mb_check_encoding($raw, 'UTF-8') ? $raw : null;The encoding must be a literal naming UTF-8. The test needs the mbstring extension, or
symfony/polyfill-mbstring, as any mb_* call does.
PHP's functions
The functions that produce binary are typed bytes: random_bytes(), hash(…, binary: true),
hash_hmac(…, binary: true), md5(…, true), sha1(…, true), pack(),
openssl_random_pseudo_bytes(), and hex2bin(), which returns bytes|false. The functions that
serve text and binary alike take either: strlen(), substr() (which returns what it was
given), strcmp(), ord(), hash_equals(), fwrite(), file_put_contents(), bin2hex(),
base64_encode(). A function meant for text, such as strtoupper(), takes a string only.
Some functions return a string that may be either, and keep PHP's type: base64_decode(),
file_get_contents() and fread(). Write (bytes) where you know the result is binary.
What the checker reports
| Code | When |
|---|---|
P2530 | bytes used as text: joined with a string, interpolated, echoed |
P2305 | === or !== between string and bytes |
P2103 | bytes passed where a string is declared, or the reverse |
Where the two compare identical, if ($frame === $name), both are string&bytes in that
branch, as after mb_check_encoding(): the code there is checked with that type.
In the compiled PHP
bytes is string in signatures and docblocks alike, so list<bytes> becomes list<string>
for PHPStan, which has no binary type. (bytes) is removed; (string) stays, as PHP's own
cast. A PHP caller sees string parameters and can pass any string: the distinction is checked
in Phaenon code only.
Migrating
phn migrate cannot know which strings hold binary data, so every string stays a string. The
checker then points at the places to change: a random_bytes() stored in a string property is
the typical first finding, which is fixed by typing the property bytes.
See also
- Type tests and narrowing, for
mb_check_encoding()and the other tests - Phaenon for PHP developers