README

NativePHP plugin for loading TensorFlow Lite models and running on-device inference from PHP or JavaScript.

This project is intentionally scoped as a small TFLite bridge, not a wakeword engine. Android and iOS do not provide reliable custom wakeword support in the way this project originally explored, so the useful surface is model storage, model metadata, and direct inference.

Status

• Android: implemented for single-input models.
• iOS: bridge stubs only; not implemented yet.
• Supported tensor types: FLOAT32, INT32, UINT8, and INT8.
• Current limitation: one input tensor per model. Multiple outputs are supported by choosing an outputIndex.
• Build validation: installed from Packagist into a clean NativePHP Mobile 3.3 app and compiled with ./gradlew assembleRelease.

Requirements

• NativePHP Mobile 3 app.
• PHP 8.3+.
• Android min SDK 33 or higher.
• Android project generated by NativePHP.
• TensorFlow Lite Android dependency from nativephp.json.

Install

Require and register the plugin from your NativePHP mobile app:

composer require 1338/nativephp-tflite
php artisan native:plugin:register 1338/nativephp-tflite
php artisan native:plugin:validate
php artisan native:install --force

PHP Usage

Load a model bundled in Android assets:

use OneThreeThreeEight\NativephpTflite\Tflite;

$info = Tflite::loadModelFromAsset('models/example.tflite');

Store a model in app storage:

$base64 = base64_encode(file_get_contents('/local/path/to/model.tflite'));

Tflite::addModel('model.tflite', $base64);
Tflite::loadModelFromFile('model.tflite');

Inspect the loaded model:

$info = Tflite::modelInfo();

Run inference:

$result = Tflite::run([
    0.1,
    0.2,
    0.3,
]);

$output = $result['data'];

The input array is flattened before being passed to TensorFlow Lite, so nested arrays are allowed:

$result = Tflite::run([
    [0.1, 0.2],
    [0.3, 0.4],
]);

For models with multiple outputs, choose the output tensor:

$result = Tflite::run($input, outputIndex: 1);

JavaScript Usage

import {
  loadModelFromAsset,
  loadModelFromFile,
  modelInfo,
  run,
} from '/_native/plugins/tflite/tflite.js';

await loadModelFromAsset('models/example.tflite');

const info = await modelInfo();
const result = await run([0.1, 0.2, 0.3]);

API

Tflite::loadModelFromAsset(string $asset): ?array

Loads a .tflite model from Android assets and returns model metadata.

Tflite::addModel(string $name, string $base64Data): ?array

Stores a base64-encoded model in app-private storage under tflite_models/.

Tflite::listModels(): array

Returns stored model files with name, size, and lastModified.

Tflite::deleteModel(string $name): bool

Deletes a stored model file.

Tflite::loadModelFromFile(string $filename): ?array

Loads a model previously stored with addModel() or copyAssetToStorage().

Tflite::copyAssetToStorage(string $assetName, string $targetName): ?array

Copies a bundled asset model into app-private model storage.

Tflite::modelInfo(): ?array

Returns metadata for the currently loaded model:

[
    'loaded' => true,
    'model' => 'file:model.tflite',
    'inputs' => [
        [
            'index' => 0,
            'name' => 'serving_default_input',
            'shape' => [1, 224, 224, 3],
            'dataType' => 'FLOAT32',
            'bytes' => 602112,
        ],
    ],
    'outputs' => [
        [
            'index' => 0,
            'name' => 'StatefulPartitionedCall',
            'shape' => [1, 1001],
            'dataType' => 'FLOAT32',
            'bytes' => 4004,
        ],
    ],
]

Tflite::run(array $input, int $outputIndex = 0): ?array

Runs inference against the loaded model.

Return shape:

[
    'outputIndex' => 0,
    'shape' => [1, 1001],
    'dataType' => 'FLOAT32',
    'data' => [0.01, 0.93, 0.06],
]

Security Notes

• Stored model names are sanitized to a basename before writing to app storage.
• Models are stored in the app-private files directory.
• This plugin does not download models by itself. If your app downloads models, validate source, integrity, size, and expected tensor metadata before loading.

Roadmap

• Add tests for PHP facade behavior.
• Add Kotlin tests for tensor flattening and output decoding.
• Support multiple input tensors.
• Add optional output reshaping instead of returning a flat array only.
• Implement iOS with TensorFlow Lite Swift or document Android-only support permanently.

Not Goals

• Wakeword detection.
• Background audio capture.
• Always-on microphone behavior.
• Model training or conversion.