README

为不使用大型框架的小型项目提供辅助类集。

此助手包含以下辅助工具

• 数据库连接和查询（Conn）
• 请求接收控制（Server/Uri）
• API 的简化 JSON 输出（Server/Output）
• 执行请求（HttpRequest）

添加到项目中

composer require szagot/helper

每个 Helper 的详细信息

注意：有一个使用此类中几乎所有 Helper 的游戏 API 后端项目。如果您想将其作为示例，请参阅 szagot/ancient-backend

数据库连接： \Szagot\Helper\Conn

连接到数据库

$conn = new Connection(
    'banco',
    'localhost',
    'root',
    'senha'
);

准备连接的执行基础

Query::setConn($conn);

直接执行查询

$search = Query::exec(
    'SELECT * FROM tabela WHERE name LIKE :name',
    [
        'name' => "%{$name}%",
    ],
    MinhaClassePersonalizada::class
)

执行上述 CRUD 请求

try {
    $search = Crud::search(MinhaClassePersonalizada::class, 'name', "%{$name}%");
} catch (ConnException $e) {
    exit($e);
}

执行自定义搜索

try {
    $search = Crud::searchCustom(
    MinhaClassePersonalizada::class, 
    'name LIKE :name AND age >= :age', 
    [
        'name' => '%fulano%', 
        'age' => 18,
    ]
    );
} catch (ConnException $e) {
    exit($e);
}

直接执行插入

Query::exec(
    'INSERT INTO tabela (campo1, campo2) VALUES (:campo1, :campo2)',
    [
        'campo1' => $valor1,
        'campo2' => $valor2,
    ],
    MinhaClassePersonalizada::class
)

$id = Query::getLastLog()?->getLastId() ?? null;

使用 CRUD 执行插入

try {
    $id = Crud::insert(MinhaClassePersonalizada::class, $minhaInstancia);
} catch (ConnException $e) {
    exit($e);
}

使用 CRUD

为了正确使用 CRUD，需要

• 创建一个 Connection 类型的连接
• 将其添加到查询中
• 拥有扩展自 aModel 的模型
• 使用必选属性 Table 和 PrimaryKey
• 如果您的模型字段是额外的，也就是说，没有在表中具有相同名称的字段，请使用可选属性 IgnoreField

注意：对于没有主键的自定义表，请直接使用 Query，而不是 CRUD。

基本示例

// Model
#[Table(name: 'nome_da_tabela_do_banco')]
class MinhaClassePersonalizada extends \Szagot\Helper\Conn\Model\aModel
{
    #[PrimaryKey]
    protected int     $id;
    protected ?string $campo1;
    protected ?string $campo2;
    
    #[IgnoreField]
    protected OutraClasse $campoQueNaoPertenceATabela;
}

// Preparando conexão
Query::setConn(
    new Connection(
        'banco',
        'localhost',
        'root',
        ''
    )
);

// Pegando um registro específico: ID = 1
try {
    /** @var MinhaClassePersonalizada $minhaInstancia */
    $minhaInstancia = Crud::get(MinhaClassePersonalizada::class, 1);
} catch (ConnException $e) {
    exit($e);
}

注意！如果主键不是自增类型，不要忘记在属性中告知这一点
主键的以下形式

// Model
#[Table(name: 'nome_da_tabela_do_banco')]
class MinhaClassePersonalizadaSemAutoIncremento extends \Szagot\Helper\Conn\Model\aModel
{
    #[PrimaryKey(autoIncrement: false)]
    protected string  $code;
    protected ?string $campo1;
    protected ?string $campo2;
}

请求接收控制： \Szagot\Helper\Server

输出类型为 JSON（Content-type: application/json）

use Szagot\Helper\Server\Output;

// Saída com sucesso
Output:success($arrayDeSaida);

// Erro
Output::error('Deu ruim');

您也可以指定与默认不同的输出头部

// Saída com sucesso
Output:success($arrayDeSaida, Output::POST_SUCCESS);

// Erro
Output::error('Deu ruim', Output::ERROR_NOT_FOUND);

注意：`Output::success` 或 `Output::error` 输出并终止应用程序。在这之后不再执行任何操作。

获取请求

use Szagot\Helper\Server\Uri;
use Szagot\Helper\Server\Models\Parameter;

$uri = Uri::newInstance();

// IP de quem fez a requisição
$requestIp = $uri->getRequestIp();
// Cabeçalhos da requisição recebida
$headers = getHeaders()
// Método (GET, POST, PUT, PATCH, DELETE, OPTION)
$method = $uri->getMethod();
// URL completa da requisição. Exemplo: "https://:8080/pagina/opcao/detalhe"
$url = $uri->getUrl();
// String da Uri. Exemplo: "pagina/opcao/detalhe"
$uri = $uri->getTextUri();
// Primeira posição da Uri. Exemplo: "pagina"
$page = $uri->getUri(0);
// Arquivo de name "file" enviado
$file = $uri->getFile('file');
// Todos os arquivos enviados
$files = $uri->getFiles();

// Pegando parâmetros
$name = $uri->getParameter('name');
// Validando se o parâmetro "isGamer" foi informado na requisição
if($uri->parameterExists('isGamer')){
    $isGamer = $uri->getParameter('isGamer', Parameter::FILTER_BOOL);
}

更改 URI 行为:

如果您的 API 部署在服务器根目录之外的不同目录中，您可以将路径固定为应用的 root。

这样它将被方法忽略。

示例：假设您的服务位于 "https://servidor.com/caminho/da/aplicacao/"，您可以这样操作

use Szagot\Helper\Server\Uri;

$uri = Uri::newInstance('caminho/da/aplicacao');

$uriTxt = $uri->getTextUri();
$page = $uri->getUri(0);
$id = $uri->getUri(1);

在上面的示例中，如果请求 "https://servidor.com/caminho/da/aplicacao/produto/20"，变量的值将是

$uriTxt: "pagina/20"
$page..: "produto"
$id....: "20"

注意：如果使用 newInstance() 或 setRoot() 传递 root，则不需要在其他应用程序的任何其他点再次传递。每个实例化的 Uri 都将保持 root，除非您再次使用其他值传递。

关于参数:

$uri->getParameter('parametro') 或 $uri->getParameters() 指的是通过 body、FormData 或甚至 Query String 发送的任何参数。

在出现重复的情况下，body 中提供的参数将具有优先级。

要获取请求的Body部分，请使用 $uri->getBody()。这将返回一个 stdClass 类型的Body。

或者使用 $uri->getBody(false) 以原始字符串格式返回。

请求执行：Szagot\Helper\HttpRequest

执行请求

use Szagot\Helper\Request\HttpRequest;

// URI do API
$uri = 'https://api.site.com.br/v1/collection'; 

// Preparando header
$header = [
    'Content-Type: application/json',
    'User-Agent: Exemplo',
];

// Preparando body
$body = [
    'campo1' => 'valor de exemplo',
    'campo2' => 99.9,
];

// Enviando requisição do tipo POST com Auth Basic
$envioExemplo = new HttpRequest( $uri, 'POST', $header );
$envioExemplo
    ->setBodyContent($body)
    ->setBasicUser('usuario')
    ->setBasicPass('senha')
    ->execute();

// Pegando dados do retorno
$response = $envioExemplo->getResponse();
$responseBody = $response->getBody();
$responseHttpStatus = $response->getStatus();

如果您想在请求中发送一个文件，只需在 setBodyContent() 之后调用 addFileToRequest()，如下所示

// Arquivo
$file = $uri->getFile('file');
$body = [
    'campo1' => 'valor de exemplo',
    'campo2' => 99.9,
];

$envioExemplo
    ->setBodyContent($body)
    ->addFileToRequest($file)
    ->execute();

// Pegando dados do retorno
$response = $envioExemplo->getResponse();
$responseBody = $response->getBody();
$responseHttpStatus = $response->getStatus();