elliotjreed/royal-mail-tracking

用于与皇家邮政跟踪服务交互的库

维护者

详细信息

github.com/elliotjreed/royal-mail-tracking

主页

源代码

问题

安装次数: 2,529

依赖项: 0

建议者: 0

安全性: 0

星标: 4

关注者: 3

分支: 0

开放问题: 0

4.2.0 2024-08-21 11:04 UTC

Requires

Requires (Dev)

MIT 7cb57e9c2d47d3e484e828f81aedbcf87cb1b27c

elliotjreedroyal-mail-tracking

This package is auto-updated.

Last update: 2024-09-21 11:17:55 UTC

README

Contributor Covenant

PHP 皇家邮政跟踪

如果您能，请在 GitHub 仓库中提出问题，如果不行，请随时联系我。

欢迎提出修复错误或潜在更改的拉取请求！

本说明书的底部列出了部分事件代码及其粗略定义。

使用方法

需要 PHP 8.1 或更高版本。

通过 Composer 安装此软件包

composer require elliotjreed/royal-mail-tracking

提供三种获取跟踪数据的方式

  • 事件：用于获取单个跟踪号码的详细信息和完整历史记录；
  • 签名：签名数据（包括图像数据 - 要么是 base64 编码的 PNG，要么是 SVG）；
  • 摘要：用于获取多个跟踪号码的最新事件。

下面详细说明了每种方式，并包含了示例。

在 事件、签名 和 摘要 信息下方提供了错误处理信息（值得阅读，因为 摘要 错误的处理方式与 事件 和 摘要 错误不同）。

实例化/设置

$tracking = (new \ElliotJReed\RoyalMail\Tracking\Events(
    new \GuzzleHttp\Client(),
    'aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee',
    '12345678901234567890123456789012345678901234567890',
    true, // Optional, when true (default: true) exceptions will be thrown for tracking errors
    true, // Optional, when true (default: true) exceptions will be thrown for technical (eg. 500 HTTP response) errors
    'https://api.royalmail.net/mailpieces/v2' // Optional, when set the default API endpoint can be overridden (default: 'https://api.royalmail.net/mailpieces/v2')
));
$signature = (new \ElliotJReed\RoyalMail\Tracking\Signature(
    new \GuzzleHttp\Client(),
    'aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee',
    '12345678901234567890123456789012345678901234567890',
    true, // Optional, when true (default: true) exceptions will be thrown for tracking errors
    true, // Optional, when true (default: true) exceptions will be thrown for technical (eg. 500 HTTP response) errors
    'https://api.royalmail.net/mailpieces/v2' // Optional, when set the default API endpoint can be overridden (default: 'https://api.royalmail.net/mailpieces/v2')
));
$summary = (new \ElliotJReed\RoyalMail\Tracking\Summary(
    new \GuzzleHttp\Client(),
    'aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee',
    '12345678901234567890123456789012345678901234567890',
    true, // Optional, when true (default: true) exceptions will be thrown for tracking errors
    true, // Optional, when true (default: true) exceptions will be thrown for technical (eg. 500 HTTP response) errors
    'https://api.royalmail.net/mailpieces/v2' // Optional, when set the default API endpoint can be overridden (default: 'https://api.royalmail.net/mailpieces/v2')
));

事件

事件操作的目的是提供一个单一邮件项目的跟踪历史记录。

返回所提供的跟踪号码的摘要、签名元数据、预计投递窗口和事件。

$tracking = (new \ElliotJReed\RoyalMail\Tracking\Events(
    new \GuzzleHttp\Client(),
    'aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee',
    '12345678901234567890123456789012345678901234567890'
));

$mailPieces = $tracking->setTrackingNumber('AB1234567890GB')->getResponse()->getMailPieces();

$mailPieces->getMailPieceId(); // 090367574000000FE1E1B
$mailPieces->getCarrierShortName(); // RM
$mailPieces->getCarrierFullName(); // Royal Mail Group Ltd

$summary = $mailPieces->getSummary();
$summary->getUniqueItemId(); // 090367574000000FE1E1B
$summary->getOneDBarcode(); // FQ087430672GB
$summary->getProductId(); // SD2
$summary->getProductName(); // Special Delivery Guaranteed
$summary->getProductDescription(); // Our guaranteed next day service with tracking and a signature on delivery
$summary->getProductCategory(); // NON-INTERNATIONAL
$summary->getDestinationCountryCode(); // GBR
$summary->getDestinationCountryName(); // United Kingdom of Great Britain and Northern Ireland
$summary->getOriginCountryCode(); // GBR
$summary->getOriginCountryName(); // United Kingdom of Great Britain and Northern Ireland
$summary->getLastEventCode(); // EVNMI
$summary->getLastEventName(); // Forwarded - Mis-sort
$summary->getLastEventDateTime(); // new DateTimeImmutable('2016-10-20T10:04:00+01:00')
$summary->getLastEventLocationName(); // Stafford DO
$summary->getStatusDescription(); // It is being redirected
$summary->getStatusCategory(); // IN TRANSIT
$summary->getStatusHelpText(); // The item is in transit
$summary->getSummaryLine(); // Item FQ087430672GB was forwarded to the Delivery Office on 2016-10-20.

$internationalPostalProvider = $summary->getInternationalPostalProvider();
$internationalPostalProvider->getUrl(); // https://www.royalmail.com/track-your-item
$internationalPostalProvider->getTitle(); // Royal Mail Group Ltd
$internationalPostalProvider->getDescription(); // Royal Mail Group Ltd

$signature = $mailPieces->getSignature();
$signature->getRecipientName(); // Elliot
$signature->getSignatureDateTime(); // new DateTimeImmutable('2016-10-20T10:04:00+01:00')
$signature->getImageId(); // 001234

$estimatedDelivery = $mailPieces->getEstimatedDelivery();
$estimatedDelivery->getDate(); // new DateTimeImmutable('2017-02-20T00:00:00+00:00')
$estimatedDelivery->getStartOfEstimatedWindow(); // new DateTimeImmutable('2017-02-20T08:00:00+01:00')
$estimatedDelivery->getEndOfEstimatedWindow(); // new DateTimeImmutable('2017-02-20T11:00:00+01:00')

$events = $mailPieces->getEvents();
$event = $events[0];
$event->getEventCode(); // EVNMI
$event->getEventName(); // Forwarded - Mis-sort
$event->getEventDateTime(); // new DateTimeImmutable('2016-10-20T10:04:00+01:00')
$event->getLocationName(); // Stafford DO

$linkSummary = $mailPieces->getLinks()->getSummary();
$linkSummary->getHref(); // /mailpieces/v2/summary?mailPieceId=090367574000000FE1E1B
$linkSummary->getTitle(); // Summary
$linkSummary->getDescription(); // Get summary

$linkSignature = $mailPieces->getLinks()->getSignature();
$linkSignature->getHref(); // /mailpieces/v2/090367574000000FE1E1B/signature
$linkSignature->getTitle(); // Signature
$linkSignature->getDescription(); // Get signature

$linkRedelivery = $mailPieces->getLinks()->getRedelivery();
$linkRedelivery->getHref(); // /personal/receiving-mail/redelivery
$linkRedelivery->getTitle(); // Redelivery
$linkRedelivery->getDescription(); // Book a redelivery

JSON 输出

$tracking = (new \ElliotJReed\RoyalMail\Tracking\Events(
    new \GuzzleHttp\Client(),
    'aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee',
    '12345678901234567890123456789012345678901234567890'
));

echo $tracking->setTrackingNumber('AB1234567890GB')->asJson();

将输出皇家邮政响应的 JSON

{
    "errors": [],
    "httpCode": null,
    "httpMessage": null,
    "mailPieces": {
        "carrierFullName": "Royal Mail Group Ltd",
        "carrierShortName": "RM",
        "estimatedDelivery": {
            "date": "2017-02-20T00:00:00+00:00",
            "endOfEstimatedWindow": "2017-02-20T11:00:00+01:00",
            "startOfEstimatedWindow": "2017-02-20T08:00:00+01:00"
        },
        "events": [
            {
                "eventCode": "EVNMI",
                "eventDateTime": "2016-10-20T10:04:00+01:00",
                "eventName": "Forwarded - Mis-sort",
                "locationName": "Stafford DO"
            }
        ],
        "links": {
            "redelivery": {
                "description": "Book a redelivery",
                "href": "/personal/receiving-mail/redelivery",
                "title": "Redelivery"
            },
            "signature": {
                "description": "Get signature",
                "href": "/mailpieces/v2/090367574000000FE1E1B/signature",
                "title": "Signature"
            },
            "summary": {
                "description": "Get summary",
                "href": "/mailpieces/v2/summary?mailPieceId=090367574000000FE1E1B",
                "title": "Summary"
            }
        },
        "mailPieceId": "090367574000000FE1E1B",
        "signature": {
            "imageId": "001234",
            "recipientName": "Elliot",
            "signatureDateTime": "2016-10-20T10:04:00+01:00"
        },
        "summary": {
            "destinationCountryCode": "GBR",
            "destinationCountryName": "United Kingdom of Great Britain and Northern Ireland",
            "internationalPostalProvider": {
                "description": "Royal Mail Group Ltd",
                "title": "Royal Mail Group Ltd",
                "url": "https://www.royalmail.com/track-your-item"
            },
            "lastEventCode": "EVNMI",
            "lastEventDateTime": "2016-10-20T10:04:00+01:00",
            "lastEventLocationName": "Stafford DO",
            "lastEventName": "Forwarded - Mis-sort",
            "oneDBarcode": "FQ087430672GB",
            "originCountryCode": "GBR",
            "originCountryName": "United Kingdom of Great Britain and Northern Ireland",
            "productCategory": "NON-INTERNATIONAL",
            "productDescription": "Our guaranteed next day service with tracking and a signature on delivery",
            "productId": "SD2",
            "productName": "Special Delivery Guaranteed",
            "statusCategory": "IN TRANSIT",
            "statusDescription": "It is being redirected",
            "statusHelpText": "The item is in transit",
            "summaryLine": "Item FQ087430672GB was forwarded to the Delivery Office on 2016-10-20.",
            "uniqueItemId": "090367574000000FE1E1B"
        }
    },
    "moreInformation": null
}

签名

$tracking = (new \ElliotJReed\RoyalMail\Tracking\Signature(
    new \GuzzleHttp\Client(),
    'aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee',
    '12345678901234567890123456789012345678901234567890'
));

$mailPieces = $tracking->setTrackingNumber('AB1234567890GB')->getResponse()->getMailPieces();

$mailPieces->getMailPieceId(); // 090367574000000FE1E1B
$mailPieces->getCarrierShortName(); // RM
$mailPieces->getCarrierFullName(); // Royal Mail Group Ltd

$signature = $mailPieces->getSignature();
$signature->getRecipientName(); // Elliot
$signature->getSignatureDateTime(); // new DateTimeImmutable('2017-03-30T16:15:00+01:00')
$signature->getImageId(); // 001234
$signature->getOneDBarcode(); // FQ087430672GB
$signature->getHeight(); // 530
$signature->getWidth(); // 660
$signature->getUniqueItemId(); // 090367574000000FE1E1B
$signature->getImageFormat(); // image/svg+xml
$signature->getImage(); // <svg></svg>

$events = $mailPieces->getLinks()->getEvents();
$events->getHref(); // /mailpieces/v2/FQ087430672GB/events
$events->getTitle(); // Events
$events->getDescription(); // Get events

$linkSummary = $mailPieces->getLinks()->getSummary();
$linkSummary->getHref(); // /mailpieces/v2/summary?mailPieceId=090367574000000FE1E1B
$linkSummary->getTitle(); // Summary
$linkSummary->getDescription(); // Get summary

JSON 输出

$tracking = (new \ElliotJReed\RoyalMail\Tracking\Signature(
    new \GuzzleHttp\Client(),
    'aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee',
    '12345678901234567890123456789012345678901234567890'
));

echo $tracking->setTrackingNumber('AB1234567890GB')->asJson();

将输出皇家邮政跟踪响应的 JSON

{
    "errors": [],
    "httpCode": null,
    "httpMessage": null,
    "mailPieces": {
        "carrierFullName": "Royal Mail Group Ltd",
        "carrierShortName": "RM",
        "links": {
            "events": {
                "description": "Get events",
                "href": "/mailpieces/v2/FQ087430672GB/events",
                "title": "Events"
            },
            "summary": {
                "description": "Get summary",
                "href": "/mailpieces/v2/summary?mailPieceId=090367574000000FE1E1B",
                "title": "Summary"
            }
        },
        "mailPieceId": "090367574000000FE1E1B",
        "signature": {
            "height": 530,
            "image": "<svg></svg>",
            "imageFormat": "image/svg+xml",
            "imageId": "001234",
            "oneDBarcode": "FQ087430672GB",
            "recipientName": "Elliot",
            "signatureDateTime": "2017-03-30T16:15:00+01:00",
            "uniqueItemId": "090367574000000FE1E1B",
            "width": 660
        }
    },
    "moreInformation": null
}

摘要

摘要操作的目的是允许客户获取邮件项目的最新跟踪数据。

此操作返回请求中提供的一个或多个跟踪号码的摘要。

此操作仅允许在 ->setTrackingNumbers() 方法中提供最多 30 个跟踪号码（例如，->setTrackingNumbers(['AB0123456789GB', 'CD0123456789GB'])）。

$summary = (new \ElliotJReed\RoyalMail\Tracking\Summary(
    new \GuzzleHttp\Client(),
    'aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee',
    '12345678901234567890123456789012345678901234567890'
));

$mailPieces = $summary->setTrackingNumbers('AB1234567890GB', 'CD1234567890GB')->getResponse()->getMailPieces();

$firstMailPieces = $mailPieces[0];

$firstMailPieces->getMailPieceId(); // 090367574000000FE1E1B
$firstMailPieces->getCarrierShortName(); // RM
$firstMailPieces->getCarrierFullName(); // Royal Mail Group Ltd

$summary = $firstMailPieces->getSummary();
$summary->getUniqueItemId(); // 090367574000000FE1E1B
$summary->getOneDBarcode(); // FQ087430672GB
$summary->getProductId(); // SD2
$summary->getProductName(); // Special Delivery Guaranteed
$summary->getProductDescription(); // Our guaranteed next day service with tracking and a signature on delivery
$summary->getProductCategory(); // NON-INTERNATIONAL
$summary->getDestinationCountryCode(); // GBR
$summary->getDestinationCountryName(); // United Kingdom of Great Britain and Northern Ireland
$summary->getOriginCountryCode(); // GBR
$summary->getOriginCountryName(); // United Kingdom of Great Britain and Northern Ireland
$summary->getLastEventCode(); // EVNMI
$summary->getLastEventName(); // Forwarded - Mis-sort
$summary->getLastEventDateTime(); // new DateTimeImmutable('2016-10-20T10:04:00+01:00')
$summary->getLastEventLocationName(); // Stafford DO
$summary->getStatusDescription(); // It is being redirected
$summary->getStatusCategory(); // IN TRANSIT
$summary->getStatusHelpText(); // The item is in transit
$summary->getSummaryLine(); // Item FQ087430672GB was forwarded to the Delivery Office on 2016-10-20.

$internationalPostalProvider = $summary->getInternationalPostalProvider();
$internationalPostalProvider->getUrl(); // https://www.royalmail.com/track-your-item
$internationalPostalProvider->getTitle(); // Royal Mail Group Ltd
$internationalPostalProvider->getDescription(); // Royal Mail Group Ltd

$events = $firstMailPieces->getLinks()->getEvents();
$events->getHref(); // /mailpieces/v2/FQ087430672GB/events
$events->getTitle(); // Events
$events->getDescription(); // Get events

$error = $firstMailPieces->getError();
$error->getErrorCode(); // E1142
$error->getErrorDescription(); // Barcode reference $mailPieceId isn't recognised
$error->getErrorCause(); // A mail item with that barcode cannot be located
$error->getErrorResolution(); // Check barcode and resubmit

JSON 输出

$summary = (new \ElliotJReed\RoyalMail\Tracking\Summary(
    new \GuzzleHttp\Client(),
    'aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee',
    '12345678901234567890123456789012345678901234567890'
));

echo $summary->asJson();

将输出皇家邮政响应的 JSON

{
    "errors": [],
    "httpCode": null,
    "httpMessage": null,
    "mailPieces": [
        {
            "carrierFullName": "Royal Mail Group Ltd",
            "carrierShortName": "RM",
            "error": {
                "errorCause": "A mail item with that barcode cannot be located",
                "errorCode": "E1142",
                "errorDescription": "Barcode reference mailPieceId is not recognised",
                "errorResolution": "Check barcode and resubmit"
            },
            "links": {
                "events": {
                    "description": "Get events",
                    "href": "/mailpieces/v2/FQ087430672GB/events",
                    "title": "Events"
                }
            },
            "mailPieceId": "090367574000000FE1E1B",
            "summary": {
                "destinationCountryCode": "GBR",
                "destinationCountryName": "United Kingdom of Great Britain and Northern Ireland",
                "internationalPostalProvider": {
                    "description": "Royal Mail Group Ltd",
                    "title": "Royal Mail Group Ltd",
                    "url": "https://www.royalmail.com/track-your-item"
                },
                "lastEventCode": "EVNMI",
                "lastEventDateTime": "2016-10-20T10:04:00+01:00",
                "lastEventLocationName": "Stafford DO",
                "lastEventName": "Forwarded - Mis-sort",
                "oneDBarcode": "FQ087430672GB",
                "originCountryCode": "GBR",
                "originCountryName": "United Kingdom of Great Britain and Northern Ireland",
                "productCategory": "NON-INTERNATIONAL",
                "productDescription": "Our guaranteed next day service with tracking and a signature on delivery",
                "productId": "SD2",
                "productName": "Special Delivery Guaranteed",
                "statusCategory": "IN TRANSIT",
                "statusDescription": "It is being redirected",
                "statusHelpText": "The item is in transit",
                "summaryLine": "Item FQ087430672GB was forwarded to the Delivery Office on 2016-10-20.",
                "uniqueItemId": "090367574000000FE1E1B"
            }
        }
    ],
    "moreInformation": null
}

错误

错误以 \ElliotJReed\RoyalMail\Tracking\Exception\RoyalMailError 异常的实例抛出。

当可用时，可以通过抛出的异常上的 ->getResponse() 方法访问更多错误信息。

当可用时，可以通过 ->getErrorResponse()->getErrors() 访问潜在原因和解决方案。

致命异常/错误

当皇家邮政 API 的响应超出了他们预期的响应范围时，将抛出 \ElliotJReed\RoyalMail\Tracking\Exception\RoyalMailResponseError。

这仅在皇家邮政 API 发生严重故障（例如，DNS 故障）时才会抛出。

技术异常/错误

默认情况下，对于特定于应用程序的错误，对于 事件、签名 和 摘要 请求会抛出异常，作为 \ElliotJReed\RoyalMail\Tracking\Exception\RoyalMailTechnicalError 异常的实例。

try {
    $tracking = (new \ElliotJReed\RoyalMail\Tracking\Events(
        new \GuzzleHttp\Client(),
        'aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee',
        '12345678901234567890123456789012345678901234567890'
    ));
    $tracking->setTrackingNumber('AB1234567890GB');
} catch (\ElliotJReed\RoyalMail\Tracking\Exception\RoyalMailTechnicalError $exception) {
    echo $exception->getMessage();
    echo $exception->getResponse()?->getHttpCode();
    echo $exception->getResponse()?->getHttpMessage();
    echo $exception->getResponse()?->getMoreInformation();

    echo $exception->getResponse()?->getErrors()[0]->getErrorCode();
    echo $exception->getResponse()?->getErrors()[0]->getErrorDescription();
    echo $exception->getResponse()?->getErrors()[0]->getErrorCause();
    echo $exception->getResponse()?->getErrors()[0]->getErrorResolution();
}
禁用异常

可以禁用特定于应用程序的异常，以便在 Response 对象（通过 ->getResponse()）中返回错误。

例如，当在前端解析结果和处理错误时，这可能很有用。

要在构造函数中将抛出异常禁用，请将 $throwExceptionOnTechnicalError 设置为 false

$tracking = (new \ElliotJReed\RoyalMail\Tracking\Events(
    new \GuzzleHttp\Client(),
    'aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee',
    '12345678901234567890123456789012345678901234567890',
    true, // $throwExceptionOnTrackingError
    false // $throwExceptionOnTechnicalError
));
$response = $tracking->setTrackingNumber('AB1234567890GB')->getResponse();

echo $response->getMoreInformation();
echo $response->getErrors()[0]->getErrorCode();
echo $response->getErrors()[0]->getErrorCause();
echo $response->getErrors()[0]->getErrorDescription();
echo $response->getErrors()[0]->getErrorResolution();
$tracking = (new \ElliotJReed\RoyalMail\Tracking\Signature(
    new \GuzzleHttp\Client(),
    'aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee',
    '12345678901234567890123456789012345678901234567890',
    true, // $throwExceptionOnTrackingError
    false // $throwExceptionOnTechnicalError
));
$response = $tracking->setTrackingNumber('AB1234567890GB')->getResponse();

echo $response->getMoreInformation();
echo $response->getErrors()[0]->getErrorCode();
echo $response->getErrors()[0]->getErrorCause();
echo $response->getErrors()[0]->getErrorDescription();
echo $response->getErrors()[0]->getErrorResolution();
$tracking = (new \ElliotJReed\RoyalMail\Tracking\Summary(
    new \GuzzleHttp\Client(),
    'aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee',
    '12345678901234567890123456789012345678901234567890',
    false // $throwExceptionOnTechnicalError
));
$response = $tracking->setTrackingNumbers('AB1234567890GB')->getResponse();

echo $response->getMoreInformation();
echo $response->getErrors()[0]->getErrorCode();
echo $response->getErrors()[0]->getErrorCause();
echo $response->getErrors()[0]->getErrorDescription();
echo $response->getErrors()[0]->getErrorResolution();

业务异常/错误

默认情况下，对于业务/跟踪号特定的错误，会抛出对Events和Signature请求的异常（例如，无效的跟踪号），作为\ElliotJReed\RoyalMail\Tracking\Exception\RoyalMailTrackingError异常的实例。

事件和签名
try {
    $tracking = (new \ElliotJReed\RoyalMail\Tracking\Events(
        new \GuzzleHttp\Client(),
        'aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee',
        '12345678901234567890123456789012345678901234567890'
    ));

    $tracking->setTrackingNumber('AB1234567890GB');
} catch (\ElliotJReed\RoyalMail\Tracking\Exception\RoyalMailTrackingError $exception) {
    echo $exception->getMessage();
    echo $exception->getResponse()?->getHttpCode();
    echo $exception->getResponse()?->getHttpMessage();
    echo $exception->getResponse()?->getMoreInformation();

    echo $exception->getMessage();
    echo $exception->getResponse()?->getHttpCode();
    echo $exception->getResponse()?->getHttpMessage();
    echo $exception->getResponse()?->getMoreInformation();

    echo $exception->getResponse()?->getErrors()[0]->getErrorCode();
    echo $exception->getResponse()?->getErrors()[0]->getErrorDescription();
    echo $exception->getResponse()?->getErrors()[0]->getErrorCause();
    echo $exception->getResponse()?->getErrors()[0]->getErrorResolution();
}
摘要

业务/跟踪号特定的Summary请求错误将以MailPiece对象返回，而不是抛出异常（因为Summary将返回多个跟踪号的信息）。

因此，当遇到错误时，只有当它是特定于应用程序的错误时才会抛出异常，而不是当错误与特定跟踪号相关时。相反，错误将通过Mailpieces对象返回特定跟踪号。

$tracking = (new \ElliotJReed\RoyalMail\Tracking\Summary(
    new \GuzzleHttp\Client(),
    'aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee',
    '12345678901234567890123456789012345678901234567890'
));

$response = $tracking->setTrackingNumbers('AB1234567890GB')->getResponse();

echo $response->getMailPieces()[0]->getError()->getMoreInformation();
echo $response->getMailPieces()[0]->getError()->getErrorCode();
echo $response->getMailPieces()[0]->getError()->getErrorCause();
echo $response->getMailPieces()[0]->getError()->getErrorDescription();
echo $response->getMailPieces()[0]->getError()->getErrorResolution();

禁用异常

可以禁用业务/跟踪号特定的Events和Signature异常，以便错误在Response对象中返回（通过->getResponse()）。

要禁用抛出异常，请在构造函数中将$throwExceptionOnTrackingError设置为false。

$tracking = (new \ElliotJReed\RoyalMail\Tracking\Events(
    new \GuzzleHttp\Client(),
    'aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee',
    '12345678901234567890123456789012345678901234567890',
    false // $throwExceptionOnTrackingError
));
$response = $tracking->setTrackingNumber('AB1234567890GB')->getResponse();

echo $response->getMoreInformation();
echo $response->getErrors()[0]->getErrorCode();
echo $response->getErrors()[0]->getErrorCause();
echo $response->getErrors()[0]->getErrorDescription();
echo $response->getErrors()[0]->getErrorResolution();
$tracking = (new \ElliotJReed\RoyalMail\Tracking\Signature(
    new \GuzzleHttp\Client(),
    'aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee',
    '12345678901234567890123456789012345678901234567890',
    false // $throwExceptionOnTrackingError
));
$response = $tracking->setTrackingNumber('AB1234567890GB')->getResponse();

echo $response->getMoreInformation();
echo $response->getErrors()[0]->getErrorCode();
echo $response->getErrors()[0]->getErrorCause();
echo $response->getErrors()[0]->getErrorDescription();
echo $response->getErrors()[0]->getErrorResolution();

摘要错误

Summary调用返回多个跟踪号的信息，其中一些可能包含错误。

$summary = (new \ElliotJReed\RoyalMail\Tracking\Summary(
    new \GuzzleHttp\Client(),
    'aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee',
    '12345678901234567890123456789012345678901234567890'
));

$summary->setTrackingNumbers('AB1234567890GB', 'CD1234567890GB');

foreach ($summary->get() as $mailPiece) {
    if ($mailPiece->getError() !== null) {
        echo $responseError->getErrorCode() . \PHP_EOL;
        echo $responseError->getErrorDescription() . \PHP_EOL;
        echo $responseError->getErrorCause() . \PHP_EOL;
        echo $responseError->getErrorResolution() . \PHP_EOL;
    }
}

在Symfony中使用

要在Symfony中使用此库，将以下内容添加到services.yaml中，以便自动装配Events、Signature和Summary：

  guzzle.client.royal_mail_tracking:
    class: GuzzleHttp\Client
    arguments:
      - {
          timeout: 10
        }

  ElliotJReed\RoyalMail\Tracking\Events:
    class: ElliotJReed\RoyalMail\Tracking\Events
    arguments:
      $httpClient: '@guzzle.client.royal_mail_tracking'
      $royalMailClientId: '%env(string:ROYAL_MAIL_API_CLIENT_ID)%'
      $royalMailClientSecret: '%env(string:ROYAL_MAIL_API_CLIENT_SECRET)%'
      $throwExceptionOnTrackingError: true
      $throwExceptionOnTechnicalError: true

  ElliotJReed\RoyalMail\Tracking\Signature:
    class: ElliotJReed\RoyalMail\Tracking\Signature
    arguments:
      $httpClient: '@guzzle.client.royal_mail_tracking'
      $royalMailClientId: '%env(string:ROYAL_MAIL_API_CLIENT_ID)%'
      $royalMailClientSecret: '%env(string:ROYAL_MAIL_API_CLIENT_SECRET)%'
      $throwExceptionOnTrackingError: true
      $throwExceptionOnTechnicalError: true

  ElliotJReed\RoyalMail\Tracking\Summary:
    class: ElliotJReed\RoyalMail\Tracking\Summary
    arguments:
      $httpClient: '@guzzle.client.royal_mail_tracking'
      $royalMailClientId: '%env(string:ROYAL_MAIL_API_CLIENT_ID)%'
      $royalMailClientSecret: '%env(string:ROYAL_MAIL_API_CLIENT_SECRET)%'
      $throwExceptionOnTechnicalError: true

事件代码

EVAIP: 发件人发送物品。

EVAIE: 发件人发送物品。

ASRXS: 如有需要，如果我们无法交付您的物品，我们将安排在[X]处重寄。如果再次没有人，我们将把您的物品送到您选择的收货点。我们将通知您物品已送达。

EVAIP: 发件人已告知他们已将您的物品发送给我们。

EVBAH: 我们在国家级包裹中心有您的物品，它正在路上。

EVDAC: 我们在[X] MC有您的物品，它正在路上。

EVDAV: 我们在[X] MC有您的物品，它正在路上。

EVGMI: 抱歉，您的物品错误地发往[X] DO，所以我们立即重新路由。更多信息将在它通过我们的网络时提供。

EVGPD: 您的物品于[X]在[X]由[X] DO接收，现在应今天交付。

EVIAV: 您的物品已到达[X] MC，现在将发送到您的本地投递办公室。

EVIMC: 您的物品已到达[X] MC，现在将发送到您的本地投递办公室。

EVIPI: 抱歉，您的物品错误地发往[X] MC，所以我们立即重新路由。更多信息将在它通过我们的网络时提供。

EVKAA: 抱歉，我们无法在[X]交付此物品，因为地址无法访问。我们将在下一个工作日再次尝试交付您的物品。

EVKAI: 抱歉，我们无法在[X]交付此物品，因为无法识别投递地址。现在将返回给发件人。

EVKDN: 我们在[X]将您的物品送到邻居[X]在[X]。

EVKGA: 抱歉，我们无法在[X]交付此物品，因为收件人不再在该地址。我们将把物品返回给发件人。

EVKLC: 您的物品已送达您指定的收集点[X]，现在可以取货。

EVKNA: 抱歉，我们尝试在[X]交付您的包裹，但没有人在。请选择以下选项。

EVKOP: 您的物品已于[X]交付。

EVKRF: 抱歉，我们无法在[X]交付此物品，因为收件人拒绝接受。现在将返回给发件人。

EVKSF: 您的物品已于[X]送至您的收货点。

EVKSP: 您的物品已于[X]交付。

EVKSU: 对不起，我们今天未能将您的物品送达指定的安全地点[X]。请选择以下选项之一。

EVNAA: 对不起，由于地址无法进入，我们未能于[X]交付此物品。我们将尝试在下一个工作日再次交付。

EVNAR: 预计将在下一个工作日再次交付。

EVNDA: 对不起，我们试图在[X]交付您的包裹，但似乎没有人。请选择以下选项。

EVNDN: 对不起，我们未能于[X]交付此物品。我们将在下一个工作日尝试交付。以下为更多信息。

EVNGA: 对不起，由于收件人不再居住在该地址，我们未能于[X]交付此物品。我们将将其退还给寄件人。

EVNKS: 如您所请求，我们将此物品存放在[X]的DO作为我们KeepSafe服务的一部分。以下为更多信息。

EVNMI: 对不起，您的物品错误地送往[X]的DO，我们立即将其重新路由。更多信息将在它通过我们的网络时提供。

EVNOC: 您的物品已于[X]的DO于[X]被取走。

EVNRF: 对不起，由于收件人拒绝接收，我们未能于[X]交付此物品。它现在将被退还给寄件人。

EVNRT: 我们将此物品存放在[X]的DO。我们已收到不将邮件送至该物品地址的请求。我们将按照收到的指示尝试交付。

EVPLC: 物品[X]已被客户从[X]邮政局[X]于[X]取走。

EVRTS: 您的物品已于[X]退还给寄件人。

RFRXS: 如您所请求，我们将安排于[X]再次交付。如果家中无人，我们将把您的物品送到您选择的邻居处。

RNRXS: 如您所请求，我们将安排于[X]再次交付到您选择的地址。

RORXS: 如您所请求，我们将安排于[X]再次交付您的物品。

RPRXS: 如您所请求，我们将安排于您选择的邮政局再次交付。

RSRXS: 如您所请求，我们将安排于[X]再次交付。如果家中无人，我们将把您的物品送到您选择的存放点。我们将通知您交付时间。

开发

需要安装PHP 8.0或更高版本和Composer。

安装Composer

有关如何安装Composer的说明，请访问getcomposer.org。

安装

在克隆此存储库后，切换到新创建的目录，并运行

composer install

或者如果您已在本目录中本地安装了Composer

php composer.phar install

这将安装项目所需的所有依赖项。

从现在起，本README的其余部分将假设已全局安装composer（即如果您使用composer.phar，您需要在终端/命令行中使用composer.phar而不是composer）。

运行测试

单元测试

此项目的单元测试是通过PHPUnit进行的。

可以通过执行以下操作来运行所有单元测试

composer phpunit

调试

要使PHPUnit在遇到第一个失败的测试时停止并报告，请运行

composer phpunit:debug

代码格式化

在团队合作中，代码风格标准可以很重要，因为这意味着开发者处理他们所阅读的内容时花费的时间会更少（因为一切都将是一致的）。

代码格式化是通过PHP-CS-Fixer自动化的。PHP-CS-Fixer不会格式化构成PSR-2编码标准一部分的行长度，因此当通过PHP Code Sniffer进行检查时，这些行将产生警告。

可以通过执行以下命令来运行：

composer phpcs

运行所有内容

所有测试可以通过执行以下命令来运行：

composer test

过时的依赖项

可以通过执行以下命令来检查过时的Composer依赖项：

composer outdated

验证Composer配置

通过执行以下命令来验证composer.json文件的有效性：

composer validate --no-check-publish

通过GNU Make运行

如果已安装GNU Make，您可以用make替换上述composer命令的前缀。

所有测试可以通过执行以下命令来运行：

make test

在持续集成平台（例如GitHub Actions或Travis）上运行测试

包含特定输出格式，这些格式更适合CI平台，作为Composer脚本。

以文本格式和Clover XML格式输出单元测试覆盖率（这些格式可用于服务，如Coveralls）

composer phpunit:ci

以checkstyle格式输出PHP-CS-Fixer（dry run）和PHPCS结果（GitHub Actions将使用它来输出可读格式）

composer phpcs:github-actions

构建工具

许可协议

本项目采用MIT许可协议，详细信息请参阅LICENCE.md文件。