Hatalar
Her başarısızlık istisna fırlatır. Ret için bir sınıf, yanıt gelmemesi için bir sınıf ve her API hatasında bir istek kimliği.
Hata yakalama
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;}Bir gönderimdeki permission_error genellikle çalışma alanından değil ANAHTARIN gönderim kapsamından, yani kendisine verilmemiş bir alan adından veya adresten kaynaklanır. Örnek kodun, bu anahtarın hangi adresler adına gönderebileceğine dair addresses->listAll() çağrısının söylediklerini günlüğe yazmasının nedeni budur.
Her ret türünün kendine ait bir alt sınıfı vardır; böylece bir catch, ele aldıklarını sınıfa göre seçip geri kalanların yukarı doğru ilerlemesine izin verebilir.
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;}Sınıflar
Tüm sınıflar OpenEmail\Exception içinde yer alır.
| Sınıf | Ne zaman |
|---|---|
| OpenEmailException | Paketin fırlattığı her istisnanın uyguladığı arayüzdür; bu yüzden catch (OpenEmailException $error), InvalidArgumentException dahil hepsini yakalar. |
| ApiException | API yanıt verdi, ama başarıyla değil. status, type, errorCode, param, docUrl, requestId, retryAfterSeconds, fields ve body taşır. type değeri api_error olduğunda (bir sunucu arızasında olduğu gibi) kendisi olarak, aksi hâlde type değerine karşılık gelen alt sınıf olarak fırlatılır. RuntimeException sınıfını genişletir. |
| InvalidRequestException, AuthenticationException, PermissionException, NotFoundException, ConflictException, ValidationException ve RateLimitException | Her type için bir tane olmak üzere ApiException alt sınıfları: invalid_request_error, authentication_error, permission_error, not_found_error, conflict_error, validation_error ve rate_limit_error. |
| NetworkException | Hiç yanıt gelmedi: DNS, TLS, reddedilen ya da kopan bir bağlantı veya zaman aşımı. getPrevious() alttaki istisnayı tutar ve neden zaman aşımıysa isTimeout() true olur. RuntimeException sınıfını genişletir. |
| WebhookSignatureException | OpenEmail::verifyWebhookSignature() bir teslimi reddetti. UnexpectedValueException sınıfını genişletir. |
| InvalidArgumentException | Hiçbir şey gönderilmeden önce fırlatılır: eksik ya da hatalı biçimlendirilmiş bir anahtar, kullanılamaz bir baseUrl:, boş bir kimlik. PHP'nin kendi InvalidArgumentException sınıfını genişletir, çünkü çağrının kendisinin yanlış olduğu anlamına gelir. |
Bir ApiException'ın taşıdıkları
getMessage()string- API'nin bir insan için yazdığı ve varsa soruna yol açan değeri adlandıran kendi cümlesi. Kararlı bir tanımlayıcı değildir, bu yüzden dallanmayı `errorCode` üzerinden yapın.
statusint or null- Yanıtın HTTP durumu; `getCode()` da bunu döndürür. Yalnızca başarılı bir yanıt istemcinin okuyamadığı bir biçimde geldiğinde null olur.
typestring- `OpenEmail\Constants\ErrorTypes` içindeki sekiz değerden biri; bu küme sabittir ve büyümeyecektir. Gövde bir değer belirtmediğinde durumdan çıkarılır.
errorCodestring- `from_address_forbidden` ya da `invalid_email_address` gibi belirli hata. Adı `errorCode`, çünkü PHP `code` adını `getCode()` metodunun döndürdüğü sayı için ayırır. Açık ve genişletilebilir bir kümedir, bu yüzden tanımadığınız bir kodu `type` değerine göre ele alın. Gövde API'nin hata zarfı olmadığında `unrecognised_response` olur.
paramstring or null- Hata bir alan belirttiğinde, `to.0` gibi noktalı bir yol olarak reddedilen alan.
docUrlstring or null- API bir sayfa belirttiğinde, bu hatayla ilgili sayfa.
requestIdstring or null- Sunucunun isteği günlüğe kaydettiği kimlik; gövdeden ya da `x-request-id` başlığından alınır.
retryAfterSecondsint, float or null- Sunucunun `Retry-After` içinde istediği bekleme süresi, saniye cinsinden; sunucu ister bir sayı ister bir tarih göndermiş olsun. Hiçbir şey göndermediyse null.
fieldsarray or null- Her sorun için `key` ve `error` içeren bir dizi; örneğin `forms->subscribe` yanıtları 422 `invalid_form_submission` ile reddettiğinde `['key' => 'email', 'error' => 'email']`. Hata hiçbir sorun listelemiyorsa null.
bodymixed- Hata yanıtının tamamı, kodu çözülmüş olarak. Boşsa ya da JSON değilse null.
| Metot | Şu durumda true |
|---|---|
| isAuth() | type değeri authentication_error, yani 401: anahtar yok, yanlış türde bir kimlik bilgisi veya bizim vermediğimiz bir anahtar. |
| isPermission() | permission_error, 403: ihtiyaç duyduğu kapsama veya From adresine sahip olmayan gerçek bir anahtar. |
| isScopeMissing() | errorCode değeri insufficient_scope, yani eksik kapsamı adıyla belirten 403. |
| isInvalidRequest() | invalid_request_error, 400: anlaşılamayan bir istek. Boyut tavanını aşan bir mesaj 422 message_too_large olarak döner; dolayısıyla onu yakalayan metot isValidation() metodudur. |
| isValidation() | validation_error, 422: şema isteği reddetti ve param hangi alanın sorunlu olduğunu belirtir. |
| isNotFound() | not_found_error, 404: böyle bir kaynak yok. |
| isConflict() | conflict_error, 409: kaynak, bu işlemin kendisine yapılabileceği noktayı geçmiş. |
| isRateLimited() | rate_limit_error, 429. Sunucu bir süre belirttiğinde bekleme süresi retryAfterSeconds içindedir. |
| isServerError() | status 500 veya üzeri. Destekle iletişime geçerseniz requestId değerini belirtin. |
| isRetryable() | status 408, 429, 500, 502, 503 veya 504. |
| isStepUpRequired() | errorCode değeri step_up_required'dır: bir OAuth erişim tokenının, kişi bir kodu doğrulayana kadar hassas bir değişiklikten önce aldığı 403. |
Bunların çoğu, zarfın sabit yarısı olan type değerini okur ve her alt sınıf bir type değerine karşılık gelir. errorCode bir dize olarak kalır, çünkü API onun açık ve genişletilebilir olduğunu garanti eder; bu yüzden tanımadığınız bir kodu type değerine göre ele alın. Kapalı bir liste, yeni bir hata türünü okuyabilmeyi bir paket yükseltmesine bağlardı.
API'nin hata zarfı olmayan bir gövde de, type değeri durumdan çıkarılmış ve errorCode değeri unrecognised_response olarak ayarlanmış bir ApiException fırlatır. Gövdesi JSON olmayan başarılı bir yanıt da aynı istisnayı fırlatır.
isRetryable() çağrınızı değil, durumu tanımlar. Tekrarlanması güvenli bir çağrı, istisna fırlattığı anda zaten yeniden denenmiştir; send_quota_exceeded ya da ai_quota_exceeded gibi bir 429 ise kotası sıfırlanana kadar aynı şekilde başarısız olur. Bu yüzden onu bir döngüde tekrarlamak yerine bir kişiye gösterin.
HTTP istemcinizin fırlattığı bir istisna, çağrının izin verdiği yeniden denemeler tükendiğinde, asıl istisna getPrevious() olarak kalacak şekilde bir NetworkException hâline gelir. Bir LogicException ve TypeError gibi herhangi bir Error, istemcide bir hata olduğu anlamına gelir; bu yüzden değiştirilmeden fırlatılırlar ve asla yeniden denenmezler. Psr18HttpClient, sardığı istemcinin istisnasından yalnızca iletiyi tutar, çünkü o istisna isteği ve Authorization başlığını taşır.
requestId
Her ApiException, sunucunun gönderdiği istek kimliğini hata gövdesinden ya da x-request-id başlığından alarak taşır ve hatanızı sunucu günlüğündeki bir satıra bağlayan tek şey budur. Başarılı bir yanıt yalnızca kodu çözülmüş gövdeyi döndürür, bu yüzden onda okunacak bir istek kimliği yoktur.