PHPackages                             skie/rop - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. skie/rop

ActiveLibrary[Utility & Helpers](/categories/utility)

skie/rop
========

Railway Oriented Programming for PHP

2.0.2(5mo ago)2161[1 PRs](https://github.com/skie/ROP/pulls)MITPHP

Since Dec 20Pushed 5mo ago1 watchersCompare

[ Source](https://github.com/skie/ROP)[ Packagist](https://packagist.org/packages/skie/rop)[ Docs](https://github.com/skie/ROP)[ RSS](/packages/skie-rop/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (1)Dependencies (3)Versions (7)Used By (0)

Railway Oriented Programming (ROP)
==================================

[](#railway-oriented-programming-rop)

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

Motivation
----------

[](#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
--------

[](#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)

[](#one-track-function-1-1)

Has 1 input and 1 output.

[![One track](doc/images/one_track.png)](doc/images/one_track.png)

### Two Track Function (2-2)

[](#two-track-function-2-2)

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

[![Two track](doc/images/two_track.png)](doc/images/two_track.png)

### Switch (1-2)

[](#switch-1-2)

Has 1 input and 2 outputs (`Result`).

[![Switch](doc/images/switch.png)](doc/images/switch.png)

Core Types
----------

[](#core-types)

### Result Monad

[](#result-monad)

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

[![Result](doc/images/result.png)](doc/images/result.png)

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

The foundational type that represents either success or failure:

```
use ROP\Result;

// Create success result
$success = Result::success(42);
$value = $success->getValue();    // 42
$error = $success->getError();    // null
$isSuccess = $success->isSuccess(); // true

// Create failure result
$failure = Result::failure("Invalid input");
$value = $failure->getValue();    // null
$error = $failure->getError();    // "Invalid input"
$isSuccess = $failure->isSuccess(); // false
```

### Railway Core Class

[](#railway-core-class)

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

```
use ROP\Railway;

$result = Railway::of(42)
    ->map(fn($x) => $x * 2)
    ->bind(fn($x) => validateNumber($x));
```

### Pipe

[](#pipe)

Utility class for composing functions left-to-right:

```
use ROP\Pipe;

// Compose functions
$pipeline = Pipe::of(
    fn($x) => $x + 1,
    fn($x) => $x * 2,
    fn($x) => "Result: $x"
);

// Execute pipeline
$result = $pipeline(5);  // "Result: 12"

// With Railway
$railway = Railway::of(5)
    ->bind(Pipe::of(
        fn($x) => $x + 1,
        fn($x) => validateNumber($x),
        fn($x) => saveToDatabase($x)
    ));
```

Installation
------------

[](#installation)

```
composer require your-vendor/rop
```

Quick Start
-----------

[](#quick-start)

```
use ROP\Railway;

// Simple value transformation
$result = Railway::of(42)
    ->map(fn($x) => $x * 2)
    ->map(fn($x) => $x + 1)
    ->match(
        fn($value) => "Success: $value",
        fn($error) => "Error: $error"
    );

// Error handling
$result = Railway::of($userData)
    ->map(fn($data) => new User($data))         // transform data
    ->bind(fn($user) => validateUser($user))    // might fail
    ->bind(fn($user) => saveToDatabase($user))  // might fail
    ->tee(fn($user) => sendWelcomeEmail($user)) // side effect
    ->match(
        fn($user) => ['success' => true, 'id' => $user->id],
        fn($error) => ['success' => false, 'error' => $error]
    );
```

Core Concepts
-------------

[](#core-concepts)

### Creating Railways

[](#creating-railways)

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

```
// Success path
$success = Railway::of($value);

// Failure path
$failure = Railway::fail($error);

// From existing Result
$railway = Railway::fromResult($result);
```

### Mapping Operations

[](#mapping-operations)

#### Map (Success Only)

[](#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.

[![Map](doc/images/map.png)](doc/images/map.png)

```
$result = Railway::of(42)
    ->map(fn($x) => $x * 2);  // transforms success value
```

#### DoubleMap (Both Tracks)

[](#doublemap-both-tracks)

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

[![DoubleMap](doc/images/double-map.png)](doc/images/double-map.png)

```
// Transform both success and error values
$result = Railway::of(42)
    ->doubleMap(
        fn($value) => $value * 2,           // success transformer
        fn($error) => "Error: $error"       // error transformer
    );

// Real-world example: API response formatting
$apiResult = fetchUserData($userId)          // Railway
    ->doubleMap(
        fn(User $user) => [                 // success case
            'status' => 'success',
            'data' => [
                'id' => $user->id,
                'name' => $user->name,
                'email' => $user->email
            ]
        ],
        fn(ApiError $error) => [            // error case
            'status' => 'error',
            'code' => $error->getCode(),
            'message' => $error->getMessage()
        ]
    );

// Localization example
$message = Railway::of($value)
    ->doubleMap(
        fn($val) => translate("success.$val"),
        fn($err) => translate("error.$err")
    );

// Type conversion example
$result = validateInput($data)              // Railway
    ->doubleMap(
        fn(int $n) => new SuccessResponse($n),
        fn(string $err) => new ErrorResponse($err)
    );
```

### Bind

[](#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.

[![Bind](doc/images/bind.png)](doc/images/bind.png)

```
// Chain operations that might fail
$result = Railway::of($input)
    ->bind(fn($x) => validateInput($x))   // returns Railway
    ->bind(fn($x) => processData($x));    // returns Railway
```

### Error Handling

[](#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.

[![TryCatch](doc/images/try-catch.png)](doc/images/try-catch.png)

```
// Try/catch wrapper
$result = Railway::of($riskyData)
    ->tryCatch(
        fn($data) => riskyOperation($data),
        fn(\Throwable $e) => "Failed: " . $e->getMessage()
    );

// Combine multiple operations
$result = Railway::plus(
    fn($r1, $r2) => $r1 + $r2,        // success combiner
    fn($errors) => implode(", ", $errors),  // error combiner
    $railway1,
    $railway2
);
```

### Side Effects

[](#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.

[![Tee](doc/images/tee.png)](doc/images/tee.png)

```
$result = Railway::of($user)
    ->tee(fn($u) => logger("Processing user: {$u->id}"))
    ->bind(fn($u) => updateUser($u))
    ->tee(fn($u) => logger("User updated: {$u->id}"));
```

### Pattern Matching

[](#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.

```
$message = $railway->match(
    success: fn($value) => "Success: $value",
    failure: fn($error) => "Error: $error"
);
```

### Lifting Functions

[](#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.

[![Lift](doc/images/lift.png)](doc/images/lift.png)

```
use ROP\Railway;

// Regular function
$double = fn($x) => $x * 2;

// Lift into Railway
$liftedDouble = Railway::lift($double);

// Use lifted function
$result = Railway::of(21)
    ->bind($liftedDouble);  // Railway

// Compose multiple lifted functions
$result = Railway::of($input)
    ->bind(Railway::lift(validateInput))
    ->bind(Railway::lift(transform))
    ->bind(Railway::lift(save));
```

### Combining Railways

[](#combining-railways)

#### Unite

[](#unite)

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

[![Unite](doc/images/unite.png)](doc/images/unite.png)

```
// Form validation example
$requiredCheck = Railway::of($form->email)
    ->bind(fn($email) => validateRequired($email));    // Railway

$emailCheck = Railway::of($form->email)
    ->bind(fn($email) => validateEmail($email));      // Railway

$result = $requiredCheck->unite($emailCheck);

// File processing example
$existsCheck = Railway::of($path)
    ->bind(fn($p) => checkFileExists($p));           // Railway

$permissionCheck = Railway::of($path)
    ->bind(fn($p) => checkFilePermissions($p));      // Railway

$contentReader = Railway::of($path)
    ->bind(fn($p) => readFileContents($p));          // Railway

$result = $existsCheck
    ->unite($permissionCheck)
    ->unite($contentReader);
```

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

[](#pluswith)

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

[![PlusWith](doc/images/plus.png)](doc/images/plus.png)

```
// Combine user and profile data
$userResult = fetchUser($id);        // Railway
$profileResult = fetchProfile($id);   // Railway

$combined = $userResult->plusWith(
    // Combine success values
    fn(User $user, Profile $profile) => [
        'id' => $user->id,
        'name' => $user->name,
        'avatar' => $profile->avatar
    ],
    // Combine errors
    fn(array $errors) => implode(', ', $errors),
    $profileResult
);

// Parallel validation example
$emailValidation = validateEmail($email);     // Railway
$passwordValidation = validatePassword($pwd);  // Railway

$result = $emailValidation->plusWith(
    fn($email, $password) => new Credentials($email, $password),
    fn($errors) => new ValidationErrors($errors),
    $passwordValidation
);
```

#### Plus (Static Version)

[](#plus-static-version)

Static version of plusWith for combining multiple Railways:

[![Plus](doc/images/plus.png)](doc/images/plus.png)

```
$result = Railway::plus(
    // Combine success values
    fn($user, $profile) => new UserProfile($user, $profile),
    // Combine errors
    fn($errors) => new CombinedError($errors),
    $userResult,
    $profileResult
);
```

Type Safety
-----------

[](#type-safety)

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

```
/** @var Railway */
$result = Railway::of($userData)
    ->map(fn(array $data): User => new User($data))
    ->bind(fn(User $user): Railway => validateUser($user));

/** @var Railway */
$order = Railway::of($orderData)
    ->bind(fn($data) => validateOrder($data))  // might return ValidationError
    ->bind(fn($data) => saveOrder($data));     // might return DbError
```

Benefits
--------

[](#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
--------------------

[](#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
------------

[](#contributing)

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

License
-------

[](#license)

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

###  Health Score

35

—

LowBetter than 80% of packages

Maintenance71

Regular maintenance activity

Popularity10

Limited adoption so far

Community8

Small or concentrated contributor base

Maturity43

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~70 days

Recently: every ~88 days

Total

6

Last Release

164d ago

Major Versions

1.x-dev → 2.0.02025-12-06

### Community

Maintainers

![](https://www.gravatar.com/avatar/f1f53020a99b0b08cda73130f837f37cae2ae8420ff0cc4ceb650a733c4a1bd6?d=identicon)[skiedr](/maintainers/skiedr)

---

Top Contributors

[![skie](https://avatars.githubusercontent.com/u/130799?v=4)](https://github.com/skie "skie (6 commits)")

---

Tags

phpprogrammingorientedrailway

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Type Coverage Yes

### Embed Badge

![Health badge](/badges/skie-rop/health.svg)

```
[![Health](https://phpackages.com/badges/skie-rop/health.svg)](https://phpackages.com/packages/skie-rop)
```

###  Alternatives

[imanghafoori/laravel-anypass

A minimal yet powerful package to help you in development.

21421.6k](/packages/imanghafoori-laravel-anypass)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)