PHPackages william-nahirnei/bagual-php - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Framework](/categories/framework) 4. / 5. william-nahirnei/bagual-php ActiveLibrary[Framework](/categories/framework) william-nahirnei/bagual-php =========================== Framework para construção de APIs PHP de maneira solida, consistente e modular. 1.0.0(1y ago)17MITPHPPHP >=7.4 Since Aug 20Pushed 1y ago1 watchersCompare [ Source](https://github.com/WilliamNahirnei/BagualPHP)[ Packagist](https://packagist.org/packages/william-nahirnei/bagual-php)[ RSS](/packages/william-nahirnei-bagual-php/feed)WikiDiscussions main Synced 1mo ago READMEChangelogDependenciesVersions (2)Used By (0) BagualPHP ========= [](#bagualphp) Descrição --------- [](#descrição) O Bagual PHP é um framework, pensado na construção de APIs utilizando PHP de maneira simples, padronizada, consiste e modular. Funcionalidades --------------- [](#funcionalidades) - **Roteamento**: Define e gerencia rotas para diferentes métodos HTTP (GET, POST, PUT, DELETE). - **Requisições**: Manipula dados de requisições HTTP, incluindo parâmetros de consulta, corpo da requisição e cabeçalhos. - **Respostas**: Gera e envia respostas HTTP com códigos de status e mensagens apropriadas. - **Autenticação**: Implementa uma estrutura básica de autenticação. - **Erros**: Gerencia exceções e erros, fornecendo mensagens e códigos de status apropriados. - **Configurações**: Gerencia configurações personalizadas de arquivos .env no sistema. Requisitos ---------- [](#requisitos) - PHP 7.4 ou superior Instalação ---------- [](#instalação) 1. Crie um novo projeto através do composer com o comando : ``` composer create-project william-nahirnei/bagual-php nome-projeto ``` 2. Navegue para o diretório do projeto: ``` cd nome-projeto ``` 3. Configure seu ambiente PHP para atender aos requisitos do projeto. 4. **Execute o Servidor PHP:** - O servidor PHP deve ser executado na raiz do arquivo index.php projeto para garantir que todas as rotas e configurações sejam corretamente carregadas: ``` php -S localhost:8000 ``` Uso --- [](#uso) ### Estrutura do Projeto [](#estrutura-do-projeto) A estrutura do projeto deve seguir o seguinte formato: ``` src/ │ ├── Modules/ │ ├── ModuloExemplo/ │ │ ├── Api.php │ │ └── ... (outros arquivos do módulo) │ └── ... (outros módulos) └── ... (outros diretórios e arquivos) ``` Cada módulo deve ter um arquivo `Api.php`, que será lido pelo sistema para determinar os endpoints e configurar as rotas. ### Como Usar [](#como-usar) 1. **Roteamento**: O BagualPHP conta com um sistema de roteamento baseado em módulos. - A maneira correta de utilizar o BagualPHP é criar diretórios para cada um dos módulos da sua API dentro do diretório `Src/Modules`. - Após criar o diretório do seu módulo, você deve criar uma classe Api.php que deve estender `Server\Routing\AbstractApi`. É nessa classe que seus endpoints serão definidos. - O BagualPHP faz uma busca por todos os diretórios de módulos dentro de `Src/Modules` e realiza a leitura automática dos endpoints definidos na sua classe `Api.php`. - Defina o atributo `protected ?string $moduleName = "usuario";` O atributo `moduleName` define um nome padrão para o módulo. Caso você não defina uma rota específica para os endpoints, o BagualPHP assumirá o nome do módulo como rota. Por exemplo, o endpoint será acessível em: `http://localhost:8080/usuario`. - O atributo `defaultAuthClass` e o atributo `defaultAuthMethod` devem ser definidos para especificar uma classe e um método de autenticação para o módulo. Quando um endpoint for acionado, o BagualPHP irá autenticar conforme a classe e o método definidos. Caso você não queira autenticar o módulo, defina esses dois atributos como nulos. Leia mais sobre autenticação na seção de 'Autenticação'. ``` protected ?string $defaultAuthClass = TokenAuth::class; protected ?string $defaultAuthMethod = "authenticate"; ``` - O atributo `ignoreAuth`, é usado para identificar se o modulo ira ignorar a autenticação definida seja nas configurações do sistema, modulo, ou endpoint. - Defina o construtor da sua classe Api, enviando os valores para o construtor da classe pai. ``` public function __construct() { parent::__construct( $this->moduleName, $this->defaultAuthClass, $this->defaultAuthMethod, $this->ignoreAuth ); } ``` - Definindo endpoints: A lista de endpoints deve ser definida dentro do método público `defineEndpointList`. - addEndpoint: Cada endpoint é definido pela chamada do método `addEndpoint(método [GET, POST, PUT, DELETE], "nomeEndpoint", Classe que irá responder à chamada, "nome do método que irá responder à chamada", classe de autenticação, "nome do método de autenticação", ignorar autenticação)`. ``` $this->addEndpoint(static::METHOD_GET, null, UsuarioController::class, "listar"); ``` - Os métodos de controlador e de autenticação deverão ser estáticos. - Abaixo, temos um exemplo de uma classe `Api.php` completa para um módulo de usuário. ``` ``` 2. **Request:** A classe `Request` é a classe que disponibiliza acesso a alguns dados da requisição feita para a sua aplicação. A classe `Request` implementa a `InterfacePHPRequest`, responsável por definir as constantes para alguns índices das variáveis superglobais. - A classe Request é um singleton que é inicializado após o sistema determinar se o prefixo da API da requisição é válido em relação ao que foi configurado. - A classe Request disponibiliza alguns dados importantes, como parâmetros de query string, parâmetros do corpo da requisição, arquivos e headers. Para acessar esses dados, utilize a classe Request. Para acessar parâmetros da query string, como em site.com/user?idUser=1&qtdRegistros=15, você pode usar: ``` $parametrosQueryString = Request::getInstance()->getQueryParams(); ``` - Para acessar parâmetros do corpo da requisição, utilize: ``` $parametrosBody = Request::getInstance()->getBodyParams(); ``` - Para acessar parâmetros de query string e do corpo da requisição, utilize: ``` $todosParametros = Request::getInstance()->getAllMergedParams(); ``` - Esse método retorna os parâmetros da query string e do corpo da requisição, substituindo os parâmetros da query string pelos parâmetros do corpo da requisição quando os nomes forem iguais. - Para acessar os headers, utilize: ``` $headers = Request::getInstance()->getHeaders(); ``` - Para acessar outros dados da requisição, consulte a documentação da classe para ver os dados disponibilizados e os métodos para recuperá-los. 3. **Response**: A classe Response é responsável por gerenciar e montar a resposta para a sua requisição. - Para definir os dados de resposta da requisição, basta retornar os dados desejados no método que foi acionado pelo endpoint. Automaticamente, a classe Response tentará converter os dados informados para JSON. - A classe Response implementa algumas interfaces para valores padrão de resposta e a interface `InterfaceHeaders`, que define as strings padrão para headers de resposta. - O valor padrão de uma resposta, caso o método do controlador não retorne nada, é o seguinte conteúdo, com código HTTP padrão 200: ``` { "message": "", "data": null } ``` - Para definir um código HTTP de status, utilize: ``` Response::setStatusCode(StatusCodes::HTTP_OK); ``` - Os códigos de resposta HTTP estão definidos em constantes da classe StatusCodes. - Para adicionar um header de resposta, utilize `addHeader(nomeHeader, valorHeader)`: ``` Response::addHeader(Response::HEADER_CONTENT_TYPE, Response::CONTENT_TYPE_JSON); ``` - Para adicionar mais de um valor ao mesmo header, utilize o método `addHeader`, informando o nome do header e o valor adicional. 4. **Autenticação**: O BagualPHP oferece uma maneira de definir métodos de autenticação de forma customizada e simples para sua API. Basta desenvolver a lógica de autenticação e definir quais serão os locais autenticados no seu sistema. - Autenticação geral de api. - Para autenticar toda a sua API em um único local, crie uma classe de autenticação que estenda a classe `AbstractAuthenticable` com o método estático `authenticate`. Esse método deverá retornar `true` ou `false`, indicando se a autenticação foi bem-sucedida. Além disso, implemente o método `callAuthError`, que deverá lançar uma exceção caso a autenticação não seja válida. - Aconselhamos sempre utilizar a `AuthenticationException` para autenticações inválidas. - Após a implementação da sua autenticação, configure o arquivo `envsConfigs/.auth.env` com o nome da classe de autenticação criada. Depois disso, o sistema irá automaticamente autenticar toda a sua API. Caso a sua classe de autenticação apenas retorne `true` ou `false`, o sistema utilizará automaticamente um erro padrão de autenticação. - Todas as classes de autenticação deverão estender a classe `AbstractAuthenticable`. - O método principal de autenticação a ser chamado pelo BagualPHP deverá sempre ser estático e não deve ter parâmetros. - Aqui está um exemplo de uma classe de autenticação padrão para o sistema: ``` ``` - Aqui está o arquivo de configuração `.env` configurado: ``` DEFAULT_CLASS_NAMESPACE = Src\Auth\GeneralAuth ``` - Autenticação de Módulo: - Como mencionado anteriormente, você pode definir autenticações de maneira isolada para módulos e métodos. Para definir uma autenticação isolada para todo um módulo, configure as variáveis a seguir no arquivo `Api.php` do seu módulo. Caso não queira autenticar o módulo, defina essas variáveis como `null`. ``` protected ?string $defaultAuthClass = TokenAuth::class; protected ?string $defaultAuthMethod = "authenticate"; ``` - Autenticação de Endpoint: - Caso queira autenticar somente um endpoint do módulo, defina a autenticação no método `addEndpoint` para o endpoint que deseja autenticar. Alternativamente, você pode autenticar todo o módulo e usar a variável de ignorar autenticação para todos os endpoints, exceto aquele que deseja autenticar. ``` $this->addEndpoint(static::METHOD_GET, null, UsuarioController::class, "listar", TokenAuth::class, "authenticate"); ``` - Ignorando Autenticações: - Você também pode ignorar autenticações em sua API, seja em nível de módulo ou de endpoint. Para ignorar uma autenticação definida globalmente para a API, em nível de módulo, defina a variável `$ignoreAuth = true` no arquivo `Api.php` do módulo. - Para ignorar a autenticação de um endpoint específico, seja global ou de módulo, envie o parâmetro `ignoreAuth` como `true` no método `addEndpoint`. - Prioridades de Autenticação: - O BagualPHP sempre tentará aplicar a autenticação seguindo uma ordem de prioridade específica. Caso não tenha sido definida autenticação para um nível específico, o BagualPHP tentará assumir a autenticação do nível superior. A ordem de prioridade é a seguinte: do item mais específico para o item mais genérico. - 1: Método `addEndpoint`, autenticação específica do endpoint. - 2: Autenticação padrão do módulo. - 3: Autenticação geral da API. - Caso você envie valores nulos para autenticação no método `addEndpoint`, o BagualPHP tentará usar os valores definidos no módulo e, se necessário, recorrerá à autenticação geral da API. 5. **Erros**: O BagualPHP conta com um sistema de tratamento personalizado para exceções do tipo `ApiException`. Quando o BagualPHP encontrar uma exceção desse tipo, ele retornará uma resposta de API com o código HTTP definido na exceção e a mensagem definida na exceção. Aqui está um exemplo de como lançar uma exceção desse tipo: ``` throw new ApiException(true, ApiExceptionTypes::ERROR, ["Usuario não encontrado"], StatusCodes::HTTP_NOT_FOUND); ``` - Caso a sua exceção tenha mais de uma mensagem, o BagualPHP retornará a lista de mensagens concatenadas, separadas pelo caractere `|`. 6. **Configurações personalizadas**: O BagualPHP conta com um gerenciamento de configurações para arquivos `.env` personalizados, que você pode utilizar para criar e administrar configurações para suas APIs. - Para utilizar as configurações personalizadas, crie um arquivo de configuração .env dentro da pasta `envsConfigs`. - Como, por exemplo, o arquivo de configuração `exemplo.env`. ``` CFG_EXEMPLO = TESTE ``` - Crie uma classe que estenda `Config/ConfigLoader.php`. Dentro da classe, defina uma constante com o nome do seu arquivo de configuração. ``` protected const FILE_NAME = '.exemplo.env'; ``` Defina o array de configurações de leitura permitida ``` protected const CONFIG_KEYS = ["CFG_EXEMPLO"]; ``` Pronto, suas configurações estão preparadas para serem utilizadas. Você pode criar múltiplos arquivos de configuração conforme necessário para diferentes usos. - Aqui está o exemplo da classe de teste completa: ``` ``` - Para realizar a leitura das suas configurações, basta utilizar: ``` ConfigExemplo::getInstance()->getConfig("Nome da configuração definida no arquivo .env"); ``` Licença Este projeto é licenciado sob a Licença MIT. Contato Se você tiver alguma dúvida ou sugestão, sinta-se à vontade para entrar em contato: ``` E-mail: william.nahirnei@gmail.com GitHub: WilliamNahirnei ``` ### Health Score 23 — LowBetter than 27% of packages Maintenance34 Infrequent updates — may be unmaintained Popularity6 Limited adoption so far Community7 Small or concentrated contributor base Maturity39 Early-stage or recently created project Bus Factor1 Top contributor holds 100% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Unknown Total 1 Last Release 628d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/c86cab48e964c4c113cd1053c10c9658d84c7cc336a8d69e0c00f5f2a83d5142?d=identicon)[WilliamNahirnei](/maintainers/WilliamNahirnei) --- Top Contributors [![WilliamNahirnei](https://avatars.githubusercontent.com/u/37477933?v=4)](https://github.com/WilliamNahirnei "WilliamNahirnei (38 commits)") ### Embed Badge ![Health badge](/badges/william-nahirnei-bagual-php/health.svg) ``` [![Health](https://phpackages.com/badges/william-nahirnei-bagual-php/health.svg)](https://phpackages.com/packages/william-nahirnei-bagual-php) ``` ### Alternatives [laravel/telescope An elegant debug assistant for the Laravel framework. 5.2k67.8M192](/packages/laravel-telescope)[spiral/roadrunner RoadRunner: High-performance PHP application server and process manager written in Go and powered with plugins 8.4k12.2M84](/packages/spiral-roadrunner)[nolimits4web/swiper Most modern mobile touch slider and framework with hardware accelerated transitions 41.8k177.2k1](/packages/nolimits4web-swiper)[laravel/dusk Laravel Dusk provides simple end-to-end testing and browser automation. 1.9k36.7M257](/packages/laravel-dusk)[laravel/prompts Add beautiful and user-friendly forms to your command-line applications. 708181.8M593](/packages/laravel-prompts)[cakephp/chronos A simple API extension for DateTime. 1.4k47.7M121](/packages/cakephp-chronos) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)