omnisense/omnifund API reference

Omnifund

Capabilities class

final readonly class Capabilities Capabilities.php:6

What a provider can be asked, said before it is asked anything, and whose terms apply.

public bool $profile

the account's profile (ProfileInterface)

public bool $sponsors

its public sponsors (SponsorsInterface)

public bool $tiers

the tiers it offers (TiersInterface)

public bool $key

whether a key or token is needed to read it

public array $terms

the terms whoever runs it must follow (URLs)

Capabilities::__construct()

public function __construct(public bool $profile = false, public bool $sponsors = false, public bool $tiers = false, public bool $key = false, public array $terms = [])

$profile

the account's profile (ProfileInterface)

$sponsors

its public sponsors (SponsorsInterface)

$tiers

the tiers it offers (TiersInterface)

$key

whether a key or token is needed to read it

$terms

the terms whoever runs it must follow (URLs)

Capabilities::contracts()

public function contracts(): array

Returns

what it can be asked, by contract: profile, sponsors, tiers

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".

ProfileInterface interface

interface ProfileInterface extends ProviderInterface ProfileInterface.php:8

The account as it shows itself: name, page, how many fund it, what it receives, its goal.

ProfileInterface::profile()

public function profile(?string $account = null): Profile

$account

another account than the configured one

ProviderFactory class

abstract class ProviderFactory implements ProviderFactoryInterface ProviderFactory.php:15

A provider's factory fills a Config - its name ("omnifund.factory_name"), its title ("omnifund.factory_title"), the options it needs ("omnifund.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 (an account, a token...).

ProviderFactoryInterface::getName()

public function getName(): string

The name providers are configured with: "github-sponsors", "liberapay".

..

ProviderFactoryInterface::create()

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

ProviderInterface interface

interface ProviderInterface ProviderInterface.php:12

One funding platform, configured for an account: GitHub Sponsors, Open Collective, Liberapay... Its Capabilities say what it can be asked - the account's profile (ProfileInterface), its public sponsors (SponsorsInterface), the tiers it offers (TiersInterface) - and whose terms apply.

ProviderInterface::getName()

public function getName(): string

The factory's name: "github-sponsors", "opencollective", "liberapay".

..

ProviderInterface::getTitle()

public function getTitle(): string

ProviderInterface::capabilities()

public function capabilities(): Capabilities

Registry class

final class Registry Registry.php:20

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

$registry = new Registry([new GitHubSponsorsFactory($http), new LiberapayFactory($http)], [ 'github' => ['factory' => 'github-sponsors', 'options' => ['account' => 'glitchr-studio', 'token' => '...']], 'liberapay' => ['factory' => 'liberapay', 'options' => ['account' => 'Liberapay']], ]);

$registry->profile('liberapay')->profile()->sponsors; $registry->sponsors('github')->sponsors();

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::profile()

public function profile(string $name): ProfileInterface

The provider, as the account's profile.

Registry::sponsors()

public function sponsors(string $name): SponsorsInterface

The provider, as the account's public sponsors.

Registry::tiers()

public function tiers(string $name): TiersInterface

The provider, as the tiers the account offers.

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

SponsorsInterface interface

interface SponsorsInterface extends ProviderInterface SponsorsInterface.php:8

Who funds the account, as far as the platform shows them publicly.

SponsorsInterface::sponsors()

public function sponsors(?string $account = null, ?int $limit = null): array

$account

another account than the configured one

$limit

at most this many; null: every one, page after page

TiersInterface interface

interface TiersInterface extends ProviderInterface TiersInterface.php:8

The ways to give the account offers.

TiersInterface::tiers()

public function tiers(?string $account = null): array

$account

another account than the configured one

Omnifund\Exception

InvalidConfigException class

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

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

NotSupportedException class

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

A provider asked for what it cannot give: the sponsors of a platform that keeps them private.

NotSupportedException::capability()

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

OmnifundException interface

interface OmnifundException extends Throwable OmnifundException.php:6

Every exception omnifund throws.

ProviderException class

final class ProviderException extends RuntimeException implements OmnifundException ProviderException.php:6

The provider answered, and not with what was asked: an error status, an error in a GraphQL answer, no such account.

ProviderException::answered()

public static function answered(string $provider, string $what, int|string $status): self

UnreachableException class

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

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

Omnifund\Http

Json class

final class Json Json.php:15

A JSON request on the application's HTTP client, its failures turned into omnifund's exceptions; and typed reads of what came back, for providers that walk an answer they do not control.

Json::request()

public static function request(HttpClientInterface $http, string $method, string $url, array $options, string $provider, string $what): array

$options

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

Returns

the decoded answer

Json::get()

public static function get(mixed $data, string|int ...$path): mixed

The value at a path of keys; null when any step is missing.

Json::string()

public static function string(mixed $data, string|int ...$path): ?string

A non-empty string at the path, or null.

Json::int()

public static function int(mixed $data, string|int ...$path): ?int

Json::bool()

public static function bool(mixed $data, string|int ...$path): bool

Json::list()

public static function list(mixed $data, string|int ...$path): array

Returns

the list at the path; empty when there is none

Json::date()

public static function date(mixed $data, string|int ...$path): ?\DateTimeImmutable

A date at the path, or null.

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.

Omnifund\Model

Goal class

final readonly class Goal Goal.php:10

What an account says it aims for: an amount (Liberapay, GitHub's MONTHLY_SPONSORSHIP_AMOUNT) or a number of sponsors (GitHub's TOTAL_SPONSORS_COUNT), and how far it has got when the provider says.

public ?string $title

public ?string $description

public ?Money $amount

public ?Period $period

public ?int $sponsors

public ?int $percent

Goal::__construct()

public function __construct(public ?string $title = null, public ?string $description = null, public ?Money $amount = null, public ?Period $period = null, public ?int $sponsors = null, public ?int $percent = null)

Goal::toArray()

public function toArray(): array

Income class

final readonly class Income Income.php:6

What an account receives, every period: Liberapay counts it by the week, GitHub by the month.

public Money $amount

public Period $period

Income::__construct()

public function __construct(public Money $amount, public Period $period)

Income::monthly()

public function monthly(): ?Money

The same income by the month (a week is 52/12 of a month); null for a one-time amount.

Income::toArray()

public function toArray(): array

Money class

final readonly class Money Money.php:12

An amount in hundredths of its currency's unit, as the providers count it (GitHub's monthlyPriceInCents, Open Collective's valueInCents, Liberapay's "636.28"), and its ISO 4217 currency.

public string $currency

public int $cents

Money::__construct()

public function __construct(public int $cents, string $currency)

Money::fromDecimal()

public static function fromDecimal(string|int|float $amount, string $currency): self

From a decimal amount: "636.28", 636.28, 5.

Money::decimal()

public function decimal(): string

"636.28"

Money::multiply()

public function multiply(float $factor): self

Money::toArray()

public function toArray(): array

Period enum

enum Period Period.php:6

How often an amount is given: once, or every week, month, year.

case Once = 'once'

case Week = 'week'

case Month = 'month'

case Year = 'year'

Period::perMonth()

public function perMonth(): ?float

How many of this period make a month (52 weeks a year); null for a one-time amount.

Profile class

final readonly class Profile Profile.php:10

An account where funding is received, as it shows itself: its name and page, how many fund it, what it receives and what it aims for - each null when the provider does not say.

public string $provider

public string $handle

public ?string $name

public ?string $description

public ?string $url

public ?string $avatarUrl

public ?int $sponsors

public ?Income $income

public ?Goal $goal

Profile::__construct()

public function __construct(public string $provider, public string $handle, public ?string $name = null, public ?string $description = null, public ?string $url = null, public ?string $avatarUrl = null, public ?int $sponsors = null, public ?Income $income = null, public ?Goal $goal = null)

Profile::toArray()

public function toArray(): array

Sponsor class

final readonly class Sponsor Sponsor.php:10

Someone who funds the account, as the provider shows them publicly: a handle, a name, a picture, a page; their tier, since when and how much when the provider says.

const USER = 'user'

const ORGANIZATION = 'organization'

const OTHER = 'other'

public string $handle

public ?string $name

public ?string $avatarUrl

public ?string $url

public string $kind

public ?\DateTimeImmutable $since

public ?string $tier

public ?Money $total

Sponsor::__construct()

public function __construct(public string $handle, public ?string $name = null, public ?string $avatarUrl = null, public ?string $url = null, public string $kind = self::USER, public ?\DateTimeImmutable $since = null, public ?string $tier = null, public ?Money $total = null)

Sponsor::label()

public function label(): string

The name shown: the name, or the handle.

Sponsor::toArray()

public function toArray(): array

Tier class

final readonly class Tier Tier.php:6

One way to give that an account offers: "$5 a month", "Backer", a custom amount.

public string $name

public ?Money $price

public Period $period

public ?string $id

public ?string $description

public bool $customAmount

public ?Money $minimum

Tier::__construct()

public function __construct(public string $name, public ?Money $price = null, public Period $period = Period::Month, public ?string $id = null, public ?string $description = null, public bool $customAmount = false, public ?Money $minimum = null)

Tier::toArray()

public function toArray(): array

Omnifund\Testing

ArrayFactory class

final class ArrayFactory extends ProviderFactory ArrayFactory.php:20

ArrayProvider, from its options:

profile a Model\Profile (required) sponsors a list of Model\Sponsor tiers a list of Model\Tier

Options

ArrayProvider class

final class ArrayProvider implements ProfileInterface, SponsorsInterface, TiersInterface ArrayProvider.php:14

A provider that answers what it was given: for tests, demos and an application's fixtures.

ArrayProvider::__construct()

public function __construct(readonly Profile $profile, readonly array $sponsors = [], readonly array $tiers = [])

ArrayProvider::getName()

public function getName(): string

ArrayProvider::getTitle()

public function getTitle(): string

ArrayProvider::capabilities()

public function capabilities(): Capabilities

ArrayProvider::profile()

public function profile(?string $account = null): Profile

ArrayProvider::sponsors()

public function sponsors(?string $account = null, ?int $limit = null): array

ArrayProvider::tiers()

public function tiers(?string $account = null): array