README

意图

基于约定优于配置（CoC）的范例创建一个框架。
创建一个框架，可以将您的数据库中的所有表映射到路由，无需做太多工作。
创建一个无需努力即可创建自定义路由的平台。

免责声明

首先，在开始使用此框架之前，您需要分析您的问题，以便在阅读此文档时检查框架是否适合作为您问题的可能解决方案。

您必须做什么？

您必须适应框架的配置。
您必须遵守此框架中类或文件命名的约定，如果不遵守，则框架无法正常运行。
您必须阅读以下文档，以便了解语法、可能的配置、命名、如何设置框架等。
为了使用框架的通用功能，您的数据库需要具备一些特性。

框架包含哪些内容？

支持多个数据库连接
公开通用的CRUD REST，暴露所有数据库表（创建、获取全部、更新、按ID获取、删除）
您可以使用自己的代码影响通用REST的生命周期
通用CRUD REST有一些自定义配置，例如软删除、更新前更改列、创建后更改列等。
您可以使用自己的代码创建自定义REST端点
如果您将代码放入特定的文件夹，则代码将自动转换为服务、配置、库，而无需任何配置
框架支持JWT进行身份验证，并链接到数据库中的一个枢纽表。
框架可以将代码分为版本（因为它是面向API的框架）
框架有一个简单但有效的迁移系统。
您可以通过终端创建命令（类似于symfony控制台）
框架支持使用Swagger注释的文档
框架包含一些示例代码，以展示如何在其中使用/创建代码。
支持Docker，您可以使用Docker和docker-compose设置您的项目。
支持CORS。
支持基于Swagger的文档。

框架不包含什么？

框架支持身份验证，但不支持授权，即框架阻止无权JWT的请求，但如果您有正确的JWT，则可以访问所有路由。
迁移系统不支持回滚，只能检查与其他SQL语句的冲突。
框架不支持长URL（请参阅以下教程以了解原因）。
支持后台进程，框架可以创建命令，但不能创建守护进程，如果您需要，请使用Linux中的cron服务。
不支持MySQL或PostgreSQL之外的不同数据库

在哪些情况下此框架是一个好主意？

如果您需要用最少的时间创建大量CRUD端点。
如果您希望以低工作量创建MVP（最小可行产品）。
如果您对JWT一无所知，但需要仅使用身份验证。
如果您喜欢以最小努力设置的项目。

在哪些情况下此框架不是一个好主意？

在性能是重要因素的项目中，框架执行速度较慢，因为约定优于配置。
在大项目中，最好使用更健壮的框架，如laravel、slim（无需此类修改）、lumen、库、速度、社区等。
如果您想了解一个框架是如何工作的（因为这个框架隐藏了所有这些复杂性）。
如果您的数据库不满足框架的要求，因为它可能会导致组件/配置问题。
如果您的数据库与mysql或postgresql不同（当前框架只支持这些数据库管理器）
如果您需要除了JWT之外的其他认证方法（这个框架只支持JWT）

教程

框架的要求

PHP 7.0或更高版本
MySQL或PostgreSQL
Docker
Docker-compose
composer

设置

使用composer创建一个新的项目

composer create-project microservice/raptor [name_of_directory]

框架的配置

首先，框架有一个配置文件的示例，请复制

cp configuration/application.yml.example configuration/application.yml

配置基于yaml格式，想象每个制表符都是一个点（.），例如这个

Application:
    display_error_details: true

我将被称为

Application.display_error_details: true

配置是

关于框架系统

Application.display_error_details: for show errors, true for show false for production

Application.add_content_length_header: always in false

Application.views.path: path where your html is (if you would like to use the templates), by default the templates are in the ./templates path

Application.logs.path: path where the application will put the messages in the log, by default the logs will be in ./logs/app.log

Application.logs.level: level for logging, the permitted values are: ERROR, DEBUG, WARN, INFO.

Application.logs.name: string that it will be showing in the logs.

Application.entity_configuration_file: for the characteristics of create CRUD on the fly the framework use this file for configurations of each table, please see the GENERIC CRUD section.

关于数据库连接

您可以添加多个数据库连接，主要连接命名为default，如果您需要添加另一个连接，请在Database.connections部分下放置配置，选项如下

Database.connections.[connection_name].host: host of the database
Database.connections.[connection_name].driver: the drivers supported are **mysql** or **postgres**
Database.connections.[connection_name].database: name of the database
Database.connections.[connection_name].charset: charset of the database
Database.connections.[connection_name].username: username of the database
Database.connections.[connection_name].password: password of the database
Database.connections.[connection_name].port: port of the database
Database.connections.[connection_name].lifecycle_callbacks: these are callbacks for the custom CRUD APIs, please check the LIFECICLE CUSTOM CRUD section, for that moment delete that section.

关于JWT配置

框架支持JWT认证，框架只需要一个连接，一个枢纽表（例如用户所在的表），密钥，枢纽表的列和JWT算法，请查看JWT网页以手动创建有效的jwt。

选项如下

JWT.table: the name of the table where the microservice will use in order to detect if is a valid user for the system.
JWT.connection: the principal connection where the database is (check the param Database.connections parameter).
JWT.algorithm: the algorithm wich the JWT module will based on
JWT.payload_user_field: the key of the JWT payload where the module will extract the value to search in the table.
JWT.table_user_field: the field of the table to compare with the JWT.payload_user_field value.
JWT.secret: the secret wich the module will analize if the jwt is valid.
JWT.whitelist: an array of urls wich the module will not find a valid JWT i.e, these url will not have Authorization.

示例：假设您有一个名为esans_prueba的数据库，数据库有一个名为usuario的表，其中存储了用户，它有一个名为identificador的列

pivot table example

另一方面，jwt有一个名为username的有效载荷字段，如下所示

JWT example

配置必须在configuration/application.yml

Application:
    display_error_details: true
    add_content_length_header: true
    views:
        path: "/../templates/"
    logs:
        path: '/../logs/app.log'
        level: DEBUG
        name: 'API-Catalogs'
    entity_configuration_name_file: entity
Database:
    connections:
        default:
            host: localhost
            driver: mysql
            database: esans_prueba
            charset: utf8
            username: root
            password: 56974993
            port: 3306
JWT:
    table: usuario
    connection: default
    algorithm: HS512
    payload_user_field: username
    table_user_field: identificador
    secret: secretkeyforthejwtgeneration
    whitelist:
        - /hola_mundo
        - /api/docs/{version}
        - /api/documentation/{version}

使用这个配置，对于每个请求，JWT模块将

分析请求是否包含JWT
如果请求包含JWT，将分析是否是有效的JWT（nbf，exp等，请查看JWT文档）
如果JWT有效，模块将使用以下查询获取用户：SELECT FROM usuario WHERE identificador=[jwt username key]，如果用户存在，用户将存储在框架容器中作为user_claim。

限制

此版本不支持枢纽表的软删除，即，如果您有一个用于标记非活动用户的active列，模块将在所有记录中查找。

将表映射到GENERIC CRUD模块

框架提供了一组使用Silly命令微型框架的命令，Jarvis PHP提供了一组命令来同步数据库的表到GENERIC CRUD模块

php scripts/jarvis.php database:schema:entity:synchronize

语法是

php scripts/jarvis.php database:schema:entity:synchronize [connection_from_application_yml] [version]

命令将创建/更新路径为Modules/[版本]/Configuration/[实体.yml]的存档，文件名取决于配置参数Application.entity_configuration_name_file。

您的实体文件可能如下所示

entity file example

如果您想了解自定义GENERIC CRUD URL的不同选项，请查看下面的部分

用于实时检查日志或

docker network inspect bridge --format='{{(index .IPAM.Config 0).Gateway}}'

以静默模式运行微型服务。

在执行docker-compose命令之前，请检查您的postgres/mysql是否支持外部连接。

如果所有这些都没有问题，请执行docker-compose

docker-compose up