Documentation

TextApiHandler
in package
implements ApiRoutableInterface uses ApiRoutableTrait

Handler for text-related API operations.

Delegates to TextPositionApiHandler, TextAnnotationApiHandler, and TextTermApiHandler for actual logic.

Table of Contents

Interfaces

ApiRoutableInterface
Interface for API handlers that participate in route dispatch.

Properties

$annotationHandler  : TextAnnotationApiHandler
$positionHandler  : TextPositionApiHandler
$termHandler  : TextTermApiHandler

Methods

__construct()  : mixed
editTermForm()  : string
formatArchivedTextsByLanguage()  : array<string|int, mixed>
formatEditTermForm()  : array<string|int, mixed>
formatGetAnnotation()  : array<string|int, mixed>
formatGetPrintItems()  : array<string|int, mixed>
formatGetRecommendedTexts()  : array<string|int, mixed>
formatGetTextScore()  : array<string|int, mixed>
formatGetTextScores()  : array<string|int, mixed>
formatGetWords()  : array<string|int, mixed>
formatMarkAllIgnored()  : array<string|int, mixed>
formatMarkAllWellKnown()  : array<string|int, mixed>
formatSetAnnotation()  : array<string|int, mixed>
formatSetAudioPosition()  : array<string|int, mixed>
formatSetDisplayMode()  : array<string|int, mixed>
formatSetTextPosition()  : array<string|int, mixed>
formatTermTranslations()  : array<string|int, mixed>
formatTextsByLanguage()  : array<string|int, mixed>
getAnnotation()  : array<string|int, mixed>
getPrintItems()  : array<string|int, mixed>
getTermTranslations()  : array<string|int, mixed>
getTranslations()  : array<string|int, mixed>
getWords()  : array<string|int, mixed>
makeTrans()  : string
markAllIgnored()  : array<string|int, mixed>
markAllWellKnown()  : array<string|int, mixed>
routeDelete()  : JsonResponse
routeGet()  : JsonResponse
Handle a GET request for this resource.
routePost()  : JsonResponse
Handle a POST request for this resource.
routePut()  : JsonResponse
Handle a PUT request for this resource.
saveAudioPosition()  : void
saveImprText()  : array<string|int, mixed>
saveImprTextData()  : array<string|int, mixed>
saveTextPosition()  : void
setDisplayMode()  : array<string|int, mixed>
frag()  : string
Extract a fragment from the fragments array.
formatGetAudio()  : JsonResponse
Handle GET /texts/{id}/audio — the reading screen's media-player config.
formatGetBookContext()  : JsonResponse
Handle GET /texts/{id}/book-context — the reading screen's chapter nav.
handleBulkAction()  : JsonResponse
Handle PUT /texts/bulk-action — archive or delete multiple texts.
handleExtractEpubUrl()  : JsonResponse
Handle Global Digital Library ePUB import requests.
handleGdlSearch()  : JsonResponse
Handle Global Digital Library search/browse requests.
handleGutenbergSuggestions()  : JsonResponse
Handle Gutenberg suggestion requests (popular books by language).
handleLibraryPreview()  : JsonResponse
Handle library preview requests (accurate vocabulary coverage).
handleLibrarySearch()  : JsonResponse
Handle library search requests.
handleReaderLevel()  : JsonResponse
Handle reader-level requests (vocabulary size + beginner flag).
resolveLanguageCode()  : string|null
Resolve a language ID to an ISO 639-1 code for Gutenberg.

Properties

Methods

editTermForm()

public editTermForm(int $textid) : string
Parameters
$textid : int
Return values
string

formatArchivedTextsByLanguage()

public formatArchivedTextsByLanguage(int $langId, array<string|int, mixed> $params) : array<string|int, mixed>
Parameters
$langId : int
$params : array<string|int, mixed>
Return values
array<string|int, mixed>

formatEditTermForm()

public formatEditTermForm(int $textId) : array<string|int, mixed>
Parameters
$textId : int
Return values
array<string|int, mixed>

formatGetAnnotation()

public formatGetAnnotation(int $textId) : array<string|int, mixed>
Parameters
$textId : int
Return values
array<string|int, mixed>

formatGetPrintItems()

public formatGetPrintItems(int $textId) : array<string|int, mixed>
Parameters
$textId : int
Return values
array<string|int, mixed>

formatGetRecommendedTexts()

public formatGetRecommendedTexts(int $languageId, array<string|int, mixed> $params) : array<string|int, mixed>
Parameters
$languageId : int
$params : array<string|int, mixed>
Return values
array<string|int, mixed>

formatGetTextScore()

public formatGetTextScore(int $textId) : array<string|int, mixed>
Parameters
$textId : int
Return values
array<string|int, mixed>

formatGetTextScores()

public formatGetTextScores(array<string|int, mixed> $textIds) : array<string|int, mixed>
Parameters
$textIds : array<string|int, mixed>
Return values
array<string|int, mixed>

formatGetWords()

public formatGetWords(int $textId) : array<string|int, mixed>
Parameters
$textId : int
Return values
array<string|int, mixed>

formatMarkAllIgnored()

public formatMarkAllIgnored(int $textId) : array<string|int, mixed>
Parameters
$textId : int
Return values
array<string|int, mixed>

formatMarkAllWellKnown()

public formatMarkAllWellKnown(int $textId) : array<string|int, mixed>
Parameters
$textId : int
Return values
array<string|int, mixed>

formatSetAnnotation()

public formatSetAnnotation(int $textId, string $elem, string $data) : array<string|int, mixed>
Parameters
$textId : int
$elem : string
$data : string
Return values
array<string|int, mixed>

formatSetAudioPosition()

public formatSetAudioPosition(int $textId, float $position) : array<string|int, mixed>
Parameters
$textId : int
$position : float
Return values
array<string|int, mixed>

formatSetDisplayMode()

public formatSetDisplayMode(int $textId, array<string|int, mixed> $params) : array<string|int, mixed>
Parameters
$textId : int
$params : array<string|int, mixed>
Return values
array<string|int, mixed>

formatSetTextPosition()

public formatSetTextPosition(int $textId, int $position) : array<string|int, mixed>
Parameters
$textId : int
$position : int
Return values
array<string|int, mixed>

formatTermTranslations()

public formatTermTranslations(string $termLc, int $textId) : array<string|int, mixed>
Parameters
$termLc : string
$textId : int
Return values
array<string|int, mixed>

formatTextsByLanguage()

public formatTextsByLanguage(int $langId, array<string|int, mixed> $params) : array<string|int, mixed>
Parameters
$langId : int
$params : array<string|int, mixed>
Return values
array<string|int, mixed>

getAnnotation()

public getAnnotation(int $textId) : array<string|int, mixed>
Parameters
$textId : int
Return values
array<string|int, mixed>

getPrintItems()

public getPrintItems(int $textId) : array<string|int, mixed>
Parameters
$textId : int
Return values
array<string|int, mixed>

getTermTranslations()

public getTermTranslations(string $wordlc, int $textid) : array<string|int, mixed>
Parameters
$wordlc : string
$textid : int
Return values
array<string|int, mixed>

getTranslations()

public getTranslations(int $wordId) : array<string|int, mixed>
Parameters
$wordId : int
Return values
array<string|int, mixed>

getWords()

public getWords(int $textId) : array<string|int, mixed>
Parameters
$textId : int
Return values
array<string|int, mixed>

makeTrans()

public makeTrans(int $i, int|null $wid, string $trans, string $word, int $lang) : string
Parameters
$i : int
$wid : int|null
$trans : string
$word : string
$lang : int
Return values
string

markAllIgnored()

public markAllIgnored(int $textId) : array<string|int, mixed>
Parameters
$textId : int
Return values
array<string|int, mixed>

markAllWellKnown()

public markAllWellKnown(int $textId) : array<string|int, mixed>
Parameters
$textId : int
Return values
array<string|int, mixed>

routeDelete()

public routeDelete(array<string|int, mixed> $fragments, array<string|int, mixed> $params) : JsonResponse
Parameters
$fragments : array<string|int, mixed>
$params : array<string|int, mixed>
Return values
JsonResponse

routeGet()

Handle a GET request for this resource.

public routeGet(array<string|int, mixed> $fragments, array<string|int, mixed> $params) : JsonResponse
Parameters
$fragments : array<string|int, mixed>

URL path segments (resource name already consumed)

$params : array<string|int, mixed>

Query parameters

Return values
JsonResponse

routePost()

Handle a POST request for this resource.

public routePost(array<string|int, mixed> $fragments, array<string|int, mixed> $params) : JsonResponse
Parameters
$fragments : array<string|int, mixed>

URL path segments (resource name already consumed)

$params : array<string|int, mixed>

POST/JSON body parameters

Return values
JsonResponse

routePut()

Handle a PUT request for this resource.

public routePut(array<string|int, mixed> $fragments, array<string|int, mixed> $params) : JsonResponse
Parameters
$fragments : array<string|int, mixed>

URL path segments (resource name already consumed)

$params : array<string|int, mixed>

JSON body parameters

Return values
JsonResponse

saveAudioPosition()

public saveAudioPosition(int $textid, float $audioposition) : void
Parameters
$textid : int
$audioposition : float

saveImprText()

public saveImprText(int $textid, string $elem, object $data) : array<string|int, mixed>
Parameters
$textid : int
$elem : string
$data : object
Return values
array<string|int, mixed>

saveImprTextData()

public saveImprTextData(int $textid, int $line, string $val) : array<string|int, mixed>
Parameters
$textid : int
$line : int
$val : string
Return values
array<string|int, mixed>

saveTextPosition()

public saveTextPosition(int $textid, int $position) : void
Parameters
$textid : int
$position : int

setDisplayMode()

public setDisplayMode(int $textId, int|null $annotations, bool|null $romanization, bool|null $translation) : array<string|int, mixed>
Parameters
$textId : int
$annotations : int|null
$romanization : bool|null
$translation : bool|null
Return values
array<string|int, mixed>

frag()

Extract a fragment from the fragments array.

protected frag(array<int, string> $fragments, int $index) : string
Parameters
$fragments : array<int, string>

The URL path fragments

$index : int

The index to extract

Return values
string —

The fragment at the index, or empty string if not present

formatGetAudio()

Handle GET /texts/{id}/audio — the reading screen's media-player config.

private formatGetAudio(int $textId) : JsonResponse

Returns the per-text audio source and saved position plus the global player settings, mirroring what MediaService bakes into the server-rendered player, so a shell-free client can render the player itself. A 404 is returned when the text does not exist or is not owned by the caller (getTextForReading is per-user scoped); a present text with no audio yields an empty uri.

Parameters
$textId : int
Return values
JsonResponse

formatGetBookContext()

Handle GET /texts/{id}/book-context — the reading screen's chapter nav.

private formatGetBookContext(int $textId) : JsonResponse

Returns the book/chapter context (titles, chapter index, prev/next text ids) so a shell-free client can render the prev/next navigation that the server otherwise bakes into read_desktop.php. The body is { "book": null } when the text is standalone (not part of a book) — a normal state, not an error. The underlying query runs under QueryBuilder's per-user scope, so the context of another user's text is never returned.

Parameters
$textId : int
Return values
JsonResponse

handleBulkAction()

Handle PUT /texts/bulk-action — archive or delete multiple texts.

private handleBulkAction(array<string, mixed> $params) : JsonResponse

The JSON counterpart of the legacy mark-action form POST: it calls the same TextFacade methods, which run under QueryBuilder's automatic per-user scope, so a caller can only affect their own texts regardless of the IDs sent. Only the two destructive actions are exposed here; tag / review / reparse stay on the form path. Delivered as JSON so it works against a configurable API base URL (a form POST would hit the page origin, not the chosen server).

Parameters
$params : array<string, mixed>

{ action: "archive"|"delete", ids: int[] }

Return values
JsonResponse

handleExtractEpubUrl()

Handle Global Digital Library ePUB import requests.

private handleExtractEpubUrl(array<string|int, mixed> $params) : JsonResponse

Downloads the ePUB, extracts its text, and rejects image-only picture books with too little readable content.

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

Request parameters (url)

Return values
JsonResponse

handleGdlSearch()

Handle Global Digital Library search/browse requests.

private handleGdlSearch(array<string|int, mixed> $params) : JsonResponse

An empty query browses the catalog; difficulty tiers come from the client (derived from each book's GDL reading level).

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

Request parameters (q, language_id, page)

Return values
JsonResponse

handleGutenbergSuggestions()

Handle Gutenberg suggestion requests (popular books by language).

private handleGutenbergSuggestions(array<string|int, mixed> $params) : JsonResponse
Parameters
$params : array<string|int, mixed>

Request parameters (language_id, page)

Return values
JsonResponse

handleLibraryPreview()

Handle library preview requests (accurate vocabulary coverage).

private handleLibraryPreview(array<string|int, mixed> $params) : JsonResponse
Parameters
$params : array<string|int, mixed>

Request parameters (url, language_id)

Return values
JsonResponse

handleLibrarySearch()

Handle library search requests.

private handleLibrarySearch(array<string|int, mixed> $params) : JsonResponse
Parameters
$params : array<string|int, mixed>

Request parameters (q, language_id, page)

Return values
JsonResponse

handleReaderLevel()

Handle reader-level requests (vocabulary size + beginner flag).

private handleReaderLevel(array<string|int, mixed> $params) : JsonResponse

Drives beginner-aware ordering of home-page suggestions: beginners see the Global Digital Library's easy readers first, advanced learners see Project Gutenberg first.

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

Request parameters (language_id)

Return values
JsonResponse

resolveLanguageCode()

Resolve a language ID to an ISO 639-1 code for Gutenberg.

private resolveLanguageCode(int $languageId) : string|null

Tries LgSourceLang first, then guesses from LgName.

Parameters
$languageId : int

Language ID

Return values
string|null —

ISO code or null


        

        
    




    

    

                                

                

                                
    

        On this page

        
    


                

                            

            

    

        

            
Search results