Update 14.swoole_http_server.md

jackysong · Nov 7, 2014 · 004738b · 004738b
1 parent 6455bf4
commit 004738b
Showing 1 changed file with 237 additions and 0 deletions.
diff --git a/doc/14.swoole_http_server.md b/doc/14.swoole_http_server.md
@@ -0,0 +1,237 @@
+# 14.swoole_http_server.md
+---
+#Table of Contents
+
+- [1.swoole_http_server](#1swoole_http_server)
+    - [1.1.work_mode](#11work_mode)
+    - [1.2.callback](#12callback)
+- [2.swoole_http_request](#2swoole_http_request)
+    - [2.1.header](#21header)
+    - [2.2.server](#22server)
+    - [2.3.get](#23get)
+    - [2.4.post](#24post)
+    - [2.5.cookie](#25cookie)
+    - [2.6.message](#26message)
+- [3.swoole_http_response](#3swoole_http_response)
+    - [3.1.header](#31header)
+    - [3.2.cookie](#32cookie)
+    - [3.3.status](#33status)
+    - [3.4.message](#34message)
+    - [3.5.end](#35end)
+
+---
+
+##**1.swoole_http_server**
+从swoole-1.7.7-stable版本开始，swoole提供内置的http服务器swoole_http_server。swoole_http_server继承自swoole_server,是一个完整的http服务器实现。<br>
+示例：
+```php
+$http = new swoole_http_server("127.0.0.1", 9501);
+$http->on('request', function ($request, $response) {
+    $html = "<h1>Hello Swoole.</h1>";
+    $response->end($html);
+});
+$http->start();
+```
+
+##**1.1.work_mode**
+swoole_http_server支持同步和异步两种模式。<br>
+**同步模式：**
+这种模式类似于nginx+php-fpm/apache，它需要设置大量worker进程来完成并发请求处理。Worker进程内可以使用同步阻塞IO，编程方式与普通PHP Web程序完全一致。<br>
+与php-fpm/apache不同的是，客户端连接并不会独占进程，每一个Worker进程都会常驻内存，服务器依然可以应对大量并发连接。<br>
+
+**异步模式：**
+在这种模式下，Worker进程内不允许使用任何阻塞式API，例如MySQL、redis、http_client、file_get_contents、sleep等。需要使用swoole提供的各种异步API来实现，如异步swoole_client，swoole_event_add，swoole_timer，swoole_get_mysqli_sock等API。
+
+##**1.2.callback**
+注册事件回调函数，与[swoole_server回调函数](https://github.com/LinkedDestiny/swoole-doc/blob/master/doc/02.swoole_server%E4%BA%8B%E4%BB%B6%E5%9B%9E%E8%B0%83%E5%87%BD%E6%95%B0.md)基本相同，不同之处是：swoole_http_server不接受onConnect/onReceive/onClose回调设置，
+同时swoole_http_server额外接受2种新的事件类型onRequest/onMessage
+
+**onRequest**
+描述：收到完整的http请求时的回调。<br>
+函数原型：<br>
+```php
+function onRequest(swoole_http_request $request, swoole_http_response $response);
+```
+参数说明：<br>
+
+| 参数        | 描述   |
+| --------   | -----  |
+| [swoole_http_request](#2swoole_http_request) $request     | Http请求信息对象，包含了header/get/post/cookie等相关信息 |
+| [swoole_http_response](#3swoole_http_response) $response     | Http响应对象，支持cookie/header/status等Http操作 |
+
+说明:<br>
+在收到请求时，通过`$request`对象获取请求内容，然后通过`$response`发送响应。
+
+**onMessage**
+描述：收到一个WebSocket数据请求时的回调。<br>
+函数原型：<br>
+```php
+function onMessage(swoole_http_request $request, swoole_http_response $response);
+```
+参数说明：<br>
+
+| 参数        | 描述   |
+| --------   | -----  |
+| [swoole_http_request](#2swoole_http_request) $request     | WebSocket数据对象，存放在[message]((#26message))属性中 |
+| [swoole_http_response](#3swoole_http_response) $response     | WebSocket响应对象，支持message方法发送数据 |
+
+说明:<br>
+WebSocket协议中，`$request`，`$response`对象会常驻内存，[message](#34message)方法调用后并不会销毁这2个对象<br>
+（PS: 1.7.7版本还不支持WebSocket，因此这个回调无法正常工作。）
+
+##**2.swoole_http_request**
+swoole_http_request是Http请求信息对象，包含了header/get/post/cookie等相关信息，在WebSocket模式下包含了message数据。
+
+###**2.1.header**
+描述：<br>
+Http请求的头部信息。
+内容：<br>
+
+| key        | 描述   |
+| --------   | -----  |
+|     |          |
+
+说明：
+类型为数组，所有key均为小写。<br>
+
+###**2.2.server**
+Http请求相关的服务器信息，相当于PHP的`$_SERVER`数组。<br>
+内容：<br>
+
+| key        | 描述   |
+| --------   | -----  |
+|     |          |
+
+说明：<br>
+包含了Http请求的方法，URL路径，客户端IP等信息。数组的key全部为小写，并且与PHP的`$_SERVER`数组保持一致。<br>
+
+###**2.3.get**
+描述：<br>
+Http请求的GET参数。<b4>
+说明：<br>
+相当于PHP中的$_GET，格式为数组。<br>
+
+> 1.7.7版本暂时不支持PHP的GET参数合并，比如`hello[]=1&hello[]=2`这样的参数<br>
+为防止HASH攻击，GET参数最大不允许超过128个
+
+###**2.4.post**
+描述：<br>
+Http请求的POST参数。<b4>
+说明：<br>
+相当于PHP中的$_POST，格式为数组。<br>
+
+> POST与Header加起来的尺寸不得超过package_max_length的设置，否则会认为是恶意请求<br>
+POST参数的个数最大不超过128个
+
+###**2.5.cookie**
+描述：<br>
+HTTP请求携带的COOKIE信息。<b4>
+说明：<br>
+相当于PHP中的$_COOKIE，格式为数组。<br>
+
+###**2.6.message**
+描述：<br>
+WebSocket发送来的数据。<b4>
+说明：无<br>
+
+##**3.swoole_http_response**
+###**3.1.header**
+描述：设置HTTP响应的Header信息。<br>
+函数原型：<br>
+```php
+public function swoole_http_response::header(string $key, string $value);
+```
+参数说明：<br>
+
+| 参数        | 描述   |
+| --------   | -----  |
+|  | 中 |
+
+说明：<br>
+header设置必须在[end](#35end)方法之前。<br>
+示例：<br>
+```php
+$response->header("content-type", "text/html");
+```
+
+###**3.2.cookie**
+描述：设置HTTP响应的Cookie信息。<br>
+函数原型：<br>
+```php
+public function swoole_http_response::cookie(string $key, string $value = '', int $expire = 0 , string $path = '/', string $domain  = '', bool $secure = false , bool $httponly = false);
+```
+参数说明：<br>
+
+| 参数        | 描述   |
+| --------   | -----  |
+|  | 中 |
+
+说明：<br>
+cookie设置必须在[end](#35end)方法之前。<br>
+示例：<br>
+```php
+$response->cookie("content-type", "text/html");
+```
+
+###**3.3.status**
+描述：发送Http状态码。<br>
+函数原型：<br>
+```php
+public function swoole_http_response::status(int $http_status_code);
+```
+参数说明：<br>
+
+| 参数        | 描述   |
+| --------   | -----  |
+| int $http_status_code | 合法的HttpCode，如200,404等 |
+
+说明：<br>
+cookie设置必须在[end](#35end)方法之前。<br>
+`$http_status_code`必须为合法的HttpCode，如200， 502， 301, 404等，否则会报错<br>
+示例：<br>
+```php
+$response->status(200);
+```
+
+###**3.4.message**
+描述：通过WebSocket发送数据。<br>
+函数原型：<br>
+```php
+public function swoole_http_response::message(string $message, bool $binary = false);
+```
+参数说明：<br>
+
+| 参数        | 描述   |
+| --------   | -----  |
+| string $message | 待发送的数据 |
+| bool $binary | 是否为二进制数据，默认为false |
+
+说明：<br>
+该函数只能用在WebSocket握手成功的Http客户端。<br>
+message方法不同于[end](#35end)，它并不会销毁request/response对象。<br>
+(PS: )
+示例：<br>
+```php
+$response->message("Hello World");
+```
+
+###**3.5.end**
+描述：发送Http响应体，并结束请求处理。<br>
+函数原型：<br>
+```php
+public function swoole_http_response::end(string $html);
+```
+参数说明：<br>
+
+| 参数        | 描述   |
+| --------   | -----  |
+| string $html | 待发送的数据 |
+
+说明：<br>
+end操作后将向客户端浏览器发送HTML内容，并销毁`$request`/`$response`对象<br>
+如果开启了KeepAlive，连接将会保持，服务器会等待下一次请求<br>
+未开启KeepAlive，服务器将会切断连接<br>
+示例：<br>
+```php
+$response->end("<h1>Hello Swoole.</h1>");
+```