Utils Laravel Package

Getting Started

Start by installing the package via Composer:

composer require nette/utils

This package is dependency-light and PHP 8.2+ required (v4.x). First port of call: Nette\Utils\Arrays, Nette\Utils\Strings, and Nette\Utils\Json. These provide reliable, UTF-8–safe equivalents to PHP’s built-ins — e.g., Arrays::get($arr, $key, $default) to avoid undefined index warnings, or Strings::trim($str, " \t\n\r\0\x0B") for consistent whitespace handling. For quick validation, use Validators::isEmail($value) or isUrl($value).

Implementation Patterns

• Array manipulation: Prefer Arrays::map(), filter(), first(), last($array, $else), and mapWithKeys() over manual array_map or loops. They handle edge cases (null, non-iterables) gracefully and support iterable.
• String safety: Use Strings::webalize() for SEO-friendly slugs (requires ext-intl; fallback triggers warning). For HTML snippets, Html::addText() safely escapes text into HTML (e.g., <b>Text</b> → <b>Text</b>).
• JSON with safety: Use Json::encode($data, $flags) and Json::decode($json, Json::FORCE_ARRAY) — both throw exceptions on failure (no JSON_ERROR_* polling needed). Json::decodeFile($file) is ideal for config loading.
• DateTime handling: DateTime::from($input) handles DateTimeInterface, strings, null, or timestamp; relativeToSeconds('2 days') parses relative intervals reliably — including DST transitions.
• Strong passwords: Helpers::generatePassword($length = 12, $type = 'alphanumeric') gives cryptographically secure random strings.
• Finder & file paths: FileSystem::resolvePath($path) normalizes paths (Windows/Unix), Finder::findFiles('*.php') is a fluent iterator wrapper.

Gotchas and Tips

• v4.x requires PHP 8.2+ — ensure your project aligns. Type system now leverages native types rigorously; use PHPStan (mandatory in CI).
• Strings::webalize() silently fails on systems missing ext-intl (PHP 4.3+ fallback via iconv is deprecated and error-prone). Check support with Image::getSupportedTypes() or Intl::isSupported() in your env.
• Arrays::first()/last(): Default fallback ($else) defaults to null; pass a third arg ($predicate) for conditional retrieval (e.g., Arrays::first($items, null, fn($x) => $x->isActive())).
• Type::isSimple() (renamed from isSingle() in v3.2.9) clarifies type analysis — useful for reflection-heavy code.
• PHP 8.5+ support: Image::getSupportedTypes() now includes AVIF/WEBP where GD/Imagick supports them; always check Image::isTypeSupported(ImageType::Avif) before writing AVIF.
• StaticClass constructors are private — you’ll get a clear error if someone tries new Finder() instead of Finder::create().
• Watch for String::length() fallback chain: mbstring → iconv → utf8_decode. If none available, throws ShouldNotHappenException — ensure mbstring is enabled in production.
• Use Arrays::memoize() or Iterables::memoize() to cache expensive operations within a single request — but avoid memoizing stateful callbacks (reference capture issues).
• For testing: Random\Randomizer (PHP 8.3+) powers password generation; override via Nette\Utils\Random::setGenerator() for deterministic tests.