Merge branch '2.x' into 3.x

* 2.x:
  Add stream utility

Author: bkdotcom

src/HttpMessage/Utility/Stream.php

@@ -0,0 +1,45 @@
+<?php
+
+/**
+ * This file is part of HttpMessage
+ *
+ * @package   bdk/http-message
+ * @author    Brad Kent <bkfake-github@yahoo.com>
+ * @license   http://opensource.org/licenses/MIT MIT
+ * @copyright 2014-2024 Brad Kent
+ * @since     x.3.3
+ */
+
+namespace bdk\HttpMessage\Utility;
+
+use Exception;
+use Psr\Http\Message\StreamInterface;
+
+/**
+ * Stream Utilities
+ *
+ * @psalm-api
+ */
+class Stream
+{
+    /**
+     * Get stream contents without affecting pointer
+     *
+     * @param StreamInterface $stream StreamInterface
+     *
+     * @return string
+     */
+    public static function getContents(StreamInterface $stream)
+    {
+        try {
+            $pos = $stream->tell();
+            $body = (string) $stream; // __toString() is like getContents(), but without throwing exceptions
+            $stream->seek($pos);
+            return $body;
+            // @codeCoverageIgnoreStart
+        } catch (Exception $e) {
+            return '';
+            // @codeCoverageIgnoreEnd
+        }
+    }
+}

tests/HttpMessage/Utility/UtilityTest.php

@@ -0,0 +1,23 @@
+<?php
+
+namespace bdk\Test\HttpMessage\Utility;
+
+use bdk\HttpMessage\Stream;
+use bdk\HttpMessage\Utility\Stream as StreamUtility;
+use PHPUnit\Framework\TestCase;
+
+/**
+ * @covers bdk\HttpMessage\Utility\Response
+ *
+ * @phpcs:disable SlevomatCodingStandard.Arrays.AlphabeticallySortedByKeys.IncorrectKeyOrder
+ */
+class UtilityTest extends TestCase
+{
+    public function testGetStreamContents()
+    {
+        $stream = new Stream('this is a test');
+        $stream->seek(8);
+        self::assertSame('this is a test', StreamUtility::getContents($stream));
+        self::assertSame('a test', $stream->getContents());
+    }
+}