From: Michael Wallner <mike@php.net>
Date: Fri, 8 Nov 2013 20:22:26 +0000 (+0100)
Subject: http\Response
X-Git-Url: https://git.m6w6.name/?a=commitdiff_plain;h=aa6f2151a85bd39270a9a341eca8ad1f9a095944;p=mdref%2Fmdref-http

http\Response
---

diff --git a/http/Env/Response.md b/http/Env/Response.md
new file mode 100644
index 0000000..dcb4f24
--- /dev/null
+++ b/http/Env/Response.md
@@ -0,0 +1,39 @@
+# class http\Env\Response extends http\Message is callable
+
+The http\Env\Response class' instances represent the server's current HTTP response.
+
+See http\Message for inherited members.
+
+## Constants:
+
+* CONTENT_ENCODING_NONE  
+  Do not use content encoding.
+* CONTENT_ENCODING_GZIP  
+  Support "Accept-Encoding" requests with gzip and deflate encoding.
+* CACHE_NO  
+  No caching info available.
+* CACHE_HIT  
+  The cache was hit.
+* CACHE_MISS  
+  The cache was missed.
+
+## Properties:
+
+* protected $request = NULL  
+  A http\Env\Request instance which overrides the environments default request.
+* protected $contentType = NULL  
+  The response's MIME content type.
+* protected $contentDisposition = NULL  
+  The response's MIME content disposition.
+* protected $contentEncoding = NULL  
+  See http\Env\Response::CONTENT_ENCODING_* constants.
+* protected $cacheControl = NULL  
+  How the client should treat this response in regards to caching.
+* protected $etag = NULL  
+  A custom ETag.
+* protected $lastModified = NULL  
+  A "Last-Modified" time stamp.
+* protected $throttleDelay = NULL  
+  Any throttling delay.
+* protected $throttleChunk = NULL  
+  The chunk to send every $throttleDelay seconds.
diff --git a/http/Env/Response/__construct.md b/http/Env/Response/__construct.md
new file mode 100644
index 0000000..fc2e6d9
--- /dev/null
+++ b/http/Env/Response/__construct.md
@@ -0,0 +1,29 @@
+# void http\Env\Response::__construct()
+
+Create a new env response message instance.
+
+## Params:
+
+None.
+
+## Throws:
+
+* http\Exception.
+
+## Example:
+
+    <?php
+    $res = new http\Env\Response;
+    $res->setContentType("text/plain");
+    $res->getBody()->append("Hello world!\n");
+    $res->send(STDOUT);
+    ?>
+
+Yields:
+
+    HTTP/1.1 200 OK
+    Accept-Ranges: bytes
+    Content-Type: text/plain
+    ETag: "b2a9e441"
+
+    Hello world!
diff --git a/http/Env/Response/__invoke.md b/http/Env/Response/__invoke.md
new file mode 100644
index 0000000..7f8d320
--- /dev/null
+++ b/http/Env/Response/__invoke.md
@@ -0,0 +1,38 @@
+# bool http\Response::__invoke(string $data[, int $ob_flags = 0])
+
+Output buffer handler.
+Appends output data to the body.
+
+## Params:
+
+* string $data  
+  The data output.
+* Optional int $ob_flags = 0  
+  Output buffering flags passed from the output buffering control layer.
+
+## Returns:
+
+* bool, success.
+
+## Example:
+
+    <?php
+    $res = new http\Env\Response;
+    $res->setContentType("text/plain");
+
+    ob_start($res);
+    // yeah, well
+    // not the greatest application logic...
+    echo "Hello world!\n";
+
+    $res->send();
+    ?>
+
+Yields:
+
+    Accept-Ranges: bytes
+    X-Powered-By: PHP/5.5.5
+    Content-Type: text/plain
+    ETag: "b2a9e441"
+
+    Hello world!
diff --git a/http/Env/Response/isCachedByEtag.md b/http/Env/Response/isCachedByEtag.md
new file mode 100644
index 0000000..3bccc6b
--- /dev/null
+++ b/http/Env/Response/isCachedByEtag.md
@@ -0,0 +1,13 @@
+# int http\Env\Response::isCachedByEtag([string $header_name = "If-None-Match"])
+
+Manually test the header $header_name of the environment's request for a cache hit.
+http\Env\Response::send() checks that itself, though.
+
+## Params:
+
+* Optional string $header_name = "If-None-Match"  
+  The request header to test.
+
+## Returns:
+
+* int, a http\Env\Response::CACHE_* constant.
diff --git a/http/Env/Response/isCachedByLastModified.md b/http/Env/Response/isCachedByLastModified.md
new file mode 100644
index 0000000..600473b
--- /dev/null
+++ b/http/Env/Response/isCachedByLastModified.md
@@ -0,0 +1,13 @@
+# int http\Env\Response::isCachedByLastModified([string $header_name = "If-Modified-Since"])
+
+Manually test the header $header_name of the environment's request for a cache hit.
+http\Env\Response::send() checks that itself, though.
+
+## Params:
+
+* Optional string $header_name = "If-Modified-Since"  
+  The request header to test.
+
+## Returns:
+
+* int, a http\Env\Response::CACHE_* constant.
diff --git a/http/Env/Response/send.md b/http/Env/Response/send.md
new file mode 100644
index 0000000..768cd0a
--- /dev/null
+++ b/http/Env/Response/send.md
@@ -0,0 +1,13 @@
+# bool http\Env\Response::send([resource $stream = NULL])
+
+Send the response through the SAPI or $stream.
+Flushes all output buffers.
+
+## Params:
+
+* Optional resource $stream = NULL  
+  A writable stream to send the response through.
+
+## Returns:
+
+* bool, success.
diff --git a/http/Env/Response/setCacheControl.md b/http/Env/Response/setCacheControl.md
new file mode 100644
index 0000000..0ab810c
--- /dev/null
+++ b/http/Env/Response/setCacheControl.md
@@ -0,0 +1,12 @@
+# http\Env\Response http\Env\Response::setCacheControl(string $cache_control)
+
+Make suggestions to the client how it should cache the response.
+
+## Params:
+
+* string $cache_control  
+  (A) "Cache-Control" header value(s).
+
+## Returns:
+
+* http\Env\Response, self.
diff --git a/http/Env/Response/setContentDisposition.md b/http/Env/Response/setContentDisposition.md
new file mode 100644
index 0000000..0b4a551
--- /dev/null
+++ b/http/Env/Response/setContentDisposition.md
@@ -0,0 +1,33 @@
+# http\Env\Response http\Env\Response::setContentDisposition(array $disposition_params)
+
+Set the reponse's content disposition parameters.
+
+## Params:
+
+* array $disposition_params  
+  MIME content disposition as http\Params array.  
+  
+## Returns:
+
+* http\Env\Response, self.
+
+## Example:
+
+    <?php ob_end_Clean();chdir(__DIR__."/../../..");
+    $res = new http\Env\Response;
+    $res->setBody(new http\Message\Body(fopen("http.zip", "r")));
+    $res->setContentType("application/zip");
+    $res->setContentDisposition(["attachment" => ["filename" => "download.zip"]]);
+    $res->send();
+    ?>
+
+Yields:
+
+    Accept-Ranges: bytes
+    X-Powered-By: PHP/5.5.5
+    Content-Type: application/zip
+    Content-Disposition: attachment;filename=download.zip
+    ETag: "12009be-527d3e84-a0"
+    Last-Modified: Fri, 08 Nov 2013 19:41:56 GMT
+
+    PK...
diff --git a/http/Env/Response/setContentEncoding.md b/http/Env/Response/setContentEncoding.md
new file mode 100644
index 0000000..3b3d612
--- /dev/null
+++ b/http/Env/Response/setContentEncoding.md
@@ -0,0 +1,13 @@
+# http\Env\Response http\Env\Response::setContentEncoding(int $content_encoding)
+
+Enable support for "Accept-Encoding" requests with deflate or gzip.
+The response will be compressed if the client indicates support and wishes that.
+
+## Params:
+
+* int $content_encoding  
+  See http\Env\Response::CONTENT_ENCODING_* constants.
+
+## Returns:
+
+* http\Env\Response, self.
diff --git a/http/Env/Response/setContentType.md b/http/Env/Response/setContentType.md
new file mode 100644
index 0000000..78674df
--- /dev/null
+++ b/http/Env/Response/setContentType.md
@@ -0,0 +1,12 @@
+# http\Env\Response http\Env\Response::setContentType(string $content_type)
+
+Set the MIME content type of the response.
+
+## Params:
+
+* string $conten_type  
+  The response's content type.
+
+## Returns:
+
+* http\Env\Response, self.
diff --git a/http/Env/Response/setEnvRequest.md b/http/Env/Response/setEnvRequest.md
new file mode 100644
index 0000000..83cb5bf
--- /dev/null
+++ b/http/Env/Response/setEnvRequest.md
@@ -0,0 +1,21 @@
+# http\Env\Response http\Env\Response::setEnvRequest(http\Message $env_request)
+
+Override the environment's request.
+
+## Params:
+
+* http\Message $env_request  
+  The overriding request message.
+
+## Returns:
+
+* http\Env\Response, self.
+
+## Example:
+
+    <?php
+    $req = new http\Env\Request;
+    $req->setRequestUrl("/ha/I/changed/it");
+    $res = new http\Env\Response;
+    $res->setEnvRequest($req);
+    ?>
diff --git a/http/Env/Response/setEtag.md b/http/Env/Response/setEtag.md
new file mode 100644
index 0000000..b8d0e66
--- /dev/null
+++ b/http/Env/Response/setEtag.md
@@ -0,0 +1,14 @@
+# http\Env\Response http\Env\Response::setEtag(string $etag)
+
+Set a custom ETag.
+
+> **Note:** This will be used for caching and pre-condition checks.
+
+## Params:
+
+* string $etag  
+  A ETag.
+
+## Returns:
+
+* http\Env\Response, self.
diff --git a/http/Env/Response/setLastModified.md b/http/Env/Response/setLastModified.md
new file mode 100644
index 0000000..17f4337
--- /dev/null
+++ b/http/Env/Response/setLastModified.md
@@ -0,0 +1,14 @@
+# http\Env\Response http\Env\Response::setLastModified(int $last_modified)
+
+Set a custom last modified time stamp.
+
+> **Note:** This will be used for caching and pre-condition checks.
+
+## Params:
+
+* int $last_modified  
+  A unix timestamp.
+
+## Returns:
+
+* http\Env\Response, self.
diff --git a/http/Env/Response/setThrottleRate.md b/http/Env/Response/setThrottleRate.md
new file mode 100644
index 0000000..03b7047
--- /dev/null
+++ b/http/Env/Response/setThrottleRate.md
@@ -0,0 +1,17 @@
+# http\Env\Response http\Env\Response::setThrottleRate(int $chunk_size[, float $delay = 1])
+
+Enable throttling.
+Send $chunk_size bytes every $delay seconds.
+
+> **Note:** If you need throttling by regular means, check for other options in your stack, because this method blocks the executing process/thread until the response has completely been sent.
+
+## Params:
+
+* int $chunk_size  
+  Bytes to send.
+* Optional float $delay = 1  
+  Seconds to sleep.
+
+## Returns:
+
+* http\Env\Response, self.