Developing 1.0.0

.github/workflows/ci.yml

@@ -19,6 +19,9 @@ jobs:
       - name: Checkout code
         uses: actions/checkout@v4
 
+      - name: Unset local path repositories
+        run: composer config --unset repositories
+
       - name: Setup PHP
         uses: shivammathur/setup-php@v2
         with:
@@ -45,36 +48,47 @@ jobs:
         run: composer test
 
   lint:
-    name: Code Style (PHP-CS-Fixer)
+    name: PHP ${{ matrix.php }} Code Style (PHP-CS-Fixer)
     runs-on: ubuntu-latest
-
+    strategy:
+      fail-fast: false
+      matrix:
+        php: ['8.2', '8.3', '8.4']
+
     steps:
       - name: Checkout code
         uses: actions/checkout@v4
 
       - name: Setup PHP
         uses: shivammathur/setup-php@v2
         with:
-          php-version: 8.3
+          php-version: ${{ matrix.php }}
           extensions: mbstring, json
           coverage: none
           tools: php-cs-fixer
 
       - name: Run PHP-CS-Fixer
-        run: php-cs-fixer fix --dry-run --diff --verbose
+        run: php-cs-fixer fix --dry-run --diff --verbose --allow-risky=yes
 
   static-analysis:
-    name: Static Analysis (PHPStan)
+    name: PHP ${{ matrix.php }} Static Analysis (PHPStan)
     runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        php: ['8.2', '8.3', '8.4']
 
     steps:
       - name: Checkout code
         uses: actions/checkout@v4
 
+      - name: Unset local path repositories
+        run: composer config --unset repositories
+
       - name: Setup PHP
         uses: shivammathur/setup-php@v2
         with:
-          php-version: 8.3
+          php-version: ${{ matrix.php }}
           extensions: mbstring, json, pcntl, posix, zlib, sockets
           coverage: none
 
@@ -83,9 +97,9 @@ jobs:
         uses: actions/cache@v4
         with:
           path: vendor
-          key: ${{ runner.os }}-php-8.3-${{ hashFiles('**/composer.lock') }}
+          key: ${{ runner.os }}-php-${{ matrix.php }}-${{ hashFiles('**/composer.lock') }}
           restore-keys: |
-            ${{ runner.os }}-php-8.3-
+            ${{ runner.os }}-php-${{ matrix.php }}-
 
       - name: Install dependencies
         run: composer install --prefer-dist --no-progress

README.md

@@ -1,6 +1,6 @@
 # Phunkie Effect
 
-[![CI](https://github.com/phunkie/effect/workflows/CI/badge.svg)](https://github.com/phunkie/effect/actions)
+[![CI](https://github.com/phunkie/effect/actions/workflows/ci.yml/badge.svg)](https://github.com/phunkie/effect/actions)
 [![Latest Version](https://img.shields.io/packagist/v/phunkie/effect.svg?style=flat-square)](https://packagist.org/packages/phunkie/effect)
 [![Total Downloads](https://poser.pugx.org/phunkie/effect/downloads)](https://packagist.org/packages/phunkie/effect)
 [![License](https://img.shields.io/packagist/l/phunkie/effect.svg?style=flat-square)](https://github.com/phunkie/effect/blob/main/LICENSE)

composer.json

@@ -10,15 +10,14 @@
         }
     ],
     "require": {
-        "php": ">=8.2",
-        "phunkie/phunkie": "^0.11"
+        "php": "^8.2 || ^8.3 || ^8.4",
+        "phunkie/phunkie": "^1.0"
     },
     "require-dev": {
         "phpunit/phpunit": "^10.5",
-        "phunkie/phunkie-console": "dev-master",
         "phpstan/phpstan": "^2.1",
-        "friendsofphp/php-cs-fixer": "^3.75"
-
+        "phunkie/phpstan": "^1.0",
+        "friendsofphp/php-cs-fixer": "^3.90"
     },
     "suggest": {
         "ext-parallel": "Required for parallel execution using threads. PHP must be compiled with ZTS support."
@@ -38,9 +37,18 @@
     },
     "scripts": {
         "test": "phpunit",
-        "phpstan": "phpstan analyse",
-        "cs-fix": "php-cs-fixer fix",
-        "cs-check": "php-cs-fixer fix --dry-run --diff"
+        "phpstan": "phpstan analyse --memory-limit=512M",
+        "cs-fix": "php-cs-fixer fix --allow-risky=yes",
+        "cs-check": "php-cs-fixer fix --dry-run --diff --allow-risky=yes",
+        "lint": [
+            "@cs-check",
+            "@phpstan"
+        ],
+        "test-all": "scripts/test-all-versions.sh",
+        "check": [
+            "@lint",
+            "@test"
+        ]
     },
     "minimum-stability": "dev",
     "prefer-stable": true,

docs/index.md

@@ -2,25 +2,50 @@
 
 A functional effects library for PHP inspired by Scala's cats-effect. Phunkie Effects provides a way to manage side effects in a purely functional way, making your code more predictable, testable, and maintainable.
 
-## Table of Contents
+## Overview
 
-1. [Introduction](introduction.md)
+Phunkie Effect brings the power of purely functional programming to PHP, allowing you to describe side effects as values that can be composed, tested, and reasoned about before execution.
+
+## Getting Started
+
+New to Phunkie Effect? Start here:
+
+- [Introduction](introduction.md) - Learn what Phunkie Effect is and when to use it
+- [Getting Started](getting-started.md) - Installation and your first effect
+- [IO App and Console](io-app.md) - Build command-line applications
+
+## Core Concepts
+
+Master the fundamental building blocks:
+
+- [Combinators](combinators.md) - Core IO operations and composition patterns
+- [Resources](resources.md) - Safe resource management with brackets
+- [Concurrency](concurrency.md) - Parallel execution and concurrent programming
+
+## Documentation Index
+
+### 1. [Introduction](introduction.md)
    - What is Phunkie Effect?
    - Philosophy and design goals
    - When to use Phunkie Effect
 
-2. [Getting Started](getting-started.md)
+### 2. [Getting Started](getting-started.md)
    - Installation
    - Basic Usage
    - Your First Effect
 
-3. [IO App and IO Console](io-app.md)
+### 3. [IO App and IO Console](io-app.md)
    - Console Functions
    - Creating an IO App
    - Exit Codes and Error Handling
    - Best Practices
 
-4. [Concurrency](concurrency.md)
+### 4. [Combinators](combinators.md)
+   - Core IO Operations
+   - Error Handling
+   - Composition Patterns
+
+### 5. [Concurrency](concurrency.md)
    - Blockers
    - Execution Context
    - Parallel Execution
@@ -30,48 +55,20 @@ A functional effects library for PHP inspired by Scala's cats-effect. Phunkie Ef
    - Delay
    - Channels
 
-5. [Resources](resources.md)
+### 6. [Resources](resources.md)
    - Brackets
    - Resource Combinators
    - Files
    - URL
    - Database
 
-6. [Networks](networks.md)
-    - TCP
-      - Server
-      - Client
-      - Connection Management
-    - UDP
-      - Datagram Handling
-      - Broadcasting
-      - Multicasting
-
-7. [Cookbook](cookbook.md)
-    - Supervisor Patterns
-      - One-for-One Strategy
-      - All-for-One Strategy
-      - Custom Supervision
-    - Shared State with Ref
-      - Atomic Updates
-      - Cross-Fiber Communication
-    - Graceful Shutdown
-      - Resource Cleanup
-      - Signal Handling
-    - Circuit Breakers
-      - Failure Detection
-      - Automatic Recovery
-    - Rate Limiting
-      - Token Bucket
-      - Leaky Bucket
-
 ## Contributing
 
 Contributions are welcome! Please feel free to submit a Pull Request.
 
-## License
+## Licence
 
-This project is licensed under the MIT License - see the LICENSE file for details.
+This project is licensed under the MIT Licence - see the LICENCE file for details.
 
 ## Acknowledgments
 

docs/introduction.md

@@ -0,0 +1,147 @@
+# Introduction to Phunkie Effect
+
+## What is Phunkie Effect?
+
+Phunkie Effect is a functional effects library for PHP that brings the power of purely functional programming to side effect management. Inspired by Scala's cats-effect and built on top of the Phunkie functional programming library, it provides a robust framework for writing predictable, composable, and testable code.
+
+At its core, Phunkie Effect introduces the `IO` monad - a data structure that represents a computation that may perform side effects. Unlike traditional imperative code where side effects happen immediately, `IO` allows you to describe what should happen without actually executing it. This separation of description from execution is the key to writing purely functional code in PHP.
+
+```php
+use Phunkie\Effect\IO;
+
+// This doesn't execute anything - it just describes what should happen
+$program = io(fn() => file_get_contents('config.json'))
+    ->map(fn($json) => json_decode($json, true))
+    ->flatMap(fn($config) => io(fn() => connectToDatabase($config['db'])));
+
+// The program only runs when you explicitly call unsafeRun()
+$result = $program->unsafeRun();
+```
+
+## Philosophy and Design Goals
+
+### Referential Transparency
+
+Phunkie Effect is built on the principle of referential transparency - the idea that you should be able to replace an expression with its value without changing the program's behavior. This makes code easier to reason about, test, and refactor.
+
+```php
+// Without IO - side effects happen immediately
+$data = file_get_contents('data.txt'); // Executes now!
+$result = processData($data);
+
+// With IO - side effects are described, not executed
+$program = io(fn() => file_get_contents('data.txt'))
+    ->map(fn($data) => processData($data));
+// Nothing has executed yet - we can compose, test, and reason about it
+```
+
+### Composability
+
+Effects should compose just like pure functions. Phunkie Effect provides a rich set of combinators that allow you to build complex programs from simple building blocks.
+
+```php
+$readConfig = io(fn() => file_get_contents('config.json'));
+$parseJson = fn($json) => io(fn() => json_decode($json, true));
+$validateConfig = fn($config) => io(fn() => validate($config));
+
+// Compose them together
+$program = $readConfig
+    ->flatMap($parseJson)
+    ->flatMap($validateConfig);
+```
+
+### Resource Safety
+
+Managing resources (files, database connections, network sockets) is error-prone. Phunkie Effect provides automatic resource management through brackets, ensuring cleanup happens even when errors occur.
+
+```php
+use function Phunkie\Effect\Functions\blocking\blocking;
+
+$result = bracket(
+    // Acquire
+    blocking(fn() => fopen('file.txt', 'r')),
+    // Use
+    fn($handle) => blocking(fn() => fread($handle, 1024)),
+    // Release
+    fn($handle) => blocking(fn() => fclose($handle))
+);
+```
+
+### Testability
+
+By separating effect description from execution, your code becomes trivially testable. You can test the logic without performing actual side effects.
+
+```php
+// Your business logic returns IO values
+function processOrder(Order $order): IO {
+    return saveToDatabase($order)
+        ->flatMap(fn() => sendConfirmationEmail($order->email))
+        ->flatMap(fn() => updateInventory($order->items));
+}
+
+// In tests, you can inspect the IO structure without executing it
+$io = processOrder($testOrder);
+// Assert on the structure, or provide test implementations
+```
+
+### Concurrency and Parallelism
+
+Phunkie Effect provides safe, composable concurrency primitives that make it easy to write concurrent programs without the typical pitfalls of shared mutable state.
+
+```php
+use function Phunkie\Effect\Functions\io\io;
+
+// Run multiple effects in parallel
+$result = $fetchUserData
+    ->parMap2($fetchOrderHistory, fn($user, $orders) => [$user, $orders])
+    ->unsafeRun();
+```
+
+## When to Use Phunkie Effect
+
+### Perfect For:
+
+**Complex Applications with Many Side Effects**
+- Web applications with database access, external APIs, file I/O
+- CLI tools that interact with the filesystem and network
+- Background workers and job processors
+
+**Applications Requiring High Reliability**
+- Financial systems where correctness is critical
+- Healthcare applications with strict error handling requirements
+- Any system where bugs have serious consequences
+
+**Concurrent and Parallel Processing**
+- Data processing pipelines
+- Microservices that need to coordinate multiple operations
+- Applications that benefit from parallel execution
+
+**Testable Code**
+- When you need comprehensive test coverage
+- When you want to test business logic without hitting real databases/APIs
+- When you need to verify error handling paths
+
+### Consider Alternatives When:
+
+**Simple Scripts**
+- One-off scripts with minimal side effects
+- Quick prototypes where correctness isn't critical
+
+**Performance-Critical Hot Paths**
+- While Phunkie Effect is reasonably performant, the abstraction overhead may not be suitable for extremely performance-sensitive code
+- Consider using it for the application structure and dropping down to imperative code for hot paths
+
+**Team Unfamiliar with Functional Programming**
+- There's a learning curve to functional programming concepts
+- Ensure your team is willing to invest in learning these patterns
+
+## Getting Started
+
+Ready to dive in? Check out the [Getting Started](getting-started.md) guide to install Phunkie Effect and write your first effectful program.
+
+## Learn More
+
+- [IO App and Console](io-app.md) - Build command-line applications
+- [Combinators](combinators.md) - Core operations for working with IO
+- [Concurrency](concurrency.md) - Parallel and concurrent execution
+- [Resources](resources.md) - Safe resource management