Documentation

TextApiHandler
in package
implements ApiRoutableInterface uses ApiRoutableTrait

Handler for text-related API operations.

Extracted from api_v1.php lines 262-373.

Table of Contents

Interfaces

ApiRoutableInterface
Interface for API handlers that participate in route dispatch.

Properties

$discoveryService  : WordDiscoveryService
$textService  : TextFacade

Methods

__construct()  : mixed
editTermForm()  : string
Full form for terms edition in a given text.
formatArchivedTextsByLanguage()  : array{texts: array, pagination: array}
Format response for getting archived texts by language.
formatEditTermForm()  : array{html: string}
Format response for edit term form HTML.
formatGetAnnotation()  : array{items: array|null, config: array}|array{error: string}
Format response for getting annotation.
formatGetPrintItems()  : array{items: array, config: array}|array{error: string}
Format response for getting print items.
formatGetRecommendedTexts()  : array{recommendations: array[], target_comprehensibility: float}
Get recommended texts for a language based on comprehensibility.
formatGetTextScore()  : array<string, mixed>
Get the difficulty score for a single text.
formatGetTextScores()  : array{scores: array>}
Get scores for multiple texts.
formatGetWords()  : array{words: array, config: array}|array{error: string}
Format response for getting text words.
formatMarkAllIgnored()  : array{count: int, words?: array}
Format response for marking all words as ignored.
formatMarkAllWellKnown()  : array{count: int, words?: array}
Format response for marking all words as well-known.
formatSetAnnotation()  : array{save_impr_text?: string|null, error?: string}
Format response for setting annotation.
formatSetAudioPosition()  : array{audio: string}
Format response for setting audio position.
formatSetDisplayMode()  : array{updated: bool, error?: string}
Format response for setting display mode.
formatSetTextPosition()  : array{text: string}
Format response for setting text position.
formatTermTranslations()  : array{term_lc?: string, wid?: int|null, trans?: string, ann_index?: int, term_ord?: int, translations?: string[], language_id?: int, error?: string}
Format response for getting term translations.
formatTextsByLanguage()  : array{texts: array, pagination: array}
Format response for getting texts by language.
getAnnotation()  : array{items: array|null, config: array}|array{error: string}
Get annotation items for improved/annotated text view.
getPrintItems()  : array{items: array, config: array}|array{error: string}
Get print items and configuration for a text.
getTermTranslations()  : array{term_lc?: string, wid?: int|null, trans?: string, ann_index?: int, term_ord?: int, translations?: string[], language_id?: int, error?: string}
Gather useful data to edit a term annotation on a specific text.
getTranslations()  : array<string|int, string>
Find the possible translations for a term.
getWords()  : array{words: array, config: array}|array{error: string}
Get all words for a text for client-side rendering.
makeTrans()  : string
Make the translations choices for a term.
markAllIgnored()  : array{count: int, words?: array}
Mark all unknown words in a text as ignored.
markAllWellKnown()  : array{count: int, words?: array}
Mark all unknown words in a text as well-known.
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
Save the audio position in the text.
saveImprText()  : array{error?: string, success?: string}
Save a text with improved annotations.
saveImprTextData()  : array{success: bool, error?: string, requested?: int, available?: int, position?: int, found?: int}
Save data from printed text.
saveTextPosition()  : void
Save the reading position of the text.
setDisplayMode()  : array{updated: bool, error?: string}
Set display mode settings for a text.
frag()  : string
Extract a fragment from the fragments array.
formatAnnotationError()  : string
Format annotation save error into human-readable message.

Properties

Methods

editTermForm()

Full form for terms edition in a given text.

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

Text ID.

Return values
string —

HTML table for all terms

formatArchivedTextsByLanguage()

Format response for getting archived texts by language.

public formatArchivedTextsByLanguage(int $langId, array<string|int, mixed> $params) : array{texts: array, pagination: array}

Returns paginated archived texts for a specific language (for grouped archived texts page).

Parameters
$langId : int

Language ID

$params : array<string|int, mixed>

Query parameters (page, per_page, sort)

Return values
array{texts: array, pagination: array}

formatEditTermForm()

Format response for edit term form HTML.

public formatEditTermForm(int $textId) : array{html: string}
Parameters
$textId : int

Text ID

Return values
array{html: string}

formatGetAnnotation()

Format response for getting annotation.

public formatGetAnnotation(int $textId) : array{items: array|null, config: array}|array{error: string}
Parameters
$textId : int

Text ID

Return values
array{items: array|null, config: array}|array{error: string}

formatGetPrintItems()

Format response for getting print items.

public formatGetPrintItems(int $textId) : array{items: array, config: array}|array{error: string}
Parameters
$textId : int

Text ID

Return values
array{items: array, config: array}|array{error: string}

formatGetRecommendedTexts()

Get recommended texts for a language based on comprehensibility.

public formatGetRecommendedTexts(int $languageId, array<string|int, mixed> $params) : array{recommendations: array[], target_comprehensibility: float}
Parameters
$languageId : int

Language ID

$params : array<string|int, mixed>

Query parameters (target, limit)

Return values
array{recommendations: array[], target_comprehensibility: float}

formatGetTextScore()

Get the difficulty score for a single text.

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

Text ID to score

Return values
array<string, mixed>

formatGetTextScores()

Get scores for multiple texts.

public formatGetTextScores(array<string|int, int> $textIds) : array{scores: array>}
Parameters
$textIds : array<string|int, int>

Array of text IDs

Return values
array{scores: array>}

formatGetWords()

Format response for getting text words.

public formatGetWords(int $textId) : array{words: array, config: array}|array{error: string}
Parameters
$textId : int

Text ID

Return values
array{words: array, config: array}|array{error: string}

formatMarkAllIgnored()

Format response for marking all words as ignored.

public formatMarkAllIgnored(int $textId) : array{count: int, words?: array}
Parameters
$textId : int

Text ID

Return values
array{count: int, words?: array}

formatMarkAllWellKnown()

Format response for marking all words as well-known.

public formatMarkAllWellKnown(int $textId) : array{count: int, words?: array}
Parameters
$textId : int

Text ID

Return values
array{count: int, words?: array}

formatSetAnnotation()

Format response for setting annotation.

public formatSetAnnotation(int $textId, string $elem, string $data) : array{save_impr_text?: string|null, error?: string}
Parameters
$textId : int

Text ID

$elem : string

Element selector

$data : string

JSON-encoded data

Return values
array{save_impr_text?: string|null, error?: string}

formatSetAudioPosition()

Format response for setting audio position.

public formatSetAudioPosition(int $textId, int $position) : array{audio: string}
Parameters
$textId : int

Text ID

$position : int

Audio position

Return values
array{audio: string}

formatSetDisplayMode()

Format response for setting display mode.

public formatSetDisplayMode(int $textId, array<string|int, mixed> $params) : array{updated: bool, error?: string}
Parameters
$textId : int

Text ID

$params : array<string|int, mixed>

Display mode parameters

Return values
array{updated: bool, error?: string}

formatSetTextPosition()

Format response for setting text position.

public formatSetTextPosition(int $textId, int $position) : array{text: string}
Parameters
$textId : int

Text ID

$position : int

Position

Return values
array{text: string}

formatTermTranslations()

Format response for getting term translations.

public formatTermTranslations(string $termLc, int $textId) : array{term_lc?: string, wid?: int|null, trans?: string, ann_index?: int, term_ord?: int, translations?: string[], language_id?: int, error?: string}
Parameters
$termLc : string

Term in lowercase

$textId : int

Text ID

Return values
array{term_lc?: string, wid?: int|null, trans?: string, ann_index?: int, term_ord?: int, translations?: string[], language_id?: int, error?: string}

formatTextsByLanguage()

Format response for getting texts by language.

public formatTextsByLanguage(int $langId, array<string|int, mixed> $params) : array{texts: array, pagination: array}

Returns paginated texts for a specific language (for grouped texts page).

Parameters
$langId : int

Language ID

$params : array<string|int, mixed>

Query parameters (page, per_page, sort)

Return values
array{texts: array, pagination: array}

getAnnotation()

Get annotation items for improved/annotated text view.

public getAnnotation(int $textId) : array{items: array|null, config: array}|array{error: string}

Returns parsed annotation data for client-side rendering.

Parameters
$textId : int

Text ID

Return values
array{items: array|null, config: array}|array{error: string}

getPrintItems()

Get print items and configuration for a text.

public getPrintItems(int $textId) : array{items: array, config: array}|array{error: string}

Returns structured text items suitable for client-side rendering of the print view with annotation options.

Parameters
$textId : int

Text ID

Return values
array{items: array, config: array}|array{error: string}

getTermTranslations()

Gather useful data to edit a term annotation on a specific text.

public getTermTranslations(string $wordlc, int $textid) : array{term_lc?: string, wid?: int|null, trans?: string, ann_index?: int, term_ord?: int, translations?: string[], language_id?: int, error?: string}
Parameters
$wordlc : string

Term in lower case

$textid : int

Text ID

Return values
array{term_lc?: string, wid?: int|null, trans?: string, ann_index?: int, term_ord?: int, translations?: string[], language_id?: int, error?: string}

getTranslations()

Find the possible translations for a term.

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

Term ID

Return values
array<string|int, string> —

Return the possible translations.

getWords()

Get all words for a text for client-side rendering.

public getWords(int $textId) : array{words: array, config: array}|array{error: string}

Returns word tokens with position, status, translation, etc.

Parameters
$textId : int

Text ID

Return values
array{words: array, config: array}|array{error: string}

makeTrans()

Make the translations choices for a term.

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

Word unique index in the form

$wid : int|null

Word ID or null

$trans : string

Current translation set for the term, may be empty

$word : string

Term text

$lang : int

Language ID

Return values
string —

HTML-formatted string

markAllIgnored()

Mark all unknown words in a text as ignored.

public markAllIgnored(int $textId) : array{count: int, words?: array}
Parameters
$textId : int

Text ID

Return values
array{count: int, words?: array}

markAllWellKnown()

Mark all unknown words in a text as well-known.

public markAllWellKnown(int $textId) : array{count: int, words?: array}
Parameters
$textId : int

Text ID

Return values
array{count: int, words?: array}

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()

Save the audio position in the text.

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

Text ID

$audioposition : int

Audio position

saveImprText()

Save a text with improved annotations.

public saveImprText(int $textid, string $elem, object $data) : array{error?: string, success?: string}
Parameters
$textid : int

Text ID

$elem : string

Element to select

$data : object

Data element

Return values
array{error?: string, success?: string}

saveImprTextData()

Save data from printed text.

public saveImprTextData(int $textid, int $line, string $val) : array{success: bool, error?: string, requested?: int, available?: int, position?: int, found?: int}
Parameters
$textid : int

Text ID

$line : int

Line number to save

$val : string

Proposed new annotation for the term

Return values
array{success: bool, error?: string, requested?: int, available?: int, position?: int, found?: int} —

Result data with success flag and optional error details

saveTextPosition()

Save the reading position of the text.

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

Text ID

$position : int

Position in text to save

setDisplayMode()

Set display mode settings for a text.

public setDisplayMode(int $textId, int|null $annotations, bool|null $romanization, bool|null $translation) : array{updated: bool, error?: string}
Parameters
$textId : int

Text ID

$annotations : int|null

Annotation mode (0=none, 1=translations, 2=romanization, 3=both)

$romanization : bool|null

Whether to show romanization

$translation : bool|null

Whether to show translation

Return values
array{updated: bool, error?: string}

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

formatAnnotationError()

Format annotation save error into human-readable message.

private formatAnnotationError(array{success: bool, error?: string, requested?: int, available?: int, position?: int, found?: int} $result) : string
Parameters
$result : array{success: bool, error?: string, requested?: int, available?: int, position?: int, found?: int}
Return values
string —

Formatted error message


        

        
    




    

    

                                

                

                                
    

        On this page

        
    


                

                            

            

    

        

            
Search results