Utils Laravel Package

Technical Evaluation

Architecture fit

• nette/utils is a framework-agnostic, dependency-free leaf library: static utility classes (Strings, Arrays, Validators, Json, FileSystem, Image, Process, DateTime, Iterables, Type) with no container bindings, no configuration, and no service provider. It sits below the application layer and imposes no architectural opinion on a Laravel codebase.
• The architectural mismatch is not technical but conceptual: it deliberately overlaps with Illuminate\Support (Str, Arr), Laravel's Validator, Illuminate\Process, and Illuminate\Support\Facades\File. Adopting it means running two utility conventions in parallel unless a standard is set.
• It is stateless and static, so it is safe under Octane, queue workers, and CLI commands; there is no shared mutable state to leak between requests.

Integration feasibility

• Installation is a single composer require nette/utils:^4.1 with PSR-4 autoloading. Effort for a pilot is measured in hours, not sprints.
• Version 4.1.0 requires PHP 8.2, which aligns with the Laravel 11/12 baseline, so no runtime upgrade is triggered by adoption.
• PHP ceiling is no longer a concern. v4.0.11 added PHP 8.6 support, so the 4.0 line covers PHP 8.0–8.6. This removes a plausible future blocker: the library will not become the constraint on a PHP 8.6 migration. Caution: the release note is filed against 4.0.11, not the pinned 4.1 line — confirm 8.6 coverage exists in the resolved 4.1.x tag before treating this as settled for our pin.
• Optional extension dependencies must be verified per environment before committing to specific modules: ext-intl (Strings::webalize() became INTL-required in 4.1.0), ext-gd (Image), mbstring/iconv (strings length/transliteration fallbacks), and proc_open availability for Process.
• The Process API is the highest-value differentiator: Process::runExecutable() passes arguments as an array with no shell involvement, eliminating shell-injection risk by construction, and supports timeouts, incremental output consumption, and exit-code checks across Windows and POSIX.

Technical risk

• Licensing is unresolved. GitHub reports NOASSERTION; the library is understood to be BSD-family but the metadata does not confirm it. This requires legal review before production use and is a hard gate, not a formality.
• Static APIs are mock-hostile. Strings, FileSystem, Json, and Process are static classes, so unit tests cannot substitute them. Code that calls them directly becomes harder to isolate; adapters are needed wherever behavior must be faked.
• Ecosystem and release metadata in this record are unreliable. The entry pairs release_tag: v4.1.4 with release notes for v4.0.11, and the previously recorded last-release date (2026-07-17) is forward-dated while the current record says 2026-05-11. Combined with Dependents: 0 for a 2.1k-star library that is a transitive dependency of much of the PHP ecosystem, this data should not drive dependency-governance decisions. Verify tag, changelog, and PHP constraint directly against Packagist/GitHub.
• Two maintained lines (4.0.x and 4.1.x). Platform-support fixes such as PHP 8.6 landed on 4.0 first. Divergence between lines means a backported fix may be reachable only on one branch; we must state which line we pin and check both changelogs when a relevant fix appears.
• Major-version churn. The v3 → v4 line removed Reflection::getReturnType()/getParameterType()/getPropertyType(), made DateTime strict (explicit BC break), PascalCased constants, and rewrote Finder. Pinning to ^4.1 and gating minor bumps through changelog review is mandatory.
• Utility sprawl. Without a written standard, some engineers will use Str::slug(), others Strings::webalize(), producing inconsistent slug output and untranslatable content across features.

Key questions

1. Has legal cleared the NOASSERTION license status, and what is the approved license set for production dependencies?
2. Which specific gaps are we filling that Laravel does not already cover — is the driver genuinely Process, FileSystem::isValidFilename(), and strict Json, or is this opportunistic adoption?
3. Are ext-intl and ext-gd present and pinned in production, staging, and CI container images?
4. Which team owns the internal standard for when to use nette/utils versus Illuminate equivalents?
5. Do we require testability of process execution? If so, which adapter boundary do we commit to up front?
6. Is there an existing symfony/process or Illuminate\Process usage we would be duplicating or replacing?
7. What is the rollback story if a minor release introduces behavioral change in DateTime or Json?
8. Does the security model require the no-shell runExecutable() path specifically, and are there current call sites using shell_exec/exec that should be migrated?
9. Is a PHP 8.6 upgrade on the roadmap in the next 2–3 quarters, and if so, does the resolved 4.1.x tag declare 8.6 support (not just 4.0.11)?

Integration Approach

Stack fit

• Compatible with Laravel 10–12 on PHP 8.2+, and with Octane, Horizon, and standard queue workers, since all entry points are static and stateless. Upstream now declares PHP 8.0–8.6 on the 4.0 line, so the library does not narrow our supported PHP range.
• Best fit is as a targeted supplement, not a replacement for Illuminate\Support. The clearest non-overlapping wins:
  • Process — shell-injection-safe invocation of external binaries (PDF renderers, media encoders, git, container tooling) with native timeout and streaming output.
  • FileSystem::isValidFilename() — no Laravel equivalent; rejects path separators, control/reserved characters, trailing dots and spaces, and Windows device names (CON, LPT1). Directly useful on the upload path.
  • Json::decode()/encode() and Json::decodeFile() — consistent exception-based failure handling instead of json_decode() returning null.
  • Strings::webalize() — transliterating, INTL-backed slugging where ASCII-only Str::slug() output is insufficient for non-Latin content.
  • Image — GD-based resize/type detection for lightweight avatar and thumbnail work without pulling in a heavier imaging package.
• Clear overlaps to consciously leave alone: Arrays vs Arr (use Arr for consistency with Eloquent/Collection code), Validators vs Laravel's Validator (form validation stays in Laravel), Html (Blade escapes already).

Migration path

• Additive only. No refactor of existing Str/Arr/Validator call sites is required or recommended as part of adoption.
• Adopt module by module behind thin application-owned adapters where behavior needs to be faked or swapped — for example a ProcessRunner interface with a nette-backed implementation, registered in a service provider. This preserves testability while keeping the library out of business logic.
• Record the decision as a short ADR: approved modules, prohibited modules, the pinned major line, and the rule "new code uses nette/utils only for the four approved capabilities; everything else uses Illuminate."
• Enforce with a code-review checklist and, if the codebase uses architecture tests, a rule limiting direct Nette\Utils\* imports to the App\Support namespace.

Compatibility

• Pin to ^4.1 and treat minor bumps as reviewable changes, not automatic.
• Run composer why-not nette/utils ^4.1 before rollout to catch transitive PHP-version or extension conflicts; confirm no existing dependency already pins an older nette/utils major.
• PHP 8.6 forward-compatibility: add a PHP 8.6 job to the CI matrix now (or at the gate) even if production stays on 8.2/8.3. This both validates the upstream claim on the tag we actually resolve and removes a future upgrade blocker. If the 4.1 line turns out not to carry the 8.6 support shipped in 4.0.11, note the fallback path (pin within 4.0.x or wait for the 4.1 backport) in the ADR.
• Verify PHPStan compatibility early — 4.1.3 made PHPStan a mandatory upstream CI check and shipped stricter types and PHPDoc, which generally helps rather than hurts static analysis, but may surface new findings in call sites.
• Confirm the extension matrix (intl, gd, mbstring) in composer.json require/suggest and in the Dockerfile, so failures occur at build time rather than at runtime.

Sequencing

1. Week 1 — Gate. License clearance, PHPStan/extension audit, dependency-conflict check, PHP 8.6 CI matrix job, ADR drafted (including pinned line and the 4.0 vs 4.1 question).
2. Week 2 — Quick wins. FileSystem::isValidFilename() on upload validation and Json::decode() on inbound webhook payloads. Low blast radius, immediate security value, exercises deployment.
3. Weeks 3–5 — Process migration. Introduce the ProcessRunner adapter, migrate the highest-risk existing shell invocations, add timeout and exit-code assertions, and instrument failures.
4. Weeks 6–8 — Image pipeline. Only if there is a concrete upload/resize requirement that Intervention Image or an existing pipeline does not already serve.
5. Ongoing — Micro-utilities. Iterables::memoize(), Arrays::mapWithKeys(), Helpers::clamp() adopted opportunistically, and only where profiling or readability justifies it.

Operational Impact

Maintenance

• Upstream is actively maintained with frequent, well-documented releases; each ships a changelog entry, which lowers the cost of upgrade review. Pin the major, automate minor-bump PRs via Dependabot, and require changelog review before merge.
• Patch releases are now sometimes platform-support-only (4.0.11 adds PHP 8.6 with no API change). These are safe candidates for auto-merge provided the CI matrix covers the declared PHP range; keep manual review for minor bumps and anything touching DateTime, Json, Strings, or Process.
• Bus factor is concentrated in the Nette core team. There is no commercial support contract, so the internal owning team must be named explicitly in the ADR.
• Because the library is small and dependency-free, the maintenance surface is narrow: the main ongoing cost is reviewing behavioral changes in DateTime, Json, and Strings at minor bumps, plus tracking fixes that land on only one of the two maintained lines.

Support

• Community-supported OSS with GitHub issues and no SLA. Internal teams should expect to diagnose edge cases themselves, particularly around Windows path handling (Finder symlink issues under Windows are a documented upstream quirk) and locale-dependent DateTime parsing.
• Escalation path should be defined during the pilot: internal owner → pin/patch → fork only as a last resort.

Scaling

• Runtime overhead is negligible — these are pure PHP helpers with no autoload or reflection cost beyond first use, and optimized global function calls landed in 4.0.8.
• Load-bearing concerns appear only in I/O-bearing modules:
  • Process under queue workers: concurrency must be bounded by worker count and process timeouts; unbounded subprocess spawning is the primary scaling hazard.
  • Image under concurrent uploads: GD holds decoded bitmaps in memory, so large-image requests can spike worker memory far above baseline. Enforce upload size limits before decode.
  • FileSystem operations on shared or networked storage inherit that storage's latency and locking behavior.

Failure modes

• Missing ext-intl — Strings::webalize() fails where Str::slug() previously worked; surfaces only on the affected code path. Detect at build time via composer platform requirements.
• Missing ext-gd — Image operations fail; 4.0.5 added GD detection, so this can be surfaced as a health check rather than a runtime surprise.
• DateTime strictness — v4 throws on input that v3 tolerated. Any user-supplied date string is a potential exception path; wrap and validate at the boundary.
• Json exceptions — exception types and depth/flag semantics differ from native json_decode(); webhook handlers that previously received null will now throw. This is an improvement but a behavioral change requiring explicit catches.
• Process timeouts and exit codes — a killed subprocess yields a non-zero exit and partial output; the consuming job must distinguish timeout from genuine failure, and must always terminate the process on abandoned jobs to avoid orphans.
• FileSystem runtime exceptions — permission and mode failures throw rather than returning false, so upload and write paths need explicit handling.
• Image warnings — 4.1.4 added a $warnings parameter to Image::fromFile()/fromString(), so GD warnings can be logged instead of emitted as PHP warnings. Adopt this parameter rather than relying on @ suppression.
• PHP platform resolution — if we move to PHP 8.6 ahead of the pinned line's declared support, Composer will block installation rather than fail at runtime. This is a safe failure, but it must be caught in the gate and CI matrix, not during an upgrade window.

Ramp-up

• Developer ramp-up is low, roughly a half-day of documentation and one onboarding session, because the APIs are conventional and the Laravel equivalents are familiar.
• The real cost is convention discipline: engineers must know which utility family to reach for. Budget the ADR, a one-page decision table ("use Str here, Strings there"), and a code-review checklist.
• Expect a short stabilization window after the Process migration while timeout and error-handling behavior is tuned against real workloads; plan for it in the first sprint rather than treating it as a defect.