OG-изображения в PHP и Laravel
Это руководство описывает работу с OG-изображениями в PHP и Laravel с использованием FastOG — подпишите HMAC-URL на вашем бэкенде, добавьте его в мета-тег, и ваши записи в блоге автоматически получат динамические Open Graph изображения. Подписка с бесплатным аккаунтом (выберите тариф Dynamic API; создайте API-ключ в панели управления); воспользуйтесь бесплатным тестером OG-изображений, чтобы просмотреть шаблон перед подключением.
Полное руководство по реализации HMAC-подписанных URL для OG-изображений в PHP и Laravel.
Быстрый старт
1. Создание сервиса подписи
// 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. Конфигурация
// 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'),
],
];
# .env
FASTOG_API_KEY=sk_your_full_api_key_here
FASTOG_HMAC_SECRET=your_64_char_hex_secret_here
3. Регистрация как синглтон
// app/Providers/AppServiceProvider.php
use App\Services\QuickogSigner;
public function register(): void
{
$this->app->singleton(QuickogSigner::class);
}
Laravel 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
Контроллер
// 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-маршрут
// 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]);
});
Пример для электронной коммерции
// 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'));
}
Пример записи в блоге
// 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 (без фреймворка)
// 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);
}
// 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). Не собирайте features=a&features=b в URL вручную — PHP декодирует повторяющиеся ключи в скаляр (побеждает последнее значение), поэтому сервер пересобирает другой канонический запрос и отклоняет его с invalid_signature.
401 missing_signature / invalid_signature
missing_signature (401) означает, что key или s отсутствует в URL. invalid_signature (401) означает, что канонический запрос не совпал — проверьте новую строку в подписанном сообщении, одинаковый hmac_secret на обеих сторонах, rawurlencode (не urlencode) для каждого ключа и значения, а также ключи в скобках для повторяющихся параметров в URL.
Раскрытие HMAC-секрета
Никогда не раскрывайте FASTOG_HMAC_SECRET в JavaScript на фронтенде или в публичных файлах конфигурации.