diff options
| -rw-r--r-- | composer.json | 2 | ||||
| -rw-r--r-- | examples/08-datetime.php | 15 | ||||
| -rw-r--r-- | src/ZipStream.php | 90 |
3 files changed, 86 insertions, 21 deletions
diff --git a/composer.json b/composer.json index fcb6a22..7c8db10 100644 --- a/composer.json +++ b/composer.json @@ -37,7 +37,7 @@ ], "docs": [ - "phpdoc -d src -t docs" + "phpdoc -d src -t docs --template=responsive-twig --title=ZipStream" ] } } diff --git a/examples/08-datetime.php b/examples/08-datetime.php new file mode 100644 index 0000000..23ae41b --- /dev/null +++ b/examples/08-datetime.php @@ -0,0 +1,15 @@ +<?php +declare(strict_types = 1); + +require_once __DIR__ . '/../src/ZipStream.php'; + +# import classes +use Pablotron\ZipStream\DateTime; + +# create DateTime with current timestamp +$dt = new DateTime(time()); + +# print DOS date and time +echo "UNIX time: {$dt->time}\n"; +echo "DOS time: {$dt->dos_time}\n"; +echo "DOS date: {$dt->dos_date}\n"; diff --git a/src/ZipStream.php b/src/ZipStream.php index 6522803..d7948bb 100644 --- a/src/ZipStream.php +++ b/src/ZipStream.php @@ -1,5 +1,4 @@ <?php -declare(strict_types = 1); /** * Dynamically generate streamed zip archives. * @@ -9,6 +8,8 @@ declare(strict_types = 1); * @package Pablotron\ZipStream */ +declare(strict_types = 1); + namespace Pablotron\ZipStream; /** @@ -43,10 +44,18 @@ class Error extends \Exception { }; */ final class DeflateError extends Error { }; +/** + * Unknown compression method error. + */ final class UnknownMethodError extends Error { /** @var int Unknown compression method. */ public $method; + /** + * Create a new UnknownMethod error. + * + * @param int $method Unknown compression method. + */ public function __construct(int $method) { $this->method = $method; parent::__construct('unknown compression method'); @@ -60,6 +69,12 @@ final class FileError extends Error { /** @var string Name of fail in which error occurred. */ public $file_name; + /** + * Create a new UnknownMethod error. + * + * @param string $file_name File name. + * @param string $message Error message. + */ public function __construct(string $file_name, string $message) { $this->file_name = $file_name; parent::__construct($message); @@ -73,6 +88,12 @@ final class PathError extends Error { /** @var string string Invalid file name. */ public $file_name; + /** + * Create a new UnknownMethod error. + * + * @param string $file_name File name. + * @param string $message Error message. + */ public function __construct(string $file_name, string $message) { $this->file_name = $file_name; parent::__construct($message); @@ -186,7 +207,7 @@ final class HTTPResponseWriter implements Writer { * * @api * - * {@example ../examples/06-file_writer.php} + * @example "examples/06-file_writer.php" */ final class FileWriter implements Writer { /** @var string Output file path. */ @@ -204,9 +225,10 @@ final class FileWriter implements Writer { const FILE_WRITER_STATE_ERROR = 3; /** + * Create a new FileWriter. + * * @api * - * Create a new FileWriter. */ public function __construct() { # set state @@ -316,7 +338,7 @@ final class FileWriter implements Writer { * * @api * - * {@example ../examples/07-stream_writer.php} + * @example "examples/07-stream_writer.php" */ final class StreamWriter implements Writer { /** @var resource Output stream. */ @@ -331,6 +353,10 @@ final class StreamWriter implements Writer { * Create a new StreamWriter. * * @api + * + * @param resource $stream Output stream. + * + * @example "examples/07-stream_writer.php" */ public function __construct($stream) { # check stream @@ -344,10 +370,29 @@ final class StreamWriter implements Writer { $this->stream = $stream; } + /** + * Set metadata for generated archive. + * + * *Note:* This method is not used for StreamWriter. + * + * @param string $key Metadata key (one of "name" or "type"). + * @param string $val Metadata value. + * + * @return void + */ public function set(string $key, string $val) : void { # ignore metadata } + /** + * Flush metadata and begin streaming archive contents. + * + * *Note:* This method is not used for StreamWriter. + * + * @return void + * + * @throw FileError if output archive could not be opened. + */ public function open() : void { # set state $this->state = self::STREAM_WRITER_STATE_OPEN; @@ -408,7 +453,10 @@ final class StreamWriter implements Writer { /** * Convert a UNIX timestamp into DOS date and time components. + * * @internal + * + * @example "examples/08-datetime.php" */ final class DateTime { /** @@ -420,6 +468,10 @@ final class DateTime { $dos_time, $dos_date; + /** + * Minimal date/time representable by a DOS timestamp. + * @internal + */ static $DOS_EPOCH = [ 'year' => 1980, 'mon' => 1, @@ -434,13 +486,7 @@ final class DateTime { * * @param int $time Input UNIX timestamp. * - * @example - * # create DateTime with current timestamp - * $dt = new DateTime(time()); - * - * # print DOS date and time - * echo "DOS time: {$dt->dos_time}\n"; - * echo "DOS date: {$dt->dos_date}\n"; + * @example "examples/08-datetime.php" */ public function __construct(int $time) { $this->time = $time; @@ -1120,15 +1166,19 @@ final class Entry { * * @api * - * {@example ../examples/01-simple.php} + * @example "examples/01-simple.php" */ final class ZipStream { + /** @internal Initial stream state. */ const STREAM_STATE_INIT = 0; + /** @internal Writing an entry. */ const STREAM_STATE_ENTRY = 1; + /** @internal Stream is closed. */ const STREAM_STATE_CLOSED = 2; + /** @internal Encountered an error white streaming. */ const STREAM_STATE_ERROR = 3; - # stream chunk size + /** @internal Size, in bytes, of chunks to read from files. */ const READ_BUF_SIZE = 8192; /** @var string Output archive name. */ @@ -1171,7 +1221,7 @@ final class ZipStream { * @param string $name Output archive name. * @param array $args Hash of output options (optional). * - * {@example ../examples/01-simple.php} + * @example "examples/01-simple.php" */ public function __construct(string $name, array $args = []) { try { @@ -1214,7 +1264,7 @@ final class ZipStream { * * @return void * - * {@example ../examples/01-simple.php} + * @example "examples/01-simple.php" */ public function add_file( string $dst_path, @@ -1236,7 +1286,7 @@ final class ZipStream { * * @return void * - * {@example ../examples/02-add_file_from_path.php} + * @example "examples/02-add_file_from_path.php" * * @throw FileError if the file could not be opened or read. */ @@ -1279,7 +1329,7 @@ final class ZipStream { * * @return void * - * {@example ../examples/03-add_stream.php} + * @example "examples/03-add_stream.php" * * @throw Error if $src is not a resource. * @throw Error if the resource could not be read. @@ -1325,7 +1375,7 @@ final class ZipStream { * * @return void * - * {@example ../examples/04-add.php} + * @example "examples/04-add.php" * * @throw Error if the archive is in an invalid state. * @throw Error if the destination path already exists. @@ -1394,7 +1444,7 @@ final class ZipStream { * * @throw Error if the archive is in an invalid state. * - * {@example ../examples/01-simple.php} + * @example "examples/01-simple.php" */ public function close() : int { try { @@ -1447,7 +1497,7 @@ final class ZipStream { * @param callable $cb Context callback. * @param array $args Hash of archive options (optional). * - * {@example ../examples/05-send.php} + * @example "examples/05-send.php" */ public static function send( string $name, |