Added phpdoc comments for CompressedStringList and some notes for my forked GzStreamGuzzle class

Author: orware

src/CompressedString.php

@@ -147,9 +147,6 @@ public function getPath()
     * in these situations you may use the optional $options
     * and $depth parameters.
     *
-    * Returns the current size (in bytes) of the uncompressed data that has
-    * been written so far.
-    *
     * @param mixed $string
     * @param int $options
     * @param int $depth
@@ -215,7 +212,7 @@ public function read($length = 65536)
     public function prepend($string, $compressionLevel = 6)
     {
         $this->prepareForRead();
-        $gzStreamReadOnly = $this->getGzStream()->readOnlyStream();
+        $gzStreamReadOnly = $this->getGzStream()->getReadOnlyCopy();
 
         $this->replaceStream(false, $compressionLevel, 'php://memory');
 
@@ -374,20 +371,23 @@ public function getCompressedReadOnlyStream()
     }
 
     /**
-    * put your comment there...
+    * Returns a read-only stream that can be used
+    * for reading the decompressed contents back out
+    * as a stream.
     *
+    * @return GzStreamGuzzle
     */
     public function getDecompressedReadOnlyStream()
     {
         if ($this->isRealFile && $this->isReadOnly()) {
             return $this->getGzStream();
         } elseif ($this->isRealFile) {
-            return $this->getGzStream()->readOnlyStream();
+            return $this->getGzStream()->getReadOnlyCopy();
         }
 
         // More specifically for the in-memory streams:
         $this->prepareForRead();
-        $gzStreamReadOnly = $this->getGzStream()->readOnlyStream();
+        $gzStreamReadOnly = $this->getGzStream()->getReadOnlyCopy();
 
         return $gzStreamReadOnly;
     }

src/CompressedStringList.php

@@ -1,17 +1,68 @@
 <?php
 namespace Orware\Compressed;
 
+/**
+* Compressed String List Class
+*
+* Allows you to queue up multiple instances of CompressedString
+* so that you can use later or with the merge method, which allows
+* a new compressed string to be created with the combined output.
+*
+* e.g. Merging one or more compressed JSON strings of database results
+* into a JSON object containing metadata.
+*
+*/
 class CompressedStringList
 {
+    /**
+    * The internal SplQueue instance
+    *
+    * @var \SplQueue
+    */
     protected $queue = null;
 
-    public function __construct()
+    /**
+    * Creates the CompressedStringList
+    *
+    * By default it will not keep copies of the
+    * queued objects during iteration in order to
+    * conserve memory usage.
+    *
+    */
+    public function __construct($keep = false)
     {
         $this->queue = new \SplQueue();
-        $this->queue->setIteratorMode(\SplDoublyLinkedList::IT_MODE_FIFO | \SplDoublyLinkedList::IT_MODE_DELETE);
+        $mode = \SplDoublyLinkedList::IT_MODE_DELETE;
+        if ($keep) {
+            $mode = \SplDoublyLinkedList::IT_MODE_KEEP;
+        }
+        $this->queue->setIteratorMode(\SplDoublyLinkedList::IT_MODE_FIFO | $mode);
     }
 
-    public static function merge($subject, $delimiter, CompressedStringList $gzippedStrings, $compressionLevel = 6, $addQuotesToDelimiter = false)
+    /**
+    * Merges multiple CompressedStrings contained
+    * in a CompressedStringList into the $subject
+    * string based on the locations of the $delimiter.
+    *
+    * The subject will normally be a string, but you may also
+    * provide an array or object and it will be JSON encoded and then
+    * split on the provided delimiter.
+    *
+    * You may optionally provide a new compression level
+    * and make use of the option to automatically add quotes
+    * to the delimiter (useful for when the delimiter has been added
+    * to text that was then JSON encoded, otherwise your inserted text might
+    * included additional quotes around it that you won't want).
+    *
+    * @param mixed $subject
+    * @param string $delimiter
+    * @param CompressedStringList $compressedStringList
+    * @param int $compressionLevel
+    * @param bool $addQuotesToDelimiter
+    *
+    * @return CompressedString
+    */
+    public static function merge($subject, $delimiter, CompressedStringList $compressedStringList, $compressionLevel = 6, $addQuotesToDelimiter = false)
     {
         if (!is_string($subject)) {
             $subject = json_encode($subject);
@@ -27,8 +78,8 @@ public static function merge($subject, $delimiter, CompressedStringList $gzipped
 
         foreach ($subjectParts as $part) {
             $merged->write($part);
-            if (!$gzippedStrings->isEmpty()) {
-                $string = $gzippedStrings->dequeue();
+            if (!$compressedStringList->isEmpty()) {
+                $string = $compressedStringList->dequeue();
 
                 $readStream = $string->getDecompressedReadOnlyStream();
                 while ($buffer = $readStream->read()) {
@@ -40,21 +91,43 @@ public static function merge($subject, $delimiter, CompressedStringList $gzipped
         return $merged;
     }
 
+    /**
+    * Add a CompressedString to the Queue.
+    *
+    * @param CompressedString $string
+    *
+    * @return void
+    */
     public function enqueue(CompressedString $string)
     {
         return $this->queue->enqueue($string);
     }
 
+    /**
+    * Returns a CompressedString from the Queue
+    *
+    * @return CompressedString
+    */
     public function dequeue()
     {
         return $this->queue->dequeue();
     }
 
+    /**
+    * Checks whether the list is empty
+    *
+    * @return bool
+    */
     public function isEmpty()
     {
         return $this->queue->isEmpty();
     }
 
+    /**
+    * Returns the number of entries in the Queue
+    *
+    * @return int
+    */
     public function count()
     {
         return $this->queue->count();

src/GzStreamGuzzle.php

@@ -6,6 +6,25 @@
 use GuzzleHttp\Psr7\Stream;
 use GuzzleHttp\Psr7\StreamWrapper;
 
+/**
+* Modified version of the original class created by Tom Westcott that can be found here:
+* https://github.com/cyberdummy/gzstream/blob/master/src/GzStreamGuzzle.php
+*
+* Mainly the issue for me was that the original class had its internal properties
+* and certain methods (writeFooter for example) set as private, which made
+* some of the things I wanted to use the class for, more difficult.
+*
+* I've integrated this modified version of the class into this package.
+*
+* Changes made:
+*  - Convert properties to protected
+*  - Changed private methods to protected
+*  - Added ability to specify Gzip compression level
+*  - Added getReadOnlyCopy() method
+*  - Added writeFooterEarly() method
+*  - Added default read() length
+*  - Added getWriteSize() method
+*/
 class GzStreamGuzzle implements StreamInterface
 {
     use StreamDecoratorTrait;
@@ -40,16 +59,11 @@ public function __construct(StreamInterface $stream, $readOnly = false, $level =
         }
     }
 
-    public function readOnlyStream()
+    public function getReadOnlyCopy()
     {
         return new self($this->stream, true, $this->level);
     }
 
-    public function writeableStream()
-    {
-        return new self($this->stream, false, $this->level);
-    }
-
     public function read($length = 65536)
     {
         $ret = $this->stream->read($length);