Support Laravel Package

Technical Evaluation

Architecture Fit

• Pros:

  • Facade-based design aligns with Laravel’s service container and facade patterns, enabling clean, dependency-free usage (e.g., Arr::flattenKeys()).
  • Modular structure (e.g., Arr, Str, File, Digit helpers) maps naturally to Laravel’s service layer or utility layer, reducing coupling.
  • Lightweight (~10KB) with no external dependencies (beyond PHP core), making it ideal for microservices, CLI tools, or legacy system modernization.
  • Invokable methods (e.g., Arr::of()->count()) support fluent interfaces, improving readability in Laravel’s query builder-style syntax.
  • PHP 8.1+ compatibility ensures alignment with modern Laravel (10+) and PHP best practices (e.g., named arguments, attributes).

• Cons:

  • No built-in Laravel service provider: Requires manual facade registration (minor overhead for small teams).
  • Limited domain-specific utilities: Focuses on generic helpers (e.g., string/array manipulation) rather than business logic (e.g., payment processing, auth).
  • Facades may obscure dependencies: Harder to mock in unit tests compared to direct class instantiation (mitigated by Laravel’s MockFacade or partialMock).

Integration Feasibility

• Laravel Ecosystem:
  • Seamless facade integration: Works alongside Laravel’s built-in helpers (e.g., collect(), Str::of()) without conflicts.
  • Service container compatibility: Can be bound as singletons if needed (e.g., Arr helper for global array operations).
  • Testing: Supports Pest/PHPUnit via facades or direct class calls (e.g., Arr::count()).
• Non-Laravel PHP:
  • Standalone usage: Facades require manual registration, but core classes (DragonCode\Support\Arr, DragonCode\Support\Str) work independently.
  • PSR-4 autoloading: Standard Composer setup ensures no path configuration issues.

Technical Risk

Key Questions for TPM

1. Adoption Scope:

   • Will this replace custom utility classes (e.g., app/Helpers/ArrayHelper.php) or third-party packages (e.g., spatie/array)?
   • How will naming conflicts be handled (e.g., Arr::pluck() vs. Laravel’s collect()->pluck())?

2. Testing Strategy:

   • Should facades be mocked in unit tests, or will direct class calls suffice?
   • Will integration tests verify facade behavior in Laravel’s service container?

3. Maintenance:

   • Who will triage updates (e.g., PHP 8.3 compatibility)?
   • Will the team contribute fixes or fork if the package stagnates?

4. Alternatives:

   • Compare with Laravel’s built-in helpers (e.g., Str::of(), collect()) and Spatie packages (e.g., spatie/array).
   • Evaluate performance vs. alternatives (e.g., nette/utils for non-Laravel PHP).

5. Onboarding:

   • How will the team standardize usage (e.g., documentation, coding guidelines)?
   • Will internal wrappers be created for critical methods (e.g., app/Support/Arr.php)?

Integration Approach

Stack Fit

Migration Path

1. Assessment Phase:

   • Audit existing custom utilities (e.g., app/Helpers/) and third-party helpers (e.g., spatie/array).
   • Identify high-value methods (e.g., Arr::flattenKeys(), Str::slugify()) to replace.

2. Pilot Integration:

   • Install in a non-production repo or feature branch:

     composer require dragon-code/support --dev
     

   • Register facades in config/app.php:

     'aliases' => [
         'Arr' => DragonCode\Support\Facades\Arr::class,
         // ... other facades
     ],
     

   • Replace 1–2 critical utility methods (e.g., Arr::pluck() → Arr::of($array)->pluck()).

3. Gradual Rollout:

   • Phase 1: Replace array/string helpers (e.g., Arr, Str).
   • Phase 2: Adopt filesystem utilities (e.g., File::load(), Directory::copy()).
   • Phase 3: Deprecate custom utility classes in favor of package methods.

4. Deprecation Strategy:

   • Use Laravel’s deprecated() helper for custom methods:

     if (!function_exists('old_array_pluck')) {
         function old_array_pluck($array, $key) {
             deprecated('Use Arr::of($array)->pluck() instead.', '2024-01-01');
             return Arr::of($array)->pluck($key);
         }
     }
     

Compatibility

Sequencing

1. Critical Path:

   • Week 1: Install package, register facades, test in isolation.
   • Week 2: Replace high-impact utility methods (e.g., array/string operations).
   • Week 3: Integrate filesystem helpers (if needed).

2. Parallel Tasks:

   • Documentation: Create internal docs for team adoption (e.g., "When to use Arr::of() vs. collect()").
   • Testing: Write integration tests for facade behavior