Search by

fayne / laravel-ocr

fayne

Laravel OCR with built-in cloud drivers

Package info

github.com/Fayne/laravel-ocr

pkg:composer/fayne/laravel-ocr

Statistics

Installs: 1

Dependents: 0

Suggesters: 0

Stars: 0

Open Issues: 0

v0.1.0 2026-11-17 09:41 UTC

This package is auto-updated.

Last update: 2026-11-17 09:46:25 UTC


README

Laravel OCR

适用于 Laravel 12 / 13(PHP 8.3+)的 OCR 包。核心包提供连接管理、统一的输入与结果以及第三方驱动注册。目前提供的适配器:

驱动类型 API 可选 SDK
tencent GeneralAccurateOCR —
google-vision DOCUMENT_TEXT_DETECTION google/auth:^1.0
aliyun RecognizeGeneral alibabacloud/ocr-api-20210707:^3.1.3
baidu general_basic —
aws-textract DetectDocumentText aws/aws-sdk-php:^3.0

English

安装

composer require fayne/laravel-ocr:^0.1
php artisan vendor:publish --tag=ocr-config

若从本仓库安装,先在宿主 Composer 配置中添加 path repository。

{"type":"path","url":"packages/laravel-ocr","options":{"versions":{"fayne/laravel-ocr":"0.1.0"}}}

腾讯云和百度可直接使用。按需执行对应的 SDK 安装命令。

composer require google/auth:^1.0
composer require alibabacloud/ocr-api-20210707:^3.1.3
composer require aws/aws-sdk-php:^3.0

在 config/ocr.php 中添加所需连接,并将 default 设为默认连接名。

return [
    'default' => env('OCR_CONNECTION', 'tencent-cn'),
    'max_input_bytes' => 4 * 1024 * 1024,
    'connections' => [
        'tencent-cn' => [
            'driver' => 'tencent',
            'secret_id' => env('OCR_TENCENT_SECRET_ID'),
            'secret_key' => env('OCR_TENCENT_SECRET_KEY'),
            'timeout_seconds' => 10,
        ],
        'baidu-main' => [
            'driver' => 'baidu',
            'api_key' => env('OCR_BAIDU_API_KEY'),
            'secret_key' => env('OCR_BAIDU_SECRET_KEY'),
        ],
        'aliyun-main' => [
            'driver' => 'aliyun',
            'access_key_id' => env('OCR_ALIYUN_ACCESS_KEY_ID'),
            'access_key_secret' => env('OCR_ALIYUN_ACCESS_KEY_SECRET'),
        ],
        'aws-main' => [
            'driver' => 'aws-textract',
            'region' => env('OCR_AWS_REGION', 'us-east-1'),
        ],
        'vision' => [
            'driver' => 'google-vision',
            'quota_project' => env('OCR_GOOGLE_QUOTA_PROJECT'),
            'timeout_seconds' => 10,
        ],
    ],
];

Google 需启用 Vision API,并为运行环境配置 Application Default Credentials。quota_project 可选;指定时,调用身份须有权限在该项目使用服务。连接名不决定数据处理区域。

阿里云使用杭州端点,需为 RAM 身份授权。百度需启用通用文字识别标准版,该接口不返回坐标。AWS 使用默认凭据链,运行身份需要 textract:DetectDocumentText 权限。

调用

use Fayne\LaravelOcr\Data\OcrInput;
use Fayne\LaravelOcr\Data\OcrOptions;
use Fayne\LaravelOcr\Facades\OCR;

$input = OcrInput::storage('ocr/sample.jpg', 'private');
$result = OCR::recognize($input);
echo $result->text;

$result = OCR::driver('vision')->recognize(
    $input,
    new OcrOptions(languageHints: ['zh', 'en']),
);

也支持可信的本地绝对路径 OcrInput::path(...) 和内存字节 OcrInput::bytes(...)。在宿主中验证用户上传、文件归属及访问权限后再传入。默认最大 4 MiB,并受驱动能力限制。首版只支持同步图片识别,不含 URL、PDF、结构化票据和云任务轮询。

结果包含全文、页与文字块。各厂商的切块粒度可能不同;坐标注明像素或归一化单位;不可用的坐标和置信度为 null。空白图可成功返回空文本。仅 Google Vision 适配器接受语言提示,当前适配器均不接受额外厂商参数。只有设置 includeRaw: true 才返回原始响应。

所有预期错误继承 OcrException。可以区分输入、配置、能力、鉴权、权限、限流及服务异常,限流在厂商返回相关信息时提供 retryAfterSeconds。包不自动重试或切换厂商;超时请求可能已经到达服务端。不要记录原图、凭据或识别内容。

扩展

实现 Contracts\OcrDriver,由你的 Laravel Service Provider 注册:

$this->callAfterResolving(
    \Fayne\LaravelOcr\OcrManager::class,
    static function ($manager): void {
        $manager->extend('acme', static fn ($app, array $config) => new AcmeDriver($config));
    },
);

然后添加 'acme-main' => ['driver' => 'acme'] 及驱动专用配置。capabilities() 返回以能力 ID 为键的 CapabilityProfile;第三方能力使用 acme:passport 等名称,驱动接收的 ResolvedInput 已通过连接层的大小和 MIME 校验。普通应用依赖 Facade 或注入 OcrManager 即可。

在核心包目录运行 composer install 和 composer test。适配器测试使用模拟响应,不需要云凭据。

贡献与反馈

请使用 GitHub 的 缺陷报告或功能建议模板。开发和提交步骤见贡献指南。漏洞请通过安全报告渠道私下提交。变更记录见 CHANGELOG.md。

许可证

本包采用专有许可,使用和分发须遵循 LICENSE.md 的授权条款。