Utils Laravel Package

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

• 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

• Strings::matchAll(): added option 'lazy'
• added Arrays::mapWithKeys() & Iterables::mapWithKeys()
• added Iterables::memoize() & toIterator()
• Image: GD extension detection added
• support for PHP 8.4

• added Iterables
• added Arrays::firstKey(), lastKey()
• added Arrays::filter()
• Arrays::first() & last(): added parameter $else
• Arrays::first() & last(): added parameter $predicate #305
• added Image::getSupportedTypes()
• Arrays: improved phpDoc
• utilizes Random\Randomizer in PHP 8.3
• StaticClass: fixed compatibility with PHP 8.3.2
• Strings::trim() trims unicode spaces and ZWSP (#304)

• added ImageColor, replaces Image::rgb()
• added Image::rectangleWH(), filledRectangleWH(), calculateTextBox()
• Type: fixed resolving of 'static' nette/di#295

• Strings::length() uses mbstring, iconv and then utf8_decode #299
• Finder: getType() replaced with isDir() / isFile()
• StaticClass: constructor is private nette/di#292
• Arrays: add generic type declaration for some(), every() and map() (#298)
• FileSystem: can be used as instance

• support for PHP 8.3
• Callback::unwrap() returns correct class name for private methods
• improved type annotations (#290)
• Reflection: getParameterType(), getReturnType() and getPropertyType() marked as deprecated

• support for PHP 8.3
• added Image::isTypeSupported()
• added enum ImageType
• Finder: collect() returns list
• Finder: improved exception when directory is missing
• Finder: default mask is '*'
• improved type annotations (#290)
• Callback::unwrap() returns correct class name for private methods

• uses PHP 8 featurs
• includes a completely rewritten Finder
• PascalCase constants
• Strings: added support for UTF-8 offsets in regexp
• Translator: improved interface, accepts and returns string|Stringable [Closes #231]
• ArrayHash & ArrayList: support iteration with reference (#289)

new methods:

• Nette\Utils\Json::decodeFile() reads JSON from a file
• Nette\Utils\FileSystem::unixSlashes() & platformSlashes() converts slashes to Unix slashes
• Nette\Utils\Strings::ord(), unixNewLines() & platformNewLines()
• Nette\Utils\Helpers::compare() compare using the operator

new parameters:

• Nette\Utils\Strings::split() added parameter $limit
• Nette\Utils\Strings::replace() added parameters $captureOffset, $unmatchedAsNull
• Nette\Utils\Strings, Nette\Utils\Arrays, Nette\Utils\Json: flags replaced with parameters

removed

• Reflection: removed obsolete getReturnType(), getParameterType(), getPropertyType() (BC break)

• Type: supports Disjunctive Normal Form Types
• Validators: added isTypeDeclaration(), isBuiltinType(), isClassKeyword()
• used PhpStorm Language attribute (#277)
• Types::isSingle() -> isSimple()

• support for PHP 8.2
• tests: deprecated GD changed to PNG
• Image::clone() uses PNG format because GD2 is disabled since libgd 2.3.3
• Image::detectTypeFromFile & detectTypeFromString returns width & height
• Image: added extensionToType()
• private constants are PascalCase
• ObjectHelpers: fixed parsing static @methods #278

• SmartObject: supports property deprecation
• Image: added support for AVIF
• Image: distinguishes between fatal errors and warnings
• Validators: isNumeric support string number '1.' (#276)
• Json: accepts native JSON_* constants #275
• Arrays::isList() uses array_is_list() is PHP 8.1

Deprecated properties are written as [@property-deprecated](https://github.com/property-deprecated), no standard here exists. PhpStorm and static analysis tools do not see them, which is the intention.

• FileSystem: messages use normalized paths (#250)
• Strings::indexOf() fixed empty $haystack and negative $nth #271
• Strings: improved things around flags
• Callback::unwrap can return non-callable #270
• used @return never
• added Helpers::clamp()
• Validators::isPhpIdentifier(): Value is always string. (#268)
• Reflection::expandClassName() recognizes 'parent'
• added Reflection::isClassKeyword(), Type::isClassKeyword()

• support for PHP 8.1
• added Type
• Type, Reflection: supports intersection types
• Reflection::getReturnType() & Type::fromReflection() return tentative type in PHP 8.1
• Reflection::getUseStatements supports enums
• Reflection: added 'never' built-in type
• Reflection: getReturnTypes(), getParameterTypes(), getPropertyTypes() are deprecated
• improved phpDoc, used generics
• added ArrayList::from()

• added Type
• improved phpDoc, used generics
• Strings::replace: default replacement is empty string #241
• Reflection: getReturnTypes(), getParameterTypes(), getPropertyTypes() are deprecated

• FileSystem: Add method makeWritable() (#244)
• Paginator: add firstItemOnPage & lastItemOnPage #262 (#263)
• ObjectHelpers: improved error messages, added scope

• Arrays: added wrap() method (#180)
• Arrays::insertAfter() & insertBefore() fixed when $key is null
• DateTime::fromParts() is non-locale aware #248
• compatibility: improved code hinting

• added Arrays::first(), last() & contains()
• added Array::invoke() & invokeMethod()
• Arrays: some methods accepts iterable
• Strings::toAscii() fixed to correctly convert german umlauts (BC break) (#240)
• Strings::replace: default replacement is empty string #241

For the details you can have a look at the diff.

• requires PHP 7.2
• Added Nette\Utils\Floats class for comparing floats (#221)
• Arrays: searchKey() silently renamed to getKeyOffset()
• Callback::closure() triggers deprecation notice
• Image: added detectTypeFromFile() and detectTypeFromString()
• Reflection::toString() appends () after function/method name
• Strings::toAscii - triggers E_USER_NOTICE when ext-intl is not present
• renamed Nette\Localization\ITranslator -> Translator, added class alias
• renamed Nette\Utils\IHtmlString -> Nette\HtmlStringable, added class alias

• Reflection: added getReturnTypes(), getParameterTypes() and getPropertyTypes()
• Reflection::getReturnType(), getParameterType() and getPropertyType() throws exception on union types
• Image::fromString() throws UnknownImageFileException when file type is unknown

For the details you can have a look at the diff.

• compatible with PHP 8.0
• Image::fromString() throws UnknownImageFileException when file type is unknown
• Image: better processing and checking dimensions in strings #217
• DateTime::from(null) fixed #211

For the details you can have a look at the diff.

• compatible with PHP 8.0
• Image: better processing and checking dimensions in strings #217
• Html::getText() decodes '

For the details you can have a look at the diff.

• compatible with PHP 8.0
• Arrays::renameKey() fixed incorrect replacement for existing new keys #230
• Arrays::renameKey() returns true if $oldKey was found
• Arrays: added toKey()
• improved PHP doc
• Reflection: fixed parseUseStatements for PHP 8 #229
• SmartObject: better support for $onEvent with typehint
• Image: added new PHP functions
• Strings: ICONV_IMPL can be quoted
• FileSystem: Added $mode to all exceptions.
• Image: compatibility with PHP 8.0
• Reflection: added PHP 8 type 'static'
• Reflection::isBuiltinType() added PHP 8 types mixed & false
• Reflection::getReturnType() fixed for functions
• SmartObject: removed return void

For the details you can have a look at the diff.

• Image: better processing and checking dimensions in strings #217
• added Reflection::getMethodDeclaringMethod()
• Strings: throws exception when iconv is missing #215
• Strings::toAscii() removes non-ascii characters when iconv is not supported #216

For the details you can have a look at the diff.