Utils Laravel Package

Product Decisions This Supports

• Code Quality & Maintainability:

  • Adopt a standardized utility library to reduce custom utility code across the codebase, improving readability and maintainability.
  • Replace ad-hoc array/assertion logic with a battle-tested library, reducing technical debt.

• Developer Productivity:

  • Accelerate development cycles by leveraging pre-built utility methods (e.g., Arrays::flatten, Arrays::toIntList, Assert::notNull) instead of reinventing them.
  • Reduce cognitive load for junior developers by providing clear, documented utility functions.

• Consistency & Best Practices:

  • Enforce consistent data validation (e.g., Assert::isArray, Assert::greaterThan) across services, reducing edge-case bugs.
  • Standardize array manipulation (e.g., Arrays::groupBy, Arrays::diff, Arrays::toIntList) to ensure predictable behavior — notably, a single sanctioned way to normalize ID lists (query params, form arrays, CSV splits) rather than scattered array_map('intval', ...) casts.

• Roadmap Alignment:

  • Feature Flagging: Use Closures::unfold to lazy-load heavy services (e.g., external APIs) behind feature flags.
  • Data Transformation: Leverage Arrays::mapAssoc/Arrays::reindex for API payload transformations, and Arrays::toIntList for normalizing identifier collections at the boundary of new integrations.
  • Error Handling: Replace manual if (empty($var)) checks with fluent assertions (e.g., Assert::nonEmptyArray($data)) in validation-heavy flows.

• Build vs. Buy:

  • Buy: Justify adoption by comparing the cost of maintaining custom utilities (e.g., bug fixes, edge-case handling) against the MIT-licensed package’s active development (recent releases, PHP 8.3+ support).
  • Custom Alternatives: Only build if the package lacks critical niche functionality (e.g., domain-specific array operations).

When to Consider This Package

Adopt When:

• Your Laravel/PHP codebase relies heavily on array manipulation (e.g., nested data, transformations, filtering) or data validation (e.g., input sanitization, API responses).
• You’re standardizing utility functions across microservices or monoliths to reduce duplication (e.g., replacing array_key_exists() with Arrays::contains()).
• Your team prioritizes developer experience (e.g., reducing boilerplate in controllers/services) or consistent error messages (e.g., Assert::notNull() with custom failure messages).
• You need type safety (e.g., ComparableInterface/EquatableInterface support) for complex data structures (e.g., DTOs, collections).
• Your project uses PHP 8.3+ and can tolerate minor API changes (active development suggests forward compatibility).

Look Elsewhere When:

• You require domain-specific utilities (e.g., financial calculations, geospatial operations) not covered by this package.
• Your team prefers zero dependencies or has strict vendor lock-in concerns (though MIT license mitigates this).
• You need enterprise-grade support (e.g., SLAs, security patches) — this is a community-driven package with no dependents.
• The package’s low stars (1) or lack of external adoption raise concerns about long-term viability (mitigate by evaluating release frequency and contributor activity).
• You’re using PHP < 8.3 (minimum version requirement).

How to Pitch It (Stakeholders)

For Executives:

"This utility package is a force multiplier for our development team. By adopting digitalrevolution/utils, we can:

• Cut 20–30% of boilerplate code in array/validation logic, accelerating feature delivery.
• Reduce bugs from inconsistent data handling (e.g., Arrays::equals() ensures predictable comparisons, Arrays::toIntList() removes hand-rolled ID casting).
• Lower maintenance costs by replacing custom utilities with a maintained library (last release: v1.34.0).
• Improve onboarding with clear, documented methods (e.g., Assert::nonEmptyString() for input validation).

For a one-time Composer install (composer require digitalrevolution/utils), we gain a reusable toolkit used internally by a 50+ developer team at 123inkt. This aligns with our goal to [reduce technical debt] while keeping costs minimal."

For Engineering Teams:

"This package solves three key pain points:

1. Array Operations: Replace array_map, array_filter, and nested foreach loops with fluent methods like Arrays::flatten(), Arrays::groupBy(), and Arrays::fetchByPath().
   • Example: Transform a nested API response:

     $grouped = Arrays::groupBy($users, fn($user) => $user['department']);
     

   • Example: Normalize a request-supplied ID list without ad-hoc casts:

     $ids = Arrays::toIntList($request->input('ids', []));
     

2. Validation: Replace verbose if chains with expressive assertions:

   Assert::nonEmptyArray($payload)->notNull($payload['id'])->positiveInt($payload['quantity']);
   

   • Benefits: Clear error messages, reduced nesting, and support for ComparableInterface.
3. Productivity: Add Closures::unfold() for lazy initialization (e.g., feature flags) and Stringify::value() for debugging.

Migration Path:

• Start with assertions in validation layers (e.g., DTOs, API requests).
• Replace array helpers in services/controllers (e.g., Arrays::mapAssoc for payload transformations, Arrays::toIntList for ID normalization).
• Use unfold for deferred service initialization.

Risks: Minimal—package is MIT-licensed, PHP 8.3+, and actively maintained. v1.34.0 is an additive, non-breaking release (Arrays::toIntList plus a dev-only PHPMD v3 bump that does not affect consumers). We can phase adoption by service."*