PHP 与 Laravel 中的 OG 图片
本指南介绍如何在 PHP 与 Laravel 中使用 FastOG 实现 OG 图片——在后端签署 HMAC URL，将其放入 meta 标签中，您的博客文章即可自动获得动态 Open Graph 图片。基于订阅制，提供免费账户（选择 Dynamic API 套餐；在仪表盘中创建您的 API 密钥）；您可以使用免费的 OG 图片测试器在接入前预览模板。
在 PHP 和 Laravel 中实现 HMAC 签名 OG 图片 URL 的完整指南。
快速开始
1. 创建签名服务
php
// app/Services/QuickogSigner.php
namespace App\Services;
class QuickogSigner
{
public function generateSignedOgUrl(array $params, array $options = []): string
{
$baseUrl = $options['base_url'] ?? config('services.fastog.base_url', 'https://fastog.com/api/v1/og');
$apiKey = $options['api_key'] ?? config('services.fastog.api_key');
$hmacSecret = $options['hmac_secret'] ?? config('services.fastog.hmac_secret');
if (!$apiKey || !$hmacSecret) {
throw new \RuntimeException('Missing FASTOG_API_KEY or FASTOG_HMAC_SECRET');
}
// Canonical query: every param except `s`, including `key`
$all = array_merge($params, ['key' => $apiKey]);
$pairs = [];
foreach ($all as $k => $v) {
$values = is_array($v) ? $v : [$v];
sort($values, SORT_STRING);
foreach ($values as $vv) {
$pairs[] = rawurlencode((string) $k) . '=' . rawurlencode((string) $vv);
}
}
sort($pairs, SORT_STRING);
$canonical = implode('&', $pairs);
$signature = hash_hmac('sha256', 'GET/api/v1/og' . "\n" . $canonical, $hmacSecret);
return $baseUrl . '?' . http_build_query(array_merge($all, ['s' => $signature]), '', '&', PHP_QUERY_RFC3986);
}
}
为什么使用 rawurlencode？ 规范查询按 RFC-3986 进行百分号编码（空格 → %20，而非 +）。rawurlencode 与此完全匹配——urlencode 则不然（它会生成 +），这会破坏签名并返回 invalid_signature。将 PHP_QUERY_RFC3986 传递给 http_build_query 可确保最终 URL 保持相同的编码。
2. 配置
php
// config/services.php
return [
// ...
'fastog' => [
'api_key' => env('FASTOG_API_KEY'),
'hmac_secret' => env('FASTOG_HMAC_SECRET'),
'base_url' => env('FASTOG_BASE_URL', 'https://fastog.com/api/v1/og'),
],
];
bash
# .env
FASTOG_API_KEY=sk_your_full_api_key_here
FASTOG_HMAC_SECRET=your_64_char_hex_secret_here
3. 注册为单例
php
// app/Providers/AppServiceProvider.php
use App\Services\QuickogSigner;
public function register(): void
{
$this->app->singleton(QuickogSigner::class);
}
Laravel Blade
blade
{{-- resources/views/blog/show.blade.php --}}
@extends('layouts.app')
@section('head')
<meta property="og:image" content="{{ $ogImageUrl }}" />
<meta property="og:title" content="{{ $post->title }}" />
<meta property="og:description" content="{{ $post->excerpt }}" />
@endsection
@section('content')
<article>
<h1>{{ $post->title }}</h1>
<p>{{ $post->excerpt }}</p>
</article>
@endsection
控制器
php
// app/Http/Controllers/BlogController.php
namespace App\Http\Controllers;
use App\Services\QuickogSigner;
use App\Models\Post;
class BlogController extends Controller
{
public function show(Post $post, QuickogSigner $signer)
{
$ogImageUrl = $signer->generateSignedOgUrl([
'template' => 'blog',
'title' => $post->title,
'subtitle' => $post->excerpt,
'author' => $post->author->name,
]);
return view('blog.show', compact('post', 'ogImageUrl'));
}
}
API 路由
php
// routes/api.php
use App\Services\QuickogSigner;
use Illuminate\Http\Request;
Route::get('/og', function (Request $request, QuickogSigner $signer) {
$validated = $request->validate([
'title' => 'required|string',
'template' => 'nullable|string',
]);
$ogImageUrl = $signer->generateSignedOgUrl([
'template' => $validated['template'] ?? 'default',
'title' => $validated['title'],
]);
return response()->json(['ogImageUrl' => $ogImageUrl]);
});
电子商务示例
php
// app/Http/Controllers/ProductController.php
public function show(Product $product, QuickogSigner $signer)
{
$ogImageUrl = $signer->generateSignedOgUrl([
'template' => 'ecommerce',
'title' => $product->name,
'price' => $product->formatted_price,
'image' => $product->image_url,
]);
return view('products.show', compact('product', 'ogImageUrl'));
}
博客文章示例
php
// app/Http/Controllers/ProfileController.php
public function show(User $user, QuickogSigner $signer)
{
$ogImageUrl = $signer->generateSignedOgUrl([
'template' => 'blog',
'title' => $user->name,
'subtitle' => $user->bio,
'author' => $user->name,
]);
return view('profile.show', compact('user', 'ogImageUrl'));
}
纯 PHP（无框架）
php
// lib/fastog-signer.php
function generateSignedOgUrl(array $params, array $options = []): string
{
$baseUrl = $options['base_url'] ?? 'https://fastog.com/api/v1/og';
$apiKey = $options['api_key'] ?? $_ENV['FASTOG_API_KEY'];
$hmacSecret = $options['hmac_secret'] ?? $_ENV['FASTOG_HMAC_SECRET'];
$all = array_merge($params, ['key' => $apiKey]);
$pairs = [];
foreach ($all as $k => $v) {
$values = is_array($v) ? $v : [$v];
sort($values, SORT_STRING);
foreach ($values as $vv) {
$pairs[] = rawurlencode((string) $k) . '=' . rawurlencode((string) $vv);
}
}
sort($pairs, SORT_STRING);
$canonical = implode('&', $pairs);
$signature = hash_hmac('sha256', 'GET/api/v1/og' . "\n" . $canonical, $hmacSecret);
return $baseUrl . '?' . http_build_query(array_merge($all, ['s' => $signature]), '', '&', PHP_QUERY_RFC3986);
}
php
// index.php
require_once 'lib/fastog-signer.php';
$ogUrl = generateSignedOgUrl([
'template' => 'blog',
'title' => 'My Blog Post',
]);
?>
<!DOCTYPE html>
<html>
<head>
<meta property="og:image" content="<?= htmlspecialchars($ogUrl) ?>" />
<meta property="og:title" content="My Blog Post" />
</head>
<body>
<h1>My Blog Post</h1>
</body>
</html>
常见陷阱
签名错误的消息
❌ 错误：hash_hmac('sha256', 'GET/api/v1/og' . $canonical, $hmacSecret) — 缺少换行分隔符。
✅ 正确：hash_hmac('sha256', 'GET/api/v1/og' . "\n" . $canonical, $hmacSecret) — 方法 + 路径、换行、然后是规范化查询字符串。
将 key 排除在签名之外
❌ 错误：仅对内容参数签名，之后再将 key 附加到 URL。
✅ 正确：key 在构建规范化查询字符串之前合并到参数中，并出现在最终 URL 中。
重复参数（数组）
将数组值传递给 generateSignedOgUrl，并让 http_build_query 编写 URL：它会生成括号键（features[0]=a&features[1]=b），而规范化签名则签署普通的重复键（features=a&features=b）。不要在 URL 中手动构建 features=a&features=b — PHP 会将重复键解码为标量（最后一个值生效），因此服务器会重建不同的规范化字符串并返回 invalid_signature 拒绝请求。
401 missing_signature / invalid_signature
missing_signature（401）表示 URL 中缺少 key 或 s。invalid_signature（401）表示规范化字符串不匹配 — 请确认签名消息中的换行、两侧使用相同的 hmac_secret、每个键和值都使用 rawurlencode（而非 urlencode），以及 URL 中重复参数使用括号键。
暴露 HMAC 密钥
切勿在前端 JavaScript 或公开配置文件中暴露 FASTOG_HMAC_SECRET。