Update Socket API doc

docs/cn/README.md

@@ -16,6 +16,7 @@ PHP 扩展
 * [内存拷贝](php/memory.md)
 * [性能测试](benchmark.md)
 * [IDE 提示](php/composer.md)
+* [Socket API](php/socket.md)
 
 Python 模块
 ---

docs/cn/php/core.md

@@ -45,7 +45,8 @@ $class = $m->$className;
 - `PyCore::dict()` 构造一个字典对象
 - `PyCore::set()` 构造一个集合对象
 - `PyCore::range()` 构造一个范围序列
-- `PyCore::scalar()` 将 `PyObject` 对象转为 `PHP` 的标量类型，例如 `PyStr` 将转为 `PHP 字符串`，`Dict/Tuple/Set/List` 将转为 `Array`
+- `PyCore::scalar($pyobj)` 将 `PyObject` 对象转为 `PHP` 的标量类型，例如 `PyStr` 将转为 `PHP 字符串`，`Dict/Tuple/Set/List` 将转为 `Array`
+- `PyCore::fileno($fp)` 获取 `PHP Stream` 资源的文件描述符，请注意仅支持 `tcp/udp/unix` 类型的资源
 
 > `PyCore` 实现了 `__callStatic()` 魔术方法，对于 `PyCore` 静态方法调用会自动调用 `Python` 的 `builtins` 模块对应的方法 ，
 > 可参考 [Built-in Functions](https://docs.python.org/3/library/functions.html) 了解更多内置方法的使用

docs/cn/php/socket.md

@@ -0,0 +1,49 @@
+Socket API
+=====
+在 `phpy` 编程开发中经常需要使用 `Socket API` 编写网络通信程序，
+可使用下面的方法实现 `Python Socket 对象` 与 `PHP Stream 资源` 互相转换。 
+
+Python 转 PHP
+-----
+```php
+$socket = PyCore::import('socket');
+const HOST = "127.0.0.1";
+const PORT = 5432;
+
+$client = $socket->socket($socket->AF_INET, $socket->SOCK_STREAM);
+$client->connect(PyCore::tuple([HOST, PORT]));
+
+$fp = fopen('php://fd/' . $client->fileno(), 'rw');
+fwrite($fp, $msg);
+$data = fread($fp, 1024);
+fclose($fp);
+```
+
+- 使用 `Python Socket.fileno()` 方法获取文件描述符
+- 使用 `PHP fopen('php://fd/{$fileno}')` 将文件句柄对应的 `Socket` 转为 `PHP Stream`
+- 使用 `fwrite/fread/fclose` 读写、关闭句柄
+
+`fopen()` 会复制文件描述符，因此 `fclose()` 关闭时不会影响 `Python Socket 对象`，
+依然可以使用 `Python Socket API` 对此网络连接进行数据传输操作。
+
+PHP 转 Python
+----
+```php
+$socket = PyCore::import('socket');
+
+$HOST = "127.0.0.1";
+$PORT = 5432;
+
+$fp = stream_socket_client("tcp://$HOST:$PORT", $errno, $errstr, 30);
+if (!$fp) {
+    exit("Error: $errstr ($errno)\n");
+}
+$client = $socket->fromfd(PyCore::fileno($fp), $socket->AF_INET, $socket->SOCK_STREAM);
+fclose($fp);
+```
+
+- 使用 `PyCore::fileno($fp)` 方法获取 `PHP Stream` 文件描述符
+- 使用 `Python Socket.fromfd()` 将文件句柄对应的 `Socket` 转为 `Python Socket 对象`
+
+`Socket.fromfd()` 会复制文件描述符，因此 `Python Socket` 关闭时不会影响 `PHP Stream`，
+依然可以使用 `PHP` 的  `fwrite/fread/fclose` 对此网络连接进行数据传输操作。