omnisense/omnireach API reference

Omnireach

AudienceInterface interface

interface AudienceInterface extends ProviderInterface AudienceInterface.php:12

Who visits the site, as an analytics tool counted it: visitors, visits, pages viewed, by entry page, page, source, country, device or day.

AudienceInterface::audience()

public function audience(ReachQuery $query): Report

Metrics by default: visitors, visits, pageviews.

Throws

Exception\NotSupportedException for a dimension, filter or metric it does not report

Capabilities class

final readonly class Capabilities Capabilities.php:15

What a provider is, said before it is asked anything: which reports, by which dimensions and metrics, and the terms and limits whoever runs it must keep.

public bool $searchPerformance

it reports search queries, pages and positions (SearchPerformanceInterface)

public bool $audience

it reports visits, entry pages and sources (AudienceInterface)

public array $dimensions

the dimensions it breaks a report down by

public array $metrics

the metrics it counts

public bool $combined

dimensions can be combined; false: one at a time, besides the date

public array $terms

the terms whoever runs it must follow (URLs)

public array $limits

the rate limits, quotas and freshness the provider states, in words

Capabilities::__construct()

public function __construct(public bool $searchPerformance = false, public bool $audience = false, public array $dimensions = [], public array $metrics = [], public bool $combined = true, public array $terms = [], public array $limits = [])

$searchPerformance

it reports search queries, pages and positions (SearchPerformanceInterface)

$audience

it reports visits, entry pages and sources (AudienceInterface)

$dimensions

the dimensions it breaks a report down by

$metrics

the metrics it counts

$combined

dimensions can be combined; false: one at a time, besides the date

$terms

the terms whoever runs it must follow (URLs)

$limits

the rate limits, quotas and freshness the provider states, in words

Capabilities::contracts()

public function contracts(): array

Returns

what it can be asked, by contract: searchPerformance, audience

Capabilities::check()

public function check(ReachQuery $query, array $metrics, string $provider): void

Throws when the query asks for a dimension, a filter or a metric the provider does not report, or combines dimensions it cannot.

$metrics

the metrics the report will count (the query's or the defaults)

Capabilities::toArray()

public function toArray(): array

Config class

final class Config extends ArrayObject Config.php:14

A provider'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::int()

public function int(string $key, int $default = 0): int

Config::float()

public function float(string $key, float $default = 0.0): float

Config::bool()

public function bool(string $key): bool

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

ProviderFactory class

abstract class ProviderFactory implements ProviderFactoryInterface ProviderFactory.php:15

A provider's factory fills a Config - its name ("omnireach.factory_name"), its title ("omnireach.factory_title"), the options it needs ("omnireach.required_options") and the defaults of the others - then builds the provider 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.

ProviderFactory::getName()

public function getName(): string

ProviderFactory::create()

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

ProviderFactory::createConfig()

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

ProviderFactoryInterface interface

interface ProviderFactoryInterface ProviderFactoryInterface.php:6

Builds a provider from its options (a key, a site, a server URL...).

ProviderFactoryInterface::getName()

public function getName(): string

The name providers are configured with: "search-console", "matomo".

..

ProviderFactoryInterface::create()

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

ProviderInterface interface

interface ProviderInterface ProviderInterface.php:11

One outside tool that knows the site's audience, configured: Search Console, Bing Webmaster Tools, Matomo, Plausible, Google Analytics... Its Capabilities say what it can be asked - how the site shows in search results (SearchPerformanceInterface), who visits it (AudienceInterface).

ProviderInterface::getName()

public function getName(): string

The factory's name: "search-console", "matomo".

..

ProviderInterface::getTitle()

public function getTitle(): string

ProviderInterface::capabilities()

public function capabilities(): Capabilities

Registry class

final class Registry Registry.php:20

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

$registry = new Registry([new SearchConsoleFactory($http), new MatomoFactory($http)], [ 'google' => ['factory' => 'search-console', 'options' => ['site' => 'sc-domain:example.org', 'credentials' => '...']], 'stats' => ['factory' => 'matomo', 'options' => ['url' => 'https://stats.example.org', 'site' => '1', 'token' => '...']], ]);

$registry->search('google')->searchPerformance(ReachQuery::lastDays(28, [Dimension::Query])); $registry->audience('stats')->audience(ReachQuery::lastDays(28, [Dimension::EntryPage]));

Registry::__construct()

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

Registry::get()

public function get(string $name): ProviderInterface

Registry::has()

public function has(string $name): bool

Registry::search()

public function search(string $name): SearchPerformanceInterface

The provider, as a search engine's report.

Registry::audience()

public function audience(string $name): AudienceInterface

The provider, as an analytics report.

Registry::options()

public function options(string $name): array

Returns

the options a provider is configured with

Registry::names()

public function names(): array

Returns

the configured providers' names

Registry::factories()

public function factories(): array

Returns

the factories installed: what factory: may name

SearchPerformanceInterface interface

interface SearchPerformanceInterface extends ProviderInterface SearchPerformanceInterface.php:12

How the site shows in a search engine: the queries it appears for, its pages shown, clicks, impressions, CTR and average position.

SearchPerformanceInterface::searchPerformance()

public function searchPerformance(ReachQuery $query): Report

Metrics by default: clicks, impressions, CTR, position.

Throws

Exception\NotSupportedException for a dimension, filter or metric it does not report

Omnireach\Exception

InvalidArgumentException class

final class InvalidArgumentException extends InvalidArgumentException implements OmnireachException InvalidArgumentException.php:6

A query no report can answer: a period that ends before it starts, a limit below 1.

InvalidConfigException class

final class InvalidConfigException extends InvalidArgumentException implements OmnireachException InvalidConfigException.php:6

A provider asked for with options it cannot work with, or not configured at all.

InvalidKeyException class

final class InvalidKeyException extends ProviderException InvalidKeyException.php:6

The provider refused the credentials (401, 403): a wrong or revoked key, a token past its time, a scope not granted.

InvalidKeyException::refused()

public static function refused(string $provider, string $what, int $status, ?string $message = null): self

NotFoundException class

final class NotFoundException extends ProviderException NotFoundException.php:6

The provider has nothing under that identifier (404): a site or a property that does not exist or is not this account's.

NotFoundException::of()

public static function of(string $provider, string $what, ?string $message = null): self

NotSupportedException class

final class NotSupportedException extends LogicException implements OmnireachException NotSupportedException.php:6

A provider asked for what it cannot do: a dimension it does not report, search queries from an analytics tool.

NotSupportedException::capability()

public static function capability(object $provider, string $name, string $capability): self

OmnireachException interface

interface OmnireachException extends Throwable OmnireachException.php:6

Every exception omnireach throws.

ProviderException class

class ProviderException extends RuntimeException implements OmnireachException ProviderException.php:6

The provider answered, and not with what was asked: an error status, an answer that is not JSON.

ProviderException::answered()

public static function answered(string $provider, string $what, int $status, ?string $message = null): self

UnreachableException class

final class UnreachableException extends RuntimeException implements OmnireachException UnreachableException.php:6

The provider could not be reached: a network error, a timeout.

Omnireach\Http

JsonApi class

final class JsonApi JsonApi.php:29

A JSON API called through the application's HTTP client (Symfony's contracts: its own client, or a MockHttpClient in a test), the answer turned into Data and every failure into one of omnireach's exceptions: not reached (UnreachableException), the key refused (401, 403: InvalidKeyException), nothing there (404: NotFoundException), any other error or an answer that is not JSON (ProviderException) - with the provider's own message when it gives one.

An UnreachableException's message names the method and the path, and the HTTP client's reason without the address it quotes: never the query, where a key may travel (Bing's apikey). Its previous exception is a copy of the client's (Redaction::copy(): same class and code, the key masked in its message), and neither keeps its trace's arguments, where the request's query and headers stood.

JsonApi::__construct()

public function __construct(readonly HttpClientInterface $http, readonly string $provider)

JsonApi::request()

public function request(string $method, string $url, array $options = [], string $what = 'the request'): Data

$options

the HTTP client's options (query, headers, json, body, auth_bearer...)

JsonApi::reason()

public static function reason(string $message): string

An HTTP client's message without the addresses it quotes: Symfony's ' for "<url>"' dropped, any other address cut to its scheme, host and path (no credentials, no query, no fragment).

JsonApi::message()

public static function message(Data $answer): ?string

The error message an answer carries, under the names APIs give it.

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.

Omnireach\Model

Dimension enum

enum Dimension Dimension.php:6

What a report's rows are broken down by, in the words every provider is mapped to.

case Query = 'query'

The search query typed (search engines only).

case Page = 'page'

A page: shown in search results (search engines), or viewed (analytics).

case EntryPage = 'entry_page'

The page a visit started on: the landing page (analytics only).

case Country = 'country'

The visitor's country, as the provider gives it (ISO 3166-1 alpha-2 upper case, alpha-3 for Search Console).

case Device = 'device'

desktop, mobile, tablet.

case Source = 'source'

Where a visit came from: a search engine, a site, "direct" (analytics only).

case Date = 'date'

The day, Y-m-d: a period's history.

Metric enum

enum Metric Metric.php:6

What a report counts.

case Clicks = 'clicks'

Clicks from search results to the site.

case Impressions = 'impressions'

Times the site was shown in search results.

case Ctr = 'ctr'

Clicks per impression, a ratio from 0 to 1.

case Position = 'position'

The average position in search results, 1 the first.

case Visitors = 'visitors'

Distinct visitors (users).

case Visits = 'visits'

Visits (sessions).

case Pageviews = 'pageviews'

Pages viewed.

case BounceRate = 'bounce_rate'

Visits of one page only, a ratio from 0 to 1.

case VisitDuration = 'visit_duration'

The average length of a visit, in seconds.

Metric::isSearch()

public function isSearch(): bool

Whether it is a search engine's figure (clicks, impressions, CTR, position).

Metric::isAdditive()

public function isAdditive(): bool

Whether rows' values add up to the total (a sum of averages or of distinct counts does not).

ReachQuery class

final readonly class ReachQuery ReachQuery.php:13

What a report is asked for: a period (whole days, both included), the dimensions to break it down by, the metrics, exact filters on dimensions, at most how many rows - and the site, when it is not the one the provider is configured with.

public \DateTimeImmutable $start

public \DateTimeImmutable $end

public array $dimensions

public array $metrics

none: the provider's defaults for the report asked

public array $filters

by Dimension value: rows whose dimension is exactly that value

public int $limit

public ?string $site

ReachQuery::__construct()

public function __construct(\DateTimeImmutable $start, \DateTimeImmutable $end, public array $dimensions = [], public array $metrics = [], public array $filters = [], public int $limit = 1000, public ?string $site = null)

$metrics

none: the provider's defaults for the report asked

$filters

by Dimension value: rows whose dimension is exactly that value

ReachQuery::lastDays()

public static function lastDays(int $days, array $dimensions = [], array $metrics = [], ?\DateTimeImmutable $today = null): self

The last $days whole days, yesterday the last (today's figures are not complete anywhere).

ReachQuery::has()

public function has(Dimension $dimension): bool

ReachQuery::filter()

public function filter(Dimension $dimension): ?string

ReachQuery::metricsOr()

public function metricsOr(array $defaults): array

ReachQuery::breakdown()

public function breakdown(): array

Returns

the dimensions but the date

ReachQuery::apply()

public function apply(iterable $rows): array

The query's filters and limit applied to rows: what a provider that cannot filter (or not on everything) returns through it, so a query means the same everywhere.

Report class

final readonly class Report Report.php:6

A provider's answer to a ReachQuery: its rows, and what to know about them.

public string $provider

public string $site

public ReachQuery $query

public array $rows

public ?string $note

what the figures are not: sampled, rounded, a week behind...

Report::__construct()

public function __construct(public string $provider, public string $site, public ReachQuery $query, public array $rows, public ?string $note = null)

$note

what the figures are not: sampled, rounded, a week behind...

Report::totals()

public function totals(): array

Returns

the sums of the metrics that add up (clicks, impressions, visits, pageviews)

Report::toArray()

public function toArray(): array

Row class

final readonly class Row Row.php:6

One line of a report: its dimensions' values and its metrics.

public array $dimensions

by Dimension value

public array $metrics

by Metric value

Row::__construct()

public function __construct(public array $dimensions, public array $metrics)

$dimensions

by Dimension value

$metrics

by Metric value

Row::dimension()

public function dimension(Dimension $dimension): ?string

Row::metric()

public function metric(Metric $metric): int|float|null

Row::toArray()

public function toArray(): array

Omnireach\Support

Data class

final class Data Data.php:10

A decoded JSON answer, read with types: a provider asks for the string, the number, the date or the list it expects at a dotted path, and gets null (or an empty list) when the answer holds something else.

public readonly array $values

Data::__construct()

public function __construct(public readonly array $values = [])

Data::of()

public static function of(mixed $value): self

Data::raw()

public function raw(string $path): mixed

The value at a dotted path ("venue.city.name"), as it is.

Data::has()

public function has(string $path): bool

Data::string()

public function string(string $path): ?string

A string; null when absent or empty.

Data::int()

public function int(string $path): ?int

Data::float()

public function float(string $path): ?float

Data::bool()

public function bool(string $path): bool

true, 1, "1", "true", "yes".

Data::date()

public function date(string $path, ?\DateTimeZone $timezone = null): ?\DateTimeImmutable

A date: a UNIX timestamp, or a string PHP reads ("2026-11-14 20:00:00", ISO 8601), in $timezone when it names none. Null when absent, empty, unreadable or "0000-00-00...".

Data::data()

public function data(string $path): self

The object at a path; an empty one when absent.

Data::list()

public function list(string $path): array

Returns

the items of the list (or object) at a path

Data::items()

public function items(): array

Returns

the items of this value itself, when it is a list

Omnireach\Testing

FixedReach class

final class FixedReach implements SearchPerformanceInterface, AudienceInterface FixedReach.php:19

A provider that answers from rows it was given: an application's tests, a demo, the harness's bare script. Both reports, no network; the rows given are filtered, cut and projected on the query's dimensions.

FixedReach::__construct()

public function __construct(readonly array $search = [], readonly array $audience = [], readonly string $site = 'https://example.org/')

$search

search engine rows

$audience

analytics rows

FixedReach::getName()

public function getName(): string

FixedReach::getTitle()

public function getTitle(): string

FixedReach::capabilities()

public function capabilities(): Capabilities

FixedReach::searchPerformance()

public function searchPerformance(ReachQuery $query): Report

FixedReach::audience()

public function audience(ReachQuery $query): Report

FixedReachFactory class

final class FixedReachFactory extends ProviderFactory FixedReachFactory.php:11

FixedReach under the name "fixed", for a Registry.

FixedReachFactory::__construct()

public function __construct(readonly array $search = [], readonly array $audience = [])

LoadCheck class

final class LoadCheck LoadCheck.php:12

The check every package of the family runs in its BareTest: each class of the package loaded in a PHP process of its own, with the autoloader that knows it, then what came from outside - classes of a framework, an HTTP client or an application, and files of packages it does not require.

const FOREIGN = '~^(?:Symfony\\\\(?!Contracts\\\\HttpClient\\\\|Contracts\\\\Service\\\\|Polyfill\\\\)|(?:Illuminate|Laravel|Doctrine|Twig|League|GuzzleHttp|Nyholm|Http|Omni…

Classes no package of the family may load: a framework, an HTTP client, an application. Symfony's HTTP client contracts are interfaces, allowed.

LoadCheck::run()

public static function run(string $root, string $namespace, string $autoload, array $extra = []): array

$root

the package's directory

$namespace

its namespace, "Omnireach\\Billetweb\\"

$autoload

the autoload.php that knows it

$extra

classes to load besides (the check that it is not blind)

Returns

the files without those Composer includes at start for every package

LoadCheck::foreign()

public static function foreign(array $symbols): array

LoadCheck::outside()

public static function outside(array $files, string $root, array $allowed): array

The files loaded from outside the package and outside the vendor directories allowed.

$allowed

path fragments: "/vendor/psr/", "/vendor/omnisense/omnireach/"...

LoadCheck::autoload()

public static function autoload(string $class, string $test, string $root): ?string

The autoloader that knows a class and the test asking: the package's own or its harness's. Null when the package sits in an application's vendor/ (the application's autoloader loads what it needs at start: the check is the package's own) or when none knows it.

RecordedHttpClient class

final class RecordedHttpClient implements HttpClientInterface RecordedHttpClient.php:15

An HTTP client that answers from what it was given - a callable of the method, the URL and the options, returning [status, body, headers] - and keeps every request made ($requests): a provider's calls checked with no network.

public array $requests = []

RecordedHttpClient::__construct()

public function __construct(readonly \Closure $answer)

RecordedHttpClient::routes()

public static function routes(array $routes): self

Answers by route: "GET /api/v2/query" => the body (status 200) or [status, body] - the first route whose method matches and whose path ends the URL's path; 404 for anything not recorded.

RecordedHttpClient::request()

public function request(string $method, string $url, array $options = []): ResponseInterface

RecordedHttpClient::stream()

public function stream(ResponseInterface|iterable $responses, ?float $timeout = null): ResponseStreamInterface

RecordedHttpClient::withOptions()

public function withOptions(array $options): static

RecordedResponse class

final class RecordedResponse implements ResponseInterface RecordedResponse.php:8

RecordedHttpClient's answer.

RecordedResponse::__construct()

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

RecordedResponse::getStatusCode()

public function getStatusCode(): int

RecordedResponse::getHeaders()

public function getHeaders(bool $throw = true): array

RecordedResponse::getContent()

public function getContent(bool $throw = true): string

RecordedResponse::toArray()

public function toArray(bool $throw = true): array

RecordedResponse::cancel()

public function cancel(): void

RecordedResponse::getInfo()

public function getInfo(?string $type = null): mixed