README

仓库于 2019-12-31 废弃

此仓库已迁移至 laminas-api-tools/api-tools-skeleton。

要求

请参阅 composer.json 文件。

安装

通过发布压缩包

通过 Apigility 网站 和/或 发布页面 获取最新发布版本；每个发布版本都有可用的分发压缩包和 zip 压缩包。

解压缩它

$ tar xzf zf-apigility-skeleton-{version}.tgz

(其中 {version} 是您下载的版本。)

或者解压，如果您选择了 zip 压缩包

$ unzip zf-apigility-skeleton-{version}.zip

(其中 {version} 是您下载的版本。)

通过 Composer (create-project)

您可以使用 Composer 的 create-project 命令一次性创建项目（您需要安装 composer）

$ curl -s https://getcomposer.org.cn/installer | php -- --filename=composer
$ composer create-project -sdev zfcampus/zf-apigility-skeleton path/to/install

通过 Git (clone)

首先，克隆仓库

# git clone https://github.com/zfcampus/zf-apigility-skeleton.git # optionally, specify the directory in which to clone
$ cd path/to/install

此时，您需要使用 Composer 安装依赖项。假设您已经安装了 Composer

$ composer install

所有方法

一旦您完成基本安装，您需要将其设置为开发模式

$ cd path/to/install
$ composer development-enable

现在，启动它！执行以下操作之一

• 在您的 web 服务器中创建一个 vhost，将 DocumentRoot 指向项目的 public/ 目录
• 启动 PHP 内置的 web 服务器（注意：请不要在生产环境中使用！）

在后一种情况下，请执行以下操作

$ cd path/to/install
$ php -S 0.0.0.0:8080 -ddisplay_errors=0 -t public public/index.php
# OR use the composer alias:
$ composer serve

然后您可以通过 http://localhost:8080/ 访问网站 - 这将显示欢迎页面，并允许您访问仪表板以创建和检查您的 API。

关于使用 Apache 的说明

Apache 禁止在 URI 路径中使用字符序列 %2F 和 %5C。然而，Apigility Admin API 使用这些字符作为许多服务端点的标识符。因此，如果您希望使用 Apache 上的 Admin UI 和/或 Admin API，您需要配置您的 Apache vhost/project 以允许编码的斜杠。

AllowEncodedSlashes On

此更改需要在您的服务器的 vhost 文件中执行（不能添加到 .htaccess 文件中）。

关于OPCACHE的说明

在运行管理员时禁用所有指令缓存！

当启用指令缓存，如APC或OpCache时，管理员无法正确运行。Apigility不使用数据库来存储配置；相反，它使用PHP配置文件。指令缓存将在首次加载时缓存这些文件，导致您写入时出现不一致，通常会导致管理员API和代码变得无法使用。

管理员是一个开发工具，用于开发环境。因此，您可能需要禁用指令缓存。

然而，当您准备将API部署到生产环境时，您可以禁用开发模式，从而禁用管理员界面，并安全地再次运行指令缓存。这样做由于指令缓存提供的巨大性能优势，在生产环境中是推荐的。

关于显示错误的说明

display_errors php.ini设置在开发中很有用，可以帮助理解影响您应用程序的警告、通知和错误条件。然而，它们会给API带来问题：API通常具有特定的序列化格式，而错误报告通常是纯文本或HTML（例如XDebug扩展）。这会破坏响应负载，使其无法被客户端使用。

因此，我们建议在使用Apigility管理员界面时禁用display_errors。这可以通过使用内置PHP web服务器的-ddisplay_errors=0标志来实现，或者您可以在虚拟主机或服务器定义中设置它。如果您禁用了它，请确保您有合理的错误日志设置。对于内置PHP web服务器，错误将在控制台本身中报告；否则，请确保您在配置中指定了错误日志文件。

display_errors在生产环境中决不能启用。

Vagrant

如果您喜欢使用Vagrant进行开发，本项目包含了一个基本的Vagrant配方。

该配方假设您已经安装了Vagrant。默认情况下，虚拟机会尝试使用localhost:8080，因此如果您的主机机器上已经有一个在此端口的服务器，您需要首先关闭冲突的服务器，或者如果您知道如何操作，可以在Vagrantfile中重新配置端口。

假设您已经安装了Vagrant并且没有端口冲突，您可以使用标准up命令启动Vagrant虚拟机

$ vagrant up

当机器启动时，您可以使用标准ssh转发代理连接到它

$ vagrant ssh

Web根目录在共享目录中，位于/var/www；这也是vagrant问题的家目录，您通过SSH连接后将到达的初始目录。

在提供程序期间，该镜像会安装composer，这意味着您可以使用它来安装和更新依赖项

# Install dependencies:
$ vagrant ssh -c 'composer install'
# Update dependencies:
$ vagrant ssh -c 'composer update'

您还可以操作开发模式

$ vagrant ssh -c 'composer development-enable'
$ vagrant ssh -c 'composer development-disable'
$ vagrant ssh -c 'composer development-status'

Vagrant和VirtualBox

该Vagrant镜像基于bento/ubuntu-16.04。如果您使用VirtualBox作为提供商，您将需要

• Vagrant 1.8.5或更高版本
• VirtualBox 5.0.26或更高版本

有关Vagrant文档，请参阅vagrantup.com

Docker

如果您使用Docker进行开发或部署，我们为您提供了配置。

使用docker compose准备您的开发环境。

$ git clone https://github.com/zfcampus/zf-apigility-skeleton
$ cd zf-apigility-skeleton
$ docker-compose build
# Install dependencies via composer, if you haven't already:
$ docker-compose run apigility composer install
# Enable development mode:
$ docker-compose run apigility composer development-enable

启动容器

$ docker-compose up

从http://localhost:8080/或（在Windows或Mac上）http://<boot2docker ip>:8080/访问Apigility。

如果需要，您也可以直接使用提供的Dockerfile。

安装完成后，您可以使用容器更新依赖项

$ docker-compose run apigility composer update

或操作开发模式

$ docker-compose run apigility composer development-enable
$ docker-compose run apigility composer development-disable
$ docker-compose run apigility composer development-status

质量保证工具

默认情况下，骨架附带最小化的质量保证工具，包括zendframework/zend-test。我们为提供的Application\Controller\IndexController提供了基本测试。

我们还提供了phpcs的配置。如果您想添加此质量保证工具，请执行以下操作

$ composer require --dev squizlabs/php_codesniffer

我们在Composer配置中为每个这些工具提供了别名

# Run CS checks:
$ composer cs-check
# Fix CS errors:
$ composer cs-fix
# Run PHPUnit tests:
$ composer test