nette/utils

This release adds an immutable date/time class, makes file writes safer, background processes possible, and Finder masks smarter. Plus a couple of bug fixes worth picking up.

✨ New Features

• DateTimeImmutable – a new immutable counterpart to Nette\Utils\DateTime. It extends PHP's \DateTimeImmutable with strict validation (invalid dates and times throw instead of being silently rolled over), convenient factories from() and fromParts(), DST-safe relative modifications, and JSON serialization.
• FileSystem::writeAtomic() – writes a file atomically via a temporary file and rename, so a concurrent reader never sees it partially written or truncated. Ideal for caches and generated configs.
• Process::detach() – lets a process keep running in the background after the Process object is destroyed, instead of being killed by the destructor. Output must go to a file or be discarded, since nobody reads the pipes after detaching.
• Process – on Windows with PHP 8.5, captured output now flows through real pipes instead of temporary files, thanks to the fixed stream_select().
• Html::fragment() and add() – create a nameless element pre-filled with children, or append children to an existing element. Unlike addHtml(), plain strings are escaped by default and nulls are skipped.
• Html::text() and Html::html() – new static factories replacing fromText() and fromHtml(), which are now deprecated.
• Finder – the mask now fully drives recursion: **/foo together with in() searches recursively, and the ** short form expands like in zsh, so test/** means test/**/* and **.c means **/*.c (previously such masks silently degraded to a single *).
• Finder – a trailing slash in a find() mask matches directories only: find('temp/').
• Finder::exclude() – now uses the same mask grammar as find(): **.txt works, ./ anchors to the search root, and a trailing /, /* or /** controls whether the directory itself, its contents, or both are excluded.
• Finder – paths are no longer normalized to forward slashes; they stay in their native form, which also fixes corruption of backslashes in POSIX file names. Note: on Windows, returned paths may now contain backslashes where they used to be unified.

🐛 Bug Fixes

• ArrayList::prepend() – no longer misbehaves on an empty list.
• Validators::isUrl() – now rejects malformed IPv4 addresses with octets above 255, so nonsense like http://999.1.1.1 no longer passes as a valid URL.
• Strings::compare() – tolerates invalid UTF-8 instead of failing when the Normalizer gives up.
• Strings::length() – the fallback used when neither mbstring nor iconv is available no longer relies on the deprecated utf8_decode(), so it stays quiet on PHP 8.2+.
• Finder::exclude() – exclude('subdir/') silently excluded nothing due to a greedy regex; the trailing /, /* and /** variants now work as documented.

• Process – a new class for starting and controlling external processes: read their output, feed them input, pipe one process into another, wait for completion, terminate, and check exit codes. Process::runExecutable() passes arguments as an array so there's zero shell involvement and no risk of shell injection, while Process::runCommand() is there when you really do want the shell. Comes with timeouts, incremental output consumption (consumeStdOutput() / consumeStdError()), and works on Windows too.
• FileSystem::isValidFilename() – quickly check whether a string is a safe, cross-platform filename: it rejects path separators, control and reserved characters, trailing dots or spaces, and Windows device names like CON or LPT1.
• Image::fromFile() and Image::fromString() now accept an optional $warnings parameter – pass it in and any GD warnings are handed back to you as a string instead of being emitted as a PHP warning, so you can log or display them on your own terms.

A maintenance release focused on code quality: stricter types, better PHPDoc annotations, and PHPStan now runs as a mandatory CI check. No breaking changes.

• Html::addText() accepts int|null for back compatibility [Closes #332][Closes #333]

• requires PHP 8.2
• DateTime: strict behavior (BC break)
• Strings::webalize() requires INTL extension
• StaticClass: is not overriding __callStatic()

• added Type::with()
• added Type::fromValue()
• added Helpers::splitClassName()
• added Iterables::repeatable()
• Finder: is_file() does not work with symlinks under Windows

• support for PHP 8.5
• Strings::trim() trims Line Separator and Ideographic Space (#326)
• DateTime: fixed parsing 'ago' modifier #327
• DateTime::relativeToSeconds() checks for error
• optimized global function calls

• DateTime: constructor and modify() correctly handle the relative time even if the daylight saving time is changed
• DateTime: added static method relativeToSeconds() for converting relative time string to seconds
• DateTime: triggers a warning when time overflow occurs

• Image: catches all errors during saving
• added Helpers::IsWindows
• added ShouldNotHappenException
• added FileSystem::resolvePath() #308
• tests: improved descriptions
• exception: use natural explanatory style