README

#Correios

用于与Correios服务交互的包。

##资源

• 根据CEP查找地址;
• 获取包裹追踪数据;
• 计算价格和交货时间.

觉得缺少什么？ 提交问题！

##为什么？

已经存在多个包与Correios服务交互，但总有某些原因让我不能使用它们，无论是它们专为某种软件或框架制作，还是它们没有我需要的所有功能等。因此，产生了尝试创建一个新包的想法，以下是一些目标

• 独立：用于任何项目/框架，尽可能减少额外的依赖；
• 功能完整：尽可能通过官方或非官方API覆盖Correios提供的所有资源；
• PSR合规：autoload兼容PSR-4和PSR-2格式；
• 测试：尽可能测试库。

##安装

通过Composer

$ composer require eberfreitas/correios

##如何使用

要使用此库，首先需要创建一个实例

$correios = new Correios\Correios();

这应该足以开始使用库。可选地，您可以以不同的方式配置实例。类的构造函数接受包含以下键的数组

示例

$adaptador = new MinhaClasseHttp;

$correios = new Correios\Correios([
    'usuario' => 'joao',
    'senha' => 'segredo',
    'http_adapter' => $adaptador
]);

虽然您可以选择提供适配器，但如果您未指定，则库将默认使用Guzzle。

###通过CEP查找地址

要从CEP查找地址，只需使用endereco方法

$endereco = $correios->endereco('70150900');

print_r($endereco);

它将产生以下输出

Array
(
    [logradouro] => Praça dos Três Poderes
    [logradouro_extra] =>
    [bairro] => Zona Cívico-Administrativa
    [cidade] => Brasília
    [uf] => DF
    [cep] => 70150900
)

在查询失败的情况下将抛出异常。如有必要，请留意捕获这些异常。如有疑问，请查看源代码。它有很好的文档，应该可以帮助您正确理解每个方法。

###追踪包裹

要追踪包裹，只需使用rastreamento方法

$eventos = $correios->rastreamento('PE024442250BR');

print_r($eventos);

它将产生以下输出

Array
(
    [0] => Array
        (
            [data] => DateTime Object
                (
                    [date] => 2015-03-12 18:12:00
                    [timezone_type] => 3
                    [timezone] => UTC
                )
            [descricao] => Entrega Efetuada
            [local] => CEE JABOATAO DOS GUARARAPES
            [cidade] => Recife
            [uf] => PE
        )
    [1] => Array
        (
            [data] => DateTime Object
                (
                    [date] => 2015-03-12 09:22:00
                    [timezone_type] => 3
                    [timezone] => UTC
                )
            [descricao] => Saiu para entrega ao destinatio
            [local] => CTE RECIFE
            [cidade] => Recife
            [uf] => PE
        )
    [2] => Array
        (
            [data] => DateTime Object
                (
                    [date] => 2015-03-11 11:31:00
                    [timezone_type] => 3
                    [timezone] => UTC
                )
            [descricao] => Encaminhado
            [local] => CTE RECIFE
            [cidade] => Recife
            [uf] => PE
        )
    [3] => ...
)

如你所见，我们有一个关联数组，其中包含与被查询的包裹相关的各种事件数据。每个条目都对应一个事件，并具有以下键：

关于包裹查询的说明：中国邮政提供特定的包裹查询webservice，但该webservice仅限有合同的客户使用。因此，该库执行“网络爬虫”过程以从常规查询页面提取数据。尽管使用的页面已经显示了多年来的结构稳定性，但该页面的HTML任何更改都可能导致此方法失败。

###计算运费和配送期限

要计算运费和配送期限，只需使用 calculaFrete 方法。

$calculado = $correios->calculaFrete([
    'usuario' => null,
    'senha' => null,
    'servicos' => [Correios\Correios::PAC],
    'cep_origem' => '08820400',
    'cep_destino' => '21832150',
    'peso' => 0.3,
    'formato' => Correios\Correios::CAIXA,
    'comprimento' => 16,
    'altura' => 2,
    'largura' => 11,
    'diametro' => 5,
    'mao_propria' => false,
    'valor_declarado' => 0,
    'aviso_recebimento' => false
]);

print_r($calculado);

与其它方法不同，此方法接收一个包含一些选项的数组，以便执行计算。让我们看看它们是什么：

非必需的值将由最小合理的默认值填充。请确保计算出的价值与实际的派送条件相符。

上面的调用将产生以下输出

Array
(
    [0] => Correios\Calculo Object
        (
            [raw:protected] => Array
                (
                    [codigo] => 41106
                    [valor] => 15.5
                    [prazo_entrega] => 11
                    [valor_sem_adicionais] => 15.5
                    [valor_mao_propria] => 0
                    [valor_aviso_recebimento] => 0
                    [valor_valor_declarado] => 0
                    [entrega_domiciliar] => 1
                    [entrega_sabado] =>
                    [erro] => 010
                    [msg_erro] => O CEP de destino está sujeito a condições especiais de entrega  pela  ECT e será realizada com o acréscimo de até 7 (sete) dias ao prazo regular.
                    [servico_descricao] => PAC
                )

            [serviceMap:protected] => Array
                (
                    //...
                )
        )
)

请注意，我们得到的是一个包含 Correios\Calculo 类实例的数组返回值。这是一个简单的类，它允许我们通过数组或对象访问查询结果的数据。

echo $calculado[0]['codigo']; //41106
echo $calculado[0]->valor; //15.5

可用数据如下

####计算送货日期

记得查询结果返回一个对象吗？它有一些有趣的方法可以帮助你更好地处理价格和期限查询的返回数据。其中一个方法是 calculaEntrega。通过它我们可以得到一个估计的送货日期。看

$entrega = $calculado[0]->calculaEntrega(new DateTime('now'));

print_r($entrega);

它将产生以下输出

DateTime Object
(
    [date] => 2015-05-18 00:00:00
    [timezone_type] => 3
    [timezone] => UTC
)

看，该方法接收一个 DateTime 对象并返回一个表示送货日期的 DateTime 对象。该方法会考虑从发货日期开始，期限总和是否落在周末的某一天，并调整日期为下一个工作日，除非送货在周六，并且送货地址具有 entrega_sabado 键的值为 true。

####格式化值

你还可以轻松地返回已格式化的运费值。看

echo $calculado[0]->formataValor('valor');

它将产生以下输出

R$ 15,50

值将按照巴西货币标准格式化。如果你想要，可以通过在第二个参数中传递 false 来省略“R$”前缀

echo $calculado[0]->formataValor('valor', talse); //15,50

你可以对查询提供的任何值键进行这种格式化。

####智能包装调整

没有必须填写包装尺寸的值。因此，该库使用大多数运输的标准模式，并应该返回适当的值。如果你想自定义尺寸值，库会自动调整这些值，如果它们超出了邮局定义的标准。

因此，库将检查定义的格式，该格式的规则，并尝试调整尺寸以确保计算不出现错误。

如果你希望库不自动进行此调整，只需以以下方式调用方法

$config = []; //a configuração de sua chamada aqui...
$calculado = $correios->calculaFrete($config, false);

####服务表

以下是一些查询的代码及其描述

###使用不同的 http 适配器

默认情况下，库将使用 Guzzle 来执行对 webservices 和库使用的 endpoints 的 http 请求。如果你想，你可以使用其他包代替 Guzzle，在实例化邮局类时提供一个新对象。

为此，你必须创建一个中间类，该类实现 Correios\Adapters\AdapterInterface 接口，该接口只有一个方法：get 和 post。

这两个方法都必须返回一个表示请求响应体的 string，并且在请求过程中出现的任何错误都必须通过抛出异常来指示。

请查看以下示例实现这里。

##致谢

• 由Éber F. Dias创建
• 在Tiago Correa的帮助下
• 由Tanlup赞助