README

目录

• 关于
• 安装
• 配置
• 使用示例
• 工作原理
• 测试
• 路线图

关于

Philarmony是一个用于帮助您创建模块化REST API的包。从数据库到控制器和表单，以及授权和数据验证，您可以在几分钟内轻松管理API。

V.3.0 - 新特性

更好的性能，这就是Philarmony V3的总结。核心已经用以下方式重写

安装

假设composer已经全局安装，您可以使用以下命令进行安装

composer require deozza/philarmony-core-bundle

配置

为了在项目中使用Philarmony，您需要对其进行配置。首先，创建一个philarmony.yaml文件，其结构如下

deozza_philarmony:
    directory:
      entity: ~
      property: ~
      enumeration: ~

这将用于定位数据库模式文件。默认情况下，它们被创建并存储在/var/Philarmony/。

然后，为了使用Philarmony内嵌的服务，例如控制器和存储库，您需要在您的/config/services.yaml和config/routes/annotations.yaml中启用它们

services: 
    Deozza\PhilarmonyCoreBundle\Controller\:
      resource: '@DeozzaPhilarmonyCoreBundle/Controller'
      tags: ['controller.service_arguments']
      
    Deozza\PhilarmonyCoreBundle\Repository\:
      resource: '@DeozzaPhilarmonyCoreBundle/Repository'
      tags: ['doctrine.service_entity']  

philarmony_controllers:
    resource: '@DeozzaPhilarmonyCoreBundle/Controller'
    type: annotation
    prefix: /

最后，为了在查询中使用过滤器，您需要在doctrine.yaml配置文件中添加以下功能

doctrine:
    orm:
        dql:
            string_functions:
                JSON_EXTRACT: Scienta\DoctrineJsonFunctions\Query\AST\Functions\Mysql\JsonExtract
                JSON_UNQUOTE: Scienta\DoctrineJsonFunctions\Query\AST\Functions\Mysql\JsonUnquote

使用示例

在这个示例中，我们的API示例将管理度假租赁。用户可以创建租赁报价、预订假期并通过内部消息服务进行交流。

因此，数据库将包含4种不同的实体类型

• offer：包含有关租赁报价的所有信息
• booking：包含有关预订及其关联报价的所有信息
• conversation：包含两个用户之间的所有消息
• message：包含消息内容及其它相关信息

这些实体在默认的entity.yaml配置文件中定义，其属性在property.yaml文件中。

以下是一个使用JSON体（在JSON中）创建新的租赁报价的cUrl请求示例

curl --header "Content-Type: application/json"
     --request POST
     --data '{"title": "Stunning appartment in Tokyo", "description": "Located in central Tokyo. 2 bedrooms, bathroom, wifi.", "price": 82, "place_category":"appartment"}'
     http://www.mysuper.app/api/entity/offer

如您所见，您在URL中指定了要发布的实体类型。这将允许Philarmony根据您在yaml配置文件中实现的业务逻辑以及您的业务逻辑来调整API的行为。以下是您从上一个请求中期望的JSON响应

{
  "uuid": "00100000-0000-4000-a000-000000000000",
  "kind": "offer",
  "owner": "00100000-0000-4000-a000-000000000000",
  "date_of_Creation": "2019-01-01T12:00:00+02:00",
  "properties": {
    "title": "Stunning appartment in Tokyo",
    "description": "Located in central Tokyo. 2 bedrooms, bathroom, wifi.",
    "price": 82,
    "place_category": "appartment"
  }
}

假设一个报价可以有多个描述，您想添加另一个，只需发送如下请求

curl --header "Content-Type: application/json"
     --request POST
     --data '{"description": "Animals are allowed"}'
     http://www.mysuper.app/api/offer/00100000-0000-4000-a000-000000000000/description

以下将是预期的响应

{
  "uuid": "00100000-0000-4000-a000-000000000000",
  "kind": "offer",
  "owner": "00100000-0000-4000-a000-000000000000",
  "date_of_Creation": "2019-01-01T12:00:00+02:00",
  "properties": {
    "title": "Stunning appartment in Tokyo",
    "description": [
       "Located in central Tokyo. 2 bedrooms, bathroom, wifi.",
       "Animals are allowed"
       ],
    "price": 82,
    "house_category": "appartment"
    }
}

响应

当您对Philarmony执行请求时，它将始终发送一个包含序列化JSON和一个上述HTTP状态码的响应。

工作原理

数据库模式

您的数据库模式完全由3个yaml文件设计。

实体

实体可以被视为MySQL表，是数据的容器。默认情况下，它由所有者（创建实体的用户）、类型、创建日期及其属性定义。

• 阅读更多

属性

属性可以被视为MySQL列，是特定数据的容器。默认情况下，它由类型、unique参数和required参数定义。

• 阅读更多

枚举

枚举是属性处理的可能值的列表。

• 阅读更多

验证状态

验证状态用于断言实体处于良好的使用状态。每个状态定义了特定用户可用的特定方法。

• 阅读更多

授权

为了确保正确的用户正在操作资源，授权由验证状态处理。它决定了哪些用户可以发送不同的请求。

• 阅读更多

约束

为了从一个状态过渡到下一个状态，实体及其数据必须根据约束有效。

• 阅读更多

冲突规则

冲突规则是一个需要开发和不能添加到配置文件的定制和高级约束。

• 阅读更多

测试

已经开发了一个演示应用程序，可在此处查看。通过该应用程序的测试，我们确保Philarmony的每个功能都经过测试，并保证包的稳定性。

路线图

• 数据库迁移：目前，当你删除或更新属性或实体时，你需要手动处理迁移。为了获得更好的体验，我正在考虑一种自动解决方案。