Initial commit

Author: cspray

.gitattributes

@@ -0,0 +1,4 @@
+.github
+.gitignore
+phpunit.xml
+tests

.github/workflows/ci.yml

@@ -0,0 +1,21 @@
+name: 'Unit Tests'
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  continuous-integration:
+
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v2
+      - name: Composer
+        uses: php-actions/composer@v6
+      - name: Tests
+        uses: php-actions/phpunit@v3
+        with:
+          version: 10.0

.gitignore

@@ -0,0 +1,3 @@
+/vendor
+.phpunit.cache
+.phpunit.result.cache

LICENSE

@@ -0,0 +1,13 @@
+Copyright 2023 Charles Sprayberry
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation
+files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy,
+ modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the
+ Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
+BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

README.md

@@ -0,0 +1,79 @@
+# Stream Buffer Intercept
+
+A PHP testing utility designed to capture stream output and facilitate writing unit tests for systems that require writing to streams.
+
+## Installation
+
+```shell
+composer require --dev cspray/stream-buffer-intercept
+```
+
+## Usage Guide
+
+There are scenarios where you may want to unit test some piece of code that writes to a stream. An example might be where you're writing tests to confirm log messages sent to `stdout` or `stderr`. The `Cspray\StreamBufferIntercept\StreamBuffer` class allows you to easily capture output sent to these streams, and others, to easily assert your expectations.
+
+Let's take a look at a quick code example.
+
+```php
+<?php declare(strict_types=1);
+
+namespace Cspray\StreamBufferDemo;
+
+use Cspray\StreamBufferIntercept\BufferIdentifier;use Cspray\StreamBufferIntercept\StreamBuffer;
+use PHPUnit\Framework\TestCase;
+
+class MyLogger {
+
+    private $stdout;
+    private $stderr;
+
+    public function __construct($stdout, $stderr) {
+        $this->stdout = $stdout;
+        $this->stderr = $stderr;
+    }
+    
+    public function log(string $message) : void {
+        fwrite($this->stdout, $message);
+    }
+    
+    public function logError(string $message) : void {
+        fwrite($this->stderr, $message);
+    }
+
+}
+
+class MyLoggerTest extends TestCase {
+
+    private BufferIdentifier $stdout;
+    
+    private BufferIdentifier $stderr;
+    
+    private MyLogger $subject;
+
+    protected function setUp() : void{
+        StreamBuffer::register();
+        $this->stdout = StreamBuffer::intercept(STDOUT);
+        $this->stderr = StreamBuffer::intercept(STDERR);
+        $this->subject = new MyLogger(STDOUT, STDERR);
+    }
+    
+    protected function tearDown() : void{
+        StreamBuffer::stopIntercepting($this->stdout);
+        StreamBuffer::stopIntercepting($this->stderr);
+    }
+    
+    public function testLogMessageSentToStdOutAndNotStdErr() : void {
+        $this->subject->log('My stdout output'); 
+        
+        self::assertSame('My stdout output', StreamBuffer::output($this->stdout));
+        self::assertSame('', StreamBuffer::output($this->stderr));
+    }
+
+    public function testLogErrorMessageSentToStdErrAndNotStdOut() : void {
+        $this->subject->logError('My stderr output'); 
+        
+        self::assertSame('My stderr output', StreamBuffer::output($this->stderr));
+        self::assertSame('', StreamBuffer::output($this->stdout));
+    }
+}
+```

composer.json

@@ -0,0 +1,21 @@
+{
+  "name": "cspray/stream-buffer-intercept",
+  "description": "A test utility to help capture output sent to stream resources.",
+  "license": ["MIT"],
+  "require": {
+    "php": "^8.1"
+  },
+  "require-dev": {
+    "phpunit/phpunit": "^10.0"
+  },
+  "autoload": {
+    "psr-4": {
+      "Cspray\\StreamBufferIntercept\\": "src"
+    }
+  },
+  "autoload-dev": {
+    "psr-4": {
+      "Cspray\\StreamBufferIntercept\\Test\\": "tests"
+    }
+  }
+}