summaryrefslogtreecommitdiff
path: root/src/ZipStream.php
diff options
context:
space:
mode:
Diffstat (limited to 'src/ZipStream.php')
-rw-r--r--src/ZipStream.php90
1 files changed, 70 insertions, 20 deletions
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,
generated by cgit v1.2.3 (git 2.39.1) at 2024-11-10 03:19:28 +0000