TextScoringService
in package
Service for calculating text difficulty scores.
Analyzes texts against the user's known vocabulary to determine comprehensibility - useful for recommending appropriate reading material.
Tags
Table of Contents
Methods
- getRecommendedTexts() : array<string|int, TextScore>
- Get texts recommended for reading based on comprehensibility.
- scoreText() : TextScore
- Calculate the difficulty score for a single text.
- scoreTexts() : array<int, TextScore>
- Score multiple texts at once (for listing/recommendations).
- calculateVocabularyStats() : array{total: int, known: int, learning: int, unknown: int}
- Calculate vocabulary statistics for a single text.
- calculateVocabularyStatsForTexts() : array<int, array{total: int, known: int, learning: int, unknown: int}>
- Calculate vocabulary statistics for multiple texts.
- filterOwnedTextIds() : array<string|int, int>
- Filter a list of text IDs down to those owned by the current user.
- getUnknownWords() : array<string|int, string>
- Get the list of unknown words in a text.
- ownsText() : bool
- Check if the current user owns the given text.
Methods
getRecommendedTexts()
Get texts recommended for reading based on comprehensibility.
public
getRecommendedTexts(int $languageId[, float $targetComprehensibility = 0.95 ][, int $limit = 10 ]) : array<string|int, TextScore>
Returns texts ordered by proximity to optimal comprehensibility (95%).
Parameters
- $languageId : int
-
The language to filter by
- $targetComprehensibility : float = 0.95
-
Target comprehensibility (default 0.95)
- $limit : int = 10
-
Maximum number of texts to return
Return values
array<string|int, TextScore> —Array of TextScore objects, best matches first
scoreText()
Calculate the difficulty score for a single text.
public
scoreText(int $textId[, int $unknownWordsLimit = 20 ]) : TextScore
Parameters
- $textId : int
-
The text ID to score
- $unknownWordsLimit : int = 20
-
Maximum unknown words to return in preview
Return values
TextScore —The calculated score
scoreTexts()
Score multiple texts at once (for listing/recommendations).
public
scoreTexts(array<string|int, int> $textIds) : array<int, TextScore>
Parameters
- $textIds : array<string|int, int>
-
Array of text IDs to score
Return values
array<int, TextScore> —Map of textId => TextScore
calculateVocabularyStats()
Calculate vocabulary statistics for a single text.
private
calculateVocabularyStats(int $textId) : array{total: int, known: int, learning: int, unknown: int}
Parameters
- $textId : int
-
The text ID
Return values
array{total: int, known: int, learning: int, unknown: int}calculateVocabularyStatsForTexts()
Calculate vocabulary statistics for multiple texts.
private
calculateVocabularyStatsForTexts(array<string|int, int> $textIds) : array<int, array{total: int, known: int, learning: int, unknown: int}>
Parameters
- $textIds : array<string|int, int>
-
Array of text IDs
Return values
array<int, array{total: int, known: int, learning: int, unknown: int}>filterOwnedTextIds()
Filter a list of text IDs down to those owned by the current user.
private
filterOwnedTextIds(array<string|int, int> $textIds) : array<string|int, int>
Mirrors WordListService::filterOwnedWordIds — runs a single user-scoped SELECT and returns the surviving IDs.
Parameters
- $textIds : array<string|int, int>
-
Array of text IDs
Return values
array<string|int, int> —Owned IDs (subset of $textIds)
getUnknownWords()
Get the list of unknown words in a text.
private
getUnknownWords(int $textId, int $limit) : array<string|int, string>
Parameters
- $textId : int
-
The text ID
- $limit : int
-
Maximum number of words to return
Return values
array<string|int, string> —Array of unknown word texts
ownsText()
Check if the current user owns the given text.
private
ownsText(int $textId) : bool
texts is in QueryBuilder::USER_SCOPED_TABLES so the where + count
returns 0 for unowned IDs in multi-user mode. In single-user mode
the auto-scope is a no-op and existence is the only check.
Parameters
- $textId : int
-
The text ID to check
Return values
bool —True if the text exists and belongs to the caller