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');

依赖

至少需要PHP v7.3，并且与php v8.0和后续版本兼容
该库需要ext-sybase扩展。在Ubuntu上，可以使用sudo apt install php-sybase进行安装
该库可选地使用uspdev/cache。如果您想使用缓存，请参阅以下文档：https://github.com/uspdev/cache

如何使用

通过composer安装

composer require uspdev/replicado

传递$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);

使用环境变量的示例使用

<?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);

如何在Laravel中使用

查看项目Uspdev\laravel-replicado。

变量说明

大多数变量都是自解释的，但有些则不是。

REPLICADO_CODUNDCLG - 这个变量是单位的代码。截至2022年11月，它可能包含以逗号分隔的值。然而，为了保持兼容性和更好地组织，创建了另一个变量来包含多个值

REPLICADO_CODUNDCLG=8

REPLICADO_CODUNDCLGS（以S结尾）- 表示单位的学院。对于有共享课程的单位很重要。

REPLICADO_CODUNDCLGS=8,27

注意，不要使用引号，如下例所示：REPLICADO_CODUNDCLG="8,27"。

REPLICADO_SYBASE - 用于指示是否使用SYBASE或MSSQL。这意味着

库或freetds进行UTF-8转换
移除字符串末尾的额外空格

根据MSSQL的配置，可能需要激活此变量。

REPLICADO_USAR_CACHE - replicado可以使用通过库（https://github.com/uspdev/cache）提供的memcached。

要使用它，需要使用以下命令安装它

composer require uspdev/Cache

并按照库的文档启动memcached服务器并配置它。

最后，使用以下命令激活replicado的缓存

putenv('REPLICADO_USAR_CACHE=1');

还可以使用以下方式仅控制replicado的缓存行为

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

在生产环境中值得使用，但在测试中保持禁用。

调试

如果变量debug为true，则在出现错误时在屏幕上显示消息。

默认情况下，错误也会记录在日志中。如果要将执行的查询记录到replicado的数据库中，请将debugLevel增加到2。

putenv('REPLICADO_DEBUG_LEVEL=2');

配置重置

在Lattes::obterZip()方法中，可能需要暂时更改replicado的配置，将sybase = false定义为true。这可以通过以下命令实现

    Replicado::setConfig(['sybase' => false]);

要返回到环境变量中的配置，可以使用以下命令的reset

    Replicado::setConfig(['reset' => true]);

关于表的信息

https://uspdigital.usp.br/replunidade

为该项目贡献的建议

视频： https://youtu.be/p5dFJOrMN30

Replicado可以查询MSSQL和sybase-ase以及多个不同版本。因此，需要与各单位的不同replicado保持兼容性。

在开始修改代码之前，请先打开一个issue。预先讨论对于统一想法很重要。
贡献将通过pull requests接受。为此，请在issue_xx分支上做出更改。
记录DOCBLOCK
- 主文本，补充文本，@param，@return
- @author 您的姓名，于 xx/xx/xxxx 或
- @author 您的姓名，修改于 xx/xx/xxxx
将 SQL 放置于 resources/queries 目录下
方法参数必须进行类型化，包括 int，string 等
(11/2022) 如果发生错误，方法 DB::fetch 和 DB::fetchAll 返回 false 和错误信息。如果返回“空”，一些方法需要处理
- obterXxxx: PDOStatement::fetch() 在空的情况下返回 false。在这种情况下使用
  return DB::fetch($query) ?: [];;
- retornarXxxx: 应返回 null
在字符串中优先使用单引号，因为 PHP 不会解析其内容
master 分支被认为是稳定的，可以用于生产，但是 releases 是定期的。

参考：Pessoa::listarDesignados()

关于方法命名的建议

listarXxx - 返回数据记录列表 (fetchAll)
obterXxxx - 返回单个记录 (fetch)
contarXxxx - 返回计数 (count()) - 返回类型 int
retornarXxxx - 返回记录的值 - 返回类型 string，int 等
verificarXxxx - 根据条件返回 true 或 false - 返回类型 bool

注意1：当传递简单数组时，可以可选地传递由逗号分隔的字符串。例如：Pessoa::contarServidoresSetor()

注意2：(11/2022) 方法中的查询应放置在 resources/queries 中，如果需要，可以在方法 DB::getQuery('arquivo.sql', $replaces) 中进行替换

注意3：(10/2023) 如果需要使用 REPLICADO_CODUNDCLGS 或 REPLICADO_CODUNDCLG 在查询中，只需放置 __codundclgs__ 或 __codundclg__，库将执行相应的替换。替换在方法 DB::overrideFetch 中执行。但如果想要传递与 config 不同的内容，请随意。

注意4：在方法中不要使用 getenv('REPLICADO_VARIAVEL')。如果需要，使用 Replicado::getConfig('variavel')。

已弃用方法

如果您在系统中使用这些方法之一，请将其更新为相应的新方法。

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 -> 将被移除并添加到 uspdev/web-ldap-admin 中 listarVinculosExtensoSetores (11/2022)

phpunit

在创建新方法时，需要创建相应的测试方法，使用 phpunit。为此，您需要一个可以删除表的 sybase 或 mssql 数据库，有四种选项可以运行测试

下载 mssql 或 sybase 并手动安装
使用 https://github.com/uspdev/asedocker 启动 Sybase 容器
使用 ansible 安装 sybase https://github.com/fflch/ansible-role-sap-ase
我们维护一个 sybase 测试服务器，如果您需要，可以请求凭据 uspdev@usp.br

拉取请求会自动由 travis 进行测试，因此，在打开 PR 之前，请确保测试通过

./vendor/bin/phpunit

文档

请参阅文档： https://uspdev.github.io/replicado/

文档是自动生成的，使用 phpDocumentor，因此不需要执行任何操作，因为每次推送都会由 github action 进行更新。

但如果你想本地测试它

wget http://phpdoc.org/phpDocumentor.phar
sudo mv phpDocumentor.phar /usr/local/bin/phpdoc
sudo chmod a+x /usr/local/bin/phpdoc

还需要安装

sudo apt install graphviz

生成文档中

phpdoc

uspdev / replicado

维护者

详细信息