Download the PHP package jot/hf-repository without Composer

hf-repository

O hf-repository é uma library extensível para gerenciamento de dados, oferecendo uma camada de abstração baseada no conceito de Repositories. Ele foi projetado para trabalhar de forma eficiente com o Elasticsearch, utilizando o padrão de design Repository Pattern para isolar a lógica de acesso aos dados. Simplifica a interação com índices, facilita o mapeamento de resultados para entidades e fornece suporte confiável para operações CRUD, busca avançada, paginação e geração de consultas dinâmicas.

Recursos Principais

• Abstração de Repositórios: Camada central para comunicação com o Elasticsearch.
• CRUD Completo: Operações básicas para criar, buscar, atualizar e remover itens.
• Paginação Simplificada: Paginador nativo com alta personalização de parâmetros.
• Mapeamento de Entidades: Integra resultados aos objetos do domínio do projeto.
• Flexibilidade de Consultas: Filtros, ordenações e seleção de atributos via consulta.
• Fácil Extensão: Estrutura modular para criação de repositórios específicos.
• Gerador de código: Comandos inteligentes para criar as entidades, repositórios e controladores, construindo um CRUD completo para as chamadas de API.

Estrutura do Projeto

O projeto segue uma arquitetura limpa e bem organizada:

• Entidades (Entity): Representam os dados do negócio e oferecem funcionalidades para manipulação e hidratação de valores.
• Repositórios (Repository): Realizam todas as interações com a camada de dados, encapsulando as operações.
• Construtor de Consultas (QueryBuilder): Fornece suporte à criação e execução de consultas dinâmicas no Elasticsearch.

Tecnologias Utilizadas

• Hyperf Framework: Utilizado como base para o projeto, com suporte ao paradigma reativo e arquitetura moderna.
• Elasticsearch: Banco de dados NoSQL utilizado para indexação e busca avançada.
• Redis: Armazenamento em memória de alta performance utilizado para caching, controle do rate-limit e gerenciamento de sessões, otimizando a eficiência e performance do sistema.
• PSR-11 (Container): Integração do padrão de contêiner de dependências para maior compatibilidade.
• PHP 8.1+: Versão mínima do PHP, aproveitando recursos modernos como atributos e tipagem forte.

Instalação

Para integrar o hf-repository no seu projeto Hyperf adicione as dependências necessárias ao seu projeto (via composer):

Após a instalação, publique os arquivos de configuração das dependências necessárias:

Exemplo de Uso

O comando mais importante desta biblioteca é a criação de um CRUD completo a partir de um índice do Elasticsearch.

O comando repo:crud vai criar as classes de entidades, repositório e controlador, além de já preparar toda a documentação do swagger e aplicar um rate limit padrão de 10 requisições por segundo.

`

Os detalhes de cada classe gerada por este comando serão explicadas no próximo tópico.

Criando as classes individualmente

Para criar individualmente as classes necessárias, siga os comandos na ordem abaixo:

1. Criando dinamicamente as classes das entidades

Utilize o comando de console para gerar as entidades relacionadas ao índice.

Conforme demonstrado, o comando vai analisar o mapping do índice informado e vai criar a entidade principal do índice e caso haja objetos e objetos nested no índice, uma classe de entidade será gerada para cada um deles.

Cada classe gerada já vem aplicada com as configurações do Swagger, criando as referências necessárias para a documentação do projeto.

2. Criando o repositório

Para criar o repositório relacionado ao índice do elasticsearch, utilize o comando abaixo:

O comando criará dentro do diretório uma classe User com o seguinte conteúdo:

3. Criando um controlador que fará uso do repositório

O comando repo:controller vai criar um controlador OrderController já preparado para receber os métodos GET, POST, PUT, DELETE e HEAD com as consultas e persistências realizadas pelo repositório gerado anteriormente.

Repare que o diretório final do controlador é baseada em uma versão. É possível definir a versão da api acrescentando a opção --api-version= ao comando.

Caso o arquivo do controlador exista, o comando perguntará se deseja substituí-lo.

Também é possível já forçar a substituição do arquivo diretamente no comando usando a opção --force

O arquivo do controlador gerado também vem com as configurações do Swagger aplicadas. Além disso, também são aplicadas configurações de rate limit para limitar as requisições à API.