Oihana PHP

encoding

Table of Contents

Functions

base64UrlDecode()  : string|false
Decodes a base64url-encoded string (RFC 4648 §5).
base64UrlEncode()  : string
Encodes binary data into a base64url string (RFC 4648 §5).
hexDecode()  : string|false
Decodes a hexadecimal string into raw bytes.
hexEncode()  : string
Encodes binary data into a lowercase hexadecimal string.
randomBase64Url()  : string
Generates a cryptographically secure random token, encoded in base64url (RFC 4648 §5, URL-safe, no padding).
randomHex()  : string
Generates a cryptographically secure random token, encoded as a lowercase hexadecimal string.

Functions

base64UrlDecode()

Decodes a base64url-encoded string (RFC 4648 §5).

base64UrlDecode(string $value) : string|false

The decoder is permissive on padding but strict on alphabet:

  • Inputs in canonical URL-safe form (no trailing =) are accepted.
  • Inputs that still carry the standard padding (=, ==) are also accepted, for interoperability with implementations that emit padded base64url.
  • Any character outside [A-Za-z0-9_\-] (or = only as trailing padding) causes the function to return false. This includes +, /, whitespace, newlines, control characters and any non-ASCII byte.

The function is binary-safe: it operates on ASCII bytes regardless of the current mbstring.func_overload setting or locale.

The function does not raise exceptions ; it mirrors the contract of base64_decode() and returns false on any invalid input.

Note: when comparing a decoded value to a known secret (e.g. an HMAC tag), always use a constant-time comparison such as hash_equals() ; this function itself does not perform any cryptographic comparison.

Parameters
$value : string

The base64url string to decode. May be empty.

Tags
example 
use function oihana\core\encoding\base64UrlDecode;

echo base64UrlDecode( 'aGVsbG8' ) ;          // "hello"  (no padding)
echo base64UrlDecode( 'aGVsbG8=' ) ;         // "hello"  (with padding, tolerated)
echo base64UrlDecode( '-_8' ) ;              // "\xFB\xFF"

var_dump( base64UrlDecode( 'aGVsbG8+' ) ) ;  // bool(false) — '+' is not URL-safe
var_dump( base64UrlDecode( "aGVs\nbG8" ) ) ; // bool(false) — whitespace forbidden
var_dump( base64UrlDecode( 'aGVsbG8é' ) ) ;  // bool(false) — non-ASCII forbidden
see
base64UrlEncode()

For the inverse operation.

author

Marc Alcaraz (ekameleon)

since
1.0.8
Return values
string|false —

The decoded raw bytes, or false if $value is not a valid base64url string.

base64UrlEncode()

Encodes binary data into a base64url string (RFC 4648 §5).

base64UrlEncode(string $binary) : string

The output uses the URL- and filename-safe alphabet (- and _ instead of + and /) and omits the trailing = padding, producing the canonical URL-safe form used by JWT/JOSE, WebPush, signed URLs, etc.

The function is binary-safe: any byte sequence is accepted, including null bytes and arbitrary UTF-8.

Parameters
$binary : string

Raw bytes to encode. May be empty.

Tags
example 
use function oihana\core\encoding\base64UrlEncode;

echo base64UrlEncode( 'hello' ) ;
// Outputs: aGVsbG8

echo base64UrlEncode( "\xFB\xFF" ) ;
// Outputs: -_8 (note the URL-safe '-' and '_', no '=' padding)

// JWT-style usage
$header  = base64UrlEncode( json_encode( [ 'alg' => 'HS256' , 'typ' => 'JWT' ] ) ) ;
$payload = base64UrlEncode( json_encode( [ 'sub' => '42' , 'iat' => time() ] ) ) ;
$signing = $header . '.' . $payload ;
see
base64UrlDecode()

For the inverse operation.

author

Marc Alcaraz (ekameleon)

since
1.0.8
Return values
string —

The base64url-encoded representation, without padding. Always a subset of [A-Za-z0-9_-].

hexDecode()

Decodes a hexadecimal string into raw bytes.

hexDecode(string $value) : string|false

Strict, warning-free counterpart of hex2bin() :

  • Accepts both lowercase and uppercase digits ([0-9a-fA-F]).
  • Requires an even number of characters ; an odd length yields false.
  • Rejects any character outside the hex alphabet (including whitespace and non-ASCII bytes) with false instead of PHP's native warning.
  • The empty string decodes to the empty string.

The function does not raise exceptions ; it returns false on any invalid input, mirroring the contract of base64UrlDecode().

Note: when comparing a decoded value to a known secret (e.g. an HMAC tag), always use hash_equals() for constant-time comparison.

Parameters
$value : string

The hexadecimal string to decode. May be empty.

Tags
example 
use function oihana\core\encoding\hexDecode;

echo hexDecode( '616263' ) ;          // "abc"
echo hexDecode( '00FF'   ) ;          // "\x00\xFF" (uppercase accepted)
echo hexDecode( ''       ) ;          // ""

var_dump( hexDecode( '6'      ) ) ;   // bool(false) — odd length
var_dump( hexDecode( '6Z'     ) ) ;   // bool(false) — invalid char
var_dump( hexDecode( '61 62'  ) ) ;   // bool(false) — whitespace forbidden
see
hexEncode()

For the inverse operation.

author

Marc Alcaraz (ekameleon)

since
1.0.8
Return values
string|false —

The decoded raw bytes, or false if $value is not a valid hexadecimal string of even length.

hexEncode()

Encodes binary data into a lowercase hexadecimal string.

hexEncode(string $binary) : string

Thin wrapper around bin2hex() provided for API symmetry with the other helpers of this package (hexDecode(), base64UrlEncode()).

The function is binary-safe and always produces lowercase output, which matches the convention used for hashes, tokens and HMAC tags across the Oihana ecosystem.

Parameters
$binary : string

Raw bytes to encode. May be empty.

Tags
example 
use function oihana\core\encoding\hexEncode;

echo hexEncode( 'abc' ) ;        // "616263"
echo hexEncode( "\x00\xFF" ) ;   // "00ff"
echo hexEncode( '' ) ;           // ""
see
hexDecode()

For the inverse operation.

author

Marc Alcaraz (ekameleon)

since
1.0.8
Return values
string —

A string of [0-9a-f] characters, twice as long as $binary.

randomBase64Url()

Generates a cryptographically secure random token, encoded in base64url (RFC 4648 §5, URL-safe, no padding).

randomBase64Url([int $bytes = 32 ]) : string

The function reads $bytes of entropy from random_bytes() (a CSPRNG) and encodes the result with base64UrlEncode(). The output is safe to use in URLs, HTTP headers, filenames, JWT identifiers, OAuth state/nonce, CSRF tokens and similar contexts.

Output length is ceil( $bytes * 4 / 3 ) characters (without padding). Default $bytes = 32 yields 256 bits of entropy → 43 characters, which is the recommended size for cryptographic tokens.

Parameters
$bytes : int = 32

Number of random bytes to generate. Must be >= 1. Defaults to 32 (256 bits of entropy).

Tags
throws
InvalidArgumentException

If $bytes is less than 1.

RandomException

If no source of randomness is available (propagated from random_bytes()).

example 
use function oihana\core\encoding\randomBase64Url;

$csrfToken     = randomBase64Url() ;        // 256 bits, 43 chars
$oauthState    = randomBase64Url( 16 ) ;    // 128 bits, 22 chars
$refreshToken  = randomBase64Url( 48 ) ;    // 384 bits, 64 chars

// Always URL-safe and unpadded
preg_match( '/^[A-Za-z0-9_\-]+$/' , $csrfToken ) ; // 1
see
base64UrlEncode()

Encoder used internally.

randomHex()

Hex-encoded variant.

author

Marc Alcaraz (ekameleon)

since
1.0.8
Return values
string —

The base64url-encoded random token. Always a subset of [A-Za-z0-9_-].

randomHex()

Generates a cryptographically secure random token, encoded as a lowercase hexadecimal string.

randomHex([int $bytes = 32 ]) : string

The function reads $bytes of entropy from random_bytes() (a CSPRNG) and encodes the result with bin2hex(). The output is safe to use in URLs, logs, filenames, correlation/request IDs, JWT jti, refresh tokens and similar contexts.

Output length is exactly 2 * $bytes characters. Default $bytes = 32 yields 256 bits of entropy → 64 characters.

For shorter URL-friendly tokens at equivalent entropy, prefer randomBase64Url().

Parameters
$bytes : int = 32

Number of random bytes to generate. Must be >= 1. Defaults to 32 (256 bits of entropy).

Tags
throws
InvalidArgumentException

If $bytes is less than 1.

RandomException

If no source of randomness is available (propagated from random_bytes()).

example 
use function oihana\core\encoding\randomHex;

$requestId     = randomHex( 8  ) ; // 16 hex chars  ( 64 bits)
$correlationId = randomHex( 16 ) ; // 32 hex chars  (128 bits)
$refreshToken  = randomHex()      ; // 64 hex chars (256 bits, default)

// Always lowercase hex
preg_match( '/^[0-9a-f]+$/' , $refreshToken ) ; // 1
see
hexEncode()

Encoder used internally.

randomBase64Url()

Base64url variant (shorter at equivalent entropy).

author

Marc Alcaraz (ekameleon)

since
1.0.8
Return values
string —

Lowercase hexadecimal string of length 2 * $bytes.

On this page

Search results