Utilidades y constantes
Lo que el paquete define además de los métodos del cliente.
Métodos estáticos
| Método | Qué es |
|---|---|
| OpenEmail::init(), OpenEmail::getClient() | Configura el cliente compartido una vez y luego accede a él desde cualquier sitio. getClient() construye uno a partir del entorno si init nunca se ejecutó. |
| OpenEmail::resetClient() | Descarta el cliente compartido, para que el siguiente getClient() construya uno nuevo, que es lo que necesita una prueba entre casos. |
| new OpenEmail(), OpenEmail::createClient() | Un cliente aparte. Ambos leen el entorno para todo lo que omitas. |
| OpenEmail::createTempMail() | Un cliente de buzón desechable que no lleva ninguna clave de API. |
| OpenEmail::verifyWebhookSignature() | Comprueba la firma de una entrega en tiempo constante, con una ventana de repetición de cinco minutos que cambia toleranceSeconds:. Devuelve el evento decodificado, y lanza WebhookSignatureException ante cualquier fallo. |
| OpenEmail::toBase64() | Base64 para los bytes de un adjunto, a partir de una cadena, un recurso de stream, un SplFileInfo o un stream PSR-7. |
| OpenEmail::isApiKey() | Si un valor tiene la forma oe_live_ u oe_test_. Es una comprobación de forma, no una prueba de que la clave siga funcionando. |
| OpenEmail::isAccessToken() | Si un valor tiene la forma de un token de acceso OAuth: de 1 a 512 caracteres, sin empezar por oe_. |
| OpenEmail::isSealed() | Si el cuerpo de un mensaje es texto cifrado. Es false para los dos formatos firmados, cuyos cuerpos llegaron en claro. |
| OpenEmail::resolveLanguage(), OpenEmail::languageByCode(), OpenEmail::isRtlLanguage() | Las búsquedas que necesita un selector de idioma, sobre la tabla Languages::ALL incluida. |
| $client->close() | Libera el handle de cURL del cliente y la conexión que hay detrás. Un cliente al que ya no se hace referencia hace lo mismo cuando PHP lo libera. |
Constantes
Cada conjunto de valores que exporta el SDK de TypeScript es una clase final en OpenEmail\Constants, con una constante por miembro con los mismos nombres, así que WebhookEvents::EMAIL_DELIVERED es email.delivered. values() devuelve el conjunto completo, que es también la forma de comprobar un valor que vino de fuera.
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 | Qué contiene |
|---|---|
| OpenEmail::VERSION | La versión del paquete. |
| ApiScopes | El vocabulario de ámbitos, para una pantalla de creación de claves. |
| WebhookEvents, WebhookSignatureHeaders | Los eventos a los que se puede suscribir un endpoint, y los nombres de las cabeceras que lleva una entrega. |
| ErrorTypes | El vocabulario de errores que toma ApiException::$type. |
| PageLimits | El limit: máximo y el predeterminado en la mayoría de las listas paginadas, MAX_LIMIT y DEFAULT_LIMIT: 100 y 25. Unas pocas listas admiten más, y la referencia de cada método lo indica. |
| RuleFields, RuleOperators, RuleActions | El vocabulario con el que se construyen las condiciones y las acciones de una regla. |
| MessageEncryptionFormats | Los cinco sobres que puede nombrar la ingesta. Tres de ellos están sellados. |
| CredentialKinds, StepUpMethods, StepUpErrorCodes | Qué credencial describen me->get y me->ping, cómo se comprueba un código de verificación y los códigos con los que puede fallar una verificación. |
| ThreadSorts, PeopleSorts, FileSorts y los demás *Sorts | Los órdenes en los que se puede ordenar una lista. |
| FormStatuses, BroadcastStatuses, SuppressionReasons y los demás conjuntos | Los valores que puede tomar un campo de un recurso. Cada conjunto se nombra según lo que contiene. |
| Languages::ALL | Todos los idiomas que acepta un envío traducido o una vista previa, con su código, sus nombres y su dirección de escritura. |
Objetos
Una respuesta es el JSON decodificado como array asociativo. El paquete solo construye un objeto propio donde da forma a la respuesta, y cada uno vive en OpenEmail\Result, es inmutable y es IteratorAggregate y Countable sobre sus filas.
| Clase | Lo que lleva |
|---|---|
| Page | items, hasMore y nextCursor, de cada list paginado. |
| PeoplePage | Lo mismo más seen, de contacts->listPeople. |
| TempMessagesPage | Lo mismo más expiresAt, de tempMail->listMessages. |
| AddressBookPage, AddressBook | unrestricted, addresses y domains, de addresses->list (con hasMore y nextCursor) y de addresses->listAll. |
| BatchResult | items, sent y failed, de emails->sendBatch. |
| TemplateSends | items, total, page y pageSize, de templates->listSends. |
| OpenEmail\Http\HttpRequest, OpenEmail\Http\HttpResponse | Lo que recibe y devuelve un httpClient:. var_dump(), print_r() y json_encode() muestran la cabecera Authorization de una solicitud como [redacted], mientras que var_export() y el dump() de Symfony la muestran tal cual. |
Toda excepción que lanza el paquete implementa OpenEmail\Exception\OpenEmailException: ApiException y sus subclases, NetworkException, WebhookSignatureException e InvalidArgumentException, que se lanza por un error en la propia llamada y no por algo que dijo la API.
Un endpoint que esto todavía no envuelve
Una versión del paquete nunca debería ser lo que te separa de un endpoint que ya funciona. $client->raw->request() recibe una ruta y argumentos nombrados y devuelve el cuerpo decodificado, aplicando la credencial, la URL base, el tiempo de espera y la política de reintentos del cliente.
$result = $client->raw->request( '/labels', method: 'POST', query: ['dryRun' => true], body: ['name' => 'Invoices'], repeatable: true,); var_dump($result);Un GET se reintenta como cualquier otra lectura. Cualquier otro método se envía una sola vez salvo que pases repeatable: true, que es tu afirmación de que puede enviarse dos veces. query: omite los valores null o vacíos, y apiKey: funciona igual que en todos los demás métodos.
Lo que deliberadamente no hace
- No valida ningún cuerpo de solicitud. El esquema del servidor es la única copia de las reglas, y una segunda copia aquí acabaría rechazando una dirección que un servidor más reciente acepta, en una versión que alguien fijó hace dos años.
- No tiene dependencias en tiempo de ejecución aparte de las extensiones curl y json. Un cliente PSR-18 es una opción, nunca un requisito.
- Solo cambia la forma de una respuesta de una manera: el array
datade una colección se saca de su sobre y se coloca en uno de los objetos de arriba. Cualquier otra respuesta vuelve tal como la envió la API, con las claves en camelCase de la API.
La comprobación de paridad del paquete mantiene esto honesto. Hace fallar la compilación cuando un método de TypeScript no tiene gemelo en PHP, acepta argumentos distintos o envía una solicitud distinta.