Or Else Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require spatie/or-else
   

   No configuration is required—just use the trait directly.

2. First Use Case: Add the OrElse trait to any class (e.g., a model, service, or DTO) to enable orElse() behavior:

   use Spatie\OrElse\OrElse;
   
   class UserService
   {
       use OrElse;
   
       public function getUser($id)
       {
           return User::find($id);
       }
   }
   

   Now call it with a fallback:

   $user = app(UserService::class)->getUser(1)->orElse(fn() => User::find(2));
   

Where to Look First

• Trait Documentation: The package is self-documenting—focus on the orElse() method’s behavior.
• Use Cases: Ideal for optional method chaining (e.g., find()->orElse(fn() => defaultValue())).

Implementation Patterns

Core Workflow

1. Method Chaining with Fallbacks: Use orElse() to provide a default value or alternative logic when the primary result is null or false:

   $result = $this->fetchData()->orElse(fn() => $this->fetchCache());
   

2. Integration with Laravel Collections: Combine with collections for fluent fallbacks:

   $items = collect($this->getItems())->orElse(fn() => collect([]));
   

3. Service Layer Abstraction: Encapsulate fallback logic in services:

   class OrderService
   {
       use OrElse;
   
       public function getOrder($id)
       {
           return Order::find($id);
       }
   
       public function resolveOrder($id)
       {
           return $this->getOrder($id)->orElse(fn() => $this->createDefaultOrder());
       }
   }
   

Advanced Patterns

• Closure-Based Fallbacks: Defer expensive operations until needed:

  $user = $this->findUser()->orElse(fn() => $this->loadFromExternalApi());
  

• Static Method Usage: Apply to static methods for utility classes:

  class StringHelper
  {
      use OrElse;
  
      public static function getEnv($key)
      {
          return env($key);
      }
  }
  // Usage:
  $value = StringHelper::getEnv('APP_NAME')->orElse('DefaultApp');
  

• Testing: Mock fallbacks in tests:

  $this->mock(UserService::class)
       ->shouldReceive('getUser')
       ->andReturnNull()
       ->once();
  $result = app(UserService::class)->getUser(999)->orElse(fn() => 'fallback');
  $this->assertEquals('fallback', $result);
  

Gotchas and Tips

Pitfalls

1. Null vs. False: orElse() triggers on both null and false. Use orElseIf() (if available in extensions) for precise control:

   // Hypothetical: if the package supported it
   $value = $this->getValue()->orElseIf(is_null, fn() => 'null fallback');
   

2. Performance: Avoid heavy fallbacks in tight loops. Cache or lazy-load:

   // Bad: Expensive fallback in loop
   foreach ($ids as $id) {
       $this->getData($id)->orElse(fn() => $this->slowOperation());
   }
   // Good: Pre-compute or use static fallbacks
   

3. Trait Conflicts: If another trait uses the same method name (e.g., orElse), resolve conflicts with:

   class MyClass {
       use \Spatie\OrElse\OrElse {
           orElse as private orElseSpatie;
       }
   
       public function orElse($callback) {
           return $this->orElseSpatie($callback);
       }
   }
   

Debugging Tips

• Check Return Types: Ensure methods returning null/false are intentional. Use orElse() only for optional values.

  // Debug: Log the value before orElse
  $value = $this->getValue();
  \Log::debug('Value before fallback:', ['value' => $value]);
  $result = $value->orElse('fallback');
  

• Closure Scope: Closures in orElse() inherit the class scope. Access private properties/methods directly:

  $user = $this->findUser()->orElse(fn() => $this->createDefault());
  

Extension Points

1. Custom Logic: Extend the trait to add orElseIf or orElseThrow:

   trait CustomOrElse {
       public function orElseIf($condition, $callback) {
           return $this->value === null ? $callback() : $this->value;
       }
   }
   

2. Integration with Laravel: Combine with optional() for stricter null checks:

   $value = optional($this->getValue())->orElse(fn() => 'fallback');
   

3. Legacy Code: Use orElse() to migrate away from ternary checks:

   // Before:
   $user = $this->findUser() ?: $this->createDefault();
   // After:
   $user = $this->findUser()->orElse(fn() => $this->createDefault());