README

A dead simple, minimal REPL (Read-Evaluate-Print-Loop) for PHP 8.2+.

Features

• 🎯 Dead Simple - Minimal codebase with clear, focused classes
• 🧩 Modular - Clean separation of concerns
• 🎨 Modern - Built with PHP 8.2+ features (typed properties, enums, match expressions)
• 🎨 Colorful - Syntax-highlighted output
• 📝 History - Command history support via readline
• 📄 Multiline Support - Automatic detection and explicit backslash continuation
• 🔧 Extensible - Easy to customize and extend

Requirements

• PHP 8.2 or higher
• ext-readline extension

Installation

Install via Composer:

composer require vaibhavpandeyvpz/prayog

Or add to your composer.json:

{
    "require": {
        "vaibhavpandeyvpz/prayog": "^1.0"
    }
}

Then run:

composer install

Usage

Basic Usage

./bin/prayog

Or if installed via Composer:

vendor/bin/prayog

Programmatic Usage

<?php

use Prayog\Config;
use Prayog\Repl;

// Create a custom configuration
$config = new Config(
    prompt: 'myapp> ',
    historyFile: '/path/to/history',
    colorOutput: true,
    welcomeMessage: "Welcome to MyApp REPL!\nPHP " . PHP_VERSION,
);

// Create and start the REPL
$repl = new Repl($config);

// Optionally set initial variables
$repl->setVariable('app', $myApp);
$repl->setVariables(['user' => $user, 'db' => $db]);

// Start the REPL
$repl->start();

Examples

prayog> $x = 42
int(42)

prayog> $name = "Prayog"
string(6) "Prayog"

prayog> $numbers = [1, 2, 3, 4, 5]
array(5) [0 => 1, 1 => 2, 2 => 3, ...]

prayog> array_sum($numbers)
int(15)

prayog> class Calculator {
*>     public function add($a, $b) {
*>         return $a + $b;
*>     }
*> }

prayog> $calc = new Calculator()
object(Calculator)

prayog> $calc->add(10, 20)
int(30)

prayog> exit

Multiline Input

Prayog supports multiline input in two ways:

1. Automatic Detection - The REPL automatically detects incomplete statements (unbalanced braces, brackets, parentheses) and continues reading:

prayog> if ($x > 0) {
*>     echo "Positive";
*> }

1. Backslash Continuation - Use a backslash (\) at the end of a line to explicitly continue on the next line:

prayog> $result = $a + \
*>     $b + \
*>     $c
int(15)

Configuration

The Config class allows you to customize the REPL behavior:

• prompt (string, default: 'prayog> ') - The prompt string displayed before each input
• historyFile (string|null, default: null) - Path to history file. If null, uses ~/.prayog_history
• colorOutput (bool, default: true) - Enable/disable colored output
• welcomeMessage (string|null, default: null) - Custom welcome message. If null, shows default message

Example with custom welcome message:

$config = new Config(
    prompt: 'myapp> ',
    welcomeMessage: "MyApp Interactive Shell\nVersion 1.0.0\n",
);
$repl = new Repl($config);

Testing

The library includes comprehensive test coverage. To run the tests:

# Install development dependencies
composer install

# Run tests
vendor/bin/phpunit

# Run tests with coverage (requires xdebug)
XDEBUG_MODE=coverage vendor/bin/phpunit --coverage-text

Test Coverage

The test suite includes:

• 110 tests covering all components
• 79% code coverage (core logic at 100%)
• Tests for Config, Evaluator, Formatter, ReadlineInput, and Repl classes
• Integration tests and edge case handling

Architecture

The library is organized into clean, focused modules:

• Repl - Main REPL class that orchestrates the read-eval-print loop
• Config - Configuration with sensible defaults
• Input\ReadlineInput - Handles readline input and history
• Evaluator - Evaluates PHP code and manages variable scope
• Output\Formatter - Formats output with syntax highlighting

All classes are designed to be extensible - you can extend any class to customize behavior.

Contributing

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

License

MIT License - see LICENSE file for details.