fayne / laravel-ocr
Laravel OCR with built-in cloud drivers
Requires
- php: ^8.3
- ext-ctype: *
- ext-fileinfo: *
- illuminate/contracts: ^12.0 || ^13.0
- illuminate/filesystem: ^12.0 || ^13.0
- illuminate/http: ^12.0 || ^13.0
- illuminate/support: ^12.0 || ^13.0
Requires (Dev)
- alibabacloud/ocr-api-20210707: ^3.1.3
- aws/aws-sdk-php: ^3.0
- google/auth: ^1.0
- laravel/pint: ^1.0
- orchestra/testbench: ^10.0 || ^11.0
Suggests
- alibabacloud/ocr-api-20210707: Required for the Aliyun driver (^3.1.3)
- aws/aws-sdk-php: Required for the AwsTextract driver (^3.0)
- google/auth: Required for the GoogleVision driver (^1.0)
Provides
None
Conflicts
None
Replaces
None
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 |
安装
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 的授权条款。