Fantasy Land Laravel Package

Getting Started

This package is not a traditional Laravel package—it’s a specification (aligned with the Fantasy Land standard) for functional programming constructs like Maybe, Either, IO, etc. To use it in a Laravel app, first install the implementation that conforms to this spec—e.g., webimpressions/fantasy-land or php-functional/php-fantasy-land. Then, require only the specific types you need (e.g., composer require webimpressions/fantasy-land). Start by replacing error-prone parts of your service layer with Maybe::of($value)->map(...)->getOrElse(...) to handle nullable values safely, avoiding NullPointerException risks.

Implementation Patterns

• Service Layer Orchestration: Chain pure transformations using Maybe, Either, or IO to model workflows with error handling (e.g., Either::fromTry(fn () => $this->fetchExternalApi())...fold(...)).
• Validation Pipelines: Use Either to represent validation results—left for errors, right for success—without early exceptions.
• Side-Effect Isolation: Wrap Laravel’s DB::table()->get() or Storage::get() in IO::of(fn () => ...) to defer execution and maintain referential transparency.
• Integration with Laravel: Wrap Laravel helpers (request(), auth()->user()) in IO or Reader (if available in your implementation) to inject dependencies cleanly during testing.
• Custom Domain Types: Define your own App\ValueObjects\Email that implements Map and Chain tocompose domain-safe transformations.

Gotchas and Tips

• ⚠️ No active Laravel integration: This is a low-level spec/implementation—no service provider, no config, no auto-wiring. You must wire everything manually.
• ⚠️ Mutable state & side effects still exist: Fantasy Land types only help structure side effects—they don’t magically prevent bugs. Always map() without side effects; use tap() or chain() (if supported) only for side-effecting functions when absolutely necessary.
• 🔧 Debugging: Implement custom peek() methods on your wrappers (Maybe, Either) to log intermediate values without breaking the chain.
• 📦 Implementation mismatch risk: Different implementations may vary slightly in method names or extras (e.g., mapMaybe vs chainNullable). Lock your version and stick to one implementation across the project.
• 🛠️ Extension tip: Extend core types (e.g., class MyMaybe extends Maybe) to add domain-specific helpers like MyMaybe::fromUser(?User $user) to reduce boilerplate.
• 🧪 Testing: Because types are pure, unit tests become trivial—assert against expected Right/Left or Just/Nothing values without mocking.