Option Laravel Package

Technical Evaluation

Architecture Fit

• Functional Paradigm Alignment: The Option type enforces explicit presence/absence semantics, aligning with functional programming principles. This is particularly valuable in Laravel for:
  • Domain Models: Clearly distinguishing between "not found" (e.g., User::find(999) → None) and "found but empty" (e.g., User::find(1)->address → None).
  • API Layers: Explicitly marking missing data in responses (e.g., Option<Payment> vs. null for failed transactions).
  • Configuration: Validating required vs. optional settings (e.g., Option::fromNullable(env('DB_HOST'))).
• Laravel-Specific Synergies:
  • Eloquent Integration: Wrapping query results in Option enforces null safety for ORM operations (e.g., Option::fromNullable(User::find($id))).
  • Service Container: Can be used to explicitly handle dependency injection failures (e.g., Option::fromNullable(app()->make('MissingService'))).
• Anti-Patterns:
  • Overhead for Simple Cases: For trivial CRUD operations where null is sufficient, Option introduces unnecessary complexity.
  • Cognitive Load: Teams unfamiliar with monadic patterns may resist adoption due to learning curve (e.g., map/flatMap vs. if/else).

Integration Feasibility

• Laravel Compatibility:
  • Native PHP: Zero Laravel-specific dependencies; works anywhere PHP 8.0+ runs.
  • Eloquent: Seamless integration via Option::fromNullable($model) for query results.
  • Collections: Leverages Laravel’s Collection methods (e.g., map, filter) but requires explicit Option handling.
  • Service Container: Can be auto-resolved if registered as a binding (e.g., Option::class => fn() => Option::none()).
• Performance:
  • Runtime Overhead: Minimal (~1–2 method calls per operation). Benchmarking shows negligible impact vs. null checks.
  • Memory: Slight increase for Some cases (object wrapping), but insignificant at scale.
• Tooling:
  • Static Analysis: Requires custom PHPStan/Nikita rules to enforce Option usage (e.g., Option where null was previously allowed).
  • IDE Support: Limited autocompletion for Option methods (e.g., isSome(), unwrap()).

Technical Risk

• Breaking Changes:
  • Refactoring Scope: Replacing null with Option requires updating all return types and method signatures (e.g., function getUser(): ?User → function getUser(): Option).
  • Legacy Code: Mixed null/Option logic may cause runtime errors if not handled via adapters (e.g., Option::fromNullable($legacyResult)).
• Tooling Gaps:
  • Static Analysis: May flag false positives/negatives without tailored rules.
  • Debugging: Stack traces for Option::map calls may obscure the original null source.
• Testing:
  • Requires updating tests to handle Option assertions (e.g., assertTrue($option->isSome())).
  • Edge cases (e.g., nested Options) need validation.

Key Questions

1. Adoption Strategy:
   • Should Option be global (all nullable types) or targeted (specific domains like Order/User)?
2. Backward Compatibility:
   • How will legacy null-returning methods coexist with new Option-returning methods?
3. Team Readiness:
   • Does the team have experience with functional patterns (e.g., Rust’s Option, Scala’s Either)?
4. Alternatives:
   • Could null + @phpstan-ignore or PHP 8.1’s null attributes suffice for the use case?
5. Testing Strategy:
   • How will edge cases (e.g., nested Options, None handling) be validated in CI/CD?
6. Performance Tradeoffs:
   • Is the minimal overhead acceptable for the maintainability gains?

Integration Approach

Stack Fit

• PHP/Laravel Ecosystem:
  • Best Fit: Projects already using functional patterns (e.g., with libraries like spatie/array-to-object or league/pipe) or those prioritizing null safety.
  • Challenges:
    • Magic Methods: Laravel’s dynamic properties (e.g., User::address->city) may conflict with Option chaining (e.g., $user->address()->city()).
    • Middleware: May need adapters to convert between null and Option (e.g., Option::fromNullable($request->input('optional_field'))).
• Tooling Integration:
  • PHPStan: Configure to expect Option types where null was previously allowed (e.g., Option instead of ?Type).
  • Laravel Mix: No impact (pure PHP library).
  • Database: ORM layers (Eloquent) will need wrappers for raw queries (e.g., Option::fromNullable($query->first())).

Migration Path

1. Phase 1: Proof of Concept (2–4 weeks)

   • Scope: Isolate a single domain (e.g., Order entity) and refactor all nullable fields to Option.
   • Tasks:
     • Replace ?Type with Option in return types (e.g., function getShippingAddress(): Option).
     • Update 1–2 controllers/services to use Option methods (map, filter, unwrap).
     • Add Option-aware Blade helpers (e.g., @if($option->isSome())).
   • Validation: Measure bug reduction in null handling (e.g., fewer NullPointerException-like errors).

2. Phase 2: Incremental Adoption (4–8 weeks)

   • New Features: Default to Option for all nullable returns.
   • Legacy Code: Use adapters to bridge null and Option (e.g., Option::fromNullable($legacyResult)).
   • Testing: Add Option-aware assertions (e.g., assertSame(Some::create($value), $option)).
   • Static Analysis: Update PHPStan/Nikita rules to enforce Option usage.
   • Documentation: Create internal guidelines for Option patterns (e.g., "Always handle None cases").

3. Phase 3: Full Migration (8–12 weeks)

   • Deprecation: Phase out null-returning methods in favor of Option.
   • Training: Conduct workshops on Option patterns (e.g., map vs. if/else).
   • Tooling: Integrate Option into CI/CD (e.g., fail builds on unhandled None cases).

Compatibility

• Laravel-Specific:
  • Eloquent: Wrap query results in Option (e.g., Option::fromNullable(User::find($id))).
  • Request Validation: Convert nullable rules to Option handling in Form Requests:

    public function rules(): array {
        return [
            'optional_field' => ['sometimes', 'string'],
        ];
    }
    // In controller:
    $value = Option::fromNullable($request->optional_field);
    

  • Blade Templates: Create helpers like:

    @if($option->isSome())
        {{ $option->unwrap()->name }}
    @else
        <span class="text-gray">Not available</span>
    @endif
    

• Third-Party Libraries:
  • API Clients: Wrap responses in Option (e.g., Option::fromNullable($api->get('user'))).
  • Queues/Jobs: Ensure payloads are Option-compatible (e.g., Option<User> in job data).
  • Legacy ORMs: Use adapters to convert raw results to Option.

Sequencing