GutenbergSuggestionService
in package
Fetches and caches popular Gutenberg books with difficulty tiers.
Uses a file-based cache (24h TTL) to avoid hitting the Gutendex API on every home page load.
Tags
Table of Contents
Constants
- CACHE_TTL = 86400
- Cache time-to-live in seconds (24 hours).
- PAGE_SIZE = 32
- Number of books per page from Gutendex.
Methods
- getSuggestions() : array<string|int, mixed>
- Get book suggestions for a language, with caching and difficulty tiers.
- cachePath() : string
- Get the file path for a cache key.
- enrichWithTiers() : void
- Enrich results with subject-based difficulty tiers, sorted easy-first.
- readCache() : array<string|int, mixed>|null
- Read a cached result if still valid.
- resolveLanguageCode() : string|null
- Resolve language ID to ISO 639-1 code.
- writeCache() : void
- Write a result to cache.
Constants
CACHE_TTL
Cache time-to-live in seconds (24 hours).
private
mixed
CACHE_TTL
= 86400
PAGE_SIZE
Number of books per page from Gutendex.
private
mixed
PAGE_SIZE
= 32
Methods
getSuggestions()
Get book suggestions for a language, with caching and difficulty tiers.
public
getSuggestions(int $languageId[, int $page = 1 ]) : array<string|int, mixed>
Parameters
- $languageId : int
-
Language ID
- $page : int = 1
-
Page number (1-based)
Return values
array<string|int, mixed>cachePath()
Get the file path for a cache key.
private
cachePath(string $key) : string
Parameters
- $key : string
-
Cache key
Return values
string —Absolute file path
enrichWithTiers()
Enrich results with subject-based difficulty tiers, sorted easy-first.
private
enrichWithTiers(array<string|int, mixed> &$result) : void
Uses subject classification only (not vocabulary-adjusted) so that suggestions show relative difficulty between books, regardless of the user's current vocabulary size.
Parameters
- $result : array<string|int, mixed>
-
Search result (modified in place)
readCache()
Read a cached result if still valid.
private
readCache(string $key) : array<string|int, mixed>|null
Parameters
- $key : string
-
Cache key
Return values
array<string|int, mixed>|null —Cached data or null if expired/missing
resolveLanguageCode()
Resolve language ID to ISO 639-1 code.
private
resolveLanguageCode(int $languageId) : string|null
Parameters
- $languageId : int
-
Language ID
Return values
string|null —ISO code or null
writeCache()
Write a result to cache.
private
writeCache(string $key, array<string|int, mixed> $data) : void
Parameters
- $key : string
-
Cache key
- $data : array<string|int, mixed>
-
Data to cache