laravel-ocr maintained by fayne
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 的授权条款。