README

描述

Bagual PHP是一个框架，旨在使用PHP以简单、标准化、一致和模块化的方式构建API。

功能

路由：定义和管理不同HTTP方法（GET、POST、PUT、DELETE）的路线。
请求：处理HTTP请求的数据，包括查询参数、请求体和头部。
响应：生成并发送HTTP响应，包含适当的状态代码和消息。
认证：实现基本的认证结构。
错误：管理异常和错误，提供适当的消息和状态代码。
配置：管理系统中的自定义.env文件配置。

要求

PHP 7.4或更高版本

安装

通过以下命令使用composer创建新项目

composer create-project william-nahirnei/bagual-php nome-projeto

导航到项目目录
```
cd nome-projeto
```
配置您的PHP环境以满足项目要求。
运行PHP服务器
- PHP服务器应在index.php文件的根目录下运行，以确保所有路线和配置都正确加载。
```
php -S localhost:8000
```

使用方法

项目结构

项目结构应遵循以下格式


    src/
    │
    ├── Modules/
    │ ├── ModuloExemplo/
    │ │ ├── Api.php
    │ │ └── ... (outros arquivos do módulo)
    │ └── ... (outros módulos)
    └── ... (outros diretórios e arquivos)

每个模块应有一个Api.php文件，该文件将被系统读取以确定端点和配置路由。

如何使用

路由：BagualPHP拥有基于模块的路由系统。

正确使用BagualPHP的方法是在Src/Modules目录中为您的API的每个模块创建目录。
创建您的模块目录后，您必须创建一个名为Api.php的类，该类应扩展Server\Routing\AbstractApi。这是定义端点的地方。
BagualPHP会在Src/Modules中的所有模块目录中进行搜索，并自动读取您在Api.php类中定义的端点。
定义protected ?string $moduleName = "usuario";属性。属性moduleName定义了模块的默认名称。如果您没有为端点定义特定的路由，BagualPHP将使用模块名称作为路由。例如，端点将可通过https://:8080/usuario访问。
应定义defaultAuthClass和defaultAuthMethod属性以指定模块的认证类和方法。当端点被触发时，BagualPHP将根据定义的类和方法进行认证。如果您不想对模块进行认证，请将这些属性设置为null。有关认证的更多信息，请参阅“认证”部分。

    protected ?string $defaultAuthClass = TokenAuth::class;
    protected ?string $defaultAuthMethod = "authenticate";

属性ignoreAuth用于标识模块是否将忽略系统、模块或端点配置中定义的认证。

定义您的Api类的构造函数，向父类构造函数发送值。

   public function __construct() {
       parent::__construct(
           $this->moduleName,
           $this->defaultAuthClass,
           $this->defaultAuthMethod,
           $this->ignoreAuth
       );
   }

定义端点：端点列表应在公共方法defineEndpointList内定义。
addEndpoint：每个端点通过调用方法addEndpoint(método [GET, POST, PUT, DELETE], "nomeEndpoint", 回应调用的类, "nome do método que irá responder à chamada", 认证类, "nome do método de autenticação", 忽略认证)来定义。

     $this->addEndpoint(static::METHOD_GET, null, UsuarioController::class, "listar");

控制器和认证方法应为静态。
以下是一个用于用户模块的完整Api.php类示例。

<?php
namespace Src\Modules\Usuario;

use Server\Routing\AbstractApi;
use Src\Modules\Usuario\Auth\TokenAuth;
use Src\Modules\Usuario\Controller\UsuarioController;

class Api extends AbstractApi {

    protected ?string $moduleName = "usuario";

    protected ?string $defaultAuthClass = null;

    protected ?string $defaultAuthMethod = null;

    protected ?bool $ignoreAuth = false;

    public function __construct() {
        parent::__construct(
            $this->moduleName,
            $this->defaultAuthClass,
            $this->defaultAuthMethod,
            $this->ignoreAuth
        );
    }

    public function defineEndpointList(): void {
        $this->addEndpoint(static::METHOD_GET, null, UsuarioController::class, "listar", TokenAuth::class, "authenticate");
        $this->addEndpoint(static::METHOD_POST, null, UsuarioController::class, "criar", TokenAuth::class, "authenticate");
        $this->addEndpoint(static::METHOD_PUT, null, UsuarioController::class, "atualizar", TokenAuth::class, "authenticate");
        $this->addEndpoint(static::METHOD_DELETE, "deletar", UsuarioController::class, "deletar", TokenAuth::class, "authenticate");
        $this->addEndpoint(static::METHOD_GET, "publico", UsuarioController::class, "publico");
    }
}
?>

请求: Request类是提供对应用程序请求的某些数据的访问的类。该类实现了InterfacePHPRequest接口，负责定义一些全局变量的索引的常量。
- Request类是一个单例，它在系统确定请求的API前缀是否与配置一致后初始化。
- Request类提供了一些重要数据，如查询字符串参数、请求体参数、文件和头部信息。要访问这些数据，请使用Request类。要访问查询字符串参数，例如在site.com/user?idUser=1&qtdRegistros=15中，可以使用
```
    $parametrosQueryString = Request::getInstance()->getQueryParams();
```
- 要访问请求体参数，请使用
```
    $parametrosBody = Request::getInstance()->getBodyParams();
```
- 要访问查询字符串和请求体参数，请使用
```
    $todosParametros = Request::getInstance()->getAllMergedParams();
```
- 此方法返回查询字符串和请求体参数，当名称相同时，将使用请求体参数替换查询字符串参数。
- 要访问头部信息，请使用
```
    $headers = Request::getInstance()->getHeaders();
```
- 要访问其他请求数据，请查阅类文档以了解提供的数据和方法。
响应: Response类负责管理和构建请求的响应。
- 要定义请求的响应数据，只需在由端点触发的相应方法中返回所需数据即可。自动地，Response类将尝试将提供的数据转换为JSON。
- Response类实现了一些用于响应默认值的接口和InterfaceHeaders接口，该接口定义了响应头部的默认字符串。
- 如果没有返回值，响应的默认值如下，HTTP状态码为默认的200
```
{
    "message": "",
    "data": null
}
```
- 要定义HTTP状态码，请使用
```
    Response::setStatusCode(StatusCodes::HTTP_OK);
```
- HTTP响应代码定义在StatusCodes类的常量中。
- 要添加响应头，请使用addHeader(nomeHeader, valorHeader)
```
        Response::addHeader(Response::HEADER_CONTENT_TYPE, Response::CONTENT_TYPE_JSON);
```
- 要向同一个头部添加多个值，请使用addHeader方法，并提供头部名称和附加值。
认证: BagualPHP提供了一种自定义且简单的方法来定义API的认证方式。只需开发认证逻辑并定义系统中的哪些位置需要认证。
- API的通用认证。
  - 要在一个位置认证整个API，创建一个继承自AbstractAuthenticable类的认证类，并使用静态方法authenticate。此方法应返回true或false，指示认证是否成功。此外，实现callAuthError方法，在认证无效时抛出异常。
  - 建议始终使用AuthenticationException处理无效认证。
  - 在实现认证后，配置envsConfigs/.auth.env文件，指定创建的认证类名称。之后，系统将自动认证整个API。如果您的认证类仅返回true或false，则系统将自动使用默认的认证错误。
  - 所有认证类都必须继承自AbstractAuthenticable类。
  - BagualPHP将调用的主要认证方法必须是静态的，并且不应有参数。
  - 以下是一个系统标准认证类的示例
```
    <?php

   namespace Src\Auth;
   
   use Server\Auth\AbstractAuthenticable;
   use Server\Constants\ServerMessage;
   use Server\Errors\AuthenticationException;
   
   class GeneralAuth extends AbstractAuthenticable{
       /**
        * This method must be implemented by subclasses and must throw AuthenticationException
        *
        * @throws AuthenticationException
        */
       protected static function callAuthError(): void {
           throw new AuthenticationException([ServerMessage::DEFAULT_AUTH_ERROR]);
       }
   
       public static function authenticate() {
           return false;
       }
   }
   ?>
```
  - 以下是配置的.env文件
```
    DEFAULT_CLASS_NAMESPACE = Src\Auth\GeneralAuth
```
- 模块认证
  - 如前所述，您可以为模块和方法单独定义认证方式。要为整个模块定义单独的认证，请在您的模块的Api.php文件中配置以下变量。如果您不希望对该模块进行认证，将这些变量定义为null。
```
   protected ?string $defaultAuthClass = TokenAuth::class;

   protected ?string $defaultAuthMethod = "authenticate";
```
- 端点认证
  - 如果您只想认证模块中的一个端点，请在addEndpoint方法中为要认证的端点设置认证。或者，您可以认证整个模块，并使用忽略认证变量为所有端点设置，除了您想认证的那个端点。
```
   $this->addEndpoint(static::METHOD_GET, null, UsuarioController::class, "listar", TokenAuth::class, "authenticate");
```
- 忽略认证
  - 您也可以在API的模块或端点级别忽略认证。要忽略为API全局定义的模块级别的认证，请在模块的Api.php文件中将变量$ignoreAuth = true设置为true。
  - 要忽略特定端点的认证，无论是全局的还是模块的，在addEndpoint方法中将ignoreAuth参数设置为true。
- 认证优先级
  - BagualPHP总是按照特定的优先级顺序尝试应用认证。如果未定义特定级别的认证，BagualPHP将尝试应用更高级别的认证。优先级顺序如下：从最具体的到最通用的。 - 1: addEndpoint方法，端点特定认证。 - 2: 模块默认认证。 - 3: API通用认证。
  - 如果在addEndpoint方法中为认证发送了空值，BagualPHP将尝试使用模块中定义的值，如果需要，将回退到API的通用认证。
错误：BagualPHP具有一个用于处理ApiException类型异常的自定义处理系统。当BagualPHP遇到此类异常时，它将返回一个包含异常中定义的HTTP代码和消息的API响应。以下是一个抛出此类异常的示例：
```
 throw new ApiException(true, ApiExceptionTypes::ERROR, ["Usuario não encontrado"], StatusCodes::HTTP_NOT_FOUND);
```
- 如果您的异常包含多个消息，BagualPHP将返回连接的消息列表，由|分隔。

自定义配置：BagualPHP具有用于自定义.env文件的配置管理，您可以使用它来创建和管理API的配置。

要使用自定义配置，请在envsConfigs文件夹中创建一个配置文件.env。
例如，配置文件exemplo.env。

    CFG_EXEMPLO = TESTE

创建一个继承自Config/ConfigLoader.php的类。在类中，定义一个包含配置文件名称的常量。
```
  protected const FILE_NAME = '.exemplo.env';
```
定义可读配置数组
```
    protected const CONFIG_KEYS = ["CFG_EXEMPLO"];
```
好了，您的配置已准备好使用。您可以根据需要创建多个配置文件，用于不同的用途。

以下是一个完整的测试类示例

   <?php
   
   namespace Src\Modules\Usuario;
   
   use Config\ConfigLoader;
   
   class ConfigExemplo extends ConfigLoader {

       protected const FILE_NAME = '.exemplo.env';
   
       public const CFG_EXEMPLO = "CFG_EXEMPLO";
   
       protected const CONFIG_KEYS = [
           self::CFG_EXEMPLO,
       ];
   }
   ?>

要读取您的配置，只需使用

    ConfigExemplo::getInstance()->getConfig("Nome da configuração definida no arquivo .env");

许可证

本项目采用MIT许可证。联系

如果您有任何疑问或建议，请随时联系

E-mail: william.nahirnei@gmail.com
GitHub: WilliamNahirnei

william-nahirnei / bagual-php

维护者

详细信息

README

描述

功能

要求

安装

使用方法

项目结构

如何使用