NlpServiceHandler
in package
implements
ApiRoutableInterface
uses
ApiRoutableTrait
Handler for communicating with the Python NLP microservice.
Provides text-to-speech (Piper TTS), text parsing (MeCab/Jieba), and voice management functionality.
Table of Contents
Interfaces
- ApiRoutableInterface
- Interface for API handlers that participate in route dispatch.
Properties
- $baseUrl : string
- $httpClient : NlpHttpClient
- $timeout : int
Methods
- __construct() : mixed
- checkLemmatizationSupport() : array<string|int, mixed>
- Check if a language is supported for lemmatization.
- deleteVoice() : bool
- Delete an installed voice.
- downloadVoice() : bool
- Download a voice from the catalog.
- getAvailableLemmatizers() : array<string|int, mixed>
- Get list of available lemmatizers and their supported languages.
- getAvailableParsers() : array<string|int, mixed>
- Get list of available parsers.
- getInstalledVoices() : array<string|int, mixed>
- Get list of installed voices only.
- getVoices() : array<string|int, mixed>
- Get list of all voices (installed and available for download).
- isAvailable() : bool
- Check if the NLP service is available.
- lemmatize() : string|null
- Lemmatize a single word using the NLP service.
- lemmatizeBatch() : array<string, string|null>
- Lemmatize multiple words using the NLP service.
- parse() : array<string|int, mixed>|null
- Parse text using MeCab or Jieba.
- routeDelete() : JsonResponse
- Handle a DELETE request for this resource.
- routeGet() : JsonResponse
- Handle a GET request for this resource.
- routePost() : JsonResponse
- Handle a POST request for this resource.
- routePut() : JsonResponse
- speak() : string|null
- Synthesize speech using Piper TTS.
- frag() : string
- Extract a fragment from the fragments array.
- denyIfNotAdmin() : JsonResponse|null
- Reject the request unless the caller may manage shared voice models.
Properties
$baseUrl
private
string
$baseUrl
$httpClient
private
NlpHttpClient
$httpClient
$timeout
private
int
$timeout
Methods
__construct()
public
__construct([NlpHttpClient|null $httpClient = null ]) : mixed
Parameters
- $httpClient : NlpHttpClient|null = null
checkLemmatizationSupport()
Check if a language is supported for lemmatization.
public
checkLemmatizationSupport(string $languageCode) : array<string|int, mixed>
Parameters
- $languageCode : string
-
ISO language code
Return values
array<string|int, mixed> —Language support information
deleteVoice()
Delete an installed voice.
public
deleteVoice(string $voiceId) : bool
Parameters
- $voiceId : string
-
The voice ID to delete
Return values
bool —True on success
downloadVoice()
Download a voice from the catalog.
public
downloadVoice(string $voiceId) : bool
Parameters
- $voiceId : string
-
The voice ID to download
Return values
bool —True on success
getAvailableLemmatizers()
Get list of available lemmatizers and their supported languages.
public
getAvailableLemmatizers() : array<string|int, mixed>
Return values
array<string|int, mixed> —Lemmatizer information
getAvailableParsers()
Get list of available parsers.
public
getAvailableParsers() : array<string|int, mixed>
Return values
array<string|int, mixed> —List of parser objects
getInstalledVoices()
Get list of installed voices only.
public
getInstalledVoices() : array<string|int, mixed>
Return values
array<string|int, mixed> —List of installed voice objects
getVoices()
Get list of all voices (installed and available for download).
public
getVoices() : array<string|int, mixed>
Return values
array<string|int, mixed> —List of voice objects
isAvailable()
Check if the NLP service is available.
public
isAvailable() : bool
Return values
boollemmatize()
Lemmatize a single word using the NLP service.
public
lemmatize(string $word, string $languageCode[, string $lemmatizer = 'spacy' ]) : string|null
Parameters
- $word : string
-
The word to lemmatize
- $languageCode : string
-
ISO language code (e.g., 'en', 'de')
- $lemmatizer : string = 'spacy'
-
Lemmatizer type: 'spacy' (default)
Return values
string|null —The lemma, or null if word is already base form or error
lemmatizeBatch()
Lemmatize multiple words using the NLP service.
public
lemmatizeBatch(array<int, string> $words, string $languageCode[, string $lemmatizer = 'spacy' ]) : array<string, string|null>
Parameters
- $words : array<int, string>
-
Words to lemmatize
- $languageCode : string
-
ISO language code
- $lemmatizer : string = 'spacy'
-
Lemmatizer type: 'spacy' (default)
Return values
array<string, string|null> —Mapping of words to lemmas
parse()
Parse text using MeCab or Jieba.
public
parse(string $text, string $parser) : array<string|int, mixed>|null
Parameters
- $text : string
-
The text to parse
- $parser : string
-
Parser type: 'mecab' or 'jieba'
Return values
array<string|int, mixed>|null —Parsed result with sentences and tokens, or null on failure
routeDelete()
Handle a DELETE request for this resource.
public
routeDelete(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/body parameters
Return values
JsonResponserouteGet()
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
JsonResponseroutePost()
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
JsonResponseroutePut()
public
routePut(array<string|int, mixed> $fragments, array<string|int, mixed> $params) : JsonResponse
Parameters
- $fragments : array<string|int, mixed>
- $params : array<string|int, mixed>
Return values
JsonResponsespeak()
Synthesize speech using Piper TTS.
public
speak(string $text, string $voiceId) : string|null
Parameters
- $text : string
-
The text to speak
- $voiceId : string
-
The Piper voice ID
Return values
string|null —Base64 data URL of WAV audio, or null on failure
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
denyIfNotAdmin()
Reject the request unless the caller may manage shared voice models.
private
denyIfNotAdmin() : JsonResponse|null
Voices live on the NLP service and are shared by every user, so adding
or removing one is a server-level operation, not a per-user one. The
API's own gate only checks authentication, which would let any logged-in
user delete a voice others depend on or fill the disk with downloads.
Mirrors the inline admin check ApiV1 already applies to media-files,
and — like AdminMiddleware — is a no-op when multi-user mode is off.
Return values
JsonResponse|null —Error response, or null when allowed