README

phpMAE，PHP微型API引擎，是一个具有特定观点的无服务器框架，用于开发、执行和部署小型的无状态Web API，所谓“微型API”。

该框架部分基于Slim微框架构建，并利用PHPSandbox提供安全运行环境。

微型API的配置和源代码可以存储在CloudObjects Core中，并在接收到特定API请求时，通过CloudObjects SDK即时部署到运行的phpMAE实例。

CloudObjects目前提供phpMAE公共托管版本的预览版。如果您想进行开发或运行自己的微型API引擎，可以运行phpMAE作为PHAR文件，使用我们的Docker容器或直接从源代码运行。

安装

注意：以下安装步骤已在默认安装了PHP的macOS上进行了测试。如果您使用的是Linux，您可能需要首先通过您的发行版的包管理器安装PHP。phpMAE尚未在Windows上进行测试，但支持已在路线图上。

PHAR

这是开发人员创建、验证和部署微型API的推荐安装方法。

您可以从GitHub上的phpMAE发行版获取最新的PHAR（PHP ARchive）。

输入php phpmae.phar以获取可用CLI命令列表。与CloudObjects交互的任何命令或选项都需要作为先决条件安装CloudObjects CLI工具。

要从您下载phpmae.phar的目录中使phpmae CLI工具在系统上全局可用，请运行以下命令

cp phpmae.phar /usr/local/bin/phpmae
chmod +x /usr/local/bin/phpmae

Docker

如果您想在您的服务器（本地或云）上运行用于预发布和生产阶段的微型API，这是推荐的安装方法。

从Docker Hub提供了预构建镜像。您可以通过CLI下载它

docker pull cloudobjects/phpmae

在运行容器时，您需要提供CO_AUTH_NS和CO_AUTH_SECRET环境变量，以便phpMAE可以验证自身对CloudObjects的身份。否则，只能运行将co:isVisibleTo设置为co:Public的微型API。

docker run -e CO_AUTH_NS=example.com -e CO_AUTH_SECRET=XXXXXXXX -p 8080:80 cloudobjects/phpmae

对于CO_AUTH_NS，请使用您已添加到CloudObjects并希望用作此phpMAE实例身份的域名。对于CO_AUTH_SECRET，您需要检索该域名与cloudobjects.io之间的共享密钥。您可以使用以下命令使用CloudObjects CLI工具检索此密钥

cloudobjects domain-providers:secret example.com cloudobjects.io

源代码

此安装方法仅推荐用于您想“深入了解”phpMAE或使用特定选项运行时。

您需要在系统上全局安装Composer以下载和安装依赖项。

您可以从GitHub下载或使用git clone来克隆此仓库，然后运行composer install（或make）来安装依赖项。

建议使用composer通过单条命令下载和安装。

composer create-project cloudobjects/phpmae

您可以通过复制config.php.default到config.php来自定义phpMAE的安装，然后根据您的需求编辑该文件。高级功能和配置选项的文档将发布在phpMAE Wiki上。

phpMAE自带单元测试。您可以在安装源码后运行它们，以验证您所做的更改是否破坏了测试。

vendor/bin/phpunit

入门指南

创建一个类

与phpMAE兼容的微API作为PHP类实现。它们在CloudObjects中以类型phpmae:Class表示为对象。这些类上的所有公共方法都通过RPC协议（目前为JSON-RPC）以及将您的类作为依赖项的其他类使公开。如果您想使您的类暴露一个单一的入口点，可以向其中添加PHP的魔法__invoke()，并使其对象为类型phpmae:HTTPInvokableClass的实例。

与所有对象一样，phpMAE类使用COIDs（Cloud Object IDentifiers）唯一标识。COIDs被划分到域中，您只能在您在CloudObjects中创建或分配给您的域中创建对象。您可以在CloudObjects仪表板中查看这些域。

要创建一个新的类，选择一个COID，然后运行以下命令：

phpmae class:create --confjob coid://NAMESPACE/NAME/VERSION

如果您想创建一个HTTP可调用的类，请添加选项--http-invokable。

此命令将在当前目录中写入两个文件，即NAME.VERSION.xml和NAME.VERSION.php。该.xml文件包含CloudObjects的RDF/XML格式的基本对象描述，而.php文件包含PHP类的骨架代码。它还创建一个配置作业以注册COID。

打开.php文件并开始插入您的代码。

本地验证和测试

要检查您的代码是否是有效的PHP，并且也遵守phpMAE关于受保护函数和类的约束，请运行以下命令：

phpmae class:validate coid://NAMESPACE/NAME/VERSION

您可以将--watch添加到持续监视文件变化并自动重新验证。

要运行您的类，您可以启动一个本地Web服务器。打开第二个终端窗口或标签页，并运行以下命令：

phpmae testenv:start

Web服务器在前台运行，可以使用Ctrl + C（或Cmd + C）停止。切换到第一个标签页并运行以下命令：

phpmae class:testenv coid://NAMESPACE/NAME/VERSION

除了将代码部署到本地Web服务器外，此命令还打印出您的微API的基本URL，您可以在浏览器中打开它或使用类似curl的工具进行查询。支持--watch选项进行连续重新部署。

部署您的类

使用以下命令部署您的类：

phpmae class:deploy coid://NAMESPACE/NAME/VERSION

内部，此命令首先验证类，然后调用CloudObjects CLI将.php源文件作为附件上传到CloudObjects Core，并在必要时更新.xml文件以配置作业。部署的类将在瞬间对phpMAE实例可用。

部署命令的输出显示了您在公共phpMAE实例上的微API的基本URL。这些实例要求您使用HTTP基本身份验证来访问您的类。您必须使用命名空间作为用户名，并将该域和phpmae.dev之间的CloudObjects共享秘密作为密码。显示给您的此秘密的命令也显示出来。

在自定义实例上使用您的类

您也可以在自己的私有实例上使用您的类。启动一个实例，例如，使用上述方法中的Docker，然后将URL中的phpmae.dev替换为您自己的实例的URL。

帮助与支持

请加入我们在Gitter上的聊天，并随时提问或提供反馈。

您可以通过我们的GitHub问题报告错误或建议功能。我们还接受带有错误修复的PR；如果您想贡献功能，请首先创建一个问题或在聊天中讨论。如果您发现潜在的安全问题，例如沙箱功能，请勿使用公共问题跟踪器，而是发送电子邮件至phpmae-security@cloudobjects.io。

确保您关注CloudObjects博客和@CloudObjectsIO以获取最新更新、指南和教程。

商业支持和托管私有实例可通过CloudObjects咨询获得。

许可证

phpMAE在Mozilla公共许可证下授权（请参阅LICENSE文件）。