Safe

https://github.com/thecodingmachine/safe
Admin
Safe is a PHP library that wraps core PHP functions in the Safe namespace so they throw exceptions...
Tokens:117,131
Snippets:784
Trust Score:7.8
License:MIT
Update:1 week ago
Show doc for...
Tokens:
Raw
### Install Composer dependencies for Safe performance tests

Source: https://github.com/thecodingmachine/safe/blob/master/performance/README.md

Run these commands in the project root to install dependencies for both test directories (test_with_safe and test_without_safe). Each directory has its own composer.json.

```bash
cd test_with_safe
composer install
cd ..
cd test_without_safe
composer install
cd ..
```

--------------------------------

### Start PHP 7.2 environment with Blackfire

Source: https://github.com/thecodingmachine/safe/blob/master/performance/README.md

Starts the Docker environment with Blackfire enabled. Replace [xyz] and [abc] with your Blackfire server ID and token. After startup, browse to http://localhost:8888/test_with_safe and /test_without_safe to profile.

```bash
BLACKFIRE_SERVER_ID=[xyz] BLACKFIRE_SERVER_TOKEN=[abc] docker-compose up
```

--------------------------------

### Install generator dependencies

Source: https://github.com/thecodingmachine/safe/blob/master/CONTRIBUTING.md

Navigate to the generator directory and install dependencies with Composer.

```bash
$ cd generator
$ composer install
```

--------------------------------

### Install Safe-PHP via Composer

Source: https://github.com/thecodingmachine/safe/blob/master/README.md

Use Composer to install the Safe-PHP library.

```bash
composer require thecodingmachine/safe
```

--------------------------------

### proc_nice() usage example with exception handling

Source: https://github.com/thecodingmachine/safe/blob/master/_autodocs/api-reference/exec.md

Example of using Safe\proc_nice with try/catch to handle ExecException.

```php
use function Safe\proc_nice;
use Safe\Exceptions\ExecException;

try {
    proc_nice(10);
} catch (ExecException $e) {
    // permission denied or unsupported platform
}
```

--------------------------------

### shell_exec() usage example

Source: https://github.com/thecodingmachine/safe/blob/master/_autodocs/api-reference/exec.md

Example of using Safe\shell_exec to execute a command and capture output.

```php
use function Safe\shell_exec;

$output = shell_exec('cat /etc/hostname');
```

--------------------------------

### proc_open() and proc_close() usage example

Source: https://github.com/thecodingmachine/safe/blob/master/_autodocs/api-reference/exec.md

Example of using Safe\proc_open and Safe\proc_close to run a child process with pipes.

```php
use function Safe\proc_open, Safe\proc_close;

$descriptors = [
    0 => ['pipe', 'r'],
    1 => ['pipe', 'w'],
    2 => ['pipe', 'w'],
];
$process = proc_open('php worker.php', $descriptors, $pipes, __DIR__);
fwrite($pipes[0], "start\n");
fclose($pipes[0]);
echo stream_get_contents($pipes[1]);
$code = proc_close($process);
```

--------------------------------

### system() usage example

Source: https://github.com/thecodingmachine/safe/blob/master/_autodocs/api-reference/exec.md

Example of using Safe\system() to execute a command and capture the last line of output. The output is also echoed to the output buffer.

```php
use function Safe\system;

$last = system('ls -la', $code);
```

--------------------------------

### Install PHPStan and Safe-PHP Extension

Source: https://github.com/thecodingmachine/safe/blob/master/README.md

Install the PHPStan extension for Safe-PHP as a dev dependency.

```bash
composer require --dev thecodingmachine/phpstan-safe-rule
```

--------------------------------

### Install Rector for Automated Refactoring

Source: https://github.com/thecodingmachine/safe/blob/master/README.md

Install the Rector tool as a dev dependency to perform automated refactoring.

```bash
composer require --dev rector/rector
```

--------------------------------

### fopen(), fwrite(), fclose() usage example

Source: https://github.com/thecodingmachine/safe/blob/master/_autodocs/api-reference/filesystem.md

Opens a file in append mode, writes a line, and closes it. Uses Safe\fopen, Safe\fwrite, Safe\fclose.

```php
use function Safe\fopen, Safe\fwrite, Safe\fclose;

$fp = fopen('/tmp/out.log', 'a');
fwrite($fp, $line);
fclose($fp);
```

--------------------------------

### file_get_contents() usage example

Source: https://github.com/thecodingmachine/safe/blob/master/_autodocs/api-reference/filesystem.md

Reads a JSON config file and a binary file with offset and length. Uses Safe\file_get_contents.

```php
use function Safe\file_get_contents;

$config = file_get_contents('/etc/app/config.json');
$head   = file_get_contents('data.bin', false, null, 0, 1024);
```

--------------------------------

### unpack() usage example

Source: https://github.com/thecodingmachine/safe/blob/master/_autodocs/api-reference/misc.md

Example of using Safe\unpack() to parse a binary string.

```php
use function Safe\unpack;

$bin = "\x01\x00\x00\x00";
$parsed = unpack('Vnumber', $bin); // ['number' => 1]
```

--------------------------------

### exec() usage example

Source: https://github.com/thecodingmachine/safe/blob/master/_autodocs/api-reference/exec.md

Example of using Safe\exec() to run a command and capture output lines and result code. The function returns the last line of output.

```php
use function Safe\exec;

$lastLine = exec('git rev-parse HEAD', $output, $code);
```

--------------------------------

### apcu_fetch() usage example

Source: https://github.com/thecodingmachine/safe/blob/master/_autodocs/api-reference/special-cases.md

Shows how to use Safe\apcu_store() and Safe\apcu_fetch() together to store and retrieve a value. The example stores the integer 42 under key 'k' and then fetches it.

```php
use function Safe\apcu_store, Safe\apcu_fetch;

apcu_store('k', 42);
$v = apcu_fetch('k');
```

--------------------------------

### Usage of Safe\parse_ini_file

Source: https://github.com/thecodingmachine/safe/blob/master/_autodocs/api-reference/filesystem.md

Example usage importing Safe\parse_ini_file and parsing an INI file with sections and INI_SCANNER_TYPED mode.

```php
use function Safe\parse_ini_file;

$settings = parse_ini_file('app.ini', true, INI_SCANNER_TYPED);
```

--------------------------------

### preg_grep() usage example

Source: https://github.com/thecodingmachine/safe/blob/master/_autodocs/api-reference/pcre.md

Example of using Safe\preg_grep to filter files by extension.

```php
use function Safe\preg_grep;

$phpFiles = preg_grep('/\.php$/', $fileList);
```

--------------------------------

### sleep() usage example

Source: https://github.com/thecodingmachine/safe/blob/master/_autodocs/api-reference/misc.md

Example of using Safe\sleep() to sleep for 2 seconds.

```php
use function Safe\sleep;

sleep(2);
```

--------------------------------

### Usage of Safe\mkdir, Safe\rename, Safe\unlink

Source: https://github.com/thecodingmachine/safe/blob/master/_autodocs/api-reference/filesystem.md

Example usage importing the Safe functions and calling them. mkdir creates a directory with 0755 permissions recursively; rename moves a file; unlink deletes a file.

```php
use function Safe\mkdir, Safe\rename, Safe\unlink;

mkdir('/var/data/2024', 0755, true);
rename('/tmp/a.txt', '/var/data/2024/a.txt');
unlink('/tmp/stale.lock');
```

--------------------------------

### exec() exception handling example

Source: https://github.com/thecodingmachine/safe/blob/master/_autodocs/api-reference/exec.md

Example of catching ExecException thrown by Safe\exec() when the native call returns false, such as when the shell cannot be spawned. A non-zero exit status is not an exception.

```php
use function Safe\exec;
use Safe\Exceptions\ExecException;

try {
    exec('/usr/bin/missing-binary', $out, $code);
} catch (ExecException $e) {
    // shell error — native returned false
}
```

--------------------------------

### hash_hmac_file() usage example

Source: https://github.com/thecodingmachine/safe/blob/master/_autodocs/api-reference/special-cases.md

Example of computing an HMAC-SHA256 digest for a file. Requires importing the function with `use function Safe\hash_hmac_file;`.

```php
use function Safe\hash_hmac_file;

$sig = hash_hmac_file('sha256', $upload, $secret);
```

--------------------------------

### session_start(array $options = []): void

Source: https://github.com/thecodingmachine/safe/blob/master/_autodocs/api-reference/session.md

Starts or resumes a session. Throws SessionException on failure.

```APIDOC
## session_start(array $options = []): void

### Description
Starts or resumes a session. Throws SessionException on failure.

### Method
session_start

### Signature
`session_start(array $options = []): void`

### Parameters
- **$options** (array) - Optional - An associative array of session options.

### Return Value
void

### Exceptions
`Safe\Exceptions\SessionException`
```

--------------------------------

### define() usage example

Source: https://github.com/thecodingmachine/safe/blob/master/_autodocs/api-reference/misc.md

Example of using Safe\define() to define a constant without checking for redefinition.

```php
use function Safe\define;

define('APP_STARTED_AT', microtime(true));
```

--------------------------------

### socket_write() usage example

Source: https://github.com/thecodingmachine/safe/blob/master/_autodocs/api-reference/special-cases.md

Example of using Safe\socket_write() with socket_create() and socket_connect() to send an HTTP request. Requires importing the Safe functions and a valid socket connection.

```php
use function Safe\socket_create, Safe\socket_write, Safe\socket_connect;

$sock = socket_create(AF_INET, SOCK_STREAM, SOL_TCP);
socket_connect($sock, '127.0.0.1', 8080);
socket_write($sock, "GET / HTTP/1.0\r\n\r\n");
```

--------------------------------

### define() with exception handling

Source: https://github.com/thecodingmachine/safe/blob/master/_autodocs/api-reference/misc.md

Example of catching MiscException when defining an already-defined constant.

```php
use function Safe\define;
use Safe\Exceptions\MiscException;

try {
    define('PHP_VERSION', 'x'); // already defined by PHP
} catch (MiscException $e) {
    // constant redefinition attempt
}
```

--------------------------------

### Usage example for stream_filter_append with zlib.inflate

Source: https://github.com/thecodingmachine/safe/blob/master/_autodocs/api-reference/stream.md

Shows how to attach a filter (e.g., zlib.inflate) to a stream using Safe\stream_filter_append, then read the filtered content with Safe\stream_get_contents. The example uses native fopen, but Safe\fopen would also work. The filter resource is returned and can be used with stream_filter_remove.

```php
use function Safe\stream_filter_append, Safe\stream_get_contents;

$fp = \fopen('data.txt.gz', 'rb'); // native fopen (not imported) — Safe\fopen would equally work
stream_filter_append($fp, 'zlib.inflate', STREAM_FILTER_READ);
$plain = stream_get_contents($fp);
```

--------------------------------

### Using Safe\glob() to require PHP files

Source: https://github.com/thecodingmachine/safe/blob/master/_autodocs/api-reference/filesystem.md

Example of using the Safe glob() wrapper to iterate over PHP files in a directory and require them. The wrapper returns an empty array when no matches are found, so the loop simply does nothing in that case.

```php
use function Safe\glob;

foreach (glob(__DIR__ . '/src/*.php') as $file) {
    require $file;
}
```

--------------------------------

### session_start()

Source: https://github.com/thecodingmachine/safe/blob/master/_autodocs/api-reference/session.md

Starts a new or resumes an existing session. This wrapper throws an exception on failure instead of returning false.

```APIDOC
## `session_start()`

### Description
Starts a new or resumes an existing session. This wrapper throws an exception on failure instead of returning false.

### Method
Function call

### Signature
```php
function session_start(array $options = []): void
```

### Parameters
- **options** (array) - Optional - Session options (e.g. `['cookie_lifetime' => 3600]`); also supports `read_and_close`, `use_strict_mode`

### Returns
- `void` — flag-style success (`true`) is removed.

### Throws
- `Safe\Exceptions\SessionException` when the native call returns `false` (headers already sent / cannot write cookie, save path not writable, session handler error).

### Example
```php
use function Safe\session_start;

session_start(['cookie_httponly' => true, 'cookie_samesite' => 'Lax']);
$_SESSION['user_id'] = 42;
```

```php
use function Safe\session_start;
use Safe\Exceptions\SessionException;

try {
    session_start();
} catch (SessionException $e) {
    // e.g. output already sent before session_start
}
```
```

--------------------------------

### Before Refactoring: Error Handling with mkdir

Source: https://github.com/thecodingmachine/safe/blob/master/README.md

Example of existing error handling that will be refactored by Rector.

```php
if (!mkdir($dirPath)) {
    // Do something on error
}
```

--------------------------------

### Using Safe\md5_file

Source: https://github.com/thecodingmachine/safe/blob/master/_autodocs/api-reference/strings.md

Example usage of the Safe md5_file function. Imports with use function Safe\md5_file; and hashes a file.

```php
use function Safe\md5_file;

$hash = md5_file('/var/www/downloads/file.bin');
```

--------------------------------

### Download PHP documentation

Source: https://github.com/thecodingmachine/safe/blob/master/CONTRIBUTING.md

Run this command from the project root to download the PHP documentation from the official repository.

```bash
$ generator/safe.php download-docs
```

--------------------------------

### Using Safe\sha1_file with binary output

Source: https://github.com/thecodingmachine/safe/blob/master/_autodocs/api-reference/strings.md

Example usage of the Safe sha1_file function. Imports with use function Safe\sha1_file; and hashes a file with binary output.

```php
use function Safe\sha1_file;

$hash = sha1_file($archivePath, true);
```

--------------------------------

### Using Safe curl_setopt and curl_getinfo

Source: https://github.com/thecodingmachine/safe/blob/master/_autodocs/api-reference/curl.md

Example of using the Safe wrappers: initialize a cURL handle, set the CURLOPT_HEADER option, execute the request, and retrieve the HTTP response code. curl_exec is also wrapped by Safe.

```php
use function Safe\curl_init, Safe\curl_setopt, Safe\curl_exec, Safe\curl_getinfo;

$ch = curl_init('https://example.com');
curl_setopt($ch, CURLOPT_HEADER, true);
$body = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
```

--------------------------------

### sys_getloadavg() usage example

Source: https://github.com/thecodingmachine/safe/blob/master/_autodocs/api-reference/special-cases.md

Import the Safe function and call sys_getloadavg() to get load averages. The result is an array with three elements, which can be destructured into variables.

```php
use function Safe\sys_getloadavg;

[$load1, $load5, $load15] = sys_getloadavg();
```

--------------------------------

### Using Safe\mktime to create a timestamp

Source: https://github.com/thecodingmachine/safe/blob/master/_autodocs/api-reference/datetime-functions.md

Example of calling Safe\mktime with explicit time components to get a timestamp for midnight on January 1, 2025. Requires importing the function with 'use function Safe\mktime;'.

```php
use function Safe\mktime;

$midnight = mktime(0, 0, 0, 1, 1, 2025);
```

--------------------------------

### mkdir(string $directory, int $permissions = 0777, bool $recursive = false, $context = null): void

Source: https://github.com/thecodingmachine/safe/blob/master/_autodocs/api-reference/filesystem.md

Creates a directory. Throws FilesystemException on failure.

```APIDOC
## mkdir(string $directory, int $permissions = 0777, bool $recursive = false, $context = null): void

### Description
Creates a directory. Throws FilesystemException on failure.

### Method
Function call

### Signature
`mkdir(string $directory, int $permissions = 0777, bool $recursive = false, $context = null): void`

### Parameters
- `$directory` (string) - Required - The directory path.
- `$permissions` (int) - Optional - The permissions (default 0777).
- `$recursive` (bool) - Optional - Whether to create recursively.
- `$context` (resource) - Optional - A stream context resource.

### Return Value
void

### Exceptions
Throws `Safe\Exceptions\FilesystemException` on failure.
```

--------------------------------

### popen(string $command, string $mode)

Source: https://github.com/thecodingmachine/safe/blob/master/_autodocs/api-reference/filesystem.md

Opens a process file pointer. Throws FilesystemException on failure.

```APIDOC
## popen(string $command, string $mode)

### Description
Opens a process file pointer. Throws FilesystemException on failure.

### Method
Function call

### Signature
`popen(string $command, string $mode)`

### Parameters
- `$command` (string) - Required - The command to execute.
- `$mode` (string) - Required - The mode ('r' or 'w').

### Return Value
resource - Process file pointer.

### Exceptions
Throws `Safe\Exceptions\FilesystemException` on failure.
```

--------------------------------

### fopen(string $filename, string $mode, bool $use_include_path = false, $context = null)

Source: https://github.com/thecodingmachine/safe/blob/master/_autodocs/api-reference/filesystem.md

Opens a file or URL. Throws FilesystemException on failure.

```APIDOC
## fopen(string $filename, string $mode, bool $use_include_path = false, $context = null)

### Description
Opens a file or URL. Throws FilesystemException on failure.

### Method
Function call

### Signature
`fopen(string $filename, string $mode, bool $use_include_path = false, $context = null)`

### Parameters
- `$filename` (string) - Required - The file path.
- `$mode` (string) - Required - The mode (e.g., 'r', 'w').
- `$use_include_path` (bool) - Optional - Whether to search in include_path.
- `$context` (resource) - Optional - A stream context resource.

### Return Value
resource - The file stream resource.

### Exceptions
Throws `Safe\Exceptions\FilesystemException` on failure.
```

--------------------------------

### preg_match_all() usage example

Source: https://github.com/thecodingmachine/safe/blob/master/_autodocs/api-reference/pcre.md

Example of using Safe\preg_match_all to extract list items from HTML.

```php
use function Safe\preg_match_all;

preg_match_all('/<li>(.*?)<\/li>/', $html, $items);
```

--------------------------------

### mkdir()

Source: https://github.com/thecodingmachine/safe/blob/master/_autodocs/api-reference/filesystem.md

Creates a directory. This is a safe wrapper around the native mkdir() function that throws an exception on failure instead of returning false.

```APIDOC
## mkdir()

### Description
Creates a directory. This is a safe wrapper around the native mkdir() function that throws an exception on failure instead of returning false.

### Method
Function

### Endpoint
`Safe\mkdir(string $directory, int $permissions = 0777, bool $recursive = false, $context = null): void`

### Parameters
- **directory** (string) - Required - Directory to create
- **permissions** (int) - Optional - Mode; affected by umask. Default: `0777`
- **recursive** (bool) - Optional - Create intermediate directories. Default: `false`
- **context** (resource|null) - Optional - Stream context. Default: `null`

### Returns
`void` - The boolean return of the native function is removed.

### Throws
`FilesystemException` when the native call returns `false`.

### Example
```php
use function Safe\mkdir;

mkdir('/var/data/2024', 0755, true);
```
```

--------------------------------

### link(string $target, string $link): void

Source: https://github.com/thecodingmachine/safe/blob/master/_autodocs/api-reference/filesystem.md

Creates a hard link. Throws FilesystemException on failure.

```APIDOC
## link(string $target, string $link): void

### Description
Creates a hard link. Throws FilesystemException on failure.

### Method
Function call

### Signature
`link(string $target, string $link): void`

### Parameters
- `$target` (string) - Required - The target file.
- `$link` (string) - Required - The link name.

### Return Value
void

### Exceptions
Throws `Safe\Exceptions\FilesystemException` on failure.
```

--------------------------------

### copy(string $source, string $dest, $context = null): void

Source: https://github.com/thecodingmachine/safe/blob/master/_autodocs/api-reference/filesystem.md

Copies a file. Throws FilesystemException on failure.

```APIDOC
## copy(string $source, string $dest, $context = null): void

### Description
Copies a file. Throws FilesystemException on failure.

### Method
Function call

### Signature
`copy(string $source, string $dest, $context = null): void`

### Parameters
- `$source` (string) - Required - The source file path.
- `$dest` (string) - Required - The destination file path.
- `$context` (resource) - Optional - A stream context resource.

### Return Value
void

### Exceptions
Throws `Safe\Exceptions\FilesystemException` on failure.
```

--------------------------------

### Correct usage with explicit error checks

Source: https://github.com/thecodingmachine/safe/blob/master/README.md

Shows the correct version of the previous example, manually checking for false returns and throwing exceptions. This is more verbose and less readable, which Safe PHP aims to improve.

```php
$content = file_get_contents('foobar.json');
if ($content === false) {
    throw new FileLoadingException('Could not load file foobar.json');
}
$foobar = json_decode($content);
if (json_last_error() !== JSON_ERROR_NONE) {
    throw new FileLoadingException('foobar.json does not contain valid JSON: '.json_last_error_msg());
}
```

--------------------------------

### fopen() / fclose() / fwrite()

Source: https://github.com/thecodingmachine/safe/blob/master/_autodocs/api-reference/filesystem.md

Safe wrappers for file open, close, and write operations. These functions throw FilesystemException on failure instead of returning false.

```APIDOC
## `fopen()` / `fclose()` / `fwrite()`

### Description
Safe wrappers for file open, close, and write operations. These functions throw FilesystemException on failure instead of returning false.

### Methods

#### `fopen()`
```php
function fopen(string $filename, string $mode, bool $use_include_path = false, $context = null)
```

#### `fclose()`
```php
function fclose($stream): void
```

#### `fwrite()`
```php
function fwrite($handle, string $string, ?int $length = null): int
```

### Parameters
- **filename** (string) - Required - Path to the file.
- **mode** (string) - Required - File open mode: `'r'`, `'w'`, `'a'`, etc.
- **use_include_path** (bool) - Optional - Standard `fopen` option (default: `false`)
- **context** (resource|null) - Optional - Standard `fopen` option (default: `null`)
- **stream** (resource) - Required - Stream returned by `fopen()`.
- **handle** (resource) - Required - Stream returned by `fopen()`.
- **string** (string) - Required - Data to write.
- **length** (?int) - Optional - Maximum bytes to write (default: `null`)

### Returns
- **fopen** → `resource` - The file stream resource.
- **fclose** → `void` - No return value.
- **fwrite** → `int` - Number of bytes written (`0|positive-int`).

### Throws
- **FilesystemException** - `fopen` on `false` (unreadable path/bad mode), `fclose`/`fwrite` on `false` (closed/invalid stream, failed write).

### Example
```php
use function Safe\fopen, Safe\fwrite, Safe\fclose;

$fp = fopen('/tmp/out.log', 'a');
fwrite($fp, $line);
fclose($fp);
```

### Error Handling Example
```php
use function Safe\fopen;
use Safe\Exceptions\FilesystemException;

try {
    fopen('/root/secret', 'r'); // usually permission-denied
} catch (FilesystemException $e) {
    // handle read failure
}
```
```

--------------------------------

### preg_split() usage example

Source: https://github.com/thecodingmachine/safe/blob/master/_autodocs/api-reference/pcre.md

Example of using Safe\preg_split to split text into words, ignoring empty parts.

```php
use function Safe\preg_split;

$words = preg_split('/\s+/', $text, -1, PREG_SPLIT_NO_EMPTY);
```

--------------------------------

### fopen(), fclose(), fwrite() signatures

Source: https://github.com/thecodingmachine/safe/blob/master/_autodocs/api-reference/filesystem.md

Signatures of Safe wrappers for fopen, fclose, and fwrite. fopen returns resource; fclose returns void; fwrite returns int bytes written.

```php
function fopen(string $filename, string $mode, bool $use_include_path = false, $context = null)

function fclose($stream): void

function fwrite($handle, string $string, ?int $length = null): int
```

--------------------------------

### symlink(string $target, string $link): void

Source: https://github.com/thecodingmachine/safe/blob/master/_autodocs/api-reference/filesystem.md

Creates a symbolic link. Throws FilesystemException on failure.

```APIDOC
## symlink(string $target, string $link): void

### Description
Creates a symbolic link. Throws FilesystemException on failure.

### Method
Function call

### Signature
`symlink(string $target, string $link): void`

### Parameters
- `$target` (string) - Required - The target file.
- `$link` (string) - Required - The link name.

### Return Value
void

### Exceptions
Throws `Safe\Exceptions\FilesystemException` on failure.
```

--------------------------------

### fsync($stream): void

Source: https://github.com/thecodingmachine/safe/blob/master/_autodocs/api-reference/filesystem.md

Synchronizes data to disk. Throws FilesystemException on failure.

```APIDOC
## fsync($stream): void

### Description
Synchronizes data to disk. Throws FilesystemException on failure.

### Method
Function call

### Signature
`fsync($stream): void`

### Parameters
- `$stream` (resource) - Required - The file stream resource.

### Return Value
void

### Exceptions
Throws `Safe\Exceptions\FilesystemException` on failure.
```

--------------------------------

### fopen() exception handling

Source: https://github.com/thecodingmachine/safe/blob/master/_autodocs/api-reference/filesystem.md

Catches FilesystemException when opening a file with insufficient permissions. The comment notes it is usually permission-denied.

```php
use function Safe\fopen;
use Safe\Exceptions\FilesystemException;

try {
    fopen('/root/secret', 'r'); // usually permission-denied
} catch (FilesystemException $e) {
    // handle read failure
}
```

--------------------------------

### Install and run Rector migration with rector-migrate.php

Source: https://github.com/thecodingmachine/safe/blob/master/_autodocs/configuration.md

Install Rector and run the shipped migration config to automatically refactor legacy code. The config is located at vendor/thecodingmachine/safe/rector-migrate.php and dispatches by PHP version.

```bash
composer require --dev rector/rector
vendor/bin/rector process src/ --config vendor/thecodingmachine/safe/rector-migrate.php
```

--------------------------------

### parse_ini_file(string $filename, bool $process_sections = false, int $scanner_mode = INI_SCANNER_NORMAL): array

Source: https://github.com/thecodingmachine/safe/blob/master/_autodocs/api-reference/filesystem.md

Parses a configuration file. Throws FilesystemException on failure.

```APIDOC
## parse_ini_file(string $filename, bool $process_sections = false, int $scanner_mode = INI_SCANNER_NORMAL): array

### Description
Parses a configuration file. Throws FilesystemException on failure.

### Method
Function call

### Signature
`parse_ini_file(string $filename, bool $process_sections = false, int $scanner_mode = INI_SCANNER_NORMAL): array`

### Parameters
- `$filename` (string) - Required - The INI file path.
- `$process_sections` (bool) - Optional - Whether to process sections.
- `$scanner_mode` (int) - Optional - Scanner mode (e.g., INI_SCANNER_NORMAL).

### Return Value
array - INI config.

### Exceptions
Throws `Safe\Exceptions\FilesystemException` on failure.
```

--------------------------------

### simplexml_load_string() usage example

Source: https://github.com/thecodingmachine/safe/blob/master/_autodocs/api-reference/special-cases.md

Example of using Safe\simplexml_load_string() to parse an XML string and access an element. Requires importing the Safe function and a well-formed XML string.

```php
use function Safe\simplexml_load_string;

$xml = simplexml_load_string($xmlString);
echo $xml->book[0]->title;
```

--------------------------------

### fflush($stream): void

Source: https://github.com/thecodingmachine/safe/blob/master/_autodocs/api-reference/filesystem.md

Flushes buffered output. Throws FilesystemException on failure.

```APIDOC
## fflush($stream): void

### Description
Flushes buffered output. Throws FilesystemException on failure.

### Method
Function call

### Signature
`fflush($stream): void`

### Parameters
- `$stream` (resource) - Required - The file stream resource.

### Return Value
void

### Exceptions
Throws `Safe\Exceptions\FilesystemException` on failure.
```

--------------------------------

### readfile(string $filename, bool $use_include_path = false, $context = null): int

Source: https://github.com/thecodingmachine/safe/blob/master/_autodocs/api-reference/filesystem.md

Outputs a file to the output buffer. Throws FilesystemException on failure.

```APIDOC
## readfile(string $filename, bool $use_include_path = false, $context = null): int

### Description
Outputs a file to the output buffer. Throws FilesystemException on failure.

### Method
Function call

### Signature
`readfile(string $filename, bool $use_include_path = false, $context = null): int`

### Parameters
- `$filename` (string) - Required - The file path.
- `$use_include_path` (bool) - Optional - Whether to search in include_path.
- `$context` (resource) - Optional - A stream context resource.

### Return Value
int - Number of bytes read (0 or positive).

### Exceptions
Throws `Safe\Exceptions\FilesystemException` on failure.
```

--------------------------------

### fputcsv() usage example

Source: https://github.com/thecodingmachine/safe/blob/master/_autodocs/api-reference/special-cases.md

Import Safe functions and use fputcsv to write a CSV row to a file. The example opens a file for writing, writes a header row, and closes the file.

```php
use function Safe\fopen, Safe\fputcsv, Safe\fgetcsv, Safe\fclose;

$fh = fopen('/tmp/data.csv', 'w');
fputcsv($fh, ['name', 'qty']);
fclose($fh);
```

--------------------------------

### system()

Source: https://github.com/thecodingmachine/safe/blob/master/_autodocs/api-reference/exec.md

Executes a command and returns the last line of output, echoing output to the output buffer like native system(). Throws ExecException when the native call returns false.

```APIDOC
## `system()`

### Description
Executes a command and returns the last line of output, echoing output to the output buffer like native system(). Throws ExecException when the native call returns false.

### Method
`system`

### Signature
```php
function system(string $command, ?int &$result_code = null): string
```

### Parameters
- **command** (string) - Required - The command to execute
- **result_code** (int|null, by-ref) - Optional - Filled with the return status

### Returns
- **string** - The last line of output (output is also echoed to the output buffer like native `system()`).

### Throws
- `Safe\Exceptions\ExecException` when the native call returns `false`.

### Example
```php
use function Safe\system;

$last = system('ls -la', $code);
```
```

--------------------------------

### parse_url() usage example

Source: https://github.com/thecodingmachine/safe/blob/master/_autodocs/api-reference/url.md

Extracts the host component from a URL.

```php
use function Safe\parse_url;

$host = parse_url('https://user:pass@example.com:8443/path', PHP_URL_HOST);
```

--------------------------------

### Function signatures for glob(), realpath(), tempnam()

Source: https://github.com/thecodingmachine/safe/blob/master/_autodocs/api-reference/filesystem.md

Declarations of the Safe wrappers. glob() returns an array of matched paths, realpath() returns a non-empty string, and tempnam() returns a non-falsy string. All throw FilesystemException when the native call returns false.

```php
function glob(string $pattern, int $flags = 0): array

function realpath(string $path): string

function tempnam(string $directory, string $prefix): string
```

--------------------------------

### touch(string $filename, ?int $time = null, ?int $atime = null): void

Source: https://github.com/thecodingmachine/safe/blob/master/_autodocs/api-reference/filesystem.md

Sets access and modification time of file. Throws FilesystemException on failure.

```APIDOC
## touch(string $filename, ?int $time = null, ?int $atime = null): void

### Description
Sets access and modification time of file. Throws FilesystemException on failure.

### Method
Function call

### Signature
`touch(string $filename, ?int $time = null, ?int $atime = null): void`

### Parameters
- `$filename` (string) - Required - The file path.
- `$time` (?int) - Optional - The modification time.
- `$atime` (?int) - Optional - The access time.

### Return Value
void

### Exceptions
Throws `Safe\Exceptions\FilesystemException` on failure.
```

--------------------------------

### proc_nice()

Source: https://github.com/thecodingmachine/safe/blob/master/_autodocs/api-reference/exec.md

Changes the priority of the current process. Throws an exception on failure, such as permission denied or unsupported platform.

```APIDOC
## `proc_nice()`

### Description
Changes the priority of the current process. Throws an exception on failure, such as permission denied or unsupported platform.

### Method
`proc_nice`

### Signature
```php
function proc_nice(int $priority): void
```

### Parameters
- **priority** (int) - Required - New priority (lower = more favorable)

### Returns
- **void**

### Throws
- `Safe\Exceptions\ExecException`

### Example
```php
use function Safe\proc_nice;
use Safe\Exceptions\ExecException;

try {
    proc_nice(10);
} catch (ExecException $e) {
    // permission denied or unsupported platform
}
```
```

--------------------------------

### get_meta_tags() usage example

Source: https://github.com/thecodingmachine/safe/blob/master/_autodocs/api-reference/url.md

Retrieves meta tags from a URL and echoes the description.

```php
use function Safe\get_meta_tags;

$meta = get_meta_tags('https://example.com/page');
echo $meta['description'];
```

--------------------------------

### fstat($stream): array

Source: https://github.com/thecodingmachine/safe/blob/master/_autodocs/api-reference/filesystem.md

Gets information about a file using an open file pointer. Throws FilesystemException on failure.

```APIDOC
## fstat($stream): array

### Description
Gets information about a file using an open file pointer. Throws FilesystemException on failure.

### Method
Function call

### Signature
`fstat($stream): array`

### Parameters
- `$stream` (resource) - Required - The file stream resource.

### Return Value
array - Stat info on open stream.

### Exceptions
Throws `Safe\Exceptions\FilesystemException` on failure.
```

--------------------------------

### shuffle() usage example

Source: https://github.com/thecodingmachine/safe/blob/master/_autodocs/api-reference/array.md

Imports and uses Safe\shuffle to reorder an array in place.

```php
use function Safe\shuffle;

shuffle($deck); // $deck is reordered
```

--------------------------------

### array_replace_recursive() usage example

Source: https://github.com/thecodingmachine/safe/blob/master/_autodocs/api-reference/array.md

Imports and uses Safe\array_replace_recursive to merge arrays recursively.

```php
use function Safe\array_replace_recursive;

$config = array_replace_recursive($defaults, $userConfig);
```

--------------------------------

### get_headers() usage example

Source: https://github.com/thecodingmachine/safe/blob/master/_autodocs/api-reference/url.md

Fetches HTTP headers as an associative array and accesses the Content-Type header.

```php
use function Safe\get_headers;

$headers = get_headers('https://example.com', true);
$ct = $headers['Content-Type'];
```

--------------------------------

### proc_open()

Source: https://github.com/thecodingmachine/safe/blob/master/_autodocs/api-reference/exec.md

Opens a process with a command and descriptor specifications, providing pipes for communication. Returns a process resource for use with other process functions.

```APIDOC
## `proc_open()`

### Description
Opens a process with a command and descriptor specifications, providing pipes for communication. Returns a process resource for use with other process functions.

### Method
`proc_open`

### Signature
```php
function proc_open(string $cmd, array $descriptorspec, ?array &$pipes, ?string $cwd = null, ?array $env = null, ?array $other_options = null)
```

### Parameters
- **cmd** (string) - Required - Command to execute
- **descriptorspec** (array) - Required - Array of `descriptor => [type, mode, ...]` specs
- **pipes** (array, by-ref) - Required - Filled with `resource[]` stream pipes created for the child
- **cwd** (string|null) - Optional - Working directory; `null` = current
- **env** (array|null) - Optional - Environment variables (`null` = inherit)
- **other_options** (array|null) - Optional - e.g. `bypass_shell`, `suppress_errors`, `blocking_pipes`

### Returns
- **resource** - The process resource

### Throws
- `Safe\Exceptions\ExecException`

### Example
```php
use function Safe\proc_open;

$descriptors = [
    0 => ['pipe', 'r'],
    1 => ['pipe', 'w'],
    2 => ['pipe', 'w'],
];
$process = proc_open('php worker.php', $descriptors, $pipes, __DIR__);
fwrite($pipes[0], "start\n");
fclose($pipes[0]);
echo stream_get_contents($pipes[1]);
$code = proc_close($process);
```
```

--------------------------------

### Using Safe curl_multi_init and curl_multi_info_read

Source: https://github.com/thecodingmachine/safe/blob/master/_autodocs/api-reference/curl.md

Example of the multi-handle interface: create a multi handle, add easy handles with the native curl_multi_add_handle (not wrapped), run with native curl_multi_exec (not wrapped), then read completed transfers with curl_multi_info_read, which returns an array and fills $queued_messages by reference.

```php
use function Safe\curl_multi_init, Safe\curl_multi_info_read;

$mh = curl_multi_init();
// ... add handles, curl_multi_exec loop ...
while ($info = curl_multi_info_read($mh, $remaining)) {
    // $info = ['msg' => CURLMSG_DONE, 'result' => ..., 'handle' => ...]
}
```

--------------------------------

### array_flip() usage example

Source: https://github.com/thecodingmachine/safe/blob/master/_autodocs/api-reference/array.md

Imports and uses Safe\array_flip to flip keys and values of an array.

```php
use function Safe\array_flip;

$titleById = array_flip($byTitle); // $byTitle: ['Intro' => 1, ...]
```

--------------------------------

### lstat(string $filename): array

Source: https://github.com/thecodingmachine/safe/blob/master/_autodocs/api-reference/filesystem.md

Gives information about a file or symbolic link. Throws FilesystemException on failure.

```APIDOC
## lstat(string $filename): array

### Description
Gives information about a file or symbolic link. Throws FilesystemException on failure.

### Method
Function call

### Signature
`lstat(string $filename): array`

### Parameters
- `$filename` (string) - Required - The file path.

### Return Value
array - Stat info following symlink.

### Exceptions
Throws `Safe\Exceptions\FilesystemException` on failure.
```

--------------------------------

### fdatasync($stream): void

Source: https://github.com/thecodingmachine/safe/blob/master/_autodocs/api-reference/filesystem.md

Flushes data to disk. Throws FilesystemException on failure.

```APIDOC
## fdatasync($stream): void

### Description
Flushes data to disk. Throws FilesystemException on failure.

### Method
Function call

### Signature
`fdatasync($stream): void`

### Parameters
- `$stream` (resource) - Required - The file stream resource.

### Return Value
void

### Exceptions
Throws `Safe\Exceptions\FilesystemException` on failure.
```

--------------------------------

### curl_getinfo()

Source: https://github.com/thecodingmachine/safe/blob/master/_autodocs/api-reference/curl.md

Gets information about a cURL transfer. Throws a Safe\Exceptions\CurlException instead of returning false on failure.

```APIDOC
## [FUNCTION] curl_getinfo()

### Description
Gets information about a cURL transfer. Throws a Safe\Exceptions\CurlException instead of returning false on failure.

### Method
Function call

### Endpoint
`curl_getinfo(\CurlHandle $handle, ?int $option = null)`

### Parameters
- **handle** (\CurlHandle) - Required - cURL handle
- **option** (int|null) - Optional - `CURLINFO_*` constant; `null` returns the whole info array, otherwise that single value

### Request Example
```php
use function Safe\curl_init, Safe\curl_setopt, Safe\curl_exec, Safe\curl_getinfo;

$ch = curl_init('https://example.com');
curl_setopt($ch, CURLOPT_HEADER, true);
$body = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
```

### Response
#### Success Response
- **Returns:** `mixed` (docblock `@return mixed`)

#### Error Handling
- **Throws:** `Safe\Exceptions\CurlException` (with handle context)
```

--------------------------------

### base64_decode() usage example

Source: https://github.com/thecodingmachine/safe/blob/master/_autodocs/api-reference/url.md

Decodes a base64 token in strict mode. Throws UrlException on invalid characters.

```php
use function Safe\base64_decode;

$payload = base64_decode($token, true);
```

--------------------------------

### sys_getloadavg()

Source: https://github.com/thecodingmachine/safe/blob/master/_autodocs/api-reference/special-cases.md

Returns three system load average samples (over the last 1, 5, and 15 minutes). Throws a Safe\Exceptions\MiscException when the native call fails.

```APIDOC
## `sys_getloadavg()`

### Description
Returns three system load average samples (over the last 1, 5, and 15 minutes). Throws a Safe\Exceptions\MiscException when the native call fails.

### Method
`sys_getloadavg()`

### Signature
```php
function sys_getloadavg(): array
```

### Returns
- **Type:** `array<int, float>` — three samples (load over the last 1, 5 and 15 minutes).

### Throws
- `Safe\Exceptions\MiscException` when the native call returns `false`.

### Import Path
`use function Safe\sys_getloadavg;`

### Example
```php
use function Safe\sys_getloadavg;

[$load1, $load5, $load15] = sys_getloadavg();
```
```

--------------------------------

### array_walk_recursive() usage example

Source: https://github.com/thecodingmachine/safe/blob/master/_autodocs/api-reference/array.md

Imports and uses Safe\array_walk_recursive to sum all leaf values in a nested array.

```php
use function Safe\array_walk_recursive;

$total = 0;
array_walk_recursive($nested, function ($v) use (&$total) { $total += $v; });
```

--------------------------------

### lchown(string $filename, $user): void

Source: https://github.com/thecodingmachine/safe/blob/master/_autodocs/api-reference/filesystem.md

Changes owner of symlink. Throws FilesystemException on failure.

```APIDOC
## lchown(string $filename, $user): void

### Description
Changes owner of symlink. Throws FilesystemException on failure.

### Method
Function call

### Signature
`lchown(string $filename, $user): void`

### Parameters
- `$filename` (string) - Required - The path to the symlink.
- `$user` (int|string) - Required - The user name or number.

### Return Value
void

### Exceptions
Throws `Safe\Exceptions\FilesystemException` on failure.
```

--------------------------------

### array_combine() usage example

Source: https://github.com/thecodingmachine/safe/blob/master/_autodocs/api-reference/array.md

Imports and uses Safe\array_combine to combine keys and values into an associative array.

```php
use function Safe\array_combine;

$map = array_combine(['id', 'name'], [1, 'widget']);
```

--------------------------------

### tempnam(string $directory, string $prefix): string

Source: https://github.com/thecodingmachine/safe/blob/master/_autodocs/api-reference/filesystem.md

Safely wraps the native tempnam() function. Creates a file with a unique filename in the specified directory and returns the path as a non-falsy string, or throws a FilesystemException when the native call fails.

```APIDOC
## tempnam(string $directory, string $prefix): string

### Description
Safely wraps the native tempnam() function. Creates a file with a unique filename in the specified directory and returns the path as a non-falsy string, or throws a FilesystemException when the native call fails.

### Method
Function call

### Endpoint
`Safe\tempnam()`

### Parameters
- **directory** (string) - Required - Directory for the temp file
- **prefix** (string) - Required - Prefix for the temp file name

### Returns
- **string** - Non-falsy string representing the path to the created temp file

### Throws
- `FilesystemException` when the native call returns `false`

```

--------------------------------

### date() basic usage

Source: https://github.com/thecodingmachine/safe/blob/master/_autodocs/api-reference/datetime-functions.md

Example of using Safe\date() to format a timestamp from strtotime('+1 day').

```php
use function Safe\date;

echo date('Y-m-d', strtotime('+1 day'));
```

--------------------------------

### parse_ini_string(string $ini_string, bool $process_sections = false, int $scanner_mode = INI_SCANNER_NORMAL): array

Source: https://github.com/thecodingmachine/safe/blob/master/_autodocs/api-reference/filesystem.md

Parses a configuration string. Throws FilesystemException on failure.

```APIDOC
## parse_ini_string(string $ini_string, bool $process_sections = false, int $scanner_mode = INI_SCANNER_NORMAL): array

### Description
Parses a configuration string. Throws FilesystemException on failure.

### Method
Function call

### Signature
`parse_ini_string(string $ini_string, bool $process_sections = false, int $scanner_mode = INI_SCANNER_NORMAL): array`

### Parameters
- `$ini_string` (string) - Required - The INI string.
- `$process_sections` (bool) - Optional - Whether to process sections.
- `$scanner_mode` (int) - Optional - Scanner mode (e.g., INI_SCANNER_NORMAL).

### Return Value
array - INI config.

### Exceptions
Throws `Safe\Exceptions\FilesystemException` on failure.
```

--------------------------------

### stream_socket_get_name($handle, bool $want_peer): string

Source: https://github.com/thecodingmachine/safe/blob/master/_autodocs/api-reference/stream.md

Gets the name of a socket. Throws StreamException on failure.

```APIDOC
## stream_socket_get_name($handle, bool $want_peer): string

### Description
Gets the name of a socket. Throws StreamException on failure.

### Method
Function call

### Signature
`stream_socket_get_name($handle, bool $want_peer): string`

### Parameters
- `$handle` (resource) - Required - The socket resource.
- `$want_peer` (bool) - Required - Whether to get the peer name (true) or local name (false).

### Return Value
string - The socket name.

### Exceptions
Throws `Safe\Exceptions\StreamException` when the native call returns `false`.
```

--------------------------------

### Safe\DateTime::setDate() usage example

Source: https://github.com/thecodingmachine/safe/blob/master/_autodocs/api-reference/datetime-class.md

Sets the date to February 29, 2025. Overflows like the core class.

```php
use Safe\DateTime;

$d = (new DateTime('now'))->setDate(2025, 2, 29); // overflows like the core class
```

--------------------------------

### ftp_raw()

Source: https://github.com/thecodingmachine/safe/blob/master/_autodocs/api-reference/special-cases.md

Executes an arbitrary FTP command and returns the server's response lines without parsing. Throws an FtpException if the native result is null.

```APIDOC
## `ftp_raw()`

### Description
Executes an arbitrary FTP command and returns the server's response lines without parsing. Throws an FtpException if the native result is null.

### Method
`ftp_raw`

### Signature
```php
function ftp_raw(\FTP\Connection $ftp, string $command): array
```

### Parameters
- **ftp** (\FTP\Connection) - Required - FTP connection returned by `ftp_connect()`
- **command** (string) - Required - The command to execute

### Returns
- **array** (`string[]` per `@phpstan-return`) - the server's response lines; no parsing is performed.

### Throws
- `Safe\Exceptions\FtpException` when the native result is `null`.

### Import path
`use function Safe\ftp_raw;`
```

--------------------------------

### strtotime() exception handling

Source: https://github.com/thecodingmachine/safe/blob/master/_autodocs/api-reference/datetime-functions.md

Example of catching Safe\Exceptions\DatetimeException when strtotime() fails to parse an invalid date string.

```php
use function Safe\strtotime;
use Safe\Exceptions\DatetimeException;

try {
    strtotime('not a date at all');
} catch (DatetimeException $e) {
    // parse failure
}
```

--------------------------------

### session_name(?string $name = null): string

Source: https://github.com/thecodingmachine/safe/blob/master/_autodocs/api-reference/session.md

Gets or sets the session name. Throws SessionException on failure.

```APIDOC
## session_name(?string $name = null): string

### Description
Gets or sets the session name. Throws SessionException on failure.

### Method
session_name

### Signature
`session_name(?string $name = null): string`

### Parameters
- **$name** (?string) - Optional - The session name to set. If null, returns current name.

### Return Value
string (non-falsy-string) - The current session name.

### Exceptions
`Safe\Exceptions\SessionException`
```
Tokens:
Raw