Documentation

GdlClient
in package

Client for the Global Digital Library content API.

Tags
since
3.1.0

Table of Contents

Constants

API_BASE  = 'https://content.digitallibrary.io/wp-json/content-api/v1/'
GDL content API base URL (WordPress REST API).
PAGE_SIZE  = 20
Results per page. Server-fixed at 20; the only paging lever is `_skip` (an offset), so a page maps to an offset of (page - 1) * PAGE_SIZE.
TIMEOUT  = 30
HTTP fetch timeout in seconds.

Methods

browse()  : array{results: list, count: int, next: bool}|array{error: string}
Browse books for a language (no search query).
fetchEpub()  : string|null
Download the raw bytes of a GDL ePUB.
levelToTier()  : string
Map a GDL reading level to a coarse difficulty tier.
search()  : array{results: list, count: int, next: bool}|array{error: string}
Search the Global Digital Library catalog.
extractEpubUrl()  : string|null
Extract the ePUB download URL from a GDL book record.
extractLevel()  : string
Extract the reading-level label from a book's topic terms.
fetchJson()  : array<string|int, mixed>|null
Fetch and decode JSON from a URL.
parseSearchResponse()  : array{results: list, count: int, next: bool}
Map a raw contentsearch response into normalised result rows.
decodeText()  : string
Decode HTML entities in GDL text fields.
firstTermName()  : string
Read the name of the first term in a GDL taxonomy array.
firstTermSlug()  : string
Read the slug of the first term in a GDL taxonomy array.
thumbnailUrl()  : string
Resolve the cover thumbnail, which is `false` when a book has none.

Constants

API_BASE

GDL content API base URL (WordPress REST API).

private mixed API_BASE = 'https://content.digitallibrary.io/wp-json/content-api/v1/'

The legacy standalone OPDS feed (opds.digitallibrary.io) and book-api (api.digitallibrary.io) were decommissioned; both hosts no longer resolve. This WordPress JSON API is the current surface.

PAGE_SIZE

Results per page. Server-fixed at 20; the only paging lever is `_skip` (an offset), so a page maps to an offset of (page - 1) * PAGE_SIZE.

private mixed PAGE_SIZE = 20

TIMEOUT

HTTP fetch timeout in seconds.

private mixed TIMEOUT = 30

Methods

browse()

Browse books for a language (no search query).

public browse(string $languageCode[, int $page = 1 ]) : array{results: list, count: int, next: bool}|array{error: string}
Parameters
$languageCode : string

GDL language slug (e.g. "en", "swa")

$page : int = 1

Page number (1-based)

Return values
array{results: list, count: int, next: bool}|array{error: string}

fetchEpub()

Download the raw bytes of a GDL ePUB.

public fetchEpub(string $url) : string|null

Returns the binary so the (Book-module) ePUB parser can run on it elsewhere — keeping this client free of module dependencies. The same per-hop SSRF revalidation as fetchJson applies: a redirect could otherwise rotate the URL into a private address.

Parameters
$url : string

ePUB URL (epub-generator endpoint)

Return values
string|null —

Raw ePUB bytes, or null on failure

levelToTier()

Map a GDL reading level to a coarse difficulty tier.

public static levelToTier(string $level) : string

GDL levels run 1–5 with word-count bands (Level 4 = "more than 1500 words"). Books outside the levelled "Library Books" collection have no level and fall through to "medium".

Parameters
$level : string

Level label (e.g. "Level 3"), or '' when unknown

Return values
string —

One of "easy", "medium", "hard"

search()

Search the Global Digital Library catalog.

public search(string $query[, string|null $languageCode = null ][, int $page = 1 ]) : array{results: list, count: int, next: bool}|array{error: string}
Parameters
$query : string

Search query (title/keyword)

$languageCode : string|null = null

GDL language slug (e.g. "en", "swa")

$page : int = 1

Page number (1-based)

Return values
array{results: list, count: int, next: bool}|array{error: string}

extractEpubUrl()

Extract the ePUB download URL from a GDL book record.

protected extractEpubUrl(array<string|int, mixed> $book) : string|null
Parameters
$book : array<string|int, mixed>

GDL book record

Return values
string|null —

ePUB URL, or null when the book has no ePUB

extractLevel()

Extract the reading-level label from a book's topic terms.

protected extractLevel(array<string|int, mixed> $book) : string

GDL exposes the level as a topic term named "Level N" (not via the level taxonomy, which is unpopulated in the current API).

Parameters
$book : array<string|int, mixed>

GDL book record

Return values
string —

Level label (e.g. "Level 2"), or '' when absent

fetchJson()

Fetch and decode JSON from a URL.

protected fetchJson(string $url) : array<string|int, mixed>|null
Parameters
$url : string

URL to fetch

Return values
array<string|int, mixed>|null —

Decoded JSON or null on failure

parseSearchResponse()

Map a raw contentsearch response into normalised result rows.

protected parseSearchResponse(array<string|int, mixed> $response, int $page) : array{results: list, count: int, next: bool}

Kept separate from the HTTP fetch so the mapping is unit-testable without the network (mirrors GutenbergClient's extractTextUrl split).

Parameters
$response : array<string|int, mixed>

Decoded contentsearch JSON

$page : int

Page number the response is for

Return values
array{results: list, count: int, next: bool}

decodeText()

Decode HTML entities in GDL text fields.

private decodeText(string $text) : string

GDL's WordPress API HTML-encodes apostrophes and spaces in titles and descriptions (e.g. "d'Ali", " "). The frontend renders these via Alpine x-text, which sets textContent and does not decode entities — so they must be decoded here, at the data boundary.

Parameters
$text : string

Raw text from the GDL API

Return values
string —

Text with HTML entities decoded

firstTermName()

Read the name of the first term in a GDL taxonomy array.

private firstTermName(mixed $terms) : string
Parameters
$terms : mixed

Taxonomy term list from a book record

Return values
string —

First term name, or '' when empty

firstTermSlug()

Read the slug of the first term in a GDL taxonomy array.

private firstTermSlug(mixed $terms) : string
Parameters
$terms : mixed

Taxonomy term list from a book record

Return values
string —

First term slug, or '' when empty

thumbnailUrl()

Resolve the cover thumbnail, which is `false` when a book has none.

private thumbnailUrl(array<string|int, mixed> $book) : string
Parameters
$book : array<string|int, mixed>

GDL book record

Return values
string —

Thumbnail URL, or '' when absent


        

        
    




    

    

                                

                

                                
    

        On this page

        
    


                

                            

            

    

        

            
Search results