omnisense/omnistate API reference

Omnistate

Omnistate class

final class Omnistate Omnistate.php:42

What states and registries know, asked of whichever registry installed answers for it: a company by its identifier, a VAT number, a domain, a network. Answers are kept $ttl seconds when a cache is given - registers change slowly, and some count their calls.

$omnistate->company('901821074')?->name; // "GLITCH ART" $omnistate->vat('FR53901821074')->valid; // true $omnistate->domain('glitchr.dev')?->registrar; // Gandi SAS $omnistate->professional('10003461033')?->profession; // Médecin (an RPPS number) $omnistate->facility('670001234')?->name; // a FINESS number $omnistate->civilRecords(new CivilQuery(familyName: 'Chirac', born: Period::year(1932))); // acts and documents about a person

Omnistate::__construct()

public function __construct(iterable $companies = [], iterable $vat = [], readonly ?InternetRegistryInterface $internet = null, readonly ?CacheInterface $cache = null, readonly int $ttl = 86400, readonly ?string $requester = null, iterable $professionals = [], iterable $civil = [])

$professionals

registers of regulated professionals (and their facilities)

$civil

registers of acts and documents about people (births, marriages, deaths, archives)

Omnistate::company()

public function company(string $identifier): ?Company

A company by its identifier: a SIREN, a SIRET (its establishment among its establishments), a French VAT number (its SIREN).

..

Throws

NotSupportedException no registry installed knows that kind of identifier

Omnistate::search()

public function search(string $query, int $limit = 10): array

Returns

from every company registry installed, the first that finds any

Omnistate::vat()

public function vat(string $number, ?string $requester = null): VatCheck

Whether a VAT number exists, and whose. A number no member state writes that way is not valid, without asking anyone.

$requester

your own VAT number, for a consultation number

Throws

NotSupportedException no VAT registry installed answers for its country

Omnistate::professional()

public function professional(string $identifier): ?Professional

A regulated professional by their identifier: an RPPS number (or its IDNPS form, "8" + RPPS).

..

Throws

NotSupportedException no professional registry installed knows that kind of identifier

Omnistate::professionals()

public function professionals(string $name, ?string $postcode = null, int $limit = 10): array

Returns

from every professional registry installed, the first that finds any

Omnistate::facility()

public function facility(string $identifier): ?Facility

A health or social facility by its identifier (a FINESS number), asked of the professional registries that know facilities too.

Throws

NotSupportedException

Omnistate::civilRegistries()

public function civilRegistries(?string $country = null, ?CivilRecordKind $kind = null): array

The civil registers installed, those that hold records of that country (ISO 3166-1 alpha-2) and of that kind when given.

Omnistate::civilRegistry()

public function civilRegistry(string $name): ?CivilRegistryInterface

The civil register of that name, null when it is not installed.

Omnistate::civilCountries()

public function civilCountries(): array

Returns

ISO 3166-1 alpha-2 codes of the countries some civil register installed covers, sorted

Omnistate::civilRecords()

public function civilRecords(CivilQuery $query, ?string $registry = null): array

Acts and documents about a person. Asked of one register when it is named, else of every register installed the question is one for - their answers one after the other, in the order the registers were given.

A register that does not answer throws: asking them all, one that is down takes the others' answers with it. A screen that must keep what the others found asks them one by one (civilRegistries(), then this with each name).

Throws

NotSupportedException no civil registry installed takes that question

Throws

Omnistate\Exception\UnavailableException a register did not answer

Omnistate::civilRecord()

public function civilRecord(string $registry, string $identifier): ?CivilRecord

A civil record found again: the register's name (CivilRecord::$source) and its identifier there (CivilRecord::$identifier). Often more complete than the line a search gave: everyone named in the act, its pictures.

Throws

NotSupportedException that register is not installed

Omnistate::domain()

public function domain(string $name): ?Domain

Omnistate::network()

public function network(string $address): ?Network

An IP address's range, or an AS number's.

Omnistate\Bridge\Symfony

CompanySearch class

final class CompanySearch CompanySearch.php:16

Companies found by name (or number), as the search field and its endpoint hand them out: one flat row each, with what a form may fill - the SIREN, the head office's SIRET and address, and the French intra-EU VAT number derived from the SIREN (VIES still has the last word on it).

const MIN_LENGTH = 3

const MAX_RESULTS = 25

CompanySearch::__construct()

public function __construct(readonly Omnistate $omnistate)

CompanySearch::search()

public function search(string $query, int $limit = 10): array

Throws

OmnistateException when no registry answers

CompanySearch::row()

public static function row(Company $company): array

OmnistateBundle class

final class OmnistateBundle extends AbstractBundle OmnistateBundle.php:62

Omnistate in a Symfony application: Omnistate\Omnistate autowired, every registry package installed (omnistate/vies, omnistate/annuaire-entreprises, omnistate/iana) registered, answers kept in a cache pool, and the #[Siren], #[Siret] and #[VatNumber] constraints, and the company search: CompanySearchType (a form field that fills its siblings from the company picked) asking CompanySearchController (GET /omnistate/company/search, routed by importing Bridge/Symfony/Controller/ as attributes).

omnistate: cache: cache.app # null: every call asks the registry ttl: 86400 timeout: 10 requester: FR53901821074 # your VAT number: VIES answers a consultation number annuaire_sante: api_key: '%env(ESANTE_API_KEY)%' # omnistate/annuaire-sante: health professionals (RPPS) and facilities (FINESS)

matchid:
    token: '%env(MATCHID_TOKEN)%'      # omnistate/matchid: optional, a higher quota

nara:
    api_key: '%env(NARA_API_KEY)%'     # omnistate/nara: the US National Archives Catalog, 10,000 calls a month

Civil registers (omnistate/matchid, omnistate/openarchieven, omnistate/national-archives-uk, omnistate/nara) are registered when installed and tagged omnistate.civil_registry.

An application's own registries (a CompanyRegistryInterface...) are asked too, autoconfigured.

OmnistateBundle::getPath()

public function getPath(): string

This directory: its templates/ are @Omnistate (the default is two levels up).

OmnistateBundle::prependExtension()

public function prependExtension(ContainerConfigurator $container, ContainerBuilder $builder): void

The company search field's widget, in every form theme.

OmnistateBundle::configure()

public function configure(DefinitionConfigurator $definition): void

OmnistateBundle::loadExtension()

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

Omnistate\Bridge\Symfony\Controller

CompanySearchController class

class CompanySearchController CompanySearchController.php:19

GET /omnistate/company/search?q=la touche originale[&limit=10]: {results: [...]} (CompanySearch::row()), 503 when no registry answers.

What the company search field asks; answers are kept by Omnistate's cache.

Routed by importing the directory (type: attribute), or by a subclass in a directory already imported - base-bundle-market does, so every shop has it.

CompanySearchController::__construct()

public function __construct(readonly CompanySearch $companies)

CompanySearchController::__invoke()

public function __invoke(Request $request): JsonResponse

Omnistate\Bridge\Symfony\Form

CompanySearchType class

final class CompanySearchType extends AbstractType CompanySearchType.php:27

A company search field: type a name (or a SIREN), pick a company among the register's, and the sibling fields named in fill take its details.

$builder->add('company', CompanySearchType::class, [ 'fill' => ['vatNumber' => 'vatNumber', 'companyName' => 'name', 'address' => 'address'], ]);

fill maps a sibling field of the same form to a result key (CompanySearch::row(): siren, siret, name, vatNumber, address, postalCode, city, activity, legalForm...). Not mapped by default: it only helps fill the others. The suggestions come from endpoint (by default the route omnistate_company_search); the widget's script is in the form theme.

CompanySearchType::__construct()

public function __construct(readonly ?UrlGeneratorInterface $urlGenerator = null)

CompanySearchType::configureOptions()

public function configureOptions(OptionsResolver $resolver): void

CompanySearchType::getParent()

public function getParent(): string

CompanySearchType::getBlockPrefix()

public function getBlockPrefix(): string

CompanySearchType::finishView()

public function finishView(FormView $view, FormInterface $form, array $options): void

Omnistate\Bridge\Symfony\Validator

Finess class

final class Finess extends Constraint Finess.php:8

A French health or social facility's FINESS number: nine characters, its Luhn key right.

public string $message = 'This is not a valid FINESS number.'

Finess::__construct()

public function __construct(?string $message = null, ?array $groups = null, mixed $payload = null)

FinessValidator class

final class FinessValidator extends ConstraintValidator FinessValidator.php:10

FinessValidator::validate()

public function validate(mixed $value, Constraint $constraint): void

Rpps class

final class Rpps extends Constraint Rpps.php:8

A French health professional's RPPS number: eleven digits, its Luhn key right (its IDNPS form, 8 + RPPS, too).

public string $message = 'This is not a valid RPPS number.'

Rpps::__construct()

public function __construct(?string $message = null, ?array $groups = null, mixed $payload = null)

RppsValidator class

final class RppsValidator extends ConstraintValidator RppsValidator.php:10

RppsValidator::validate()

public function validate(mixed $value, Constraint $constraint): void

Siren class

final class Siren extends Constraint Siren.php:8

A French SIREN: nine digits, its Luhn key right.

public string $message = 'This is not a valid SIREN.'

Siren::__construct()

public function __construct(?string $message = null, ?array $groups = null, mixed $payload = null)

SirenValidator class

final class SirenValidator extends ConstraintValidator SirenValidator.php:10

SirenValidator::validate()

public function validate(mixed $value, Constraint $constraint): void

Siret class

final class Siret extends Constraint Siret.php:8

A French SIRET: fourteen digits, its key right (La Poste's too).

public string $message = 'This is not a valid SIRET.'

Siret::__construct()

public function __construct(?string $message = null, ?array $groups = null, mixed $payload = null)

SiretValidator class

final class SiretValidator extends ConstraintValidator SiretValidator.php:10

SiretValidator::validate()

public function validate(mixed $value, Constraint $constraint): void

VatNumber class

final class VatNumber extends Constraint VatNumber.php:12

An intra-EU VAT number: in its member state's shape (and, for France, its key agreeing with its SIREN) - and, with $checkExistence, known to VIES.

VIES down is not a wrong number: the value then passes.

public string $message = 'This is not a valid EU VAT number.'

public string $unknownMessage = 'No EU member state knows this VAT number.'

public bool $checkExistence

VatNumber::__construct()

public function __construct(public bool $checkExistence = false, ?string $message = null, ?string $unknownMessage = null, ?array $groups = null, mixed $payload = null)

VatNumberValidator class

final class VatNumberValidator extends ConstraintValidator VatNumberValidator.php:12

VatNumberValidator::__construct()

public function __construct(readonly ?Omnistate $omnistate = null)

VatNumberValidator::validate()

public function validate(mixed $value, Constraint $constraint): void

Omnistate\Exception

NotSupportedException class

class NotSupportedException extends OmnistateException NotSupportedException.php:6

No registry installed answers for that: add its package (omnistate/...).

OmnistateException class

class OmnistateException extends RuntimeException OmnistateException.php:5

UnavailableException class

class UnavailableException extends OmnistateException UnavailableException.php:12

The register did not answer: down, overloaded, a member state's service closed for the night (VIES), too many calls (then $retryAfter, in seconds).

Not an answer about the company or the number: ask again later. HTTP 401, 403, 429, 5xx, no answer and an unreadable one are all this (the family's rule, docs/providers.md), never null nor an empty list.

public readonly ?int $retryAfter

UnavailableException::__construct()

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

Omnistate\Http

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.

Omnistate\Identifier

CountryCode class

final class CountryCode CountryCode.php:9

ISO 3166-1 country codes: registers write them with three letters (INSEE: "FRA") or two; Omnistate keeps two. No network.

const ALPHA3 = ['AFG' => 'AF', 'ALA' => 'AX', 'ALB' => 'AL', 'DZA' => 'DZ', 'ASM' => 'AS', 'AND' => 'AD', 'AGO' => 'AO', 'AIA' => 'AI', 'ATA' => 'AQ', 'ATG' => 'AG', 'ARG' …

alpha-3 => alpha-2, the 249 codes officially assigned.

CountryCode::alpha2()

public static function alpha2(?string $code): ?string

The alpha-2 code of a two- or three-letter code, null when it is neither.

CountryCode::alpha3()

public static function alpha3(?string $code): ?string

CountryCode::isValid()

public static function isValid(?string $code): bool

Finess class

final class Finess Finess.php:11

A French health or social establishment's FINESS number: nine characters, the department first (two digits, or 2A / 2B for Corsica), the last a Luhn check digit over the eight before it. A legal entity (FINESS juridique) and each of its sites (FINESS géographique) have one each.

Finess::normalize()

public static function normalize(?string $finess): ?string

"67 000 123 4" -> "670001234"; null when it is not nine characters of that shape.

Finess::isValid()

public static function isValid(?string $finess): bool

Nine characters whose last checks the eight before it (Luhn). Corsica's letters count as 0 (2A) and 1 (2B), the way the register computes its key.

Finess::department()

public static function department(string $finess): ?string

The department the number was given in: "67", "2A".

Luhn class

final class Luhn Luhn.php:6

The Luhn check (ISO/IEC 7812): every second digit from the right doubled.

Luhn::isValid()

public static function isValid(string $digits): bool

Rpps class

final class Rpps Rpps.php:11

A French health professional's RPPS number (Répertoire partagé des professionnels de santé): eleven digits, the last a Luhn check digit. Its national form, the IDNPS, is "8" followed by the RPPS. No register is asked: a number can be well written and still belong to no one.

Rpps::normalize()

public static function normalize(?string $rpps): ?string

"100 0346 1033" or the IDNPS "810003461033" -> "10003461033"; null when it is neither.

Rpps::isValid()

public static function isValid(?string $rpps): bool

Eleven digits whose last checks the ten others (Luhn).

Rpps::toIdnps()

public static function toIdnps(string $rpps): string

The national identifier the Annuaire Santé and Pro Santé Connect use: "8" + RPPS.

Rpps::withKey()

public static function withKey(string $tenDigits): string

A valid number from its first ten digits (fixtures, tests): the Luhn key appended.

Siren class

final class Siren Siren.php:9

A French company's SIREN: nine digits, the last a Luhn check digit. No register is asked: a SIREN can be well written and still belong to no one.

Siren::normalize()

public static function normalize(?string $siren): ?string

"901 821 074" -> "901821074"; null when it is not nine digits.

Siren::isValid()

public static function isValid(?string $siren): bool

Siren::toVatNumber()

public static function toVatNumber(string $siren): string

The French intra-EU VAT number of that SIREN: FR + ((12 + 3 × (SIREN mod 97)) mod 97) + SIREN.

Siret class

final class Siret Siret.php:12

A French establishment's SIRET: its company's SIREN and a five-digit NIC, fourteen digits under a Luhn check - La Poste's (SIREN 356 000 000) also when the sum of their digits is a multiple of 5, the rule its many establishments' numbers follow (its head office, 356 000 000 00048, passes Luhn and not the sum).

Siret::normalize()

public static function normalize(?string $siret): ?string

"901 821 074 00019" -> "90182107400019"; null when it is not fourteen digits.

Siret::isValid()

public static function isValid(?string $siret): bool

Siret::siren()

public static function siren(string $siret): string

VatNumber class

final class VatNumber VatNumber.php:11

Intra-EU VAT numbers, as VIES writes them: a country prefix (Greece is EL, Northern Ireland XI) and the number, in each country's own shape. No register is asked here - a number can be well written and belong to no one: omnistate/vies says whether it exists.

const FORMATS = ['AT' => 'U\d{8}', 'BE' => '[01]\d{9}', 'BG' => '\d{9,10}', 'CY' => '\d{8}[A-Z]', 'CZ' => '\d{8,10}', 'DE' => '\d{9}', 'DK' => '\d{8}', 'EE' => '\d{9}', 'EL'…

Each member state's shape, after its prefix.

VatNumber::normalize()

public static function normalize(?string $number): ?string

"de 123 456-789" -> "DE123456789", "GR..." -> "EL...", and a SIREN or SIRET -> its French number; null when it has no member state's shape.

VatNumber::isWellFormed()

public static function isWellFormed(?string $number): bool

Well written, and for France its key agrees with its SIREN.

VatNumber::country()

public static function country(string $number): string

Omnistate\Model

Activity class

final readonly class Activity Activity.php:6

What a company does, in its classification (France: NAF rev. 2, e.g. 62.02A).

public string $code

public string $classification

public ?string $label

public ?string $section

The classification's section (the NAF's letter, J for IT).

Activity::__construct()

public function __construct(public string $code, public string $classification, public ?string $label = null, public ?string $section = null)

Activity::__toString()

public function __toString(): string

Address class

final readonly class Address Address.php:6

Where a company or an establishment is, as its register writes it.

public ?string $street

public ?string $postalCode

public ?string $city

public ?string $country

ISO 3166-1 alpha-2.

public ?string $full

The register's own one-line form.

public ?float $latitude

public ?float $longitude

Address::__construct()

public function __construct(public ?string $street = null, public ?string $postalCode = null, public ?string $city = null, public ?string $country = null, public ?string $full = null, public ?float $latitude = null, public ?float $longitude = null)

Address::__toString()

public function __toString(): string

Archive class

final readonly class Archive implements Stringable Archive.php:6

Who keeps the original, and under which reference: what a citation needs.

public string $name

"Brabants Historisch Informatie Centrum", "INSEE", "The National Archives, Kew".

public ?string $code

The register's code for it ("bhi").

public ?string $reference

The call number: fonds, register, folio, act number.

public ?string $url

The record at the archive itself.

Archive::__construct()

public function __construct(public string $name, public ?string $code = null, public ?string $reference = null, public ?string $url = null)

Archive::__toString()

public function __toString(): string

CivilPerson class

final readonly class CivilPerson implements Stringable CivilPerson.php:10

Someone named in a civil record: the child and both parents of a birth, the spouses of a marriage, the deceased. Whatever the register does not tell is null.

public string $familyName

public array $givenNames

public Sex $sex

public ?string $role

As the register writes it: "Child", "Father", "Bride", "Deceased", "Witness".

..

public ?PartialDate $birthDate

public ?Place $birthPlace

public ?PartialDate $deathDate

public ?Place $deathPlace

public ?int $age

At the event, in years.

public ?string $profession

public ?string $fullName

The whole name, when the register gives it in one piece only.

CivilPerson::__construct()

public function __construct(public string $familyName = '', public array $givenNames = [], public Sex $sex = Sex::UNKNOWN, public ?string $role = null, public ?PartialDate $birthDate = null, public ?Place $birthPlace = null, public ?PartialDate $deathDate = null, public ?Place $deathPlace = null, public ?int $age = null, public ?string $profession = null, public ?string $fullName = null)

CivilPerson::name()

public function name(): string

"Jacques René Chirac"

CivilPerson::givenName()

public function givenName(): ?string

CivilPerson::__toString()

public function __toString(): string

CivilQuery class

final readonly class CivilQuery CivilQuery.php:13

What is asked of a civil register: someone's name, and whatever narrows it down. A register uses what it can search on and ignores the rest - but it says beforehand, with supports(), whether the question is one for it (its country, its kinds of records).

new CivilQuery(familyName: 'Chirac', givenName: 'Jacques', born: Period::year(1932), country: 'FR')

public array $kinds

public ?string $country

public int $limit

public int $page

public ?string $familyName

public ?string $givenName

public ?Period $born

public ?Period $died

public ?Period $dated

When the event recorded took place, whatever it is.

public ?string $place

The town of the event.

public ?Sex $sex

CivilQuery::__construct()

public function __construct(public ?string $familyName = null, public ?string $givenName = null, public ?Period $born = null, public ?Period $died = null, public ?Period $dated = null, public ?string $place = null, ?string $country = null, array $kinds = [], public ?Sex $sex = null, int $limit = 20, int $page = 1)

$kinds

the kinds wanted; empty: any

$country

ISO 3166-1 alpha-2 of the country whose registers are asked; null: any

CivilQuery::name()

public function name(): string

"Jacques Chirac"

CivilQuery::hasName()

public function hasName(): bool

CivilQuery::wants()

public function wants(CivilRecordKind $kind): bool

CivilQuery::wantsAny()

public function wantsAny(CivilRecordKind ...$kinds): bool

Whether any of these kinds is wanted.

CivilQuery::inCountries()

public function inCountries(string ...$countries): bool

Whether a register of these countries may be asked.

CivilQuery::key()

public function key(): string

A key for a cache: the same question, the same key.

CivilRecord class

final readonly class CivilRecord CivilRecord.php:11

An act, or a document about a person, as a public register indexes it: what it is, when, where, who is named in it, who keeps the original and - when the register gives them - the pictures of it. $raw keeps the register's whole answer.

public string $identifier

What Omnistate::civilRecord() takes to find it again in its register.

public CivilRecordKind $kind

public string $source

The register it came from: "matchid", "openarchieven".

..

public ?PartialDate $date

Of the event (the birth, the death), not of the paper.

public ?Place $place

public array $persons

public ?Archive $archive

public ?string $url

The record's page at the register.

public array $images

public ?string $title

What the register calls it: "Civil registration births", a catalogue title.

public ?string $number

The act's number in its register.

public ?string $description

public ?Period $period

When the register dates it by a span ("1939-1945") rather than a day.

public array $raw

CivilRecord::__construct()

public function __construct(public string $identifier, public CivilRecordKind $kind, public string $source, public ?PartialDate $date = null, public ?Place $place = null, public array $persons = [], public ?Archive $archive = null, public ?string $url = null, public array $images = [], public ?string $title = null, public ?string $number = null, public ?string $description = null, public ?Period $period = null, public array $raw = [])

CivilRecord::principal()

public function principal(): ?CivilPerson

The one the record is about.

CivilRecord::hasImages()

public function hasImages(): bool

CivilRecordKind enum

enum CivilRecordKind CivilRecordKind.php:10

What a civil record records. OTHER is everything a register holds about a person that is not one of the five acts: a population register, a notarial deed, a catalogue entry of an archive.

case BIRTH = 'birth'

case BAPTISM = 'baptism'

case MARRIAGE = 'marriage'

case DEATH = 'death'

case BURIAL = 'burial'

case OTHER = 'other'

CivilRecordKind::gedcom()

public function gedcom(): ?string

The GEDCOM tag of the event it documents (BIRT, CHR, MARR, DEAT, BURI), null for OTHER.

Company class

final readonly class Company Company.php:9

A company as its register knows it. Whatever the source could not tell is null or empty; $raw keeps its whole answer, for what this model leaves out.

public string $identifier

The register's identifier (France: the SIREN).

public string $name

public CompanyStatus $status

public string $country

public string $source

Where it came from: "annuaire-entreprises", "inpi".

..

public ?string $legalName

public ?string $acronym

public ?LegalForm $legalForm

public ?Activity $activity

public ?string $category

The size category (France: PME, ETI, GE) and its year.

public ?Headcount $headcount

public ?\DateTimeImmutable $createdOn

public ?\DateTimeImmutable $closedOn

public ?Establishment $headOffice

public array $establishments

public ?int $establishmentCount

public ?int $openEstablishmentCount

public array $managers

public array $finances

public array $labels

public array $collectiveAgreements

public ?string $vatNumber

public ?\DateTimeImmutable $updatedAt

public array $raw

Company::__construct()

public function __construct(public string $identifier, public string $name, public CompanyStatus $status, public string $country, public string $source, public ?string $legalName = null, public ?string $acronym = null, public ?LegalForm $legalForm = null, public ?Activity $activity = null, public ?string $category = null, public ?Headcount $headcount = null, public ?\DateTimeImmutable $createdOn = null, public ?\DateTimeImmutable $closedOn = null, public ?Establishment $headOffice = null, public array $establishments = [], public ?int $establishmentCount = null, public ?int $openEstablishmentCount = null, public array $managers = [], public array $finances = [], public array $labels = [], public array $collectiveAgreements = [], public ?string $vatNumber = null, public ?\DateTimeImmutable $updatedAt = null, public array $raw = [])

Company::isActive()

public function isActive(): bool

Company::establishment()

public function establishment(string $identifier): ?Establishment

CompanyStatus enum

enum CompanyStatus CompanyStatus.php:5

case ACTIVE = 'active'

case CLOSED = 'closed'

Contact class

final readonly class Contact Contact.php:6

Someone a registry names (a registrar, a registrant), as far as it shows them.

public ?string $name

public ?string $organization

public ?string $email

public ?string $country

public ?string $handle

public ?string $ianaId

A registrar's IANA ID.

public ?string $url

Contact::__construct()

public function __construct(public ?string $name = null, public ?string $organization = null, public ?string $email = null, public ?string $country = null, public ?string $handle = null, public ?string $ianaId = null, public ?string $url = null)

Contact::__toString()

public function __toString(): string

Domain class

final readonly class Domain Domain.php:6

A domain name as its registry's RDAP server describes it.

public string $name

public string $source

public ?string $handle

public array $statuses

public ?Contact $registrar

public ?Contact $registrant

Null when the registry does not publish it (most do not, since the GDPR).

public ?\DateTimeImmutable $registeredAt

public ?\DateTimeImmutable $expiresAt

public ?\DateTimeImmutable $changedAt

public array $nameservers

public bool $dnssec

public ?string $server

The server that answered.

public array $raw

Domain::__construct()

public function __construct(public string $name, public string $source, public ?string $handle = null, public array $statuses = [], public ?Contact $registrar = null, public ?Contact $registrant = null, public ?\DateTimeImmutable $registeredAt = null, public ?\DateTimeImmutable $expiresAt = null, public ?\DateTimeImmutable $changedAt = null, public array $nameservers = [], public bool $dnssec = false, public ?string $server = null, public array $raw = [])

Establishment class

final readonly class Establishment Establishment.php:6

One of a company's places of business (France: a SIRET).

public string $identifier

public bool $headOffice

public CompanyStatus $status

public ?Address $address

public ?string $name

public array $signs

public ?Activity $activity

public ?Headcount $headcount

public ?\DateTimeImmutable $createdOn

public ?\DateTimeImmutable $closedOn

Establishment::__construct()

public function __construct(public string $identifier, public bool $headOffice, public CompanyStatus $status, public ?Address $address = null, public ?string $name = null, public array $signs = [], public ?Activity $activity = null, public ?Headcount $headcount = null, public ?\DateTimeImmutable $createdOn = null, public ?\DateTimeImmutable $closedOn = null)

Establishment::isActive()

public function isActive(): bool

Facility class

final readonly class Facility Facility.php:10

A health or social facility as its register knows it (France: FINESS, through the Annuaire Santé): a hospital, a health centre, a pharmacy, a multi-professional practice.

public string $identifier

The register's identifier (France: the FINESS number).

public string $name

public string $source

public ?string $kind

"legal" (the entity) or "site" (one of its places), when the register says.

public array $types

public ?Address $address

public array $phones

public array $emails

public array $secureEmails

public array $identifiers

public bool $active

public ?\DateTimeImmutable $updatedAt

public array $raw

Facility::__construct()

public function __construct(public string $identifier, public string $name, public string $source, public ?string $kind = null, public array $types = [], public ?Address $address = null, public array $phones = [], public array $emails = [], public array $secureEmails = [], public array $identifiers = [], public bool $active = true, public ?\DateTimeImmutable $updatedAt = null, public array $raw = [])

Facility::__toString()

public function __toString(): string

FinancialYear class

final readonly class FinancialYear FinancialYear.php:6

A year's accounts as the register publishes them, in the currency's major unit.

public int $year

public ?float $revenue

public ?float $netIncome

public string $currency

FinancialYear::__construct()

public function __construct(public int $year, public ?float $revenue = null, public ?float $netIncome = null, public string $currency = 'EUR')

Headcount class

final readonly class Headcount Headcount.php:6

How many employees, as the register gives it: a range, and the year it was counted.

public ?int $min

public ?int $max

public ?int $year

public ?string $code

The register's own code for the range (INSEE: "12" for 20 to 49).

Headcount::__construct()

public function __construct(public ?int $min = null, public ?int $max = null, public ?int $year = null, public ?string $code = null)

Headcount::isEmployer()

public function isEmployer(): bool

Headcount::__toString()

public function __toString(): string

LegalForm class

final readonly class LegalForm LegalForm.php:6

A legal form: the register's code, its name and the short name people use (SARL, SAS).

public string $code

public ?string $label

public ?string $short

LegalForm::__construct()

public function __construct(public string $code, public ?string $label = null, public ?string $short = null)

LegalForm::__toString()

public function __toString(): string

Manager class

final readonly class Manager Manager.php:6

Who runs a company: a person, or a company of its own (then its identifier).

public string $name

public ?string $role

public bool $person

public ?string $firstNames

public ?string $identifier

A company that manages: its identifier (France: its SIREN).

public ?int $birthYear

public ?string $nationality

Manager::__construct()

public function __construct(public string $name, public ?string $role = null, public bool $person = true, public ?string $firstNames = null, public ?string $identifier = null, public ?int $birthYear = null, public ?string $nationality = null)

Manager::__toString()

public function __toString(): string

Network class

final readonly class Network Network.php:6

An IP range or an autonomous system, as its regional registry's RDAP server describes it.

public string $handle

public string $source

public ?string $name

public ?string $type

"ALLOCATED PA", "ASSIGNED PA", "DIRECT ALLOCATION".

..

public ?string $country

public ?string $startAddress

An IP range: its first and last address.

public ?string $endAddress

public ?int $startAutnum

An autonomous system: its numbers.

public ?int $endAutnum

public ?Contact $registrant

public ?Contact $abuse

public ?\DateTimeImmutable $registeredAt

public ?\DateTimeImmutable $changedAt

public ?string $server

public array $raw

Network::__construct()

public function __construct(public string $handle, public string $source, public ?string $name = null, public ?string $type = null, public ?string $country = null, public ?string $startAddress = null, public ?string $endAddress = null, public ?int $startAutnum = null, public ?int $endAutnum = null, public ?Contact $registrant = null, public ?Contact $abuse = null, public ?\DateTimeImmutable $registeredAt = null, public ?\DateTimeImmutable $changedAt = null, public ?string $server = null, public array $raw = [])

PartialDate class

final readonly class PartialDate implements Stringable PartialDate.php:10

A date as a register knows it: often whole, sometimes a year and a month, sometimes a year alone ("born in 1932"). What is not known is null - never a 1st of January made up.

public ?int $year

public ?int $month

1 to 12

public ?int $day

PartialDate::__construct()

public function __construct(public ?int $year = null, public ?int $month = null, public ?int $day = null)

PartialDate::parse()

public static function parse(?string $value): ?self

"1932-11-29", "19321129", "29/11/1932", "1932-11", "1932", and the registers' unknown parts written as zeros ("19320000"); null when no year can be read.

PartialDate::of()

public static function of(?int $year, ?int $month = null, ?int $day = null): ?self

Zeros and out-of-range parts are unknown parts; no year, no date.

PartialDate::fromDate()

public static function fromDate(\DateTimeInterface $date): self

PartialDate::isComplete()

public function isComplete(): bool

PartialDate::toDate()

public function toDate(): ?\DateTimeImmutable

The day itself when it is whole, null otherwise.

PartialDate::earliest()

public function earliest(): ?\DateTimeImmutable

The first day it can be.

PartialDate::latest()

public function latest(): ?\DateTimeImmutable

The last day it can be.

PartialDate::__toString()

public function __toString(): string

ISO 8601, as far as it is known: "1932-11-29", "1932-11", "1932".

Period class

final readonly class Period implements Stringable Period.php:6

Between two dates, either of them open: "from 1970", "1850 to 1860", "in 1853".

public ?PartialDate $from

public ?PartialDate $to

Period::__construct()

public function __construct(public ?PartialDate $from = null, public ?PartialDate $to = null)

Period::year()

public static function year(int $year): self

Period::years()

public static function years(?int $from, ?int $to): self

Period::since()

public static function since(int $year): self

Period::around()

public static function around(int $year, int $margin = 2): self

A year give or take a few: the way a genealogist searches a birth.

Period::day()

public static function day(PartialDate $date): self

Period::isDay()

public function isDay(): bool

One date, whole, at both ends.

Period::isYear()

public function isYear(): bool

Period::contains()

public function contains(PartialDate $date): bool

Period::__toString()

public function __toString(): string

Place class

final readonly class Place implements Stringable Place.php:6

Where an act was drawn up, where someone was born: as much as the register tells.

public ?string $name

The town, as the register writes it.

public ?string $code

The register's own code for it (France: the INSEE commune code).

public ?string $postcode

public ?string $region

A subdivision: a French département's code, a province.

public ?string $country

ISO 3166-1 alpha-2.

public ?string $countryName

The country as the register writes it, when it gives no code we know.

public ?float $latitude

public ?float $longitude

Place::__construct()

public function __construct(public ?string $name = null, public ?string $code = null, public ?string $postcode = null, public ?string $region = null, public ?string $country = null, public ?string $countryName = null, public ?float $latitude = null, public ?float $longitude = null)

Place::__toString()

public function __toString(): string

Professional class

final readonly class Professional Professional.php:11

A regulated professional as their register knows them: a physician, a nurse, a physiotherapist (France: the RPPS, through the Annuaire Santé); later a lawyer (the CNB's directory). Whatever the source could not tell is null or empty; $raw keeps its whole answer.

public string $identifier

The register's identifier (France: the RPPS number).

public string $familyName

public string $source

Where it came from: "annuaire-sante", "cnb".

..

public ?string $givenName

public ?string $prefix

"M", "MME", "DR"... as the register writes it.

public ?Qualification $profession

public array $specialties

public array $diplomas

public array $workplaces

public array $phones

public array $emails

public array $secureEmails

public array $languages

public bool $active

public ?\DateTimeImmutable $updatedAt

public array $raw

Professional::__construct()

public function __construct(public string $identifier, public string $familyName, public string $source, public ?string $givenName = null, public ?string $prefix = null, public ?Qualification $profession = null, public array $specialties = [], public array $diplomas = [], public array $workplaces = [], public array $phones = [], public array $emails = [], public array $secureEmails = [], public array $languages = [], public bool $active = true, public ?\DateTimeImmutable $updatedAt = null, public array $raw = [])

Professional::name()

public function name(): string

"Arthur Saucier"

Professional::__toString()

public function __toString(): string

Qualification class

final readonly class Qualification Qualification.php:10

A coded qualification as a register writes it: a profession, a specialty, a diploma, a know-how (France: the ANS's nomenclatures, TRE_G15 for the professions, TRE_R38 for the medical specialties...).

public string $code

public string $system

The nomenclature: a URL or a short name ("TRE_G15-ProfessionSante").

public ?string $label

Qualification::__construct()

public function __construct(public string $code, public string $system, public ?string $label = null)

Qualification::__toString()

public function __toString(): string

Sex enum

enum Sex Sex.php:5

case MALE = 'M'

case FEMALE = 'F'

case UNKNOWN = 'U'

Sex::fromAny()

public static function fromAny(mixed $value): self

From what registers write: "M", "F", "male", "Man", "Vrouw", "1", "2".

..

VatCheck class

final readonly class VatCheck VatCheck.php:11

What a VAT register answered about a number: valid or not, and whose. The consultation number, when the check was made with the requester's own VAT number, is the proof it was made that day - to keep with a reverse-charge invoice.

public string $number

public bool $valid

public \DateTimeImmutable $checkedAt

public string $source

public ?string $name

public ?string $address

public ?string $consultationNumber

VatCheck::__construct()

public function __construct(public string $number, public bool $valid, public \DateTimeImmutable $checkedAt, public string $source, public ?string $name = null, public ?string $address = null, public ?string $consultationNumber = null)

VatCheck::country()

public function country(): string

Workplace class

final readonly class Workplace Workplace.php:11

Where and how a professional practises: a practice, a health centre, a hospital - its name and address, the facility's identifier when it has one (France: its FINESS), the mode of practice (self-employed, salaried) and the role held there.

public ?string $name

public ?Address $address

public ?string $facility

The facility's own identifier (France: FINESS, or the register's structure id).

public ?string $mode

How: "liberal", "salaried", or the register's own code.

public ?string $role

public array $phones

public array $secureEmails

public bool $active

Workplace::__construct()

public function __construct(public ?string $name = null, public ?Address $address = null, public ?string $facility = null, public ?string $mode = null, public ?string $role = null, public array $phones = [], public array $secureEmails = [], public bool $active = true)

Workplace::__toString()

public function __toString(): string

Omnistate\Registry

CivilRegistryInterface interface

interface CivilRegistryInterface CivilRegistryInterface.php:17

A public register of acts and documents about people: a country's deaths file (France: INSEE's, through matchID), the indexes of its archives (the Netherlands and Belgium: Open Archives), an archive's catalogue. Each one says what it covers - which countries, which kinds of records, which years - so that a search screen can tell before asking.

CivilRegistryInterface::name()

public function name(): string

A short name, the CivilRecord's $source: "matchid".

CivilRegistryInterface::countries()

public function countries(): array

Returns

ISO 3166-1 alpha-2 codes of the countries whose records it holds

CivilRegistryInterface::kinds()

public function kinds(): array

Returns

the kinds of records it holds

CivilRegistryInterface::period()

public function period(): ?Period

The years it covers, when it has bounds (France's deaths file: since 1970); null: no bound to tell.

CivilRegistryInterface::hasImages()

public function hasImages(): bool

Whether it gives the pictures of the acts (CivilRecord::$images), for some records at least.

CivilRegistryInterface::supports()

public function supports(CivilQuery $query): bool

Whether the question is one for it: its country, one of its kinds, something it can search on.

CivilRegistryInterface::search()

public function search(CivilQuery $query): array

The records that match, the likeliest first; none is an empty list.

Throws

Omnistate\Exception\UnavailableException the register did not answer

CivilRegistryInterface::find()

public function find(string $identifier): ?CivilRecord

A record by the identifier a search gave (CivilRecord::$identifier), with everything the register tells about it; null when it does not know it.

Throws

Omnistate\Exception\UnavailableException

CompanyRegistryInterface interface

interface CompanyRegistryInterface CompanyRegistryInterface.php:8

A register of companies: France's, the UK's Companies House.

..

CompanyRegistryInterface::name()

public function name(): string

A short name, the Company's $source: "annuaire-entreprises".

CompanyRegistryInterface::supports()

public function supports(string $identifier): bool

Whether it can answer for that identifier (a SIREN, a SIRET, a company number...).

CompanyRegistryInterface::company()

public function company(string $identifier): ?Company

The company, with the establishment asked for among its establishments when the identifier is one; null when the register does not know it.

Throws

Omnistate\Exception\UnavailableException the register did not answer

CompanyRegistryInterface::search()

public function search(string $query, int $limit = 10): array

Companies by name (or anything the register searches on).

Throws

Omnistate\Exception\UnavailableException

FacilityRegistryInterface interface

interface FacilityRegistryInterface FacilityRegistryInterface.php:11

A register of health and social facilities (France: FINESS). A professional registry that knows them too implements both interfaces.

FacilityRegistryInterface::name()

public function name(): string

FacilityRegistryInterface::supportsFacility()

public function supportsFacility(string $identifier): bool

Whether it can answer for that identifier (a FINESS number...).

FacilityRegistryInterface::facility()

public function facility(string $identifier): ?Facility

Throws

Omnistate\Exception\UnavailableException the register did not answer

InternetRegistryInterface interface

interface InternetRegistryInterface InternetRegistryInterface.php:9

The Internet's registries: domains, IP ranges, autonomous systems.

InternetRegistryInterface::name()

public function name(): string

InternetRegistryInterface::domain()

public function domain(string $name): ?Domain

Throws

Omnistate\Exception\UnavailableException

InternetRegistryInterface::network()

public function network(string $address): ?Network

An IP address's range, or an AS number's ("AS3215", "3215").

Throws

Omnistate\Exception\UnavailableException

ProfessionalRegistryInterface interface

interface ProfessionalRegistryInterface ProfessionalRegistryInterface.php:12

A register of regulated professionals: France's health professionals (RPPS, through the Annuaire Santé), later its lawyers (the CNB). One contract for every profession: whoever reads it need not know which.

ProfessionalRegistryInterface::name()

public function name(): string

A short name, the Professional's $source: "annuaire-sante".

ProfessionalRegistryInterface::supports()

public function supports(string $identifier): bool

Whether it can answer for that identifier (an RPPS number...).

ProfessionalRegistryInterface::professional()

public function professional(string $identifier): ?Professional

The professional, null when the register does not know them.

Throws

Omnistate\Exception\UnavailableException the register did not answer

ProfessionalRegistryInterface::search()

public function search(string $name, ?string $postcode = null, int $limit = 10): array

Professionals by name, those practising in that postcode only when one is given.

Throws

Omnistate\Exception\UnavailableException

VatRegistryInterface interface

interface VatRegistryInterface VatRegistryInterface.php:8

A register of VAT numbers: the EU's VIES.

..

VatRegistryInterface::name()

public function name(): string

VatRegistryInterface::supports()

public function supports(string $number): bool

Whether it answers for that (normalized) number's country.

VatRegistryInterface::check()

public function check(string $number, ?string $requester = null): VatCheck

$requester

your own VAT number: the register may then give a consultation number, the proof of the check

Throws

Omnistate\Exception\UnavailableException the register (or the member state behind it) did not answer

Throws

Omnistate\Exception\OmnistateException the register refused the check itself (VIES: a requester it does not accept)

Omnistate\Testing

RegistryContractTests trait

trait RegistryContractTests RegistryContractTests.php:60

What every Omnistate register does, as PHPUnit tests, offline: a provider's test case uses this trait, gives its registry (built on the HTTP client the suite hands it) and the register's recorded answers. The suite checks each of the family's contracts the registry implements (CompanyRegistryInterface, VatRegistryInterface, ProfessionalRegistryInterface, FacilityRegistryInterface, CivilRegistryInterface, InternetRegistryInterface), asked through the Omnistate facade as an application asks:

final class MatchIdContractTest extends TestCase { use RegistryContractTests;

    protected function registry(HttpClientInterface $http): object { return new MatchId($http); }
    protected function recordedAnswers(): array { return ['GET /deaths/search' => json_decode(file_get_contents(...), true)]; }
    protected function civilQuery(): ?CivilQuery { return new CivilQuery(familyName: 'Chirac'); }
    protected function civilIdentifier(): ?string { return 'fohpDS17K0Ez'; }
}

It checks: - it implements at least one of the family's contracts, under a short name (its models' $source); - what it does not take (an identifier of another kind, another country's question) is a NotSupportedException from the facade, before any HTTP request; a civil register's coverage (countries, kinds, period) is well formed; - the family's rule on errors (docs/providers.md): when the register answers HTTP 401, 403, 429, 500, 503, a body that is not what it should be, or cannot be reached, every question is an UnavailableException - never null, an empty list or an invalid VAT number, which would read "unavailable" as "not found"; a 429 carries $retryAfter; - HTTP 404 on a lookup (a company, a professional, a facility, a record, a domain, a network) is null: not known; - on the recorded answers: each lookup and search gives models carrying the registry's name as $source and their identifier, a civil record of a kind the register says it holds.

No test reaches the network: every request goes to the suite's MockHttpClient, and one with no recorded answer is answered HTTP 404 and named in the failure.

Requires phpunit/phpunit and symfony/http-client (the provider's, in require-dev).

RegistryContractTests::testItImplementsTheFamilysContractsUnderItsName()

public function testItImplementsTheFamilysContractsUnderItsName(): void

RegistryContractTests::testWhatItDoesNotTakeIsNotSupportedBeforeAnyRequest()

public function testWhatItDoesNotTakeIsNotSupportedBeforeAnyRequest(): void

RegistryContractTests::testUnavailableIsNeverReadAsNotFound()

public function testUnavailableIsNeverReadAsNotFound(): void

RegistryContractTests::testNotFoundIsNull()

public function testNotFoundIsNull(): void

RegistryContractTests::testTheRecordedAnswersGiveModelsOfItsOwn()

public function testTheRecordedAnswersGiveModelsOfItsOwn(): void