Skip to content

Expose JSON:API includes so callers can hydrate tags and other relationships - #229

Open
PeteBishwhip wants to merge 1 commit into
4.xfrom
add-tags-include
Open

Expose JSON:API includes so callers can hydrate tags and other relationships#229
PeteBishwhip wants to merge 1 commit into
4.xfrom
add-tags-include

Conversation

@PeteBishwhip

@PeteBishwhip PeteBishwhip commented Jul 2, 2026

Copy link
Copy Markdown
Member

Fixes #228.

Querying a server or a site through the SDK returned an empty relationships block and no way to hydrate related resources such as tags. Two things were missing:

  1. server() and organizationSite() did not accept a $query argument, so callers could not pass ?include=tags (or any other JSON:API include).
  2. Even when the API returned an included document, the SDK only consumed the top-level data envelope and discarded included, so relationship identifiers stayed unresolved.

Changes

  • server(string $organizationSlug, int $serverId, array $query = []) - new $query parameter, forwarded to the API.
  • organizationSite(string $organizationSlug, int $siteId, array $query = []) - same treatment.
  • Resource now exposes public array $included (populated from the response) and a small included(string $name): array helper that resolves relationships[$name].data pointers against the shared included document. Handles array, single-object, and null relationship shapes.
  • Forge::newResource(), Forge::transformCollection(), Forge::paginatedCollection(), and CursorPaginator::nextPage() thread the included document through to hydrated resources so it is available on collection items too.
  • New included() helper tests cover: server with tag includes, site with tag includes, site with a single-object relationship (latestDeployment) plus a null server relationship, and a paginated server collection propagating the shared included document.
  • README gets a short "Including Related Resources" section under Basic Usage; CHANGELOG has an [Unreleased] entry referencing Tags missing from a response when I query a resource #228.

Usage

$server = $forge->server($organizationSlug, $serverId, ['include' => 'tags']);

foreach ($server->included('tags') as $tag) {
    echo $tag['attributes']['name'];
}

The same pattern works on organizationSite() and on collection methods like servers() / serverSites().

Testing

4 new tests added

Adds a $query parameter to server() and organizationSite() so callers can pass include=tags (or any other supported include) through to the API. The top-level included document is preserved on hydrated resources and exposed via a new included($name) helper that resolves relationship pointers against it. Fixes #228.
@PeteBishwhip
PeteBishwhip marked this pull request as ready for review July 2, 2026 20:14
@PeteBishwhip

Copy link
Copy Markdown
Member Author

@PeteBishwhip PeteBishwhip added bug and removed bug labels Jul 2, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Tags missing from a response when I query a resource

2 participants