Yapılandırma
İstemci nasıl oluşturulur, tüm seçenekler ve bir istek gönderilmeden önce nelerin reddedildiği.
Seçenekler
use OpenEmail\OpenEmail; $client = new OpenEmail(); OpenEmail::init(timeout: 10);OpenEmail::getClient()->me->ping(); $billing = new OpenEmail(apiKey: (string) getenv('OPENEMAIL_BILLING_API_KEY')); echo $client->mode, ' ', $billing->mode, PHP_EOL;| Giriş noktası | Size ne verir |
|---|---|
| new OpenEmail(...) | Geçirdiğiniz adlandırılmış argümanlardan kurulan bir istemci. Belirtmediğiniz her şey ortamdan okunur: hiçbir kimlik bilgisi geçirmediğinizde anahtar OPENEMAIL_API_KEY değişkeninden ya da bir token OPENEMAIL_ACCESS_TOKEN değişkeninden, temel URL geçirmediğinizde de temel URL OPENEMAIL_BASE_URL değişkeninden. |
| OpenEmail::createClient(...) | new OpenEmail(...) ile aynı istemci; bir fabrika çağırmayı tercih eden kod için. |
| OpenEmail::init(...) | Bir istemci kurar, onu paylaşılan istemci olarak saklar ve döndürür. Aynı adlandırılmış argümanları alır. |
| OpenEmail::getClient() | Sürecin her yerinden erişilen paylaşılan istemci. init öncesinde çağrılırsa ilk çağrıda ortamdan bir istemci kurar. |
| OpenEmail::resetClient() | Paylaşılan istemciyi bırakır; böylece bir sonraki getClient() yeni bir istemci kurar. Bir testin vakalar arasında istediği de budur. |
getenv() sonucunun dizeye dönüştürülmesi bilinçlidir. Tanımlanmamış bir değişken boş bir anahtara dönüşür ve istemci bunu, ihtiyaç duyduğu değişkeni adıyla anan bir mesajla reddeder; null ise sessizce OPENEMAIL_API_KEY değerine geri dönerdi.
use OpenEmail\Http\CurlHttpClient;use OpenEmail\OpenEmail; $client = new OpenEmail( apiKey: (string) getenv('OPENEMAIL_API_KEY'), baseUrl: 'https://api.openemail.uk', httpClient: new CurlHttpClient(), maxRetries: 2, timeout: 30, userAgent: 'billing-service/1.4', headers: ['X-Team' => 'billing'], disableUpdateNotice: true,);| Seçenek | Varsayılan | Notlar |
|---|---|---|
| apiKey: | OPENEMAIL_API_KEY | oe_live_ ya da oe_test_ ile başlamalıdır. Yalnızca ne apiKey: ne de accessToken: geçirdiğinizde ortamdan okunur. |
| accessToken: | OPENEMAIL_ACCESS_TOKEN | Bir OAuth erişim tokenı ya da bir token döndüren çağrılabilir bir nesne. Aşağıdaki “OAuth erişim tokenları” bölümüne bakın. Bir anahtar ya da bir token geçirin, asla ikisini birden değil. |
| baseUrl: | https://api.openemail.uk | Ya da OPENEMAIL_BASE_URL. Sondaki eğik çizgiler kırpılır; çıplak bir konak adının önüne https://, bu makinedeki bir konağın önüne ise http:// eklenir: localhost, bir 127.x.x.x adresi ya da ::1. Bir kimlik bilgisi hiçbir zaman düz http üzerinden başka bir konağa gönderilmez ve 0.0.0.0 ya da [::] istemci kurulurken reddedilir, çünkü bunlar bir sunucunun dinlediği adreslerdir, istek gönderilecek adresler değildir. |
| timeout: | 30 | Çağrı başına değil, deneme başına saniye; bağlanmayı ve yanıtın tamamını okumayı kapsar. 0 bunu kapatır. files->upload, o çağrıda timeout: geçirmediğiniz sürece en az 600 saniye bekler. |
| maxRetries: | 2 | Tekrarlanması güvenli çağrılarda ilk denemeden sonraki ek denemeler. Çağrı başına değil, istemcide ayarlanır. 0 yeniden denemeleri kapatır. |
| httpClient: | CurlHttpClient | HTTP katmanı: OpenEmail\Http\HttpClient arayüzünü uygulayan her şey; örneğin Guzzle ya da Symfony HttpClient'ı saran Psr18HttpClient veya bir testteki sahte istemci. Her birini HTTP istemcileri sayfası anlatır. |
| headers: | [] | Her istekte gönderilir. |
| userAgent: | openemail-php/<version> | Her istekte gönderilir. |
| disableUpdateNotice: | false | Packagist'te daha yeni bir sürüm için süreç başına bir kez yapılan denetimi atlar. Denetim yalnızca komut satırında ve standart çıktı bir terminal olduğunda çalışır; OPENEMAIL_DISABLE_UPDATE_NOTICE da onu kapatır. |
Ortam değişkenleri
| Değişken | Ne yapar |
|---|---|
| OPENEMAIL_API_KEY | Ne apiKey: ne de accessToken: geçirdiğinizde bir istemcinin kullandığı anahtar. |
| OPENEMAIL_ACCESS_TOKEN | Bir OAuth erişim tokenı. Yalnızca hiçbir kimlik bilgisi geçirmediğinizde ve OPENEMAIL_API_KEY ayarlanmamışsa okunur, yani ortamdaki bir anahtar önceliklidir. |
| OPENEMAIL_BASE_URL | Hiçbiri geçirilmediğinde kullanılan temel URL. localhost:2222 gibi çıplak bir konağa şeması eklenir. |
| OPENEMAIL_DISABLE_UPDATE_NOTICE | Boş olmayan herhangi bir değer, süreçteki tüm istemciler için güncelleme bildirimini kapatır. |
| HTTPS_PROXY ve NO_PROXY ya da https_proxy ve no_proxy | cURL'ün üzerinden bağlandığı proxy ve doğrudan bağlanılan konaklar. Aşağıdaki “Proxy'ler ve TLS” bölümüne bakın. |
Her değişken önce getenv() ile, ardından $_SERVER ve $_ENV içinden okunur; bu yüzden framework'ünüzün bir .env dosyasından yüklediği bir değer de sayılır. Ayarlanmış ama boş olan bir değişken ayarlanmamış sayılır.
Göndermeden önce neleri reddeder
Bunlar, ilk gönderiminizde kafa karıştırıcı bir hata olarak ortaya çıkmak yerine, yanlış değerin bulunduğu satırdan OpenEmail\Exception\InvalidArgumentException fırlatır. Hata iletisi neyin yanlış olduğunu ve bunun yerine ne geçirileceğini söyler ve bir kimlik bilgisini asla tekrarlamaz.
| Reddedilen | Neden |
|---|---|
| Hiç kimlik bilgisi yok | Ne apiKey: ne de accessToken: geçirildi ve iki değişkenden hiçbiri de ayarlanmadı; dolayısıyla kimlik doğrulamak için hiçbir şey yok. İstemci kurulurken fırlatılır. |
| Bir anahtar ve bir token birlikte | Her istek tek bir kimlik bilgisi taşır; bu yüzden istemci hangisini kastettiğinizi anlayamaz. |
| Bir oturum çerezi, bir oturum tokenı ya da başka bir hizmete ait bir anahtar | Burada yalnızca oe_live_ ve oe_test_ kimlik doğrular ve API de aynısını söyler. Denetim yalnızca önekle ilgilidir; bu yüzden iptal edilmiş bir anahtar yine de istek sunucuya ulaştığında AuthenticationException olarak başarısız olur. |
| http ya da https URL'si olmayan veya içinde kullanıcı adı ya da parola bulunan bir baseUrl: | Başka hiçbir şeye ulaşılamaz ve kimlik bilgisinin yeri URL değil, apiKey: ya da accessToken: alanıdır. İstemci kurulurken fırlatılır. |
| Bu makinede olmayan bir konağa düz http üzerinden gönderilen bir kimlik bilgisi | Hiçbir şey gönderilmeden önce çağrı tarafından fırlatılır. https kullanan bir temel URL kullanın. |
| Negatif bir timeout: | Saniye geçirin ya da zaman aşımı istemiyorsanız 0 geçirin. İstemci kurulurken ya da tek bir çağrıya geçirilen bir zaman aşımı için o çağrı tarafından fırlatılır. |
| HTTP belirteci (token) olmayan bir başlık adı ya da bir başlık değerindeki satır sonu veya başka bir denetim karakteri | headers:, userAgent: ve idempotencyKey: içinde denetlenir, çünkü bir satır sonu ikinci bir başlık başlatır. Bir değerin başındaki ve sonundaki boşluklar, sekmeler ve satır sonları önce fetch gibi kırpılır; bu yüzden satır sonuyla biten bir dosyadan okunan anahtar da çalışır. |
| Herhangi bir metotta boş veya tamamı noktadan oluşan bir id | Metot çağrıldığında fırlatılır. Noktalardan oluşan bir yol parçası her URL ayrıştırıcısı tarafından kaldırılır; dolayısıyla istek başka bir uç noktaya ulaşırdı. Geçerli UTF-8 olmayan bir kimlik de reddedilir. |
| base64 olmayan ek içeriği | Bir dize her zaman base64 olarak okunur; bu yüzden içindeki ham baytlar bozuk veri olarak gönderilirdi. Onları OpenEmail::toBase64() ile kodlayın ya da bir SplFileInfo, bir akış veya bir PSR-7 akışı geçirin, istemci onu kodlar. |
Sınıf, PHP'nin kendi InvalidArgumentException sınıfını genişletir; bu yüzden onu zaten yakalayan kod çalışmaya devam eder. Ayrıca paketin fırlattığı diğer tüm istisnalar gibi OpenEmail\Exception\OpenEmailException arayüzünü uygular. Dize bir id'nin geleceği yerde bir sayı gibi yanlış türde bir değer, PHP'nin kendisinden gelen bir TypeError olur, çünkü her metot türlerini bildirir.
testMode: diye bir seçenek yoktur ve olmayacaktır. Anahtar şeması bir ipucu değil, kimlik bilgisinin bir parçasıdır; dolayısıyla mod anahtarın bir özelliğidir. $client->mode öneki (live ya da test) okur ve hiçbir şeye karar vermez.
Tek istemci, birkaç anahtar
İstemciyi bir kez kurun ve paylaşın. Her istek için yeni bir istemci, açık bağlantısını boş yere atar ve üzerindeki durumun hiçbir kısmı çağırana özgü değildir.
Birkaç çalışma alanı adına gönderim yapan bir iş gibi, aksi hâlde anahtar başına bir istemci gerektirecek durumlarda apiKey: değerini çağrıda geçirin. O istek için Authorization başlığının yerini alır ve istemcide arkasında hiçbir iz bırakmaz.
$message = [ 'from' => '[email protected]', 'to' => '[email protected]', 'subject' => 'Your invoice', 'text' => 'Attached.',];$workspaceKey = (string) getenv('OPENEMAIL_API_KEY'); $client->emails->send($message); $client->emails->send($message, apiKey: $workspaceKey); $client->threads->list(folder: 'inbox', apiKey: $workspaceKey);$client->webhooks->list(apiKey: $workspaceKey);tempMail dışındaki her metot bunu son adlandırılmış argümanı olarak, bir listedeki filtrelerden sonra alır; tempMail metotları ise bunun yerine inboxToken: alır. İstek gönderilmeden önce istemcinin kullandığı kuralla denetlenir; bu yüzden bir yazım hatası, sonradan gidip bulmanız gereken bir kimlik bilgisiyle ilgili bir 401 yerine, bu çağrıya geçirilen apiKey hakkında bir InvalidArgumentException fırlatır. Yeniden denenen bir çağrı kendisine verilen anahtarı korur.
$client->mode, istemcinin hangi anahtarla KURULDUĞUNU açıklar ve geçersiz kılmayı izlemez. Tek bir istemci birkaç anahtara hizmet ettiğinde bildirilecek tek bir mod yoktur; bu yüzden modu geçirdiğiniz anahtardan okuyun. var_dump($client) modu ve temel URL'yi gösterir, anahtarı asla göstermez; kimlik bilgisi alan her parametre de #[\SensitiveParameter] ile işaretlidir, bu yüzden bir yığın izi onun yerine bir yer tutucu yazdırır.
Hiçbir metodun sarmadığı uç noktalar
$client->raw, her metodun içinden geçtiği taşıma katmanıdır. $client->raw->request(), henüz hiçbir metodun sarmadığı bir yolu istemcinin kimlik bilgisi, temel URL'si, zaman aşımı ve yeniden deneme politikası uygulanmış olarak çağırır ve kodu çözülmüş gövdeyi bir metodun yaptığı gibi döndürür.
$ping = $client->raw->request('/ping'); $label = $client->raw->request('/labels', method: 'POST', body: ['name' => 'Invoices']); var_dump($ping, $label);| Adlandırılmış argüman | Ne yapar |
|---|---|
| method: | Aksini belirtmedikçe GET. Diğerleri: POST, PUT, PATCH ya da DELETE. |
| query: | Sorgu parametrelerinden oluşan bir dizi. null ve boş değerler atlanır, bir liste virgüllerle birleştirilir ve bir DateTimeInterface, UTC'de bir ISO 8601 anı olarak gönderilir. |
| body: | JSON olarak gönderilen bir dizi. |
| raw: ve contentType: | Olduğu gibi gönderilecek baytlar: bir dize, bir akış kaynağı, bir SplFileInfo ya da bir PSR-7 akışı. Bir tür belirtmediğiniz sürece application/octet-stream olarak gönderilir. |
| accept: ve binary: | JSON dışında bir accept: gövdeyi metin olarak döndürür, binary: true ise bir bayt dizesi olarak döndürür. |
| idempotent: ve idempotencyKey: | idempotent: true bir Idempotency-Key ekler. Kendi anahtarınızı geçirmezseniz bu anahtar üretilir. |
| repeatable: | Bir hatanın ardından yeniden denenip denenmeyeceği. repeatable: true geçirmediğiniz sürece yalnızca GET yeniden denenir. |
| anonymous: | true hiçbir kimlik bilgisi göndermez. |
| apiKey:, inboxToken: ve timeout: | Aynı çağrı başına kimlik bilgileri ve yalnızca bu çağrı için saniye cinsinden bir zaman aşımı. |
Yol tek bir / ile başlamalıdır. Tamamlanmış URL'si temel URL'nin kaynağının (origin) dışına çıkacak bir yol, hiçbir şey gönderilmeden önce InvalidArgumentException fırlatır; böylece kimlik bilgisi asla başka bir konağa ulaşmaz.
Tek kullanımlık gelen kutuları
OpenEmail::createTempMail(), tek kullanımlık gelen kutuları için hiç API anahtarı taşımayan ve ortamdan da anahtar okumayan bir istemci kurar. Gelen kutularını anonim olarak oluşturur ve her okuma, create çağrısının döndürdüğü gelen kutusu tokenını ya da extend çağrısının döndürdüğü daha yeni tokenı gönderir: ya her çağrıda inboxToken: olarak ya da bir kez OpenEmail::createTempMail(inboxToken: ...) olarak.
use OpenEmail\OpenEmail; $tempMail = OpenEmail::createTempMail(); $inbox = $tempMail->create();$page = $tempMail->listMessages($inbox['id'], inboxToken: $inbox['token']); echo count($page->items), ' ', $page->expiresAt, PHP_EOL;OpenEmail::createTempMail(), her istemci gibi baseUrl:, httpClient:, maxRetries:, timeout:, userAgent:, headers: ve disableUpdateNotice: alır ve temel URL geçirmediğinizde OPENEMAIL_BASE_URL değerini okur.
OAuth erişim tokenları
Bir kişinin OAuth üzerinden bağladığı, komut satırı aracı ya da ajan gibi bir uygulama, API anahtarı yerine bir erişim tokenı tutar. Onu accessToken: olarak geçirin: ya tokenın kendisini ya da tokenı döndüren, bir closure veya birinci sınıf callable gibi çağrılabilir bir nesneyi. Bu nesne her çağrı için bir kez çalışır ve o çağrının yeniden denemeleri döndürdüğü değeri yeniden kullanır; bu yüzden tokenın süresi dolmak üzereyken onu bu nesnenin içinde yenileyin, böylece istemciyi hiç yeniden kurmanız gerekmez.
use OpenEmail\OpenEmail; $tokens = ['current' => 'token-from-your-oauth-flow']; $oauthClient = new OpenEmail(accessToken: fn(): string => $tokens['current']); $me = $oauthClient->me->get(); if ($me['object'] === 'oauth_token') { echo $me['clientId'], ' ', $me['expiresAt'], PHP_EOL;}| Durum | Ne olur |
|---|---|
| apiKey: ve accessToken: birlikte ya da hiçbiri | İstemci kurulurken InvalidArgumentException fırlatır. Hiçbiri yoksa hata iletisi OPENEMAIL_API_KEY ve OPENEMAIL_ACCESS_TOKEN adlarını verir. |
| Token olmayan bir değer | Bir token 1 ile 512 karakter arasındadır ve oe_ ile başlamaz; OpenEmail::isAccessToken() bu denetimi yapar. Bu denetimi geçemeyen bir dize istemci kurulurken reddedilir, böyle bir değer döndüren çağrılabilir bir nesne ise hiçbir şey gönderilmeden önce çağrının InvalidArgumentException fırlatmasına yol açar. |
| OPENEMAIL_ACCESS_TOKEN | Hiçbir kimlik bilgisi geçirmediğinizde ve OPENEMAIL_API_KEY ayarlanmamışsa okunur; yani ortamdaki bir anahtar önceliklidir. |
| İstisna fırlatan çağrılabilir bir nesne | Çağrı bu istisnayı değiştirmeden fırlatır ve hiçbir şey gönderilmez. |
| Çağrı başına bir apiKey: | Yalnızca o istek için tokenın yerini alır ve çağrılabilir nesne çağrılmaz. |
| $client->mode | Bir tokenla her zaman live. |
| OpenEmail::createTempMail() | Ortamda ne olursa olsun hiçbir kimlik bilgisi göndermez. |
| me->get() ve me->ping() | Bir token için get; oauth_token değerinde object, null olan id ve roleId, bağlı uygulamanın clientId değeri ve kişinin uygulamaya verdiği onayın sona erdiği an olan expiresAt ile yanıt verir. ping; oauth değerinde kind, null olan keyId ve clientId ile yanıt verir. id ya da keyId okumadan önce object ya da kind değerini kontrol edin. |
Bir token bir kişi adına çalışır ve onun postasını onun okuyabildiği gibi okur, bu yüzden onu bir anahtar gibi sunucuda tutun.
Doğrulama kodları
Bir alan adını silmek ya da bir webhook'u değiştirmek gibi hassas bir değişiklikten önce API, bir erişim tokenından web uygulamasının kişiden isteyeceği doğrulama kodunu ister. Çağrı, isStepUpRequired() değeri true olan 403'lük bir PermissionException fırlatır ve hiçbir şey değişmemiştir. Bir kod isteyin, kişinin size verdiği kodu doğrulayın, ardından çağrıyı yeniden yapın. Bir API anahtarından asla kod istenmez.
use OpenEmail\Exception\ApiException; $domainId = 'b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f'; try { $client->domains->delete($domainId);} catch (ApiException $error) { if (!$error->isStepUpRequired()) { throw $error; } $challenge = $client->security->beginStepUp(); if ($challenge['method'] === 'email') { echo 'Enter the code we emailed to ', $challenge['sentTo'], PHP_EOL; } else { echo 'Enter the code from your authenticator app, or a backup code', PHP_EOL; } $client->security->verifyStepUp(['code' => trim((string) fgets(STDIN))]); $client->domains->delete($domainId);}| Metot | Ne yapar |
|---|---|
| security->stepUpStatus() | Uygulamanın şu anda doğrulanmış olup olmadığı (elevated, elevatedUntil), sonraki kodun nasıl denetleneceği (method, email ya da totp) ve pencerenin uzunluğu minutes. Hiçbir şey göndermez ve bir duraklamayı bildirmez. |
| security->beginStepUp() | Bir doğrulama talebi açar. email ile kişinin oturum açtığı adrese altı haneli bir kod gider ve sentTo bu adresi maskelenmiş olarak gösterir. totp ile kişi kodu doğrulayıcı uygulamasından okur ya da bir yedek kod kullanır. Hâlâ açık olan ve deneme hakkı kalan bir talep, ['resend' => true] geçirmediğiniz sürece yeniden kullanılır; kilitlenmiş ya da süresi dolmuş bir talep ise sıradan bir çağrıyla değiştirilir. Her uygulama her kişi için saatte 5 ve 24 saatte 20 talep açabilir; bir sonraki 429 step_up_throttled fırlatır. |
| security->verifyStepUp(['code' => ...]) | Kodu denetler ve bu uygulama için hassas değişikliklerin kilidini 60 dakikalığına, yani elevatedUntil anına kadar, hem REST üzerinden hem de aynı değişiklikleri yapan MCP araçları aracılığıyla açar. Bu uygulamadan 24 saat içinde 10 yanlış koddan ya da kişinin tüm uygulamalarından toplam 20 yanlış koddan sonra bu çağrı ve beginStepUp, doğrulamanın ne zaman yeniden açılacağını söyleyen bir iletiyle 429 step_up_locked fırlatır. |
İstemci asla kendiliğinden kod istemez ya da çağrıyı tekrarlamaz ve üç metodun hiçbiri otomatik olarak yeniden denenmez, çünkü kaybolan bir yanıttan sonraki yeniden deneme ikinci bir e-posta gönderebilir ya da ikinci bir denemeyi harcayabilir. Kapsam gerektirmezler ve bunlardan birini çağıran bir API anahtarı 400 step_up_not_applicable alır. OpenEmail\Constants\StepUpErrorCodes bir doğrulamanın başarısız olabileceği her yolu adlandırır ve API hatalar sayfası her biri için ne yapılacağını söyler.
Güncelleme bildirimi
Packagist'te paketin daha yeni bir sürümü olduğunda istemci bunu süreç başına bir kez, standart hata çıktısında ℹ openemail/sdk 0.0.2 is available, you are on 0.0.1. gibi bir satırla ve ardından paketin sayfasıyla bildirir. Denetim yalnızca komut satırında, standart çıktı bir terminal olduğunda çalışır; bir web sunucusu altında asla çalışmaz. İlk istemci kurulduğunda başlar ve isteklerinizle yan yana çalışır; betiğin sonunda da iki saniyelik bütçeden ne kaldıysa o kadar bekler. Packagist'e ulaşılamaması yok sayılır.
Denetim, istemcinin httpClient: değerinin dışında, cURL ile kendi isteğini yapar; bu yüzden bir testteki sahte HTTP istemcisi onu asla görmez. Kapatmak için disableUpdateNotice: true geçirin ya da OPENEMAIL_DISABLE_UPDATE_NOTICE değişkenini ayarlayın.
Proxy'ler ve TLS
Varsayılan CurlHttpClient proxy işini cURL'e bırakır; cURL proxy için https_proxy ya da HTTPS_PROXY, doğrudan bağlanılan konaklar için no_proxy ya da NO_PROXY değişkenini okur. Bunun yerine kodda bir proxy belirtmek için proxy: geçirin. Proxy URL'sindeki kullanıcı adı ve parola proxy'ye gönderilir.
use OpenEmail\Http\CurlHttpClient;use OpenEmail\OpenEmail; $client = new OpenEmail(httpClient: new CurlHttpClient( caBundle: '/etc/ssl/certs/corporate-ca.pem', proxy: 'http://proxy.internal:3128', curlOptions: [CURLOPT_IPRESOLVE => CURL_IPRESOLVE_V4],));Bağlantılar TLS 1.2 ya da üzerini kullanır, sunucunun sertifikasını ve konak adını denetler; yönlendirmeler asla izlenmez. caBundle:, TLS'yi inceleyen bir proxy için güvenilecek sertifika yetkililerini belirtir. curlOptions: başka herhangi bir cURL seçeneğini ayarlar; ancak bir isteğin ihtiyaç duyduğu ayarlar her zaman önceliklidir: URL ve portu, metot, başlıklar, gövde ve kapalı kalan yönlendirmeler. CURLOPT_REQUEST_TARGET reddedilir ve cURL'ün kabul etmediği bir seçenek, adını veren bir InvalidArgumentException fırlatır.