Gabimet
Çdo dështim hedh përjashtim. Një klasë për refuzimin, një për mungesën e përgjigjes dhe një id kërkese në çdo gabim të API-së.
Si ta kapni një
use OpenEmail\Exception\ApiException;use OpenEmail\Exception\NetworkException; $message = [ 'from' => '[email protected]', 'to' => '[email protected]', 'subject' => 'Your September invoice', 'text' => 'Invoice attached.',]; try { $client->emails->send($message);} catch (ApiException $error) { if ($error->isValidation()) { error_log($error->errorCode . ' ' . $error->param . ' ' . $error->getMessage()); } if ($error->isPermission()) { $book = $client->addresses->listAll(); error_log('this key may send as ' . implode(', ', array_column($book->addresses, 'address'))); } if ($error->isRateLimited()) { error_log('try again in ' . $error->retryAfterSeconds . ' seconds'); } error_log($error->status . ' ' . $error->requestId); throw $error;} catch (NetworkException $error) { if ($error->isTimeout()) { error_log('no answer in time'); } throw $error;}Një permission_error gjatë dërgimit zakonisht lidhet me fushën e dërgimit të ÇELËSIT, pra me një domen ose një adresë që nuk iu dha, dhe jo me hapësirën e punës; prandaj shembulli regjistron në log atë që thotë addresses->listAll() për adresat me të cilat mund të dërgojë ky çelës.
Çdo lloj refuzimi ka nënklasën e vet, ndaj një catch mund të zgjedhë sipas klasës ato që trajton dhe t’i lërë të tjerat të ngjiten më lart.
use OpenEmail\Exception\AuthenticationException;use OpenEmail\Exception\OpenEmailException;use OpenEmail\Exception\PermissionException;use OpenEmail\Exception\ValidationException; $message = [ 'from' => '[email protected]', 'to' => '[email protected]', 'subject' => 'Your September invoice', 'text' => 'Invoice attached.',]; try { $client->emails->send($message);} catch (ValidationException $error) { error_log($error->param . ': ' . $error->getMessage());} catch (AuthenticationException|PermissionException $error) { error_log('the key cannot do this: ' . $error->errorCode); throw $error;} catch (OpenEmailException $error) { error_log($error::class . ': ' . $error->getMessage()); throw $error;}Klasat
Çdo klasë ndodhet në OpenEmail\Exception.
| Klasa | Kur |
|---|---|
| OpenEmailException | Ndërfaqja që implementon çdo përjashtim që hedh paketa, ndaj catch (OpenEmailException $error) i kap të gjitha, përfshirë InvalidArgumentException. |
| ApiException | API-ja u përgjigj, por jo me sukses. Mbart status, type, errorCode, param, docUrl, requestId, retryAfterSeconds, fields dhe body. Hidhet si vetvetja kur type është api_error, siç ndodh me një defekt të serverit, dhe si nënklasa për type e tij në rastet e tjera. Zgjeron RuntimeException. |
| InvalidRequestException, AuthenticationException, PermissionException, NotFoundException, ConflictException, ValidationException dhe RateLimitException | Nënklasa të ApiException, një për çdo type: invalid_request_error, authentication_error, permission_error, not_found_error, conflict_error, validation_error dhe rate_limit_error. |
| NetworkException | Nuk mbërriti asnjë përgjigje: DNS, TLS, një lidhje e refuzuar ose e këputur, ose skadimi i afatit. getPrevious() mban përjashtimin poshtë tij, dhe isTimeout() është true kur arsyeja ishte skadimi i afatit. Zgjeron RuntimeException. |
| WebhookSignatureException | OpenEmail::verifyWebhookSignature() refuzoi një dërgesë. Zgjeron UnexpectedValueException. |
| InvalidArgumentException | Hidhet para se të dërgohet çfarëdo: një çelës që mungon ose është i keqformuar, një baseUrl: i papërdorshëm, një id bosh. Zgjeron vetë InvalidArgumentException të PHP-së, sepse do të thotë se vetë thirrja është e gabuar. |
Çfarë mbart një ApiException
getMessage()string- Fjalia e vetë API-së, e shkruar për një njeri dhe që përmend vlerën problematike kur ka të tillë. Nuk është identifikues i qëndrueshëm, ndaj degëzojeni sipas `errorCode`.
statusint or null- Statusi HTTP i përgjigjes, që e kthen edhe `getCode()`. Është null vetëm kur një sukses u kthye në një formë që klienti nuk mund ta lexonte.
typestring- Një nga tetë vlerat në `OpenEmail\Constants\ErrorTypes`, një bashkësi e fiksuar që nuk do të rritet. Kur trupi nuk përmend asnjë, nxirret nga statusi.
errorCodestring- Dështimi specifik, si `from_address_forbidden` ose `invalid_email_address`. Quhet `errorCode` sepse PHP-ja e mban `code` për numrin që kthen `getCode()`. Bashkësi e hapur që zgjerohet, ndaj një kod që nuk e njihni trajtojeni sipas `type` të tij. Është `unrecognised_response` kur trupi nuk ishte zarfi i gabimit të API-së.
paramstring or null- Fusha që u refuzua, si shteg me pika, p.sh. `to.0`, kur dështimi përmend një të tillë.
docUrlstring or null- Një faqe për këtë dështim, kur API-ja përmend një të tillë.
requestIdstring or null- Id-ja me të cilën serveri e regjistroi kërkesën në log, nga trupi ose nga header-i `x-request-id`.
retryAfterSecondsint, float or null- Pritja që kërkoi serveri në `Retry-After`, në sekonda, qoftë kur dërgoi një numër, qoftë një datë. null kur nuk dërgoi asnjë.
fieldsarray or null- Një array për çdo problem, secili me `key` dhe `error`, si `['key' => 'email', 'error' => 'email']` kur `forms->subscribe` i refuzoi përgjigjet me një 422 `invalid_form_submission`. null kur gabimi nuk rendit asnjë.
bodymixed- E gjithë përgjigjja e gabimit, e dekoduar. null kur ishte bosh ose nuk ishte JSON.
| Metoda | True kur |
|---|---|
| isAuth() | type është authentication_error, një 401: asnjë çelës, lloji i gabuar i kredencialit, ose një çelës që nuk e kemi lëshuar ne. |
| isPermission() | permission_error, një 403: një çelës i vërtetë pa scope-in ose pa adresën From që i duhet. |
| isScopeMissing() | errorCode është insufficient_scope, 403-shi që emërton një scope që mungon. |
| isInvalidRequest() | invalid_request_error, një 400: një kërkesë që nuk mund të kuptohej. Një mesazh mbi tavanin e madhësisë kthehet si një 422 message_too_large, pra isValidation() është metoda që e kap atë. |
| isValidation() | validation_error, një 422: skema e refuzoi, dhe param e emërton fushën. |
| isNotFound() | not_found_error, një 404: nuk ka burim të tillë. |
| isConflict() | conflict_error, një 409: burimi ka kaluar pikën ku kjo mund t'i bëhej. |
| isRateLimited() | rate_limit_error, një 429. retryAfterSeconds e mban pritjen kur serveri emërtoi një të tillë. |
| isServerError() | status është 500 ose më lart. Citoni requestId nëse kontaktoni mbështetjen. |
| isRetryable() | status është 408, 429, 500, 502, 503 ose 504. |
| isStepUpRequired() | errorCode është step_up_required, 403-shi që merr një token qasjeje OAuth para një ndryshimi të ndjeshëm derisa personi të ketë verifikuar një kod. |
Shumica e tyre lexojnë type, gjysmën e fiksuar të zarfit, dhe çdo nënklasë përfaqëson një type. errorCode mbetet string, sepse API-ja garanton se është bashkësi e hapur që zgjerohet, ndaj një kod që nuk e njihni trajtojeni sipas type të tij. Një listë e mbyllur do ta bënte përditësimin e paketës çmimin për të lexuar një lloj të ri dështimi.
Një trup që nuk është zarfi i gabimit të API-së hedh prapëseprapë një ApiException, me type të nxjerrë nga statusi dhe errorCode të barabartë me unrecognised_response. E hedh gjithashtu edhe një përgjigje e suksesshme trupi i së cilës nuk është JSON.
isRetryable() përshkruan statusin, jo thirrjen tuaj. Një thirrje që mund të përsëritet pa rrezik është riprovuar tashmë kur hedh përjashtim, dhe një 429 si send_quota_exceeded ose ai_quota_exceeded dështon në të njëjtën mënyrë derisa të rivendoset kuota e tij, ndaj tregojani një njeriu në vend që ta përsërisni në cikël.
Një përjashtim që hedh klienti juaj HTTP bëhet një NetworkException pasi të jenë shteruar riprovat që lejon thirrja, me origjinalin si getPrevious(). Një LogicException dhe çdo Error, si një TypeError, nënkuptojnë një defekt në të, ndaj hidhen të pandryshuara dhe nuk riprovohen kurrë. Psr18HttpClient mban vetëm mesazhin e një përjashtimi nga klienti që mbështjell, sepse ai përjashtim mban kërkesën dhe header-in e saj Authorization.
requestId
Çdo ApiException mbart id-në e kërkesës që dërgoi serveri, nga trupi i gabimit ose nga header-i x-request-id, dhe kjo është e vetmja gjë që e lidh dështimin tuaj me një rresht në log-un e serverit. Një sukses kthen vetëm trupin e dekoduar, ndaj në të nuk ka id kërkese për të lexuar.