Skip to content

Commit fedf4d3

Browse files
codemashercodemasher
committedNov 12, 2024·
:octocat: added File::realpath()
1 parent 5158528 commit fedf4d3

File tree

1 file changed

+87
-0
lines changed

1 file changed

+87
-0
lines changed
 

‎README.md

+87
Original file line numberDiff line numberDiff line change
@@ -34,6 +34,93 @@ This library features some common functions to reduce overall duplication and av
3434
- PHP 8.1+
3535
- extensions: `json`, `mbstring`, `sodium`
3636

37+
## API
38+
39+
### `Arr`
40+
41+
(we can't use `array` as class name because reasons)
42+
43+
| method | description |
44+
|----------------------------------|----------------------------------------------------------------------------|
45+
| `Arr::first(array $array):mixed` | Returns the first element of an array, `null` if the given array is empty. |
46+
| `Arr::last(array $array):mixed` | Returns the last element of an array, `null` if the given array is empty. |
47+
48+
49+
### `Crypto`
50+
51+
| method | description |
52+
|-------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------|
53+
| `Crypto::sha256(string $data, bool $binary = false):string` | Generates an SHA-256 hash for the given value |
54+
| `Crypto::sha512(string $data, bool $binary = false):string` | Generates an SHA-512 hash for the given value |
55+
| `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`. |
56+
| `Crypto::createEncryptionKey():string` | Creates a new cryptographically secure random encryption key for use with `encrypt()` and `decrypt()` (returned in hexadecimal format) |
57+
| `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\] |
58+
| `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\] |
59+
60+
The `Crypto` class defines the following public constants:
61+
62+
pre-defined character maps for use with `Crypto::randomString()` as `$keyspace`:
63+
64+
- `NUMERIC`: numbers 0-9
65+
- `ASCII_LOWER`: ASCII a-z
66+
- `ASCII_UPPER`: ASCII A-Z
67+
- `ASCII_SYMBOL`: ASCII printable symbols
68+
- `HEXADECIMAL`: numbers 0-9 + ASCII a-f
69+
- `ASCII_ALPHANUM`: numbers 0-9 + ASCII a-z + A-Z
70+
- `ASCII_PRINTABLE`: numbers 0-9 + ASCII a-z + A-Z + printable symbols
71+
- `ASCII_COMMON_PW`: ASCII printable minus a few troublemaker symbols
72+
73+
output and input `$format` for the functions `Crypto::encrypt()` and `Crypto::decrypt()`, respectively:
74+
75+
- `ENCRYPT_FORMAT_BINARY`: raw binary
76+
- `ENCRYPT_FORMAT_BASE64`: mime base64
77+
- `ENCRYPT_FORMAT_HEX`: hexadecimal
78+
79+
80+
### `Directory`
81+
82+
| method | description |
83+
|-------------------------------------------------------------------------------------------|---------------------------------------------------------------|
84+
| `Directory::exists(string $dir):bool` | Checks whether a directory exists |
85+
| `Directory::isReadable(string $dir):bool` | Checks whether the given directory is readable |
86+
| `Directory::isWritable(string $dir):bool` | Checks whether the given directory is writable |
87+
| `Directory::create(string $dir, int $permissions = 0o777, bool $recursive = true):string` | Creates a directory |
88+
| `Directory::remove(string $dir):bool` | Removes a directory |
89+
90+
91+
### `File`
92+
93+
| method | description |
94+
|----------------------------------------------------------------------------------------------|--------------------------------------------------------------------|
95+
| `File::exists(string $file):bool` | Checks whether a file exists |
96+
| `File::isReadable(string $file):bool` | Checks whether the given file is readable |
97+
| `File::isWritable(string $file):bool` | Checks whether the given file is writable |
98+
| `File::realpath(string $path):string` | Returns the absolute real path to the given file or directory |
99+
| `File::delete(string $file):bool` | Deletes a file |
100+
| `File::load(string $file, int $offset = 0, int\|null $length = null):string` | reads the given file into a string |
101+
| `File::save(string $file, string $data):int` | saves the given data string to the given file path |
102+
| `File::loadJSON(string $file, bool $associative = false, int $flags = 0):mixed` | load a JSON string from file into an array or object (convenience) |
103+
| `File::saveJSON(string $file, mixed $data, int $flags = Str::JSON_ENCODE_FLAGS_DEFAULT):int` | save to a JSON file (convenience) |
104+
105+
106+
### `Str`
107+
108+
(see `Arr`)
109+
110+
| method | description |
111+
|-------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------|
112+
| `Str::filter(array $mixed):array` | Filters an array and removes all elements that are not strings. Array keys are *not* retained |
113+
| `Str::toUpper(array $strings):array` | Converts the strings in an array to uppercase |
114+
| `Str::toLower(array $strings):array` | Converts the strings in an array to lowercase |
115+
| `Str::startsWith(string $haystack, array $needles, bool $ignoreCase = false):bool` | Checks whether the given string starts with *any* of the given array of needles |
116+
| `Str::containsAll(string $haystack, array $needles, bool $ignoreCase = false):bool` | Checks whether the given string (haystack) contains *all* of the given array of needles |
117+
| `Str::containsAny(string $haystack, array $needles, bool $ignoreCase = false):bool` | Checks whether the given string (haystack) contains *any* of the given array of needles |
118+
| `Str::jsonDecode(string $json, bool $associative = false, int $flags = 0):mixed` | Decodes a JSON string |
119+
| `Str::jsonEncode(mixed $data, int $flags = self::JSON_ENCODE_FLAGS_DEFAULT):string` | Encodes a value into a JSON representation |
120+
| `Str::base64encode(string $string, int $variant = SODIUM_BASE64_VARIANT_ORIGINAL):string` | Encodes a binary string to base64 (timing-safe) |
121+
| `Str::base64decode(string $base64, int $variant = SODIUM_BASE64_VARIANT_ORIGINAL):string` | Decodes a base64 string into binary (timing-safe) |
122+
123+
37124
## Disclaimer
38125

39126
Use at your own risk!

0 commit comments

Comments
 (0)