omnisense/omnireview API reference

Omnireview

Config class

final class Config extends ArrayObject Config.php:13

A gateway's configuration while its factory builds it: the options given, the factory's defaults under them, and the keys that must be filled.

Config::defaults()

public function defaults(array $defaults): self

Sets each key not set yet.

Config::validateNotEmpty()

public function validateNotEmpty(array $keys): void

Config::get()

public function get(string $key, mixed $default = null): mixed

Config::string()

public function string(string $key): ?string

A string option; null when it is empty.

Config::bool()

public function bool(string $key): bool

A boolean option, as an environment variable gives it too: "1", "true", "yes", "on".

Config::list()

public function list(string $key): array

A list given as one environment variable arrives as a single comma-separated string: split here, at run time.

GatewayFactory class

abstract class GatewayFactory implements GatewayFactoryInterface GatewayFactory.php:15

The Omnibus way, at its simplest: a gateway's factory fills a Config - its name ("omnireview.factory_name"), its title ("omnireview.factory_title"), the options it needs ("omnireview.required_options") and the defaults of the others - then builds the gateway from it.

Nothing here calls anything: a factory whose provider is reached over HTTP takes its client in its own constructor - the application's, a MockHttpClient in a test.

GatewayFactory::getName()

public function getName(): string

GatewayFactory::create()

public function create(array $options = []): GatewayInterface

GatewayFactory::createConfig()

public function createConfig(array $options = []): Config

GatewayFactoryInterface interface

interface GatewayFactoryInterface GatewayFactoryInterface.php:6

Builds a gateway from its options (an API key, an account, a locale...).

GatewayFactoryInterface::getName()

public function getName(): string

The name gateways are configured with: "google", "tripadvisor", "trustpilot".

..

GatewayFactoryInterface::create()

public function create(array $options = []): GatewayInterface

GatewayInterface interface

interface GatewayInterface GatewayInterface.php:18

One platform where customers rate and review an establishment, configured: Google, Tripadvisor, Trustpilot. It gives what its interfaces say - RatingInterface, ReviewsInterface, ReplyInterface, InviteInterface, WriteUrlInterface -, its Capabilities list them, and its Terms say how what it gives may be shown and kept.

A gateway reads and writes on the platform. It keeps nothing: the application decides what to show, for how long - within the Terms.

GatewayInterface::getName()

public function getName(): string

The factory's name: "google", "tripadvisor", "trustpilot".

..

GatewayInterface::getTitle()

public function getTitle(): string

GatewayInterface::capabilities()

public function capabilities(): Capabilities

What it gives, and on what terms.

GatewayInterface::terms()

public function terms(): Terms

How what it gives may be shown and kept, as the platform's rules say.

InviteInterface interface

interface InviteInterface extends GatewayInterface InviteInterface.php:9

Inviting a customer to leave a review, by the platform's own e-mail.

InviteInterface::invite()

public function invite(Place $place, Invitation $invitation): ?string

Returns

the platform's reference for the invitation, when it gives one

RatingInterface interface

interface RatingInterface extends GatewayInterface RatingInterface.php:9

The establishment's rating on the platform: a score, a number of reviews, the page they are on.

RatingInterface::rating()

public function rating(Place $place): Rating

Throws

Exception\UnreachableException when the platform did not answer

Throws

Exception\ProviderException when it does not know the place

Registry class

final class Registry Registry.php:23

The application's gateways by name, each built once from its factory and options:

new Registry([new GoogleGatewayFactory($http), new TrustpilotGatewayFactory($http)], [ 'google' => ['factory' => 'google', 'options' => ['api_key' => '...']], 'trustpilot' => ['factory' => 'trustpilot', 'options' => ['api_key' => '...']], ]);

$registry->rating('google')->rating(new Place('ChIJ...'));

A typed getter gives the gateway when it implements the interface and its capabilities() say it gives that as configured (Trustpilot replies only with a business user): otherwise a NotSupportedException.

Registry::__construct()

public function __construct(iterable $factories, readonly array $config)

Registry::get()

public function get(string $name): GatewayInterface

Registry::has()

public function has(string $name): bool

Registry::rating()

public function rating(string $name): RatingInterface

The gateway, as what gives its rating.

Registry::reviews()

public function reviews(string $name): ReviewsInterface

The gateway, as what gives its reviews.

Registry::replies()

public function replies(string $name): ReplyInterface

The gateway, as what gives replying to a review.

Registry::invitations()

public function invitations(string $name): InviteInterface

The gateway, as what gives inviting a customer to review.

Registry::writeUrl()

public function writeUrl(string $name): WriteUrlInterface

The gateway, as what gives the address to leave a review.

Registry::options()

public function options(string $name): array

Returns

the options a gateway is configured with

Registry::create()

public function create(string $name, array $overrides = []): GatewayInterface

A gateway built afresh, its configured options with $overrides over them - a key typed in a back office, say. Not kept: get() still gives the configured one.

Registry::names()

public function names(): array

Returns

the configured gateways' names

Registry::all()

public function all(): array

Registry::factories()

public function factories(): array

Returns

the factories installed: what factory: may name

ReplyInterface interface

interface ReplyInterface extends GatewayInterface ReplyInterface.php:10

Answering a review as the establishment: the owner's access to the platform needed.

ReplyInterface::reply()

public function reply(Place $place, Review $review, string $text): Reply

The reply, as published.

ReviewsInterface interface

interface ReviewsInterface extends GatewayInterface ReviewsInterface.php:9

Reviews of the establishment, as the platform gives them: in its order, as many as it allows.

ReviewsInterface::reviews()

public function reviews(Place $place, int $limit = 5, ?string $language = null): array

$limit

how many at most: the platform may give fewer (Terms::$maxReviews)

$language

the reviews' language, where the platform filters or translates

WriteUrlInterface interface

interface WriteUrlInterface extends GatewayInterface WriteUrlInterface.php:8

Where a customer leaves a review: a link to give them - a button, an e-mail, a receipt.

WriteUrlInterface::writeUrl()

public function writeUrl(Place $place): string

Omnireview\Bridge\Symfony

OmnireviewBundle class

final class OmnireviewBundle extends AbstractBundle OmnireviewBundle.php:46

Omnireview in a Symfony application: the gateway packages installed (omnireview/google, omnireview/tripadvisor, omnireview/trustpilot) registered, the gateways built from configuration and injectable by their name, and Twig's functions with the application's cache:

omnireview: gateways: google: { factory: google, options: { api_key: '%env(GOOGLE_PLACES_KEY)%' } } trustpilot: { factory: trustpilot, options: { api_key: '%env(TRUSTPILOT_KEY)%' } } cache: pool: cache.app # kept no longer than each platform allows ttl: 3600

public function __construct(GatewayInterface $google) }
{{ omnireview_widget('google', place_id) }}

Nothing is built, nor checked, when the container compiles. A factory is autowired, the application's http_client given to it when it has one.

OmnireviewBundle::configure()

public function configure(DefinitionConfigurator $definition): void

OmnireviewBundle::getPath()

public function getPath(): string

The bundle's resources, Bridge/Twig: TwigBundle registers its templates/ as @Omnireview after the application's templates/bundles/OmnireviewBundle/, so a widget placed there wins.

OmnireviewBundle::loadExtension()

public function loadExtension(array $config, ContainerConfigurator $container, ContainerBuilder $builder): void

Omnireview\Bridge\Twig

OmnireviewExtension class

final class OmnireviewExtension extends AbstractExtension OmnireviewExtension.php:31

Ratings and reviews in a template, always with their origin, date and link - never as JSON-LD:

{{ omnireview_widget('google', place_id) }} {# @Omnireview/reviews.html.twig: override it to dress it #} {% set rating = omnireview_rating('trustpilot', business_unit_id) %} {% for review in omnireview_reviews('tripadvisor', location_id, 3) %}...{% endfor %} <a href="{{ omnireview_write_url('google', place_id) }}">Leave a review</a>

Kept in the application's cache (symfony/cache-contracts) no longer than the platform allows (Terms::$cacheFor): not at all for Google and Tripadvisor, a day for Trustpilot. A platform that does not answer shows nothing rather than an error.

OmnireviewExtension::__construct()

public function __construct(readonly Registry $registry, readonly ?CacheInterface $cache = null, readonly int $ttl = 3600)

OmnireviewExtension::getFunctions()

public function getFunctions(): array

OmnireviewExtension::rating()

public function rating(string $gateway, Place|string $place): ?Rating

OmnireviewExtension::reviews()

public function reviews(string $gateway, Place|string $place, int $limit = 5, ?string $language = null): array

OmnireviewExtension::terms()

public function terms(string $gateway): Terms

OmnireviewExtension::writeUrl()

public function writeUrl(string $gateway, Place|string $place): ?string

null when the platform, which Tripadvisor and Trustpilot ask for the link, does not answer.

OmnireviewExtension::widget()

public function widget(Environment $twig, string $gateway, Place|string $place, int $limit = 3, ?string $language = null): string

Omnireview\Exception

InvalidConfigException class

final class InvalidConfigException extends LogicException implements OmnireviewException InvalidConfigException.php:6

A gateway misconfigured: an option missing, an unknown factory, a submission without what the provider needs.

InvalidKeyException class

final class InvalidKeyException extends ProviderException InvalidKeyException.php:9

The platform refused the site's key, token or account: the configuration is wrong, or the access was never granted (a Business Profile's owner).

NotSupportedException class

final class NotSupportedException extends LogicException implements OmnireviewException NotSupportedException.php:12

The gateway does not do that: no reply on Tripadvisor's Content API, no invitation without a business account. Its Capabilities say so beforehand.

NotSupportedException::question()

public static function question(GatewayInterface $gateway, string $name, string $question): self

NotSupportedException::operation()

public static function operation(string $gateway, string $operation, string $why = ''): self

OmnireviewException interface

interface OmnireviewException extends Throwable OmnireviewException.php:6

Every exception Omnireview throws.

ProviderException class

class ProviderException extends RuntimeException implements OmnireviewException ProviderException.php:9

The platform answered with an error rather than what was asked: a place it does not know, a request it could not read.

public readonly string $provider

public readonly ?string $providerCode

The provider's own error code, when it gave one

ProviderException::__construct()

public function __construct(public readonly string $provider, string $message, public readonly ?string $providerCode = null, ?\Throwable $previous = null)

UnreachableException class

final class UnreachableException extends ProviderException UnreachableException.php:10

The platform did not answer: no connection, a timeout, a server error, a quota exceeded. Show nothing rather than something stale beyond what the platform allows.

Omnireview\Http

Answer class

final readonly class Answer Answer.php:21

A provider's answer, read whole: its status, headers (lower-case names) and body. send() is the one place the family's gateways call through: no connection, a timeout, a server error or a quota exceeded is an UnreachableException - the provider said nothing about the request - and anything else comes back for the gateway to read. The request's secrets stay out of what it throws: the HTTP client's message with the key's parameters masked (Redaction::text(), api_key=***), its exception wrapped as a copy (Redaction::copy()), no trace keeping the arguments where the options stood.

public int $status

public array $headers

public string $body

Answer::__construct()

public function __construct(public int $status, public array $headers, public string $body, string $provider)

Answer::send()

public static function send(HttpClientInterface $http, string $provider, string $method, string $url, array $options = []): self

$options

the HTTP client's options: body, json, query, headers, timeout

Answer::header()

public function header(string $name): ?string

Answer::json()

public function json(): array

The body as a JSON object.

Redaction class

final class Redaction Redaction.php:22

What a failed call may carry of its credentials, taken out before the failure leaves the package: an HTTP client's exception quotes the URL called (a key in its query, a password in its user part), and every exception's trace keeps the arguments of the calls under it (the request options, headers and query with the key) unless PHP runs with zend.exception_ignore_args.

copy() gives the previous exception to wrap instead of the client's own: the same class and code, its message with the key's parameters, the user part and every secret value replaced by ***, its trace without arguments, its own previous copied the same way. Properties of the client's class beyond those of \Exception are not copied (a Symfony HttpException's response, a PSR-18 exception's request: their URL holds the key). withoutArguments() takes the arguments out of the trace of the exception thrown in its place.

const MASK = '***'

Redaction::secrets()

public static function secrets(string $url, array $options = []): array

The secrets a request carries: the values of its query parameters, headers and body fields named as credentials (key, token, secret, password, signature, auth...), a bearer token, a basic password, the URL's user part.

$options

the HTTP client's options

Redaction::sensitive()

public static function sensitive(string $name): bool

Whether a parameter, header or field of this name holds a credential.

Redaction::text()

public static function text(string $text, array $secrets = []): string

A text without credentials: in every address, the user part and the parameters named as credentials masked (api_key=***); then every secret given, raw or URL-encoded, masked wherever it stands.

Redaction::copy()

public static function copy(\Throwable $failure, array $secrets = []): \Throwable

A copy of a failure to wrap in its place: its class, code, file and line, its message through text(), its trace without arguments, its previous copied the same way.

Redaction::withoutArguments()

public static function withoutArguments(\Throwable $failure): \Throwable

The failure given, the arguments out of its trace (and out of its previous ones'), as zend.exception_ignore_args would have left it.

Omnireview\Model

Capabilities class

final readonly class Capabilities Capabilities.php:6

What a gateway gives: the interfaces it implements, as configured (a reply needs the owner's access).

public bool $rating

public bool $reviews

public bool $reply

public bool $invite

public bool $writeUrl

Capabilities::__construct()

public function __construct(public bool $rating = false, public bool $reviews = false, public bool $reply = false, public bool $invite = false, public bool $writeUrl = false)

Capabilities::gives()

public function gives(): array

Capabilities::toArray()

public function toArray(): array

Invitation class

final readonly class Invitation Invitation.php:6

A customer to invite: their e-mail and name, what they bought (a reference), when and in which language to ask.

public string $email

public string $name

public ?string $reference

public string $locale

public ?\DateTimeImmutable $sendAt

public ?string $redirectUrl

Invitation::__construct()

public function __construct(public string $email, public string $name, public ?string $reference = null, public string $locale = 'fr-FR', public ?\DateTimeImmutable $sendAt = null, public ?string $redirectUrl = null)

Place class

final readonly class Place Place.php:10

The establishment on one platform: its identifier there - a Google place ID, a Tripadvisor location ID, a Trustpilot business unit ID -, kept by the application (every platform allows keeping it).

public string $id

the platform's identifier

public ?string $name

public ?string $owner

a second identifier the owner's side of the platform needs: Google Business Profile's "accounts/<a>/locations/<l>"

Place::__construct()

public function __construct(public string $id, public ?string $name = null, public ?string $owner = null)

$id

the platform's identifier

$owner

a second identifier the owner's side of the platform needs: Google Business Profile's "accounts/<a>/locations/<l>"

Rating class

final readonly class Rating Rating.php:6

A rating as the platform gives it, with what showing it requires.

public string $platform

public float $value

the score, on the platform's scale

public int $count

the reviews, or ratings, it rests on

public int $scale

the scale's top: 5

public ?string $url

the establishment's page on the platform: link it

public ?string $image

the platform's own picture of the score (Tripadvisor's bubbles), to show as it is, from its address

public \DateTimeImmutable $fetchedAt

Rating::__construct()

public function __construct(public string $platform, public float $value, public int $count, public int $scale = 5, public ?string $url = null, public ?string $image = null, public \DateTimeImmutable $fetchedAt = new \DateTimeImmutable())

$value

the score, on the platform's scale

$scale

the scale's top: 5

$count

the reviews, or ratings, it rests on

$url

the establishment's page on the platform: link it

$image

the platform's own picture of the score (Tripadvisor's bubbles), to show as it is, from its address

Rating::outOfFive()

public function outOfFive(): float

The score on 5, rounded to a tenth.

Reply class

final readonly class Reply Reply.php:6

The establishment's answer to a review.

public string $text

public ?\DateTimeImmutable $at

Reply::__construct()

public function __construct(public string $text, public ?\DateTimeImmutable $at = null)

Review class

final readonly class Review Review.php:9

One review, with what showing it requires: its author as the platform names them, its date, the link to it on the platform.

public string $platform

public string $id

the platform's identifier: what a reply needs

public float $rating

on the platform's scale

public ?string $text

public ?string $title

public ?string $language

public ?string $author

public ?string $authorUrl

public ?string $authorPhoto

public ?\DateTimeImmutable $publishedAt

public ?string $url

the review on the platform, or the establishment's page: link it

public ?Reply $reply

public int $scale

public bool $translated

the text is the platform's translation

public ?string $image

Review::__construct()

public function __construct(public string $platform, public string $id, public float $rating, public ?string $text = null, public ?string $title = null, public ?string $language = null, public ?string $author = null, public ?string $authorUrl = null, public ?string $authorPhoto = null, public ?\DateTimeImmutable $publishedAt = null, public ?string $url = null, public ?Reply $reply = null, public int $scale = 5, public bool $translated = false, public ?string $image = null)

$id

the platform's identifier: what a reply needs

$rating

on the platform's scale

$url

the review on the platform, or the establishment's page: link it

$translated

the text is the platform's translation

Terms class

final readonly class Terms Terms.php:10

How what a platform gives may be shown and kept - its own rules, read in its documentation and declared by its package. The family's display follows them; an application that shows things its own way must too.

public ?int $cacheFor

seconds what it gives may be kept before asking again: 0 never, null "as the platform's caching policy allows" (not published)

public ?int $maxReviews

the reviews one call gives at most

public string $attribution

what must be shown with it: the platform's name or logo

public bool $authors

each review shown with its author as the platform names them

public bool $link

a link back to the platform shown with it

public bool $noIndex

pages that show it are kept out of search engines

public array $rules

the other rules, in words

public ?string $source

where they are written

Terms::__construct()

public function __construct(public ?int $cacheFor = 0, public ?int $maxReviews = null, public string $attribution = '', public bool $authors = true, public bool $link = true, public bool $noIndex = false, public array $rules = [], public ?string $source = null)

$cacheFor

seconds what it gives may be kept before asking again: 0 never, null "as the platform's caching policy allows" (not published)

$maxReviews

the reviews one call gives at most

$attribution

what must be shown with it: the platform's name or logo

$authors

each review shown with its author as the platform names them

$link

a link back to the platform shown with it

$noIndex

pages that show it are kept out of search engines

$rules

the other rules, in words

$source

where they are written

Terms::allowsCaching()

public function allowsCaching(int $seconds): bool

Whether it may be kept $seconds.