LanguageText and bytes

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

you write
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);
}
phn build writes
<?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 . string is text, bytes . bytes is binary. Joining one with the other is P2530.
  • Interpolation, "id: $raw", and echo take text only: a bytes operand is P2530.
  • === between a string and a bytes is P2305. 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 .= $chunk keeps it bytes.
you write
namespace App;

function header(bytes $frame, string $name): string {
    $line = "frame for $name: " . $frame;

    return $frame === $name ? $line : '';
}
$ phn checkexit 1
src/Example.phn:4:13: error P2530: cannot concatenate bytes and text: mb_check_encoding($frame, 'UTF-8') checks the bytes are UTF-8 text, after which they are string&bytes and join text; (string) $frame converts them unchecked; (bytes) takes text as its UTF-8 bytes, and (bytes) '' starts a binary buffer
    4 |     $line = "frame for $name: " . $frame;
      |             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
src/Example.phn:6:12: error P2305: strict comparison between bytes and string compares binary data with text, which may still hold the same bytes: write (bytes) on the text to compare bytes, or test mb_check_encoding($frame, 'UTF-8') first to compare text (the bytes are string&bytes after it)
    6 |     return $frame === $name ? $line : '';
      |            ^^^^^^^^^^^^^^^^
1 files checked: 2 errors, 0 warnings

Converting

FromToWriteAt run time
stringbytes(bytes) $textnothing: the cast is erased
bytesstring, unchecked(string) $rawnothing
bytesstring, checkedmb_check_encoding($raw, 'UTF-8')the test, which PHP runs
bytesstring, lossymb_scrub($raw)invalid sequences replaced
byteshex or base64 textbin2hex($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

CodeWhen
P2530bytes used as text: joined with a string, interpolated, echoed
P2305=== or !== between string and bytes
P2103bytes 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