uspdev / replicado
Classes PHP que consome dados do Replicado USP
Installs: 4 297
Dependents: 5
Suggesters: 0
Security: 0
Stars: 11
Watchers: 10
Forks: 27
Open Issues: 22
Requires
- php: >=7.0
- ext-pdo_dblib: *
- illuminate/collections: ^8 || ^9 || ^10 || ^11
- monolog/monolog: ^2 || ^3
- uspdev/cache: ^1
- dev-master
- 1.24.3
- 1.24.2
- v1.24.1
- 1.24.0
- 1.23.0
- 1.22.2
- 1.22.1
- 1.22.0
- 1.21.1
- 1.21.0
- 1.20.0
- 1.19.5
- 1.19.4
- 1.19.3
- 1.19.2
- 1.19.1
- 1.19.0
- 1.18.0
- 1.17.0
- 1.16.5
- 1.16.4
- 1.16.3
- 1.16.2
- 1.16.1
- 1.16.0
- 1.15.0
- 1.14.0
- 1.13.3
- 1.13.2
- 1.13.1
- 1.13.0
- 1.12.2
- 1.12.1
- 1.12.0
- 1.11.3
- 1.11.2
- 1.11.1
- 1.11.0
- v1.10.9
- 1.10.8
- 1.10.7
- 1.10.6
- 1.10.5
- 1.10.4
- 1.10.3
- 1.10.2
- 1.10.1
- 1.10.0
- 1.9.0
- 1.8.0
- 1.7.16
- 1.7.15
- 1.7.14
- 1.7.13
- 1.7.12
- 1.7.11
- 1.7.10
- 1.7.9
- 1.7.8
- 1.7.7
- 1.7.6
- 1.7.5
- 1.7.4
- 1.7.3
- 1.7.2
- 1.7.1
- 1.7
- 1.6.11
- 1.6.10
- 1.6.9
- 1.6.8
- 1.6.7
- 1.6.6
- 1.6.5
- 1.6.4
- 1.6.3
- 1.6.2
- 1.6.1
- 1.6.0
- 1.5.17
- 1.5.16
- 1.5.15
- 1.5.14
- 1.5.13
- 1.5.12
- 1.5.11
- 1.5.10
- 1.5.9
- 1.5.8
- 1.5.7
- 1.5.6
- 1.5.5
- 1.5.4
- v1.5.3
- V1.5.2
- v1.5.1
- v1.5.0
- v1.4.0
- v1.3.0
- v1.2.0
- v1.1.0
- v1.0.2
- v1.0.1
- v1.0.0
- dev-thiagogomesverissimo-patch-1
This package is auto-updated.
Last update: 2024-10-17 15:19:51 UTC
README
Replicado
Biblioteca PHP que abstrai em classes a camada de acesso ao replicado USP, isto é, ao invés de inserir uma consulta SQL diretamente em seu código, como por exemplo:
SELECT nompes,... FROM pessoa WHERE codpes='123'
Usa-se uma classe PHP que faz a abstração do acesso e portanto deixa seu código muito mais limpo, além de torna as consultas reutilizáveis:
Pessoa::nomeCompleto('123');
Dependências
- É necessário pelo menos o PHP v7.3 e é compatível com php v8.0 e posteriores
- Esta biblioteca precisa da extensão
ext-sybase
. No ubuntu instale comsudo apt install php-sybase
- Esta biblioteca usa opcionalmente
uspdev/cache
. Caso queira usar o cache consulte a documentação em: https://github.com/uspdev/cache
Como usar
Instale via composer
composer require uspdev/replicado
Exemplo de uso passando $config
<?php namespace Meu\Lindo\App; require_once __DIR__ . '/vendor/autoload.php'; use Uspdev\Replicado\Pessoa; use Uspdev\Replicado\Replicado; $config = [ 'host' => '192.168.100.89', 'port' => 1498, 'database' => 'rep_dbc', 'username' => 'dbmaint_read', 'password' => 'secret', 'codundclg' => '8', 'codundclgs' => '8,84', 'pathlog' => 'path/to/your.log', 'sybase' => true, 'usarCache' => false, 'debug' => false, 'debugLevel' => 1, ]; Replicado::setConfig($config); $emails = Pessoa::emails('123456'); print_r($emails);
Exemplo de uso com variáveis de ambiente
<?php namespace Meu\Lindo\App; require_once __DIR__ . '/vendor/autoload.php'; use Uspdev\Replicado\Pessoa; # Obrigatórias putenv('REPLICADO_HOST=192.168.100.89'); putenv('REPLICADO_PORT=1498'); putenv('REPLICADO_DATABASE=rep_dbc'); putenv('REPLICADO_USERNAME=dbmaint_read'); putenv('REPLICADO_PASSWORD=secret'); putenv('REPLICADO_CODUNDCLG=8'); putenv('REPLICADO_CODUNDCLGS=8,84'); # Opcionais - estes são os valores default putenv('REPLICADO_PATHLOG=/tmp/replicado.log'); putenv('REPLICADO_SYBASE=true'); putenv('REPLICADO_USAR_CACHE=false'); putenv('REPLICADO_DEBUG=false'); putenv('REPLICADO_DEBUG_LEVEL=1'); $emails = Pessoa::emails('123456'); print_r($emails);
Como usar no laravel
Veja o projeto Uspdev\laravel-replicado.
Explicações das variáveis
A maioria das variáveis são autoexplicativas mas outras não.
REPLICADO_CODUNDCLG - essa variável é o código da unidade. Até 11/2022, ela podia conter valores separados por vírgula. No entanto, para manter compatibilidade e organizar melhor, criou-se outra váriável para conter múltiplos valores:
REPLICADO_CODUNDCLG=8
REPLICADO_CODUNDCLGS (com S no final) - Representa os colegiados da unidade. Importante para as unidades que tem cursos compartilhados.
REPLICADO_CODUNDCLGS=8,27
Atenção, NÃO usar aspas, como neste exemplo: REPLICADO_CODUNDCLG="8,27".
REPLICADO_SYBASE - serve para indicar se vc está usando SYBASE ou MSSQL. Implica:
- na conversão para UTF-8 pela biblioteca ou pelo freetds
- na remoção de espaços adicionais no final das strings
Dependendo da configuração do MSSQL pode ser necessário ativar essa variável.
REPLICADO_USAR_CACHE - o replicado pode usar memcached através da biblioteca (https://github.com/uspdev/cache).
Para usar é necessário instalar ele com
composer require uspdev/Cache
e seguir a documentação da biblioteca para levantar o servidor memcached e configurar ele.
Por fim ative o cache do replicado com
putenv('REPLICADO_USAR_CACHE=1');
Ainda é possível controlar o comportamento do cache somente para o replicado com
putenv('REPLICADO_CACHE_EXPIRY=14400'); // 4 horas para expirar
putenv('REPLICADO_CACHE_SMALL=32'); // tamanho máx em bytes do retorno que não vai ser cacheado
Em produção vale a pena usar mas em testes mantenha desativado.
Debug
A variável debug, se true
, mostra mensagens na tela em caso de erro.
Por padrão os erros também são gravados no log. Caso queira gravar em log as queries executadas no BD do replicado, aumente o debugLevel para 2.
putenv('REPLICADO_DEBUG_LEVEL=2');
Config reset
No método Lattes::obterZip()
, pode ser necessário alterar a configuração do replicado momentaneamente definindo sybase = false
. Isso é possível com o comando abaixo
Replicado::setConfig(['sybase' => false]);
Para retornar às configurações do env, pode-se utilizar o comando reset como segue
Replicado::setConfig(['reset' => true]);
Informações sobre tabelas
https://uspdigital.usp.br/replunidade
Recomendações para contribuir com este projeto
Vídeo: https://youtu.be/p5dFJOrMN30
O replicado pode consultar tanto o MSSQL quanto o sybase-ase e em diversas versões diferentes. Dessa forma é necessário manter a compatibilidade com os diversos replicados das unidades.
- Abra uma issue antes de começar a mexer no código. A discussão prévia é importante para alinhar as idéias.
- As contribuições serão aceitas por meio de pull requests. Para tanto faça as alterações em uma branch issue_xx.
- Documentar o DOCBLOCK
- Texto principal, texto complementar, @param, @return
- @author seu-nome, em xx/xx/xxxx ou
- @author seu-nome, modificado em xx/xx/xxxx
- Coloque o sql em resources/queries
- Os argumentos dos métodos devem ser tipados, incluindo int, string etc
- (11/2022) Caso ocorra algum erro, os métodos
DB::fetch
eDB::fetchAll
retornamfalse
e uma mensagem de erro. Em caso de retorno "vazio", alguns métodos precisam de tratamento:- obterXxxx:
PDOStatement::fetch()
retorna false em caso de vazio. Nesse caso use
return DB::fetch($query) :? [];
- retornarXxxx: deve retornar
null
- obterXxxx:
- Dar preferência para aspas simples em strings pois o PHP não tenta parsear seu conteúdo
- A branch
master
é considerada estável e pode ser usada em produção, porém osreleases
têm sido regulares.
Referência: Pessoa::listarDesignados()
Sugestão para nomear métodos:
- listarXxx - retorna lista de registros de dados (
fetchAll
) - obterXxxx - retorna somente um registro (
fetch
) - contarXxxx - retorna uma contagem (
count()
) - retorno tipoint
- retornarXxxx - retorna um valor do registro - retorno
string
,int
, etc - verificarXxxx - retorna true ou false em função da condição - retorno
bool
OBS1.: Quando passar parâmetro array
simples, deixar opcional passar string
separada por vírgula. Ex.: Pessoa::contarServidoresSetor()
OBS2.: (11/2022) As queries dos métodos devem ficar em resources/queries
e as substituições, se necessário podem ser feitas no método DB::getQuery('arquivo.sql', $replaces)
OBS3.: (10/2023) Se necessário usar REPLICADO_CODUNDCLGS
ou REPLICADO_CODUNDCLG
na query, basta colocar __codundclgs__
ou __codundclg__
que a biblioteca fará a substituição correspondente. A substituição é feita no método DB::overrideFetch
. Mas se quiser passar algo diferente do config
, fique à vontade.
OBS4.: Nos métodos não usar getenv('REPLICADO_VARIAVEL')
. Usar, se necessário, Replicado::getConfig('variavel')
.
Métodos deprecados
Se você utiliza um desses métodos nos seus sistemas, atualize para o novo método correspondente.
2020
- Pessoa::nome -> procurarPorNome (11/2020)
- Pessoa::nomeFonetico -> procurarPorNome (11/2020)
2021
- Pessoa::vinculosSiglas -> obterSiglasVinculosAtivos (3/2021)
- Pessoa::setoresSiglas -> obterSiglasSetoresAtivos (6/2021)
- Pessoa::emailusp -> retornarEmailUsp (6/2021)
- Pessoa::designados -> listarDesignados (7/2021)
- Graduacao::ativos -> listarAtivos (10/2021)
- Pessoa::nomeCompleto -> obterNome (12/2021)
2022
- Pessoa::servidores -> listarServidores (1/2022)
- Pessoa::vinculosSetores -> listarVinculosSetores (9/2022)
- Pessoa::tiposVinculos -> listarTiposVinculoExtenso (11/2022)
- Graduacao::curso -> obterCursoAtivo (11/2022)
- Pessoa::listarVinculosSetores -> a ser removido e adicionado no uspdev/web-ldap-admin listarVinculosExtensoSetores (11/2022)
phpunit
De forma opcional, se quiser fazer do jeito bonitinho, pode-se criar teste unitário, usando o phpunit. Para isso, você precisa de um banco de dados sybase ou mssql que possa deletar as tabelas, há quatro opções para você rodar os testes:
- Baixar o mssql ou sybase e instalá-los manualmente
- Subir um container Sybase com https://github.com/uspdev/asedocker
- Instalar o sybase com ansible https://github.com/fflch/ansible-role-sap-ase
- Nós mantemos um servidor sybase de testes, se quiser, solicite as credenciais uspdev@usp.br
Os Pull Request são automaticamente testadas pelo travis (desativado por enquanto). Para verificar se os testes estão passando:
./vendor/bin/phpunit
Documentação
Consulte a documentação em: https://uspdev.github.io/replicado/
A documentação é auto-gerada usando phpDocumentor e não é necessário fazer nada, pois a cada push uma github action a atualiza.
Mas se quiser testá-la localmente:
wget http://phpdoc.org/phpDocumentor.phar
sudo mv phpDocumentor.phar /usr/local/bin/phpdoc
sudo chmod a+x /usr/local/bin/phpdoc
Ainda é necessário instalar:
sudo apt install graphviz
Gerando a documentação:
phpdoc