Nette Utils

https://github.com/nette/utils
Admin
Nette Utils is a lightweight PHP utility library providing tools for string and array manipulation,...
Tokens:194,792
Snippets:1,484
Trust Score:9.4
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### compare usage examples

Source: https://github.com/nette/utils/blob/master/_autodocs/api-reference/strings.md

Examples of Strings::compare() with full comparison and with length limit.

```php
Strings::compare('ŽLUŤOUČKÝ', 'žluťoučký');       // true
Strings::compare('abcdef', 'abXdef', 2);          // true
```

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

### webalize usage examples

Source: https://github.com/nette/utils/blob/master/_autodocs/api-reference/strings.md

Examples of Strings::webalize() with default settings and with custom charlist and lower=false.

```php
Strings::webalize('Žluťoučký kůň!');  // 'zlutoucky-kun'
Strings::webalize('a b', '.', false); // 'a-b'
```

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

### fromFile usage examples

Source: https://github.com/nette/utils/blob/master/_autodocs/api-reference/image.md

Shows how to call Image::fromFile with and without the $warnings parameter. The first example retrieves the image type, the second collects decoder warnings, and the third demonstrates catching UnknownImageFileException for a missing file.

```php
$img = Image::fromFile('photo.jpg', $type);
// $type === ImageType::JPEG

$img = Image::fromFile('broken.png', $type, $warnings);
// $warnings null or comma-joined decoder warnings, never raised as PHP warnings
try {
	Image::fromFile('missing.jpg');
} catch (Nette\Utils\UnknownImageFileException $e) { }
```

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

### upper / firstUpper / capitalize usage examples

Source: https://github.com/nette/utils/blob/master/_autodocs/api-reference/strings.md

Examples of Strings::upper(), Strings::firstUpper(), and Strings::capitalize() showing their output.

```php
Strings::upper('žluťoučký');        // 'ŽLUŤOUČKÝ'
Strings::firstUpper('hello');       // 'Hello'
Strings::capitalize('hello world'); // 'Hello World'
```

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

### trim usage examples

Source: https://github.com/nette/utils/blob/master/_autodocs/api-reference/strings.md

Two examples showing default trimming of spaces and custom character trimming with 'x'.

```php
Strings::trim('  Hello  ');            // 'Hello'
Strings::trim('xxHelloxx', 'x');       // 'Hello'
```

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

### wrap usage example

Source: https://github.com/nette/utils/blob/master/_autodocs/api-reference/arrays.md

Example of Arrays::wrap wrapping each item with '<' and '>', producing ['<a>', '<b>'].

```php
Arrays::wrap(['a', 'b'], '<', '>'); // ['<a>', '<b>']
```

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

### runExecutable usage example

Source: https://github.com/nette/utils/blob/master/_autodocs/api-reference/process.md

Runs /usr/bin/php with -v argument, ensures success, and prints the captured standard output.

```php
$p = Process::runExecutable('/usr/bin/php', ['-v']);
$p->ensureSuccess();
echo $p->getStdOutput();
```

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

### substring usage examples

Source: https://github.com/nette/utils/blob/master/_autodocs/api-reference/strings.md

Examples of Strings::substring() with positive and negative start offsets. The first returns characters from index 6 to the end; the second counts 5 characters from the end.

```php
Strings::substring('Hello world', 6);      // 'world'
Strings::substring('Hello world', -5);     // 'world'
```

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

### wait() usage example

Source: https://github.com/nette/utils/blob/master/_autodocs/api-reference/process.md

Shows how to pass a callback to wait() that writes each stdout chunk to STDOUT.

```php
$p->wait(fn(string $out, string $err) => fwrite(STDOUT, $out));
```

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

### toReflection usage examples

Source: https://github.com/nette/utils/blob/master/_autodocs/api-reference/callback.md

Examples of getting reflection for a function and a method. 'strlen' returns ReflectionFunction, and an array with an object and method returns ReflectionMethod.

```php
$ref = Callback::toReflection('strlen');   // ReflectionFunction
$ref = Callback::toReflection([$obj, 'go']);  // ReflectionMethod
```

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

### insertAfter usage example

Source: https://github.com/nette/utils/blob/master/_autodocs/api-reference/arrays.md

Example showing insertion of ['x'] after key 'a' in ['a', 'b'], resulting in ['a', 'x', 'b'].

```php
Arrays::insertAfter(['a', 'b'], 'a', ['x']); // ['a', 'x', 'b']
```

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

### findPrefix usage example

Source: https://github.com/nette/utils/blob/master/_autodocs/api-reference/strings.md

Example of Strings::findPrefix() returning the common prefix of two strings.

```php
Strings::findPrefix(['prefix-a', 'prefix-b']); // 'prefix-'
```

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

### __call attribute shorthand usage example

Source: https://github.com/nette/utils/blob/master/_autodocs/api-reference/html.md

Demonstrates using the shorthand methods to set, get, and add attributes.

```php
$el->class('foo');          // set attribute
$el->setClass('foo');       // same
$el->getClass();            // 'foo'
$el->addClass('bar', true); // multi-value attribute
```

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

### Output usage examples

Source: https://github.com/nette/utils/blob/master/_autodocs/api-reference/image.md

Shows saving to PNG and JPEG, converting to a binary string, and sending WEBP to the browser.

```php
$img->save('out.png');                       // PNG, quality 9
$img->save('out.jpg', quality: 90);
$jpeg = $img->toString(Image::JPEG, 85);     // binary string
$img->send(Image::WEBP);                     // to the browser
```

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

### Process::runExecutable

Source: https://github.com/nette/utils/blob/master/_autodocs/api-reference/process.md

Starts an executable with given arguments as an array, avoiding shell involvement and injection risks. Returns a Process instance for further interaction.

```APIDOC
## Process::runExecutable

### Description
Starts an executable with given arguments. Because arguments are passed as an array, the shell is never involved, so they need no escaping and there is no risk of shell injection.

### Method
static

### Signature
```php
public static function runExecutable(
	string $executable,
	array $arguments = [],
	?array $env = null,
	array $options = [],
	mixed $stdin = '',
	mixed $stdout = null,
	mixed $stderr = null,
	?string $directory = null,
	?float $timeout = self::DefaultTimeout,
): self
```

### Parameters
- **$executable** (string) - Required - Path to the executable binary.
- **$arguments** (list<string>) - Optional - Arguments passed to the executable.
- **$env** (string[]|null) - Optional - Environment variables or null to use the same environment as the current process.
- **$options** (array<string, mixed>) - Optional - Options for proc_open(); on Windows the executable is launched directly, without cmd.exe.
- **$stdin** (mixed) - Optional - Input: string, a readable resource (its content is copied to STDIN), a Process (its STDOUT is piped in), or null (STDIN stays open for writeStdInput()).
- **$stdout** (mixed) - Optional - Output target: string filename, a writable resource backed by a real OS file descriptor (not php://memory etc.), false to discard, or null to capture into memory.
- **$stderr** (mixed) - Optional - Error output target (same options as $stdout).
- **$directory** (string|null) - Optional - Working directory.
- **$timeout** (float|null) - Optional - Time limit in seconds, checked while waiting for or reading the process; null disables it.

### Return Value
- **self** - A Process instance.

### Example
```php
$p = Process::runExecutable('/usr/bin/php', ['-v']);
$p->ensureSuccess();
echo $p->getStdOutput();
```
```

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

### Writing to process STDIN with writeStdInput and closeStdInput

Source: https://github.com/nette/utils/blob/master/_autodocs/api-reference/process.md

Starts a process with an open STDIN pipe (stdin: null), writes input, then closes the pipe to signal EOF. The example expects the child to output 'one foo\n' after processing the input.

```php
$p = Process::runExecutable('grep', ['foo'], stdin: null);
$p->writeStdInput("one foo\ntwo\n");
$p->closeStdInput();
echo $p->getStdOutput();   // "one foo\n"
```

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

### Process::runCommand

Source: https://github.com/nette/utils/blob/master/_autodocs/api-reference/process.md

Starts a process from a command string interpreted by the shell (/bin/sh on POSIX, cmd.exe on Windows). Returns a Process instance for further interaction.

```APIDOC
## Process::runCommand

### Description
Starts a process from a command string interpreted by the shell (/bin/sh on POSIX, cmd.exe on Windows). Because the shell parses the string, NEVER pass unescaped user input here - use runExecutable() for that.

### Method
static

### Signature
```php
public static function runCommand(
	string $command,
	?array $env = null,
	array $options = [],
	mixed $stdin = '',
	mixed $stdout = null,
	mixed $stderr = null,
	?string $directory = null,
	?float $timeout = self::DefaultTimeout,
): self
```

### Parameters
- **$command** (string) - Required - Shell command to run.
- **$env** (string[]|null) - Optional - Environment variables or null to use the same environment as the current process.
- **$options** (array<string, mixed>) - Optional - Options for proc_open(), e.g. ['bypass_shell' => true] on Windows to skip cmd.exe.
- **$stdin** (mixed) - Optional - Input: string, a readable resource (its content is copied to STDIN), a Process (its STDOUT is piped in), or null (STDIN stays open for writeStdInput()).
- **$stdout** (mixed) - Optional - Output target: string filename, a writable resource backed by a real OS file descriptor (not php://memory etc.), false to discard, or null to capture into memory.
- **$stderr** (mixed) - Optional - Error output target (same options as $stdout).
- **$directory** (string|null) - Optional - Working directory.
- **$timeout** (float|null) - Optional - Time limit in seconds, checked while waiting for or reading the process; null disables it.

### Return Value
- **self** - A Process instance.

### Example
```php
$p = Process::runCommand('echo hello && echo err >&2');
$p->wait();
echo $p->getStdOutput();  // "hello\n"
echo $p->getStdError();   // "err\n"
```
```

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

### associate usage examples

Source: https://github.com/nette/utils/blob/master/_autodocs/api-reference/arrays.md

Demonstrates building an associative tree from rows. The first example groups by 'id', the second creates a nested structure with 'id|name'.

```php
$rows = [['id' => 1, 'name' => 'a'], ['id' => 2, 'name' => 'b']];
Arrays::associate($rows, 'id');                    // [1 => ['id'=>1,'name'=>'a'], 2 => [...]]
Arrays::associate($rows, 'id|name');               // [1 => 'a', 2 => 'b']
```

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

### toKey usage example

Source: https://github.com/nette/utils/blob/master/_autodocs/api-reference/arrays.md

Examples of Arrays::toKey converting 'name' to 'name' and true to 1.

```php
Arrays::toKey('name');   // 'name'
Arrays::toKey(true);     // 1
```

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

### createDir usage example

Source: https://github.com/nette/utils/blob/master/_autodocs/api-reference/filesystem.md

Creates a directory with mode 0o750. No error if it already exists.

```php
FileSystem::createDir('/tmp/app/cache', 0o750);
```

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

### create usage example

Source: https://github.com/nette/utils/blob/master/_autodocs/api-reference/html.md

Creates a new 'li' element, appends it to the parent, and sets its text content.

```php
$ul->create('li')->setText('One');
```

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

### indent usage examples

Source: https://github.com/nette/utils/blob/master/_autodocs/api-reference/strings.md

Examples of Strings::indent() with default tab characters and with custom space character.

```php
Strings::indent("a\nb", 2);        // "\t\ta\n\t\tb"
Strings::indent("a", 1, ' ');      // ' a'
```

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

### open usage example

Source: https://github.com/nette/utils/blob/master/_autodocs/api-reference/filesystem.md

Opens a file in append mode using FileSystem::open.

```php
$f = FileSystem::open('/tmp/data.log', 'a');
```

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

### Strings::split() usage examples

Source: https://github.com/nette/utils/blob/master/_autodocs/api-reference/strings.md

Demonstrates splitting by a delimiter pattern and by a hyphen pattern, returning arrays of the split parts.

```php
$parts = Strings::split('a,b;c', '#[,;]#');        // ['a', 'b', 'c']
$parts = Strings::split('2024-01-05', '#-#');      // ['2024', '01', '05']
```

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

### insertBefore usage example

Source: https://github.com/nette/utils/blob/master/_autodocs/api-reference/arrays.md

Example showing insertion of ['x'] before key 'b' in ['a', 'b'], resulting in ['a', 'x', 'b'].

```php
Arrays::insertBefore(['a', 'b'], 'b', ['x']); // ['a', 'x', 'b']
```

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

### length usage example

Source: https://github.com/nette/utils/blob/master/_autodocs/api-reference/strings.md

Example counting characters in a Czech word, returning 10.

```php
Strings::length("žluťoučký"); // 10
```

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

### runCommand usage example

Source: https://github.com/nette/utils/blob/master/_autodocs/api-reference/process.md

Runs a shell command that echoes to stdout and stderr, waits for completion, and prints the captured outputs.

```php
$p = Process::runCommand('echo hello && echo err >&2');
$p->wait();
echo $p->getStdOutput();  // "hello\n"
echo $p->getStdError();   // "err\n"
```

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

### render usage example

Source: https://github.com/nette/utils/blob/master/_autodocs/api-reference/html.md

Example of rendering an HTML element with a child element using the render method.

```php
echo Html::el('ul')->add(Html::el('li')->setText('a'))->render(0);
```

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

### toString usage examples

Source: https://github.com/nette/utils/blob/master/_autodocs/api-reference/callback.md

Examples of converting callables to strings. 'strlen' stays as is, and an array with an object and method name becomes 'ClassName::m'.

```php
Callback::toString('strlen');                    // 'strlen'
Callback::toString([$obj, 'm']);                 // 'ClassName::m'
```

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

### unwrap usage example

Source: https://github.com/nette/utils/blob/master/_autodocs/api-reference/callback.md

Example of unwrapping a closure created from 'strlen' back to the string 'strlen'.

```php
$c = Closure::fromCallable('strlen');
Callback::unwrap($c);          // 'strlen'
```

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

### data usage example

Source: https://github.com/nette/utils/blob/master/_autodocs/api-reference/html.md

Demonstrates setting a data attribute with a value and then setting the plain data attribute.

```php
$el->data('id', 42)->data('role');   // data-id="42" data="role"
```

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

### encode usage examples

Source: https://github.com/nette/utils/blob/master/_autodocs/api-reference/json.md

Examples of Json::encode with different options: default unicode output, asciiSafe, pretty, htmlSafe with forceObjects, and error handling for invalid UTF-8.

```php
Json::encode(['name' => 'Žluť']);                    // {"name":"Žluť"} — unicode + slashes unescaped
Json::encode(['name' => 'Žluť'], asciiSafe: true);     // {"name":"\u017dlu\u0165"}
Json::encode([1, 2], pretty: true);
Json::encode(['x' => 1], htmlSafe: true, forceObjects: true);
try {
	Json::encode("\xB1\x31");                        // invalid UTF-8
} catch (Nette\Utils\JsonException $e) {
	// 'Malformed UTF-8 characters, possibly incorrectly encoded'
}
```

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

### Strings::matchAll() usage examples

Source: https://github.com/nette/utils/blob/master/_autodocs/api-reference/strings.md

Shows retrieving all matches as an array and iterating lazily over matches with a Generator.

```php
$m = Strings::matchAll('a1 b2', '#([a-z])(\d)#');    // [['a1','a','1'], ['b2','b','2']]
foreach (Strings::matchAll('a1 b2', '#[\w]+#', lazy: true) as $match) { ... }
```

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

### isStatic usage examples

Source: https://github.com/nette/utils/blob/master/_autodocs/api-reference/callback.md

Examples of checking static callbacks. 'strlen' is static, while an array with an object is not.

```php
Callback::isStatic('strlen');              // true
Callback::isStatic([$obj, 'm']);           // false
```

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

### invokeSafe usage example

Source: https://github.com/nette/utils/blob/master/_autodocs/api-reference/callback.md

Example of invoking file_get_contents safely with a custom error handler that throws an exception. This is the escalation mechanism behind FileSystem, Image, and Process failures.

```php
$res = Callback::invokeSafe('file_get_contents', ['/tmp/x'], function ($msg) {
	throw new Nette\IOException($msg);
});
```

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

### Children access usage examples

Source: https://github.com/nette/utils/blob/master/_autodocs/api-reference/html.md

Shows accessing the first child, counting children, and iterating over children.

```php
$el[0];            // first child
count($el);        // number of children
foreach ($el as $child) { ... }
```

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

### delete usage example

Source: https://github.com/nette/utils/blob/master/_autodocs/api-reference/filesystem.md

Recursively deletes the given directory. Throws Nette\IOException on failure.

```php
FileSystem::delete('/tmp/app/cache');   // recursive!
```

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

### grep usage examples

Source: https://github.com/nette/utils/blob/master/_autodocs/api-reference/arrays.md

Shows how to filter arrays with grep. The first example returns items matching the digit pattern, the second inverts the match to exclude items containing '1'.

```php
Arrays::grep(['a1', 'b2', 'x'], '#\d#');                    // ['a1', 'b2']
Arrays::grep(['a1', 'b2', 'x'], '#1#', invert: true);     // ['b2', 'x']
```

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

### href usage example

Source: https://github.com/nette/utils/blob/master/_autodocs/api-reference/html.md

Shows setting an href with a query string, resulting in a URL-encoded query.

```php
$el->href('/page', ['id' => 5, 'x' => 'a b']); // href="/page?id=5&x=a+b"
```

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

### fromString usage example

Source: https://github.com/nette/utils/blob/master/_autodocs/api-reference/image.md

Loads an image from a binary string variable.

```php
$img = Image::fromString($binaryData);
```

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

### Install via Composer

Source: https://github.com/nette/utils/blob/master/readme.md

Use this command to install the nette/utils package via Composer. The package is compatible with PHP 8.2 to 8.6.

```bash
composer require nette/utils
```

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

### check usage examples

Source: https://github.com/nette/utils/blob/master/_autodocs/api-reference/callback.md

Examples of validating callables. 'strlen' passes, a nonexistent class method throws, and syntax-only mode accepts 'Foo::bar' without checking existence.

```php
$fn = Callback::check('strlen');                      // 'strlen'
Callback::check('Nonexistent\\Foo::bar');            // Nette\InvalidArgumentException
Callback::check('Foo::bar', syntax: true);           // ok — only syntax
```

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

### FileSystem::rename() usage example

Source: https://github.com/nette/utils/blob/master/_autodocs/api-reference/filesystem.md

Moves a file from /tmp/old.log to /var/log/new.log using the default overwrite behavior.

```php
FileSystem::rename('/tmp/old.log', '/var/log/new.log');
```

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

### isList usage examples

Source: https://github.com/nette/utils/blob/master/_autodocs/api-reference/arrays.md

Shows how to check if a value is a list. The first example returns true, the second and third return false.

```php
Arrays::isList(['a', 'b']);       // true
Arrays::isList(['a' => 1]);       // false
Arrays::isList('abc');            // false
```

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

### invoke usage example

Source: https://github.com/nette/utils/blob/master/_autodocs/api-reference/arrays.md

Example of Arrays::invoke with two callbacks and argument 5, producing [6, 10].

```php
Arrays::invoke([fn($x) => $x + 1, fn($x) => $x * 2], 5); // [6, 10]
```

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

### Arrays::first and Arrays::last usage examples

Source: https://github.com/nette/utils/blob/master/_autodocs/api-reference/arrays.md

Shows how to call first() and last() with and without a predicate. The last example uses the $else callback to return -1 when no item matches.

```php
Arrays::first([3, 1, 2]);                                  // 3
Arrays::first([3, 1, 2], fn($v) => $v > 1);                // 3
Arrays::last([3, 1, 2], predicate: fn($v) => $v > 1);      // 2
Arrays::first([1], predicate: fn($v) => $v > 5, else: fn() => -1); // -1
```

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

### Helpers::getSuggestion usage examples

Source: https://github.com/nette/utils/blob/master/_autodocs/api-reference/helpers.md

Returns the string from possibilities most similar to the value by Levenshtein distance, or null when none is close enough. The examples show a successful suggestion and a null result.

```php
Helpers::getSuggestion(['name', 'email'], 'emial'); // 'email'
Helpers::getSuggestion(['name'], 'xxxxxx');         // null
```

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

### Strings::replace() usage examples

Source: https://github.com/nette/utils/blob/master/_autodocs/api-reference/strings.md

Shows simple character replacement, a pattern map, and a callable replacement using captured groups.

```php
Strings::replace('hello world', '#o#', '0');                 // 'hell0 w0rld'
Strings::replace('a-b-c', ['#-#' => ':', '#a#' => 'A']);     // 'A:b:c'
Strings::replace('2024-05-01', '#(\d+)-(\d+)-(\d+)#', fn($m) => "$m[3]/$m[2]/$m[1]");
```

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

### expandClassName usage examples

Source: https://github.com/nette/utils/blob/master/_autodocs/api-reference/reflection.md

Shows expansion of a built-in type and a relative class name. The second example's comment indicates the expected result for a class in the App\Models namespace.

```php
Reflection::expandClassName('DateTime', $reflectionClass);        // 'DateTime'
Reflection::expandClassName('Bar', new ReflectionClass(Foo::class)); // e.g. 'App\Models\Bar'
```

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

### exclude() usage examples

Source: https://github.com/nette/utils/blob/master/_autodocs/api-reference/finder.md

Shows three ways to use exclude(): excluding named directories, excluding directories with a trailing slash, and keeping the directory while dropping its contents with 'cache/*'. All examples use Finder::findFiles() with from('.') and demonstrate the trailing marker behavior.

```php
Finder::findFiles('*.php')->from('.')->exclude('temp', 'vendor');
Finder::findFiles('*')->from('.')->exclude('cache/');        // exclude cache dirs
Finder::findFiles('*')->from('.')->exclude('cache/*');       // keep the dir, drop contents
```

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

### ord usage example

Source: https://github.com/nette/utils/blob/master/_autodocs/api-reference/strings.md

Example getting the code point of the emoji 😀, which is 128512.

```php
$cp = Strings::ord('😀'); // 128512
```

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

### Image sharpen and place usage example

Source: https://github.com/nette/utils/blob/master/_autodocs/api-reference/image.md

Applies sharpening and places a watermark image at 50% left/top with 70% opacity.

```php
$img->sharpen();
$img->place($watermark, '50%', '50%', 70);
```

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

### FileSystem::joinPaths() and resolvePath() usage examples

Source: https://github.com/nette/utils/blob/master/_autodocs/api-reference/filesystem.md

joinPaths concatenates paths; resolvePath resolves relative paths against a base.

```php
FileSystem::joinPaths('/a', 'b', 'c');          // '/a/b/c'
FileSystem::resolvePath('/base', './x');        // '/base/x'
```

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

### before / after usage examples

Source: https://github.com/nette/utils/blob/master/_autodocs/api-reference/strings.md

Shows how to use before and after with different nth values. before('a-b-c', '-') returns 'a', after('a-b-c', '-', 2) returns 'c', and before('abc', 'x') returns null.

```php
Strings::before('a-b-c', '-');    // 'a'
Strings::after('a-b-c', '-', 2);  // 'c'
Strings::before('abc', 'x');      // null
```

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

### Blocking getter usage example

Source: https://github.com/nette/utils/blob/master/_autodocs/api-reference/process.md

Shows how to check success with isSuccess() and catch the ProcessFailedException thrown by ensureSuccess() when the exit code is non-zero.

```php
$p = Process::runExecutable('/bin/true');
$p->isSuccess();                    // true

try {
	Process::runExecutable('/bin/false')->ensureSuccess();
} catch (Nette\Utils\ProcessFailedException $e) { }
```

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

### normalize usage example

Source: https://github.com/nette/utils/blob/master/_autodocs/api-reference/arrays.md

Shows how to normalize an array. The first item 'a' gets the default null value, while 'b' keeps its value.

```php
Arrays::normalize(['a', 'b' => 2]);                  // ['a' => null, 'b' => 2]
```

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

### indexOf usage example

Source: https://github.com/nette/utils/blob/master/_autodocs/api-reference/strings.md

Shows how to use indexOf to get the character position of a needle. Strings::indexOf('žluťoučký', 'u') returns 2.

```php
Strings::indexOf('žluťoučký', 'u'); // 2
```

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

### getMethodDeclaringMethod usage example

Source: https://github.com/nette/utils/blob/master/_autodocs/api-reference/reflection.md

Shows how to obtain the declaring method for a reflection method.

```php
$m = Reflection::getMethodDeclaringMethod($reflectionMethod);
```

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

### Iterating Finder results with FileInfo

Source: https://github.com/nette/utils/blob/master/_autodocs/api-reference/filesystem.md

Example of using FileInfo methods like getRelativePathname() and read() while iterating over Finder results.

```php
foreach (Finder::findFiles('*.log')->from('/var/log') as $file) {
	echo $file->getRelativePathname();   // e.g. 'app/error.log'
	$content = $file->read();
}
```

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

### decode usage examples

Source: https://github.com/nette/utils/blob/master/_autodocs/api-reference/json.md

Examples of Json::decode: default returns stdClass, forceArrays returns array, large integers become strings, and error handling for invalid JSON.

```php
$obj = Json::decode('{"a":1}');          // stdClass { a: 1 }
$arr = Json::decode('{"a":1}', true);    // ['a' => 1]
Json::decode('12345678901234567890');    // '12345678901234567890' (string)
try {
	Json::decode('{invalid');
} catch (Nette\Utils\JsonException $e) {
	// 'Syntax error'
}
```

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

### runCommand method signature

Source: https://github.com/nette/utils/blob/master/_autodocs/api-reference/process.md

Starts a process from a shell command string interpreted by /bin/sh on POSIX or cmd.exe on Windows. Never pass unescaped user input; use runExecutable() instead.

```php
/**
 * Starts a process from a command string interpreted by the shell (/bin/sh on POSIX, cmd.exe on Windows).
 * Because the shell parses the string, NEVER pass unescaped user input here - use runExecutable() for that.
 * @param  string         $command    Shell command to run.
 * @param  string[]|null  $env        Environment variables or null to use the same environment as the current process.
 * @param  array<string, mixed>  $options  Options for proc_open(), e.g. ['bypass_shell' => true] on Windows to skip cmd.exe.
 * @param  mixed          $stdin      ... (same as runExecutable)
 * @param  mixed          $stdout     ...
 * @param  mixed          $stderr     ...
 * @param  string|null    $directory  Working directory.
 * @param  float|null     $timeout    Time limit in seconds ...; null disables it.
 */
public static function runCommand(
	string $command,
	?array $env = null,
	array $options = [],
	mixed $stdin = '',
	mixed $stdout = null,
	mixed $stderr = null,
	?string $directory = null,
	?float $timeout = self::DefaultTimeout,
): self
```

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

### Strings::match() usage examples

Source: https://github.com/nette/utils/blob/master/_autodocs/api-reference/strings.md

Shows matching a pattern with a captured group and returning null when no match is found.

```php
$m = Strings::match('pi=3.14', '#pi=([\d.]+)#');  // ['pi=3.14', '3.14']
$m = Strings::match('abc', '#\d+#');              // null
```

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

### Image::calculateTextBox usage example

Source: https://github.com/nette/utils/blob/master/_autodocs/api-reference/image.md

Calls calculateTextBox with sample text, font file, and size to obtain the bounding box.

```php
$box = Image::calculateTextBox('Hello', '/fonts/arial.ttf', 12);
```

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

### FileSystem::normalizePath() usage example

Source: https://github.com/nette/utils/blob/master/_autodocs/api-reference/filesystem.md

Returns normalized path with resolved . and .. segments.

```php
FileSystem::normalizePath('/a/./b/../c'); // '/a/c' (or '\a\c' on Windows)
```

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

### SmartObject event dispatch and strict call example

Source: https://github.com/nette/utils/blob/master/_autodocs/api-reference/smartobject.md

Demonstrates event dispatch via $onStart and strict method calls. Calling an undefined method throws MemberAccessException with a 'did you mean' hint.

```php
class Car {
	use Nette\SmartObject;
	/** @var array<callable> */
	public $onStart = [];
}
$car = new Car;
$car->onStart(function () { echo "vroom"; });   // event dispatch
$car->onStart();                                 // runs handlers

$car->nonsense();    // Nette\MemberAccessException: Call to undefined method Car::nonsense(), did you mean onStart()?
```

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

### invokeMethod usage example

Source: https://github.com/nette/utils/blob/master/_autodocs/api-reference/arrays.md

Example of Arrays::invokeMethod calling 'getName' on two objects.

```php
Arrays::invokeMethod([$obj1, $obj2], 'getName');
```

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

### setAttribute / getAttribute / removeAttribute usage example

Source: https://github.com/nette/utils/blob/master/_autodocs/api-reference/html.md

Shows setting an attribute, retrieving it, and then removing it.

```php
$el->setAttribute('title', 'Hi');
$t = $el->getAttribute('title');   // 'Hi'
$el->removeAttribute('title');
```

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

### GD passthrough usage examples

Source: https://github.com/nette/utils/blob/master/_autodocs/api-reference/image.md

Demonstrates calling GD functions via the __call passthrough, with ImageColor arguments resolved automatically.

```php
$img->rotate(45, ImageColor::rgb(255, 255, 255));
$img->filledEllipse(50, 50, 80, 80, ImageColor::hex('#f00'));
$img->setPixel(0, 0, ImageColor::rgb(0, 0, 0));
```

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

### toAscii usage example

Source: https://github.com/nette/utils/blob/master/_autodocs/api-reference/strings.md

Example of Strings::toAscii() converting accented characters to ASCII equivalents.

```php
Strings::toAscii('Žluťoučký kůň'); // 'Zlutoucky kun'
```

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

### chr usage example

Source: https://github.com/nette/utils/blob/master/_autodocs/api-reference/strings.md

Example converting the code point 0x1F600 to the emoji character 😀.

```php
echo Strings::chr(0x1F600); // 😀
```

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

### FileSystem::write

Source: https://github.com/nette/utils/blob/master/_autodocs/api-reference/filesystem.md

Writes content to a file, creating parent directories and setting permissions. Throws Nette\IOException on error.

```APIDOC
## FileSystem::write

### Description
Writes content to a file, creating parent directories and setting permissions. Throws Nette\IOException on error.

### Method
`public static function write(string $file, string $content, ?int $mode = 0o666): void`

### Parameters
- **$file** (string) - Required - Path to the file to write.
- **$content** (string) - Required - Content to write.
- **$mode** (?int) - Optional - File permissions (octal). Defaults to 0o666. If null, chmod is skipped.

### Exceptions
- **Nette\IOException** - On error occurred.

### Example
```php
FileSystem::write('/tmp/x.txt', "hello\n");                     // mode 0666
FileSystem::write('/tmp/x.txt', "hello\n", 0o600);
```
```

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

### pick usage examples

Source: https://github.com/nette/utils/blob/master/_autodocs/api-reference/arrays.md

Demonstrates picking items. The first call removes 'a' and returns 1, the second returns the default 0 for missing key 'z'.

```php
$arr = ['a' => 1, 'b' => 2];
Arrays::pick($arr, 'a');        // 1; $arr === ['b' => 2]
Arrays::pick($arr, 'z', 0);     // 0
```

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

### FileSystem::readLines() usage example

Source: https://github.com/nette/utils/blob/master/_autodocs/api-reference/filesystem.md

Iterates over lines of a file using the lazy generator returned by readLines().

```php
foreach (FileSystem::readLines('/tmp/big.csv') as $i => $line) {
	...
}
```

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

### fromString usage example

Source: https://github.com/nette/utils/blob/master/_autodocs/api-reference/type.md

Demonstrates parsing a union type and iterating over its names. Also shows that '?array' stringifies to '?array'.

```php
$t = Type::fromString('int|string|null');
foreach ($t->getNames() as $n) { ... }   // ['int', 'string', 'null']
echo Type::fromString('?array');         // '?array'
```

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

### toObject usage example

Source: https://github.com/nette/utils/blob/master/_autodocs/api-reference/arrays.md

Example of Arrays::toObject setting the 'name' property on a stdClass instance.

```php
$obj = Arrays::toObject(['name' => 'x'], new stdClass);
// $obj->name === 'x'
```

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

### Image resize usage examples

Source: https://github.com/nette/utils/blob/master/_autodocs/api-reference/image.md

Demonstrates various resize calls with different modes and dimensions. Percent strings are allowed for width/height. Cover mode performs a center crop after resizing. ShrinkOnly prevents upscaling and can be combined with other modes.

```php
$img->resize(150, 100);                  // OrSmaller
$img->resize('50%', null);               // half width
$img->resize(300, 200, Image::Stretch);
$img->resize(300, 200, Image::Cover);    // cover + center crop
$img->resize(300, 200, Image::OrBigger | Image::ShrinkOnly);
```

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

### FileSystem::isAbsolute() usage examples

Source: https://github.com/nette/utils/blob/master/_autodocs/api-reference/filesystem.md

Returns true for absolute paths and phar:// URIs, false for relative paths.

```php
FileSystem::isAbsolute('/tmp');                 // true
FileSystem::isAbsolute('phar://foo');           // true
FileSystem::isAbsolute('tmp');                  // false
```

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

### add and addHtml usage examples

Source: https://github.com/nette/utils/blob/master/_autodocs/api-reference/html.md

Demonstrates adding children with escaping and raw HTML. add skips null values, while addHtml inserts raw HTML without escaping.

```php
$el->add('text', Html::el('b')->setText('bold'), null); // null skipped
$el->addHtml('<i>raw</i>');
```

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

### truncate usage example

Source: https://github.com/nette/utils/blob/master/_autodocs/api-reference/strings.md

Example of Strings::truncate() truncating a long string and appending the default ellipsis.

```php
Strings::truncate('Hello world, this is long', 12); // 'Hello world…'
```

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

### insert usage examples

Source: https://github.com/nette/utils/blob/master/_autodocs/api-reference/html.md

Shows prepending a child at index 0 and replacing a child at index 1 with the replace flag set to true.

```php
$el->insert(0, Html::el('i'));   // prepend child
$el->insert(1, 'x', true);       // replace child at index 1
```

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

### mapWithKeys usage example

Source: https://github.com/nette/utils/blob/master/_autodocs/api-reference/arrays.md

Transforms each element into a new key-value pair, here uppercasing the value as key and using 1 as value.

```php
Arrays::mapWithKeys(['a', 'b'], fn($v) => [strtoupper($v), 1]); // ['A' => 1, 'B' => 1]
```

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

### getKeyOffset usage example

Source: https://github.com/nette/utils/blob/master/_autodocs/api-reference/arrays.md

Example call showing that getKeyOffset returns 1 for key 'y' in the array ['x', 'y'].

```php
Arrays::getKeyOffset(['x', 'y'], 'y'); // 1
```

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

### FileSystem::open(string $path, string $mode): resource

Source: https://github.com/nette/utils/blob/master/_autodocs/api-reference/filesystem.md

Opens a file and returns a resource. Wraps fopen and converts failures to Nette\IOException.

```APIDOC
## FileSystem::open(string $path, string $mode): resource

### Description
Opens file and returns resource. Wraps fopen and converts failures to Nette\IOException.

### Method
open (static method)

### Parameters
- **$path** (string) - Required - The path to the file to open.
- **$mode** (string) - Required - The fopen mode (e.g., 'a', 'r', 'w').

### Request Example
```php
$f = FileSystem::open('/tmp/data.log', 'a');
```

### Response
#### Success Response
- Returns a file resource.

#### Error Response
- Throws Nette\IOException on error.
```

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

### detach() usage example

Source: https://github.com/nette/utils/blob/master/_autodocs/api-reference/process.md

Shows how to run a long job with output redirected to files, detach it, and then unset the Process object while the process keeps running.

```php
$p = Process::runCommand('long-job', stdout: '/tmp/out.log', stderr: '/tmp/err.log');
$p->detach();
unset($p);   // process keeps running
```

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

### fixEncoding usage example

Source: https://github.com/nette/utils/blob/master/_autodocs/api-reference/strings.md

Example showing how fixEncoding removes an invalid byte (0xFF) from a string, resulting in 'ab'.

```php
$s = Strings::fixEncoding("a\xFFb"); // "ab"
```

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

### runExecutable method signature

Source: https://github.com/nette/utils/blob/master/_autodocs/api-reference/process.md

Starts an executable with arguments passed as an array, avoiding shell involvement and injection risks. Supports environment variables, proc_open options, stdin/stdout/stderr targets, working directory, and timeout.

```php
/**
 * Starts an executable with given arguments. Because the arguments are passed as an array, the shell is
 * never involved, so they need no escaping and there is no risk of shell injection.
 * @param  string         $executable Path to the executable binary.
 * @param  list<string>   $arguments  Arguments passed to the executable.
 * @param  string[]|null  $env        Environment variables or null to use the same environment as the current process.
 * @param  array<string, mixed>  $options  Options for proc_open(); on Windows the executable is launched directly, without cmd.exe.
 * @param  mixed          $stdin      Input: string, a readable resource (its content is copied to STDIN),
 *                                    a Process (its STDOUT is piped in), or null (STDIN stays open for writeStdInput()).
 * @param  mixed          $stdout     Output target: string filename, a writable resource backed by a real OS file descriptor
 *                                    (not php://memory etc.), false to discard, or null to capture into memory.
 * @param  mixed          $stderr     Error output target (same options as $stdout).
 * @param  string|null    $directory  Working directory.
 * @param  float|null     $timeout    Time limit in seconds, checked while waiting for or reading the process; null disables it.
 */
public static function runExecutable(
	string $executable,
	array $arguments = [],
	?array $env = null,
	array $options = [],
	mixed $stdin = '',
	mixed $stdout = null,
	mixed $stderr = null,
	?string $directory = null,
	?float $timeout = self::DefaultTimeout,
): self
```

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

### Using Finder with foreach and collect

Source: https://github.com/nette/utils/blob/master/_autodocs/api-reference/finder.md

Shows how to iterate over Finder results with foreach, accessing the relative pathname, and how to collect all results into an array using collect().

```php
foreach (Finder::findFiles('*.php')->from(__DIR__) as $path => FileInfo $file) {
	echo $file->getRelativePathname();
}
$all = Finder::find('*')->from('.')->collect();
```

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

### normalize usage example

Source: https://github.com/nette/utils/blob/master/_autodocs/api-reference/strings.md

Example of Strings::normalize() converting a string with CRLF and trailing spaces to normalized form with \n line breaks.

```php
Strings::normalize("  a\r\nb  \n\n"); // "a\nb"
```

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

### mergeTree usage example

Source: https://github.com/nette/utils/blob/master/_autodocs/api-reference/arrays.md

Example of Arrays::mergeTree merging nested arrays recursively, producing ['a' => ['x' => 1, 'y' => 2], 'b' => 3].

```php
Arrays::mergeTree(['a' => ['x' => 1]], ['a' => ['y' => 2], 'b' => 3]);
// ['a' => ['x' => 1, 'y' => 2], 'b' => 3]
```

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

### Iterables::mapWithKeys() usage example

Source: https://github.com/nette/utils/blob/master/_autodocs/api-reference/iterables.md

Transforms each element into a new key-value pair. The example converts ['a', 'b'] into 'A'=>1 and 'B'=>1.

```php
$g = Iterables::mapWithKeys(['a', 'b'], fn($v) => [strtoupper($v), 1]); // 'A'=>1, 'B'=>1
```

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

### compare usage examples

Source: https://github.com/nette/utils/blob/master/_autodocs/api-reference/floats.md

Demonstrates compare() results: 1.0 vs 2.0 gives -1, 0.1+0.2 vs 0.3 gives 0, and comparing NAN throws \LogicException.

```php
Floats::compare(1.0, 2.0);                       // -1
Floats::compare(0.1 + 0.2, 0.3);                 // 0
try { Floats::compare(NAN, 1.0); } catch (\LogicException $e) { ... }
```

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

### renameKey usage example

Source: https://github.com/nette/utils/blob/master/_autodocs/api-reference/arrays.md

Example showing renaming key 'b' to 'c' in an associative array, returning true and resulting in ['a' => 1, 'c' => 2].

```php
$arr = ['a' => 1, 'b' => 2];
Arrays::renameKey($arr, 'b', 'c'); // true; $arr === ['a' => 1, 'c' => 2]
```

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

### Comparison predicates usage examples

Source: https://github.com/nette/utils/blob/master/_autodocs/api-reference/floats.md

Shows results: areEqual(0.1+0.2, 0.3) is true, isLessThan(0.3, 0.1+0.2) is false, and isGreaterThanOrEqualTo(3.0, 3.0) is true.

```php
Floats::areEqual(0.1 + 0.2, 0.3);   // true
Floats::isLessThan(0.3, 0.1 + 0.2); // false
Floats::isGreaterThanOrEqualTo(3.0, 3.0); // true
```

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

### Iterables::firstKey() usage example

Source: https://github.com/nette/utils/blob/master/_autodocs/api-reference/iterables.md

Returns the key of the first element that matches the predicate. In this example, the key 'b' is returned because its value equals 2.

```php
Iterables::firstKey(['a' => 1, 'b' => 2], fn($v) => $v === 2); // 'b'
```

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

### Helpers::falseToNull usage examples

Source: https://github.com/nette/utils/blob/master/_autodocs/api-reference/helpers.md

Converts false to null; other values remain unchanged. The examples show that false becomes null while 0 stays 0.

```php
Helpers::falseToNull(false);  // null
Helpers::falseToNull(0);      // 0
```

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

### FileSystem::joinPaths / resolvePath / unixSlashes / platformSlashes method signatures

Source: https://github.com/nette/utils/blob/master/_autodocs/api-reference/filesystem.md

Path manipulation helpers: join, resolve, and convert slashes.

```php
public static function joinPaths(string ...$paths): string   // normalizePath(implode('/', $paths))
public static function resolvePath(string $basePath, string $path): string
public static function unixSlashes(string $path): string     // '\\' → '/'
public static function platformSlashes(string $path): string // to DIRECTORY_SEPARATOR; keeps protocol://
```

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

### open method signature

Source: https://github.com/nette/utils/blob/master/_autodocs/api-reference/filesystem.md

Declares the static open method that opens a file and returns a resource. Failures become Nette\IOException.

```php
/**
 * Opens file and returns resource.
 * @return resource
 * @throws Nette\IOException  on error occurred
 */
public static function open(string $path, string $mode)
```

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

### isInRange usage examples

Source: https://github.com/nette/utils/blob/master/_autodocs/api-reference/validators.md

Demonstrates range checks with numeric and date values, including a null upper limit. The third example compares a date string against a DateTime limit.

```php
Validators::isInRange(5, [0, 10]);             // true
Validators::isInRange(5, [null, 10]);          // true
Validators::isInRange('2010-01-01', [new DateTime('2009-01-01'), null]); // true
```

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

### FileInfo constructor signature

Source: https://github.com/nette/utils/blob/master/_autodocs/api-reference/filesystem.md

Constructor for FileInfo, which is internal and should not be called directly; Finder constructs instances with a relative path.

```php
public function __construct(
	string $file,
	private readonly string $relativePath = '',
)
```

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

### Fluent configuration example

Source: https://github.com/nette/utils/blob/master/_autodocs/api-reference/paginator.md

Shows fluent chaining of setters and the resulting getPage() value. After setting itemsPerPage=10, itemCount=95, and page=3, getPage() returns 3.

```php
$paginator = (new Paginator)
	->setItemsPerPage(10)
	->setItemCount(95)
	->setPage(3);
$paginator->getPage();      // 3
```

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

### FileSystem::copy() usage examples

Source: https://github.com/nette/utils/blob/master/_autodocs/api-reference/filesystem.md

Shows typical calls to FileSystem::copy(). The first overwrites the destination; the second uses overwrite: false and throws Nette\InvalidStateException when the target already exists.

```php
FileSystem::copy('/src/app.ini', '/dst/app.ini');            // overwrites
try {
	FileSystem::copy('/a', '/b', overwrite: false);       // throws when /b exists
} catch (Nette\InvalidStateException $e) { ... }
```

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

### Image type detection and conversion usage examples

Source: https://github.com/nette/utils/blob/master/_autodocs/api-reference/image.md

Shows typical usage of the static type detection and conversion methods. detectTypeFromFile returns the ImageType constant for a recognized file; typeToExtension converts a type to its extension; extensionToType accepts 'jpg' as JPEG; getSupportedTypes returns an array of supported types based on imagetypes().

```php
$type = Image::detectTypeFromFile('a.png');      // ImageType::PNG
Image::typeToExtension(ImageType::WEBP);         // 'webp'
Image::extensionToType('jpg');                   // ImageType::JPEG
Image::getSupportedTypes();                      // e.g. [GIF, JPEG, PNG, WEBP, AVIF, BMP]
```

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

### isUri usage example

Source: https://github.com/nette/utils/blob/master/_autodocs/api-reference/validators.md

Shows a mailto URI returns true.

```php
Validators::isUri('mailto:x@y.cz');  // true
```
Tokens:
Raw