Auxiliares e constantes
O que mais o pacote define além dos métodos do cliente.
Métodos estáticos
| Método | O que é |
|---|---|
| OpenEmail::init(), OpenEmail::getClient() | Configure uma vez o cliente partilhado e depois aceda-lhe a partir de qualquer lado. getClient() constrói um a partir do ambiente se init nunca tiver corrido. |
| OpenEmail::resetClient() | Descarta o cliente partilhado, para que o getClient() seguinte construa um novo, que é o que um teste quer entre casos. |
| new OpenEmail(), OpenEmail::createClient() | Um cliente separado. Ambos leem o ambiente para tudo o que deixar de fora. |
| OpenEmail::createTempMail() | Um cliente de caixas descartáveis que não leva chave de API. |
| OpenEmail::verifyWebhookSignature() | Verifica a assinatura de uma entrega em tempo constante, com uma janela de repetição de cinco minutos que toleranceSeconds: altera. Devolve o evento descodificado e lança WebhookSignatureException em qualquer falha. |
| OpenEmail::toBase64() | Base64 para os bytes de anexos, a partir de uma string, um recurso de stream, um SplFileInfo ou um stream PSR-7. |
| OpenEmail::isApiKey() | Se um valor tem a forma oe_live_ ou oe_test_. Uma verificação de forma, não uma prova de que a chave ainda funciona. |
| OpenEmail::isAccessToken() | Se um valor tem a forma de um token de acesso OAuth: de 1 a 512 caracteres, sem começar por oe_. |
| OpenEmail::isSealed() | Se o corpo de uma mensagem é texto cifrado. É false para os dois formatos assinados, cujos corpos chegaram em claro. |
| OpenEmail::resolveLanguage(), OpenEmail::languageByCode(), OpenEmail::isRtlLanguage() | As procuras de que um seletor de idioma precisa, sobre a tabela Languages::ALL incluída no pacote. |
| $client->close() | Liberta o handle cURL do cliente e a ligação por trás dele. Um cliente que já não é referenciado faz o mesmo quando o PHP o liberta. |
Constantes
Cada conjunto de valores que o SDK de TypeScript exporta é uma classe final em OpenEmail\Constants, com uma constante por membro com os mesmos nomes, por isso WebhookEvents::EMAIL_DELIVERED é email.delivered. values() devolve o conjunto inteiro, e é também assim que se verifica um valor vindo de fora.
use OpenEmail\Constants\ApiScopes;use OpenEmail\Constants\PageLimits;use OpenEmail\Constants\WebhookEvents; $events = WebhookEvents::values(); $scopes = [ApiScopes::EMAILS_SEND, ApiScopes::THREADS_READ]; $known = in_array('email.delivered', $events, true); echo count($events), ' ', implode(',', $scopes), ' ', PageLimits::MAX_LIMIT, ' ', $known ? 'known' : 'unknown', PHP_EOL;| Constante | O que contém |
|---|---|
| OpenEmail::VERSION | A versão do pacote. |
| ApiScopes | O vocabulário de âmbitos, para um ecrã de criação de chaves. |
| WebhookEvents, WebhookSignatureHeaders | Os eventos que um endpoint pode subscrever, e os nomes dos cabeçalhos que uma entrega transporta. |
| ErrorTypes | O vocabulário de erros que ApiException::$type pode assumir. |
| PageLimits | O limit: máximo e o predefinido na maioria das listas paginadas, MAX_LIMIT e DEFAULT_LIMIT: 100 e 25. Algumas listas aceitam mais, e a referência de cada método indica-o. |
| RuleFields, RuleOperators, RuleActions | O vocabulário a partir do qual as condições e as ações de uma regra são construídas. |
| MessageEncryptionFormats | Os cinco envelopes que a ingestão pode indicar. Três deles são selados. |
| CredentialKinds, StepUpMethods, StepUpErrorCodes | Que credencial me->get e me->ping descrevem, como é verificado um código de verificação e os códigos com que uma verificação pode falhar. |
| ThreadSorts, PeopleSorts, FileSorts e os outros *Sorts | As ordens pelas quais uma lista pode ser ordenada. |
| FormStatuses, BroadcastStatuses, SuppressionReasons e os outros conjuntos | Os valores que um campo de um recurso pode assumir. Cada conjunto tem o nome do que contém. |
| Languages::ALL | Cada idioma que um envio ou uma pré-visualização traduzidos aceitam, com o seu código, os seus nomes e a sua direção. |
Objetos
Uma resposta é o JSON descodificado como array associativo. O pacote só constrói um objeto próprio quando dá forma à resposta, e cada um vive em OpenEmail\Result, é imutável, e é IteratorAggregate e Countable sobre as suas linhas.
| Classe | O que contém |
|---|---|
| Page | items, hasMore e nextCursor, de cada list paginado. |
| PeoplePage | O mesmo, mais seen, de contacts->listPeople. |
| TempMessagesPage | O mesmo, mais expiresAt, de tempMail->listMessages. |
| AddressBookPage, AddressBook | unrestricted, addresses e domains, de addresses->list (com hasMore e nextCursor) e de addresses->listAll. |
| BatchResult | items, sent e failed, de emails->sendBatch. |
| TemplateSends | items, total, page e pageSize, de templates->listSends. |
| OpenEmail\Http\HttpRequest, OpenEmail\Http\HttpResponse | O que um httpClient: recebe e devolve. var_dump(), print_r() e json_encode() mostram o cabeçalho Authorization de um pedido como [redacted], enquanto var_export() e o dump() do Symfony o mostram tal como está. |
Todas as exceções que o pacote lança implementam OpenEmail\Exception\OpenEmailException: ApiException e as suas subclasses, NetworkException, WebhookSignatureException e InvalidArgumentException, que é lançada por um erro na própria chamada e não por algo que a API disse.
Um endpoint que isto ainda não envolve
Uma versão do pacote nunca deve ser o que se interpõe entre si e um endpoint que já funciona. $client->raw->request() recebe um caminho e argumentos nomeados e devolve o corpo descodificado, com a credencial, o URL base, o timeout e a política de repetição do cliente aplicados.
$result = $client->raw->request( '/labels', method: 'POST', query: ['dryRun' => true], body: ['name' => 'Invoices'], repeatable: true,); var_dump($result);Um GET é repetido como qualquer outra leitura. Qualquer outro método é enviado uma só vez, a menos que passe repeatable: true, que é a sua afirmação de que pode ser enviado duas vezes. query: ignora valores null ou vazios, e apiKey: funciona como em todos os outros métodos.
O que deliberadamente não faz
- Não valida nenhum corpo de pedido. O esquema do servidor é a única cópia das regras, e uma segunda cópia aqui acabaria por recusar um endereço que um servidor mais recente aceita, numa versão que alguém fixou há dois anos.
- Não tem dependências de execução além das extensões curl e json. Um cliente PSR-18 é uma opção, nunca um requisito.
- Só altera a forma de uma resposta de uma maneira: o array
datade uma coleção é retirado do seu envelope para um dos objetos acima. Todas as outras respostas voltam tal como a API as enviou, com as chaves em camelCase da API.
A verificação de paridade do pacote garante que isto se mantém verdade. Faz falhar a build quando um método de TypeScript não tem equivalente em PHP, aceita argumentos diferentes ou envia um pedido diferente.