README

一个易于管理Web服务的PHP引擎。

如何使用？

基础

该引擎设计为一个类似“MVC”的应用程序，通过开发控制器来轻松处理新请求。所有请求都通过一个接口处理，默认情况下为www/index.php，在其中您可以定义一些选项值以满足您的需求或环境。

前端控制器（GET或POST）使用的默认参数如下

ws：所选的Web服务；这必须是控制器的类名，
action：从Web服务中执行的操作；这必须是控制器中名为[action]Action()的方法；默认操作是index。

响应是一个包含至少一个status和message条目的JSON表

{"status":0, "message":"Hello World !"}

获取方法（默认）

$ curl -i 'http://mydomain.com/webservices/?action=helloworld'

HTTP/1.1 200 OK
Date: Thu, 11 Jul 2013 09:57:40 GMT
Connection: keep-alive
Cache-Control: max-age=0, private, must-revalidate
Content-Length: 40
Content-Type: application/json; charset=UTF-8

{"status":0,"message":"Hello World ;)"}

POST方法

$ curl -i -d "name=Pierre" 'http://mydomain.com/webservices/?action=testPost'

HTTP/1.1 200 OK
Date: Thu, 11 Jul 2013 09:57:40 GMT
Connection: keep-alive
Cache-Control: max-age=0, private, must-revalidate
Content-Length: 41
Content-Type: application/json; charset=UTF-8

{"status":0,"message":"Hello Pierre ;)"}

返回状态

FrontController设计为返回一个遵循以下规则的整数状态码

0：默认的“没有任何错误”状态，
1：“意外结果”状态，表示没有发生错误，但结果不是完全预期的，
2：“请求错误”状态，用于未找到Web服务或方法，对于错误的参数值等，
3：“处理错误”状态，必须在处理需要停止的任何原因时使用，
-1：“内部服务器错误”状态，由PHP错误和异常使用。

选项

WebServices\FrontController::create()方法接受一个第三个参数来定义一组自定义选项

array(
    // the HTTP accessible temporary files
    'tmp_directory' => __DIR__.'/tmp',
    // the HTTP NON-accessible temporary files, must be out of your document root
    'var_directory' => __DIR__.'/../var',
    // the log files, must be out of your document root (here in 'var/')
    'log_directory' => __DIR__.'/../var/logs',
    // enable full logging
    'enable_logging' => true,
    // enable the URL rewriting : "http://.../var/val" = "http://.../?var=val"
    'enable_url_rewrite' => true,
    // write your custom controllers here like "route => classname" pairs
    // then you can call "http://.../?ws=route" to access them
    'controllers_mapping' => array(
    ),
)

重写

该引擎设计为处理使用GET参数编写的请求，如key=>value对或以key/value对列表形式编写的完整URL。

例如，以下内容是等效的

$ curl -i 'http://mydomain.com/webservices/?ws=MyController&action=custom'
$ curl -i 'http://mydomain.com/webservices/ws/MyController/action/custom'

可以通过设置enable_url_rewrite选项为false来禁用此URL重写功能。

日志记录

默认情况下，引擎将记录接收到的任何请求以及从其中执行的一些PHP操作。默认日志文件路径为从包根目录开始的var/logs/。此路径可以通过选项log_directory定义。

可以通过设置enable_logging选项为false来禁用日志记录功能。

自定义

安装WebServicesEngine环境

要准备基于WebServices的包，您需要在您的计算机上安装Composer，然后只需运行

~$ php path/to/composer.phar create-project atelierspierrot/webservices YOURDIR dev-master --no-dev
...

~$ vim YOURDIR/composer.json
// add an entry in the 'autoload' of composer.json to reference your namespace, i.e.
"autoload": { "psr-0": { "WebServices":"src", "MyNamespace":"src" } }
~$ php path/to/composer.phar dump-autoload YOURDIR
...

~$ vim YOURDIR/www/index.php
// adapt the interface options to fit your needs
// reference your controllers to have a shortcut access to them

然后，您只需创建您的src/MyNamespace/目录并将您的控制器放入其中。

就是这样！

关键概念

要编写新的Web服务，只需创建一个新的PHP类，它扩展了抽象类\WebServices\Controller\AbstractController。如前所述，您必须通过命名它们为dosomethingAction()来声明您控制器的操作。

例如，考虑一个自定义的“MyController”控制器，它具有“indexAction）”和“customAction）”方法。您将使用请求调用每个这些操作

$ curl -i 'http://mydomain.com/webservices/?ws=MyController'
$ curl -i 'http://mydomain.com/webservices/?ws=MyController&action=custom'

为自定义控制器编写“使用”信息

每个控制器都可以提出一个定义$usage_filepath属性的"用法"字符串信息，该属性位于用法文件的绝对可访问路径上。如果使用.md扩展名，内容可以被Markdown Extended解析器解析。

您可以在PHP中编写您的用法内容，例如在这个例子中，当前配置设置被作为环境变量加载。特殊变量$webservice_url在当前接口URL上定义。为此，您必须使用最终扩展名.php（使用Markdown解析器则为.md.php）。

"用法"字符串将显示在调用usage操作的每个控制器上。

引用自定义控制器

您可以开发尽可能多的新控制器，并通过定义controllers_mapping选项表来构建访问它们的快捷方式，该表结构如下：快捷方式 => 类名。例如，要访问在MyNamespace\MyController类中定义的控制器，您可以编写'myctrl' => 'MyNamespace\MyController'并通过URLhttp://.../?ws=myctrl访问它。

包环境

由于它们是必需的，您可以在开发中使用包的临时目录（它们必须对Apache用户可访问，因为它们可能由它创建）

var/：临时配置和日志目录，不通过HTTP访问，
www/tmp/：临时通过HTTP访问的文件。

开发环境

由于"WebServices"依赖于它们（它们必须安装），您可以在您的脚本中使用以下第三方包的所有类

Les Ateliers Pierrot的PHP库，有关内联文档，请参阅http://docs.ateliers-pierrot.fr/library/
Les Ateliers Pierrot的PHP模式包，有关内联文档，请参阅http://docs.ateliers-pierrot.fr/patterns/

包的开发

要安装所有开发所需的PHP包，只需运行

~$ composer install --dev

使用Sami可以生成文档

~$ php vendor/sami/sami/sami.php render sami.config.php

此文档的最新版本可在网上找到：http://docs.ateliers-pierrot.fr/webservices/。

作者 & 许可证

WebServices引擎

http://github.com/atelierspierrot/webservices

版权 (c) 2013-2016 Pierre Cassat和贡献者

根据Apache 2.0许可证授权。

https://apache.ac.cn/licenses/LICENSE-2.0

Les Ateliers Pierrot - 巴黎，法国

http://www.ateliers-pierrot.fr/ - contact@ateliers-pierrot.fr

atelierspierrot / webservices

维护者

详细信息