Spaces
The space rows as a connector may read and write them — finding a place, recording every place the installation learns about, and pointing a resource at one.
Subscriby\Connector\Core\Spaces. A space is a place the installation administers: a channel, a group, a guild, a role, a board. A resource is the core's decision to sell access to it. Recording and binding are separate so a connector can report every place it learns about without deciding anything for the creator.
Reads
| Method | Returns | Null when |
|---|---|---|
find(string $id) | ?SpaceRef | No space has that UUID. |
findByExternalId(InstallationRef $installation, string $kind, string $externalId) | ?SpaceRef | The installation knows no such place of that kind. |
A join request, a member event or a post arrives naming a chat; findByExternalId() tells you whether the core gates it and which SpaceRef to pass to your ports.
record()
$space = $spaces->record(new SpaceRecord(
connector: 'example',
installationId: $installation->id,
externalId: $chat->id,
kind: 'room', // one of your resource kinds, without the connector prefix
title: $chat->title,
parentExternalId: null, // a role's guild, a topic's group
storageRef: (string) $row->id,
meta: [],
));Idempotent on the installation, the kind and the platform id; a second record refreshes the title and parent. Record a place when the platform tells you about it (a chosen chat, a guild the app joined, a channel that was renamed), so the core's rows carry the current title without asking the platform on every page.
bindResource()
$spaces->bindResource($space, $resourceId, ResourceKind::for('example', 'room'));Point a resource at a space. The core writes the resource's connector, kind and space in one step so the three can never disagree; a resource bound to another space is re-pointed. ResourceKind::for($connector, $kind) builds the stored connector:kind value; ResourceKind::fromString() parses one, and ResourceKind::manual() names the core's own kind for a perk the creator fulfils by hand.
Use it when a place should gate an existing resource outside the recovery ledger, which is what a migration moving legacy rows does. A newly picked place becomes a resource through Resources::create(), which binds it in the same step; a place that replaces one a resource lost goes through Recovery::replaceSpace(), so the ledger, the allowance and the re-admission run.
What the ref carries
SpaceRef: id, connector, externalId, kind (the stored connector:kind), storageRef, parentExternalId. Health is written by the core from your probes and never read from a connector; the title is on the row, refreshed by your record().
Report, do not decide
Recording a space sells nothing. Report every place you learn about; the creator decides which become resources, and the core decides who may be in them.
How is this guide?
Identities
The identity rows and who holds them — finding an account, recording it, linking it to a creator or a member, the handshake that proves possession, and the two lookups that turn an account into a person.
Resources
The resource rows as a connector may read them, and the one write — selling access to a place a creator picked — with its idempotency, its authorisation, its refusals and what the core announces.