Utils Laravel Package

Technical Evaluation

Architecture Fit

• Modularity: The package’s granular utilities (e.g., Strings, Arrays, Image, Process) align well with Laravel’s service-layer architecture, where domain-specific logic is encapsulated in services. For example:
  • String/Array Manipulation: Replace ad-hoc helper functions in Laravel’s Str/Arr with typed, documented alternatives (e.g., Strings::webalize() for SEO-friendly URLs).
  • Image Processing: Integrate Image utilities into Laravel’s filesystem disk drivers or media library packages (e.g., Spatie Media Library) for consistent image handling.
  • Process Management: Replace Laravel’s Process facade (if used) or custom shell exec calls with Process::runExecutable() for secure subprocess handling (e.g., in queued jobs or console commands).
• Laravel Ecosystem Synergy:
  • Validation: Extend Laravel’s validator with Type/Validators utilities (e.g., Validators::isPhpIdentifier() for custom rule logic).
  • Filesystem: Augment Laravel’s Filesystem with FileSystem::isValidFilename() for upload sanitization (e.g., in Illuminate\Http\Request middleware).
  • Testing: Leverage Iterables::memoize() or Arrays::filter() in Laravel’s testing utilities (e.g., Illuminate/Testing assertions).

Integration Feasibility

• Low Friction:
  • Composer Compatibility: Direct composer require nette/utils integration with zero Laravel-specific conflicts.
  • PHP Version Alignment: Laravel 10+ (PHP 8.2+) supports v4.1.x; Laravel 9 (PHP 8.1+) can use v4.0.x with minor deprecation warnings.
  • Namespace Isolation: Nette’s Nette\Utils\* namespace avoids collisions with Laravel’s Illuminate\* or Laravel\* namespaces.
• Key Integration Points:

  Laravel Component	Nette Utils Utility	Use Case
  Str::slug()	Strings::webalize()	SEO-friendly URLs with INTL support.
  File::exists()	FileSystem::isValidFilename()	Sanitize user uploads in UploadedFile.
  Process::run()	Process::runExecutable()	Secure CLI tool execution in jobs.
  Image facade	Image::fromFile() (with $warnings)	Log GD errors in media processing.
  Validator rules	Type::fromValue()/Validators	Custom validation logic (e.g., PHP identifiers).

Technical Risk

• Breaking Changes:
  • PHP 8.2+ Requirement: Laravel 9 (PHP 8.1) would need to pin to v4.0.x, risking deprecation warnings (e.g., Reflection methods marked deprecated).
  • BC Breaks in v4.1.0: DateTime strict behavior or Strings::webalize() requiring INTL may need polyfills for environments without extensions.
• Dependency Conflicts:
  • Nette/DI: If the Laravel app uses Nette’s DI container, nette/utils may pull in nette/di (though utils is standalone in v4+).
  • GD/PHP Extensions: Image utilities require GD; Strings::webalize() needs INTL. Document these as runtime dependencies.
• Performance Overhead:
  • Reflection/Type Utilities: Heavy use of Reflection or Type classes (e.g., in validation) could impact boot time. Benchmark critical paths.
  • Process Management: Spawning processes adds I/O overhead; cache Process instances in Laravel’s service container for reuse.

Key Questions

1. Prioritization:
   • Which Laravel features will most benefit from Nette’s utilities? (e.g., Is Process for jobs or Image for media more critical?)
   • Should we replace existing Laravel helpers (e.g., Str::slug()) or extend them as wrappers?
2. Compatibility:
   • For Laravel 9 (PHP 8.1), should we fork or polyfill v4.1.0’s PHP 8.2+ features?
   • How will we handle missing extensions (e.g., INTL for webalize()) in production?
3. Testing:
   • How will we mock Process or Image utilities in PHPUnit tests? (Nette provides mockable interfaces.)
   • Should we add custom assertions for Nette utilities in Laravel’s testing helpers?
4. Maintenance:
   • Who will triage Nette updates? (e.g., v4.2.0 breaking changes)
   • How will we document the new utilities for the team? (e.g., internal wiki or Laravel-specific guides?)

Integration Approach

Stack Fit

• Laravel Core Integration:
  • Service Providers: Register Nette utilities as bindings in AppServiceProvider:

    public function register(): void {
        $this->app->singleton('nette.utils.process', fn() => new \Nette\Utils\Process());
        $this->app->alias('nette.utils.process', \Nette\Utils\Process::class);
    }
    

  • Facades: Create Laravel facades for critical utilities (e.g., Facade\Utils::slug()) to maintain consistency with Laravel’s patterns.
• Domain-Specific Integration:
  • Media Library: Extend Spatie’s MediaLibrary to use Image::fromFile() with warning handling.
  • Validation: Add a NetteValidator class extending Laravel’s Validator to use Type/Validators utilities.
  • Jobs/Commands: Replace Process::run() with Process::runExecutable() in queued jobs or Artisan commands.

Migration Path

Compatibility

• Laravel-Specific Overrides:
  • Filename Handling: Override Illuminate\Http\UploadedFile to use FileSystem::isValidFilename():

    public function getClientOriginalName(): string {
        $name = parent::getClientOriginalName();
        if (!FileSystem::isValidFilename($name)) {
            throw new \InvalidArgumentException("Invalid filename: {$name}");
        }
        return $name;
    }
    

  • String Helpers: Create a Str facade extension:

    Str::shouldUseNetteUtils(true);
    Str::slug('Nette Utils'); // Uses Strings::webalize()
    

• Fallbacks:
  • Missing Extensions: Provide polyfills for INTL/GD (e.g., fallback webalize() implementation).
  • PHP Version: Use if (PHP_VERSION_ID >= 80200) guards for v4.1.0+ features.

Sequencing

1. Phase 1: Low-Risk Utilities (1–2 weeks)
   • Replace Str::slug() → Strings::webalize().
   • Add FileSystem::isValidFilename() to upload middleware.
   • Goal: Prove integration feasibility with minimal risk.
2. Phase 2: Core Infrastructure (2–3 weeks)
   • Integrate Process utilities into Laravel’s Process facade.
   • Extend Image handling in media libraries.
   • Goal: Enable secure subprocesses and image processing.
3. Phase 3: Validation & Testing (1–2 weeks)
   • Add Type/Validators to Laravel’s validator.
   • Write custom test assertions for Nette utilities.
   • **