README

A collection of reusable multi-purpose functions for PHP libraries.

👁 PHP Version Support
👁 Packagist version
👁 License
👁 Continuous Integration
👁 CodeCov
👁 Packagist downloads

Overview

Features

This library features some common functions to reduce overall duplication and avoid certain ugly workarounds (looking at you, phpstan...).

Requirements

• PHP 8.4+
  • extensions: json, mbstring, sodium

API

Arr

(we can't use array as class name because reasons)

method	description
Arr::first(array $array):mixed	Returns the first element of an array, null if the given array is empty.
Arr::last(array $array):mixed	Returns the last element of an array, null if the given array is empty.
Arr::random(array $array):mixed	Returns a random element of an array, null if the given array is empty.

Crypto

method	description
Crypto::sha256(string $data, bool $binary = false):string	Generates an SHA-256 hash for the given value
Crypto::sha512(string $data, bool $binary = false):string	Generates an SHA-512 hash for the given value
Crypto::randomString(int $length, string $keyspace = Crypto::ASCII_COMMON_PW):string	Generates a secure random string of the given $length, using the characters (8-bit byte) in the given $keyspace.
Crypto::createEncryptionKey():string	Creates a new cryptographically secure random encryption key for use with encrypt() and decrypt() (returned in hexadecimal format)
Crypto::encrypt(string $data, string $keyHex, int $format = Crypto::ENCRYPT_FORMAT_HEX):string	Encrypts the given $data with $key, formats the output according to $format [binary, base64, hex]
Crypto::decrypt(string $encrypted, string $keyHex, int $format = Crypto::ENCRYPT_FORMAT_HEX):string	Decrypts the given $encrypted data with $key from input formatted according to $format [binary, base64, hex]

The Crypto class defines the following public constants:

pre-defined character maps for use with Crypto::randomString() as $keyspace:

• NUMERIC: numbers 0-9
• ASCII_LOWER: ASCII a-z
• ASCII_UPPER: ASCII A-Z
• ASCII_SYMBOL: ASCII printable symbols !"#$%&\'()*+,-./:;<=>?@[\]^_`{|}~
• HEXADECIMAL: numbers 0-9 + ASCII a-f
• ASCII_ALPHANUM: numbers 0-9 + ASCII a-z + A-Z
• ASCII_PRINTABLE: numbers 0-9 + ASCII a-z + A-Z + printable symbols
• ASCII_COMMON_PW: ASCII alphanum + most of ASCII printable symbols !#$%&()*+,-./:;<=>?@[]~_| (minus a few troublemakers)

output and input $format for the functions Crypto::encrypt() and Crypto::decrypt(), respectively:

• ENCRYPT_FORMAT_BINARY: raw binary
• ENCRYPT_FORMAT_BASE64: mime base64
• ENCRYPT_FORMAT_HEX: hexadecimal

Directory

method	description
Directory::exists(string $dir):bool	Checks whether a directory exists
Directory::isReadable(string $dir):bool	Checks whether the given directory is readable
Directory::isWritable(string $dir):bool	Checks whether the given directory is writable
Directory::create(string $dir, int $permissions = 0o777, bool $recursive = true):string	Creates a directory
Directory::remove(string $dir):bool	Removes a directory
Directory::relativePath(string $path, string $from, string $separator = DIRECTORY_SEPARATOR):string	Returns the relative path from the given directory

File

method	description
File::exists(string $file):bool	Checks whether a file exists
File::isReadable(string $file):bool	Checks whether the given file is readable
File::isWritable(string $file):bool	Checks whether the given file is writable
File::realpath(string $path):string	Returns the absolute real path to the given file or directory
File::delete(string $file):bool	Deletes a file
File::load(string $file, int $offset = 0, int|null $length = null):string	reads the given file into a string
File::save(string $file, string $data):int	saves the given data string to the given file path
File::loadJSON(string $file, bool $associative = false, int $flags = 0):mixed	load a JSON string from file into an array or object (convenience)
File::saveJSON(string $file, mixed $data, int $flags = Str::JSON_ENCODE_FLAGS_DEFAULT):int	save to a JSON file (convenience)

Str

(see Arr)

method	description
Str::filter(array $mixed):array	Filters an array and removes all elements that are not strings. Array keys are not retained
Str::toUpper(array $strings):array	Converts the strings in an array to uppercase
Str::toLower(array $strings):array	Converts the strings in an array to lowercase
Str::startsWith(string $haystack, array $needles, bool $ignoreCase = false):bool	Checks whether the given string starts with any of the given array of needles
Str::containsAll(string $haystack, array $needles, bool $ignoreCase = false):bool	Checks whether the given string (haystack) contains all of the given array of needles
Str::containsAny(string $haystack, array $needles, bool $ignoreCase = false):bool	Checks whether the given string (haystack) contains any of the given array of needles
Str::jsonDecode(string $json, bool $associative = false, int $flags = 0):mixed	Decodes a JSON string
Str::jsonEncode(mixed $data, int $flags = self::JSON_ENCODE_FLAGS_DEFAULT):string	Encodes a value into a JSON representation
Str::base64encode(string $string, int $variant = SODIUM_BASE64_VARIANT_ORIGINAL):string	Encodes a binary string to base64 (timing-safe)
Str::base64decode(string $base64, int $variant = SODIUM_BASE64_VARIANT_ORIGINAL, string $ignore = ''):string	Decodes a base64 string into binary (timing-safe)

Disclaimer

Use at your own risk!