Download the PHP package skie/rop without Composer

Railway Oriented Programming (ROP)

A PHP implementation of Railway Oriented Programming pattern for elegant error handling.

Motivation

Typically every use case receives a request and produces a response. The use case passes for several steps until gets the final response to be returned. Handle every error scenario could be tedious and difficult to read.

Overview

Railway Oriented Programming is a functional programming pattern that helps manage complexity in error handling by treating the flow of data like a railway track with two lines:

• Success track (happy path)
• Failure track (error path)

Railways have switches ("points" in the UK) for directing trains onto a different track. We can think of these "Success/Failure" functions as railway switches.

One Track Function (1-1)

Has 1 input and 1 output.

Two Track Function (2-2)

Has 2 inputs (Result) and 2 outputs (Result).

Switch (1-2)

Has 1 input and 2 outputs (Result).

Core Types

Result Monad

In order to have a type that works with any workflow, we borrow the type Result from functional programming:

This object acts as a switch, where left means failure and the right means success.

The foundational type that represents either success or failure:

Railway Core Class

Builds on top of Result to provide a fluent interface for chaining operations:

Pipe

Utility class for composing functions left-to-right:

Installation

Quick Start

Core Concepts

Creating Railways

Railway is a class that allows you to create a Railway instance. It takes a value and returns a Railway.

Mapping Operations

Map (Success Only)

Map is a method that allows you to transform the success value of a Railway. It takes a function that transforms the success value and returns a Railway.

DoubleMap (Both Tracks)

Maps both success and failure paths simultaneously. Useful when you need to transform both success and error values:

Bind

Bind is a method that allows you to chain operations that might fail. It takes a function that returns a Railway and returns a Railway.

Error Handling

TryCatch is a method that allows you to wrap an existing try/catch block in a Railway. It takes a function that returns a Railway and returns a Railway.

Side Effects

Tee is a method that allows you to perform side effects on a Railway. It takes a function that performs the side effect and returns a Railway.

Pattern Matching

Match is a method that allows you to match on the success or failure of a Railway. It takes a function that returns a Railway and returns a Railway.

Lifting Functions

Lift is a method that allows you to convert regular functions into Railway-compatible ones. It takes a function and returns a Railway.

Combining Railways

Unite

Joins two Railways, taking the second Railway's value if the first one succeeds:

The unite method is particularly useful when:

• You have a sequence of validations
• You need to perform setup steps before an operation
• You want to chain operations but only care about the final result
• You're building a pipeline where intermediate results aren't needed

PlusWith

Combines two Railways in parallel, allowing custom combination of success and failure values:

Plus (Static Version)

Static version of plusWith for combining multiple Railways:

Type Safety

The library provides full type safety with PHP 8.0+ and PHPStan:

Benefits

1. Explicit Error Handling: No hidden exceptions or null checks
2. Composable Operations: Chain transformations and error handling
3. Type Safety: Full type inference and checking with PHPStan
4. Immutable: No side effects or state mutations
5. Readable: Clear, linear flow of operations
6. Flexible: Handle any combination of success/error types
7. Maintainable: Easy to add new transformations or error cases

Railway Api Patterns

1. Use map for simple transformations
2. Use bind when operations might fail
3. Use tee for logging and side effects
4. Use tryCatch to wrap existing try/catch blocks
5. Use lift to convert regular functions into Railway-compatible ones
6. Use unite when chaining operations and only care about the final result
7. Use plusWith when combining multiple Railways with custom error handling
8. Use plus when combining multiple Railways with default error handling
9. Use type hints when combining multiple error types
10. Keep transformations small and focused
11. Use descriptive error types instead of strings

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License - see the LICENSE file for details.