refactor FileWriter, add FileWriter example

2 files changed, 55 insertions, 10 deletions

diff --git a/examples/06-file_writer.php b/examples/06-file_writer.php
new file mode 100644
index 0000000..7a98910
--- /dev/null
+++ b/examples/06-file_writer.php
@@ -0,0 +1,22 @@
+<?php
+declare(strict_types = 1);
+
+require_once __DIR__ . '/../src/ZipStream.php';
+
+# import zipstream classes
+use Pablotron\ZipStream\ZipStream;
+use Pablotron\ZipStream\FileWriter;
+
+# save as "example.zip" in examples directory
+$zip_path = __DIR__ . '/example.zip';
+
+$zip = new ZipStream($zip_path, [
+  'output' => new FileWriter(),
+]);
+
+# add a file named "hello.txt" to output archive, containing
+# the string "hello world!"
+$zip->add_file('hello.txt', 'hello world!');
+
+# finalize archive
+$zip->close();
diff --git a/src/ZipStream.php b/src/ZipStream.php
index 0f3a452..2759d4d 100644
--- a/src/ZipStream.php
+++ b/src/ZipStream.php
@@ -172,12 +172,11 @@ final class HTTPResponseWriter implements Writer {
 };
 
 /**
- * @api
+ * Write generated zip archive to a local file.
  *
- * Stream generated archive to a local file.
+ * @api
  *
- * Streams generated zip archive to a local file.  This is the
- * default writer used by ZipStream if none is provided.
+ * {@example ../examples/06-file_writer.php}
  *
  * @see Writer
  */
@@ -200,12 +199,10 @@ final class FileWriter implements Writer {
    * @api
    *
    * Create a new FileWriter.
-   *
-   * @param string $path Output file path.
    */
-  public function __construct(string $path) {
+  public function __construct() {
+    # set state
     $this->state = self::FILE_WRITER_STATE_INIT;
-    $this->path = $path;
   }
 
   /**
@@ -217,15 +214,36 @@ final class FileWriter implements Writer {
    * @return void
    */
   public function set(string $key, string $val) : void {
-    # ignore metadata
+    # check state
+    if ($this->state !== self::FILE_WRITER_STATE_INIT) {
+      # set state, raise error
+      $this->state = self::FILE_WRITER_STATE_ERROR;
+      throw new Error("invalid file writer state");
+    }
+
+    if ($key == 'name') {
+      # save name
+      $this->path = $val;
+    } else {
+      # ignore other metadata
+    }
   }
 
   /**
    * Flush metadata and begin streaming archive contents.
    *
    * @return void
+   *
+   * @throw FileError if output archive could not be opened.
    */
   public function open() : void {
+    # check state
+    if ($this->state !== self::FILE_WRITER_STATE_INIT) {
+      # set state, raise error
+      $this->state = self::FILE_WRITER_STATE_ERROR;
+      throw new Error("invalid file writer state");
+    }
+
     # open output file
     $this->fh = @fopen($this->path, 'wb');
     if (!$this->fh) {
@@ -246,6 +264,8 @@ final class FileWriter implements Writer {
   public function write(string $data) : void {
     # check state
     if ($this->state != self::FILE_WRITER_STATE_OPEN) {
+      # set state, raise error
+      $this->state = self::FILE_WRITER_STATE_ERROR;
       throw new Error("invalid output state");
     }
 
@@ -254,6 +274,7 @@ final class FileWriter implements Writer {
 
     # check for error
     if ($len === false) {
+      # set state, raise error
       $this->state = self::FILE_WRITER_STATE_ERROR;
       throw new FileError($this->path, 'fwrite() failed');
     }
@@ -269,6 +290,8 @@ final class FileWriter implements Writer {
     if ($this->state == self::FILE_WRITER_STATE_CLOSED) {
       return;
     } else if ($this->state != self::FILE_WRITER_STATE_OPEN) {
+      # set state, raise error
+      $this->state = self::FILE_WRITER_STATE_ERROR;
       throw new Error("invalid output state");
     }
 
@@ -1031,7 +1054,7 @@ final class ZipStream {
    *
    * {@example ../examples/01-simple.php}
    */
-  public function __construct(string $name, array &$args = []) {
+  public function __construct(string $name, array $args = []) {
     try {
       $this->state = self::STREAM_STATE_INIT;
       $this->name = $name;