README

这是一个用于研究向 Joomla 添加 Web 服务层的实验室。

更多详情请加入 https://glip.com/ 的 #webservices 频道。

如何安装

在某处安装一个完整的当前 Joomla
$ cd JOOMLA_ROOT
编辑 composer.json

--- a/composer.json
+++ b/composer.json
@@ -5,9 +5,10 @@
     "keywords": ["joomla", "cms"],
     "homepage": "https://github.com/joomla/joomla-cms",
     "license": "GPL-2.0+",
+    "minimum-stability" : "dev",
     "config": {
         "platform": {
-            "php": "5.3.10"
+            "php": "5.5.9"
         },
         "vendor-dir": "libraries/vendor"
     },
@@ -18,7 +19,7 @@
         "docs":"https://docs.joomla.org"
     },
     "require": {
-        "php": ">=5.3.10",
+        "php": ">=5.5.9",
         "joomla/application": "~1.5",
         "joomla/data": "~1.2",
         "joomla/di": "~1.2",
@@ -31,7 +32,7 @@
         "ircmaxell/password-compat": "1.*",
         "leafo/lessphp": "0.5.0",
         "paragonie/random_compat": "~1.0",
-        "phpmailer/phpmailer": "5.2.16",
+        "phpmailer/phpmailer": "5.2.14",
         "symfony/polyfill-php55": "~1.2",
         "symfony/polyfill-php56": "~1.0",
         "symfony/yaml": "2.*",

$ composer require matware-lab/webservices
登录到管理员，转到发现扩展并安装 Webservices 组件
将 /www/htaccess.txt 复制到 /www/.htaccess 并根据需要编辑 RewriteBase
测试

警告：不要在包含您关心的数据的公共服务器上安装。当前版本绝对不安全！

注意：目前，主页的空路由会导致路由器抛出 PHP "未初始化字符串偏移" 注意。暂时忽略它们，它们不会影响功能。

路由和路由配置

Web 服务应用程序使用 Joomla 框架 2.0 路由器。有关其文档，请参阅此处：https://github.com/joomla-framework/router/blob/2.0-dev/docs/overview.md

路由存储在 routes.json 文件中。默认情况下，它在网站根目录中，但您可以将其移动到其他位置，只要您更新 config.json 中的 webservices.routes 条目。

尽管目前您需要手动修改此文件，但想法是应该可以在安装新 Web 服务的过程中自动将路由添加到 routes.json 文件。管理员组件还应扩展以允许对特定安装的路由进行自定义。这就是如何自定义路由和解决路由冲突的方法。

routes.json 文件包含一个资源数组。每个资源都有一个名称、一个描述（仅用于人类）、一个交互样式、一个路由模板集合以及与之关联的 HTTP 方法，还有一个可选的用于解析命名参数的正则表达式集合。以下将更详细地描述这些条目。

"name"。资源名称。名称 "contents" 保留用于作为 API 入口点（它是一个 IANA 注册的名称）。
"description"。一个可选的简短描述，用于人类的资源。软件不使用。
"style"。与资源关联的交互样式。默认情况下，这将使用 "rest" 来指示应使用 REST 风格。或者，使用 "soap" 来使用 SOAP 交互样式。此条目确定在 /Api 目录中加载和执行哪个交互样式类。
"routes"。这是一个将要添加到路由表中的路由定义集合。包含在 Web 请求中的路径（或 CLI 请求中的 --path 参数）将使用正则表达式与路由表进行匹配。路由定义可以包含命名参数，这些参数将复制到输入对象中。默认情况下，路由中的命名变量使用匹配正则表达式 "[^/]*"，它匹配路由中的所有内容，直到下一个 /。这可以通过添加 "regex" 条目来覆盖（见下文）。与每个路由定义相关的是一组有效的 HTTP 方法。如果一个路径与路由匹配，但方法不在该数组中，则 API 应返回 405 方法不允许错误。[需要测试]。
"regex"。在路由定义中与命名参数相关联的可选正则表达式集合。此处条目将覆盖相关参数的默认正则表达式。请注意，正则表达式中的反斜杠需要转义，以便与JSON语法兼容。

默认和强烈推荐的路线是“行业标准”的Web API路线，但您可以指定任何您想要的路线。

如果您安装了具有冲突路线的第三方扩展，则可以通过编辑routes.json文件来解决这个问题。 “routes”条目指定客户端软件可用的公共路线。 “name”条目指定与路线关联的内部资源。也就是说，它将用于确定要加载哪个配置XML文件来处理请求。

示例路线和路线定义

"/contacts"。这将返回一组联系人资源。
"/contacts/:id"。这将匹配路径如"/contacts/something"，返回id = "something"的联系人资源。id将通过输入对象传递到集成层使用。
"/contacts/:id"具有"regex"：{"id"："\\d+"}。这将缩小:id参数的指定范围，以便只有该位置的数字参数才会匹配。例如，路径"/contacts/1234"将匹配id参数设置为"1234"，但路径"/contact/something"不会匹配。

关联资源

关联资源是指由另一个资源的链接确定的资源。例如，请求"/categories/1234"将返回id为1234的类别资源，而请求"/categories/1234/contacts"将返回属于id为1234的类别资源的联系人资源集合。在这种情况下，返回的Contents资源集合是类别资源的关联资源。

要为关联资源创建路线，请使用:resource键修改routes.json文件，以指示要链接的资源名称。最好还包括一个正则表达式来限制可能取的值。例如，以下是包括Contacts作为关联资源的类别资源的可能条目。

{
	"name": "categories",
	"description": "Categories collection and individual categories",
	"style": "rest",
	"routes": {
		"/categories": ["GET","POST"],
		"/categories/:id/:resource": ["GET"],
		"/categories/:id": ["GET","PUT","PATCH","DELETE"]
	},
	"regex": {
		"id": "\\d+",
		"resource": "contacts"
	}
}

在配置文件中，您需要在routes.json文件中命名的资源中添加一个链接属性。这必须包括一个"linkField"属性，它定义资源中用于过滤关联资源的属性。例如，以下是类别资源中的可能链接属性，它将使用类别资源中的"catid"字段来过滤关联的类别资源。

<resource
	displayName="contacts"
	transform="string"
	fieldFormat="/{webserviceName}/{id}/contacts"
	displayGroup="_links"
	linkField="catid"
	linkTitle=""
	linkName=""
	hrefLang=""
	linkTemplated="false"
	linkRel="j:contacts"
	resourceSpecific="rcwsGlobal"
/>

请注意，在公共数据中可见的链接rel是链接rel属性中给出的。 displayName属性必须与关联资源的名称相对应。@TODO 这可能需要修复/更改，因为它不是很直观。

技巧

--- 只有安装了redCORE，OAuth2才能正常工作，因为我们还没有放置OAuth2服务器API

--- 如果使用需要授权的操作，您可以通过提供头信息来提供基本认证，例如（对于admin/admin）：Authorization: Basic YWRtaW46YWRtaW4=

--- 设置HAL浏览器和Chrome POSTMAN以简化REST和HAL导航（ https://github.com/mikekelly/hal-browser ）

--- 要访问主要Web服务页面，请访问 http://yoursite/index.php?api=Hal

设置文档

有关redCORE Web服务的详细文档，请在此处找到 http://redcomponent-com.github.io/redCORE/?chapters/webservices/overview.md 计划更改其中的主要功能，但到目前为止，它仍然是有效的文档。

Web服务和Web服务工作组文档

Web服务工作组文档可在此找到：https://docs.joomla.org/Web_Services_Working_Group

测试

为了在您的本地计算机上运行系统测试（Selenium），您需要

将文件 tests/acceptance.suite.dist.yml 重命名为 tests/acceptance.suite.yml。之后，请根据您的系统需求编辑该文件。
将文件 tests/api.suite.dist.yml 重命名为 tests/api.suite.yml。之后，请根据您的系统需求编辑该文件。
根据您的系统需求修改文件 config.json。测试将会将其复制到 tests/joomla-cms3/ 目录下。

要运行测试，请执行以下命令（目前仅在Linux和MacOS上工作，更多信息请参见：https://docs.joomla.org/Testing_Joomla_Extensions_with_Codeception）

$ composer install
$ vendor/bin/robo
$ vendor/bin/robo run:tests

这些命令的作用

从 tests/joomla-cms3 文件夹中的仓库下载最新的 Joomla
将文件夹 www、src 和 config.json 复制到 tests/joomla-cms3
下载并执行 Selenium Standalone Server
运行 Codeception 测试

##Windows系统

Windows系统的测试尚未工作。需要重构文件 RoboFile.php 以使其能在非 *nix 平台上工作。

matware-lab / webservices

维护者

详情