Download the PHP package hermesihq/hermesi without Composer

On this page you can find all versions of the php package hermesihq/hermesi. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.

FAQ

After the download, you have to make one include require_once('vendor/autoload.php');. After that you have to import the classes with use statements.

Example:
If you use only one package a project is not needed. But if you use more then one package, without a project it is not possible to import the classes with use statements.

In general, it is recommended to use always a project to download your libraries. In an application normally there is more than one library needed.
Some PHP packages are not free to download and because of that hosted in private repositories. In this case some credentials are needed to access such packages. Please use the auth.json textarea to insert credentials, if a package is coming from a private repository. You can look here for more information.

  • Some hosting areas are not accessible by a terminal or SSH. Then it is not possible to use Composer.
  • To use Composer is sometimes complicated. Especially for beginners.
  • Composer needs much resources. Sometimes they are not available on a simple webspace.
  • If you are using private repositories you don't need to share your credentials. You can set up everything on our site and then you provide a simple download link to your team member.
  • Simplify your Composer build process. Use our own command line tool to download the vendor folder as binary. This makes your build process faster and you don't need to expose your credentials for private repositories.
Please rate this library. Is it a good library?

Informations about the package hermesi

hermesihq/hermesi

Server-side client for Hermesi: publish events and read what became of them, keep your subscribers in sync, send a direct message, mint subscriber tokens and preference links. Thin on purpose: it builds the request, sends it with retries, and turns the answer into a typed result or an exception. It makes no decision about notifications; that is the platform's job.

For Laravel, use the wrapper, hermesihq/laravel: it adds the facade, a test fake and a queued job on top of this package.

Install

It needs a PSR-18 HTTP client and finds the one you have. If your application has none, Composer asks (through the php-http/discovery plugin) whether it may install one, and installs Symfony's HttpClient. To choose another:

If the plugin is disabled and no client is installed, the first request fails with a message that says what to install.

Publish an event

202 means the event is recorded and queued. Nothing has been delivered yet: watch the Activity Log in the dashboard.

$recipient is a subscriber's external id, a Subscriber described inline (created or updated on the fly), or a list of up to 100 of either:

The client reads HERMESI_SECRET_KEY and HERMESI_BASE_URL from the environment if you do not pass them.

Idempotency: pass your own key when your code can run twice

The SDK generates a key per call and reuses it across its own retries, which covers a lost response. It cannot cover your code running twice for the same thing (a webhook handler that is retried, a queue job that is redelivered): the second run generates a new key. For that, give the event a key derived from what happened, such as order-4821-shipped. Replaying a key with the same body within 24 hours returns the original answer, and $result->replayed is true.

Other arguments

actor: new Actor(externalId: ..., name: ...), delay: 'PT15M', sendAt: new DateTimeImmutable(...), override: [...], tenant: '...'. They are named arguments, so you pass only what you need.

Scheduling

delay holds the event back for an ISO 8601 duration (PT15M, PT1H30M, P1D: not 15m) and sendAt until an instant (a DateTimeInterface, which always carries its offset, or an ISO 8601 string with one). Give one, not both, at most 30 days ahead. A time already past runs at once. The run starts within about a minute after its time, not at the second. A request the server cannot honour is refused with 422 invalid_schedule: it is never sent immediately instead. Pass your own idempotency key and retrying a scheduled event does not schedule it twice.

override and tenant are accepted by the API but not acted on yet.

Your data, and what PHP's json_encode does to it

A notification payload is where PHP's own JSON encoding hurts, so this package does not use it as it is:

Read back what became of an event

A message's status moves on after the event was accepted (queued, sent, delivered, ...), so poll it rather than treating the first answer as final. It never returns what was sent or the recipient's address, and an event of another environment is a NotFoundException.

Keep your subscribers in sync

A key you give is set, null clears the field, and a key you leave out is left alone, so a sync job that knows half a profile does not blank the other half. data replaces the stored attributes, up to 32 KB; it is not merged. A key the SDK does not know (phoneE164 instead of phone_e164) is an \InvalidArgumentException rather than a value silently dropped. The server checks the shapes (an email looks like one, phone_e164 is E.164, locale a language tag, timezone an IANA name) and refuses what it does not know, as a ValidationException naming the field.

delete removes the email, phone, names, attributes, channel identities and preferences, and replaces the address on every message the person received by [deleted], keeping the messages and their status for your statistics. Inbox items, the stored text of messages and event payloads are not erased yet.

Import many at once

For a first import of your user table or a nightly sync: up to 1 000 rows per call (split a bigger file with array_chunk($rows, 1000)). Each row is an array with an external_id and any of the keys put takes, and means exactly what the same put would: a key you include is set (null clears it), a key you leave out is left alone, and data replaces. A key that is none of those is an \InvalidArgumentException naming the row.

All or nothing. If the server finds any row invalid it throws a ValidationException that lists every problem with its row (body.subscribers.17.email) and nothing was written, so fix them all and send the same batch again. The same external_id twice, or more than 5 MB of data in total, is refused too. Every row is an idempotent upsert, so resending after a timeout changes nothing; a full batch takes a few seconds, so do not set a very short timeout.

registerChannel refreshes the identity and makes it active again if a provider had marked it invalid; it never duplicates it. In updatePreferences, true or false sets an override and null removes it, so the category's default applies again. It is all or nothing: an unknown category (NotFoundException) or a critical one (ValidationException) refuses the whole update.

Send one message on a channel you choose

Almost everything should be an event: you say what happened and Hermesi decides the channels. When the channel is a requirement instead (an OTP that must be an SMS), send one message through one template:

It skips the workflow and nothing else: preferences, suppressions and the audit trail still apply, and a refused message is a result you can read, not an exception. A mistake (an unknown template, a template with no variant for the channel, an unknown recipient) is thrown and creates nothing. The wording lives in a published template; data becomes its payload.* and is not kept once a provider has the message. There is no inline content: it would put copy back in your code.

Pass your own idempotencyKey when your code can run twice. One is generated and kept across the retries if you give none, so a timeout cannot send a second SMS, but only your own key survives your code running again.

Subscriber tokens

A browser or an app talks to Hermesi's client API as one subscriber, with a token minted on your server:

environmentId is the env_... id shown in the dashboard; the key itself does not carry it. Minting makes no request. Also available on its own: Hermesi\SubscriberToken::mint($secretKey, $externalId, $environmentId).

Preference links

Errors

AuthenticationException (401), ForbiddenException (403), NotFoundException (404), ValidationException (400, 422; see ->details), RateLimitException (429) and ServerException (5xx) all extend ApiException, which extends HermesiException, as does ConnectionException. Branch on the class or on errorCode, never on the message. (getCode() is PHP's own integer and stays 0; the API's code is a string, so it is errorCode.) A response that is not the API's error envelope has errorType === 'sdk_error' and errorCode === 'unexpected_response', which the API never sends.

A mistake in how you call it (a public key, a missing name, a payload that cannot be sent) is a plain \InvalidArgumentException, not a HermesiException: it is a bug to fix, not a failure to handle.

Retries

Times are in seconds. A Retry-After is waited out exactly, up to maxRetryAfter; a server that asks for more gets its exception thrown, because a request that sleeps for ten minutes is worse than one that fails.

Timeouts, and the HTTP client you pass

PSR-18 has no way to ask a client for a timeout: it belongs to the client. So:

Testing your code

A simulated call validates and serialises exactly as a real one does, so a payload that would fail in production fails in your test. It does not know your workflows: it cannot tell you whether an event matches one.

Writes that are not events (subscribers->put, messages->send, registerChannel, ...) are recorded in $hermesi->simulatedCalls() (method, path, body, idempotency key) and answered with a plausible result (status === 'simulated' for a message). Reads (events->get, subscribers->get, messages->get, ...) throw SimulationException: nothing was sent, so there is nothing to read, and an invented answer would make a test pass for the wrong reason.

The key never shows

The client holds your secret key, so it is built not to leak it: var_dump, print_r, var_export, json_encode and (array) do not show it, and the client cannot be serialised (so it cannot end up in a cache or a session). On PHP 8.2 and later the key is also redacted from stack traces. On 8.1, leave zend.exception_ignore_args on in production, which is the default of the production php.ini.

Not included

The dashboard's Management API (workflows, templates, providers) and inline content for a direct message (Hermesi refuses it on purpose). Outbound webhooks are not implemented in Hermesi yet either, so there is nothing to verify.

Development

tests/LiveTest.php runs the SDK against a real Hermesi (vendor/bin/phpunit --group live) and is skipped unless you point it at one; read its header.

License

MIT


All versions of hermesi with dependencies

PHP Build Version
Package Version
Requires php Version ^8.1
ext-json Version *
php-http/discovery Version ^1.19
psr/http-client Version ^1.0
psr/http-client-implementation Version 1.0
psr/http-factory Version ^1.0
psr/http-factory-implementation Version 1.0
psr/http-message Version ^1.1 || ^2.0
Composer command for our command line client (download client) This client runs in each environment. You don't need a specific PHP version etc. The first 20 API calls are free. Standard composer command

The package hermesihq/hermesi contains the following files

Loading the files please wait ...