はじめに
- 主な機能
- 例
インストール
- 要件
使用法
設定
高度な使用法
最適化
一般的なパターン
制限事項
- Redisクラスターモード
サポートガイドライン
- コミュニティ主導のサポート
- バグと機能の優先順位付け
ライセンス - MITライセンス

はじめに

Recallは、Laravelのための高性能なRedisクライアントサイドキャッシュパッケージです。これは、Redis 6のクライアントサイドキャッシング機能を利用し、自動無効化を行うことで、Redisへの往復回数とレイテンシを劇的に削減します。Laravel Octane環境専用に構築されており、APCuまたはSwoole Tableをローカルキャッシュ層として使用し、無効化メッセージを介してRedisと同期を保ちます。

Redisから値を取得すると、Recallはそれをローカルに保存します。その値がRedisで変更されると（どのクライアントからでも）、RedisはRecallにローカルコピーを無効化するように通知します。これにより、メモリ内キャッシングの速度とRedisの一貫性の保証を得ることができます。

主な機能

自動無効化：キャッシュされたキーが変更されたときにRedisがアプリケーションに通知し、キャッシュの整合性を確保
ゼロ構成：理にかなったデフォルトでボックスからそのまま動作
Octane統合：自動接続ウォーミング、リクエストベースの無効化処理、優雅なシャットダウン
デュアルドライバサポート：すべてのOctaneサーバー用のAPCu、Swoole/OpenSwoole環境用のSwoole Table
選択的キャッシング：ローカルにキャッシュするキーのプレフィックスを構成
競合状態保護：保留中のリクエスト追跡により、同時無効化中の古いデータキャッシングを防止

例

// Recallをキャッシュドライバとして設定
// config/cache.php
'stores' => [
    'recall' => [
        'driver' => 'recall',
    ],
],
 
// Laravelのキャッシュのように使用
use Illuminate\Support\Facades\Cache;
 
// 最初の呼び出し：Redisから取得し、ローカルに保存
$user = Cache::store('recall')->get('user:1');
 
// その後の呼び出し：ローカルAPCu/Swoole Tableから提供（マイクロ秒）
$user = Cache::store('recall')->get('user:1');
 
// user:1がどこかで更新されると、RedisはRecallに無効化を通知
Cache::store('recall')->put('user:1', $newUserData, 3600);
// ローカルキャッシュはすべてのワーカーで自動的に無効化される

インストール

Composer経由でパッケージをインストールします：

composer require defectivecode/laravel-recall

要件

PHP >= 8.4
Laravel 11.xまたは12.x
Laravel Octane
Redis 6.0+（クライアントサイドキャッシングサポートのため）
ext-apcuまたはext-swoole（ローカルキャッシュのために少なくとも1つ必要）

使用法

基本設定

config/cache.phpにRecallキャッシュストアを追加します：

'stores' => [
    // ... 他のストア
 
    'recall' => [
        'driver' => 'recall',
    ],
],

アプリケーションでキャッシュストアを使用します：

use Illuminate\Support\Facades\Cache;
 
// 値を保存する（Redisに書き込み）
Cache::store('recall')->put('key', 'value', 3600);
 
// 値を取得する（最初の呼び出しはRedisに接続し、その後はローカルキャッシュを使用）
$value = Cache::store('recall')->get('key');
 
// 値を削除する
Cache::store('recall')->forget('key');

動作原理

最初の読み取り：値はRedisから取得され、ローカルAPCu/Swoole Tableキャッシュに保存されます
その後の読み取り：値はローカルメモリから直接提供されます（サブミリ秒）
どこでも書き込み：任意のクライアントがRedisでキーを変更すると、Redisは無効化メッセージを送信します
自動無効化：Recallはそのメッセージを受信し、ローカルキャッシュからキーを削除します
次の読み取り：新しい値がRedisから取得され、再度ローカルにキャッシュされます

このパターンは、リクエスト間でワーカーが持続するLaravel Octane環境で特に強力であり、ローカルキャッシュが構築され、多くのリクエストをメモリから提供できるようになります。

Octane統合

Recallは、利用可能な場合にLaravel Octaneと自動的に統合されます：

ワーカー開始：Redis無効化接続を確立（ウォームスタート）
リクエスト受信：保留中の無効化メッセージを処理
ワーカー停止：接続を優雅に閉じる

追加の設定は必要ありません。Octaneがインストールされている場合、自動的に統合されます。

設定

設定ファイルを公開します：

php artisan vendor:publish --tag=recall-config

これにより、以下のオプションを持つ config/recall.php が作成されます：

有効/無効

'enabled' => env('RECALL_ENABLED', true),

無効にされた場合、Recallはローカルキャッシュ層を使用せず、Redisに直接パススルーします。デバッグや段階的な展開に便利です。

Redisストア

'redis_store' => env('RECALL_REDIS_STORE', 'redis'),

Redis操作に使用するLaravelキャッシュストア。これは、config/cache.php に設定されたRedisストアを参照する必要があります。

キャッシュプレフィックス

'cache_prefixes' => [],

これらのプレフィックスに一致するキーのみをローカルにキャッシュします。すべてのキーをキャッシュするには空にしてください。

// ユーザーと設定のキーのみをローカルにキャッシュ
'cache_prefixes' => ['users:', 'settings:', 'config:'],

これは、頻繁に変更される高ボリュームのキーがあり、ローカルキャッシュに保存すべきでない場合に便利です。

ローカルキャッシュの設定

'local_cache' => [
    // ドライバ："apcu"または"swoole"
    'driver' => env('RECALL_LOCAL_DRIVER', 'apcu'),
 
    // ローカルキャッシュキーのプレフィックス
    'key_prefix' => env('RECALL_LOCAL_PREFIX', 'recall:'),
 
    // デフォルトのTTL（無効化を見逃した場合の安全ネット）
    'default_ttl' => (int) env('RECALL_LOCAL_TTL', 3600),
 
    // Swoole Tableサイズ（2の冪、swooleドライバ用のみ）
    'table_size' => (int) env('RECALL_SWOOLE_TABLE_SIZE', 65536),
 
    // Swoole Table内の値あたりの最大バイト数（swooleドライバ用のみ）
    'value_size' => (int) env('RECALL_SWOOLE_VALUE_SIZE', 8192),
],

APCuドライバ（デフォルト）

APCuドライバはすべてのPHP環境とOctaneサーバー（Swoole、RoadRunner、FrankenPHP）で動作します。これは、すべてのPHPプロセスでアクセス可能な共有メモリにキャッシュされた値を保存します。

要件：

ext-apcuがインストールされ、有効にされていること
CLI使用のためにphp.iniで apc.enable_cli=1

Swoole Tableドライバ

Swoole Tableドライバは、Swooleの共有メモリテーブルを使用しており、同一ワーカー内のコルーチン間で一貫したアクセスを提供します。最適なのはSwoole/OpenSwoole環境です。

設定のヒント：

table_size: 2の冪である必要があります（例：65536、131072）。最大エントリー数を決定します。
value_size: シリアル化された値の最大バイト数。大きい値は静かに切り捨てられます。

Octaneリスナー

'listeners' => [
    // ワーカー開始時に接続をウォーム（最初のリクエストレイテンシを削減）
    'warm' => env('RECALL_LISTEN_WARM', true),
 
    // タイックイベントで無効化を処理（より応答性があり、わずかなオーバーヘッド）
    'tick' => env('RECALL_LISTEN_TICK', false),
],

ウォーム接続

有効にすると、RecallはOctaneワーカーが開始したときにRedis無効化サブスクリプションを確立します。これにより、最初のリクエストでの接続遅延が解消されます。

タイック処理

有効にすると、Recallはリクエストイベントに加えてOctaneのタイックイベントで無効化メッセージを処理します。これにより、わずかな追加オーバーヘッドのコストでより応答性のあるキャッシュ無効化を提供します。

高度な使用法

手動無効化処理

長時間実行されるプロセスで無効化を手動で処理する必要がある場合：

use DefectiveCode\Recall\RecallManager;
 
$manager = app(RecallManager::class);
$manager->processInvalidations();

ローカルキャッシュのフラッシュ

Redisに影響を与えずにローカルキャッシュのみをクリアします：

use DefectiveCode\Recall\RecallManager;
 
$manager = app(RecallManager::class);
$manager->flushLocalCache();

接続管理

use DefectiveCode\Recall\RecallManager;
 
$manager = app(RecallManager::class);
 
// 無効化サブスクリプションが接続されているか確認
if ($manager->isConnected()) {
    // ...
}
 
// 手動で切断
$manager->disconnect();

最適化

ワーカーリクエスト制限

Laravel Octaneは、メモリリークを防ぐために設定可能なリクエスト数の後にワーカーを循環させます。ワーカーが循環すると、そのローカルキャッシュがクリアされます。この制限を増やすと、Recallのローカルキャッシュが長く持続し、キャッシュヒット率が向上します。

config/octane.php で：

// デフォルトは500リクエストごとに循環
'max_requests' => 10000,

より高い値は、キャッシュの利用を向上させますが、アプリケーションにメモリリークがないことに自信が必要です。この値を調整する際は、ワーカーのメモリ使用量を監視してください。

プレフィックスによる選択的キャッシング

cache_prefixes を使用して、ローカルにキャッシュされるキーを制御します。これは、次の場合に価値があります：

高変動キー：特定のキーが非常に頻繁に変更され、ローカルキャッシングがあまり利益をもたらさない
大きな値：小さく、頻繁に読み取られるキーのみをキャッシュしてメモリプレッシャーを軽減
機密データ：セキュリティやコンプライアンス上の理由から、特定のデータをRedisのみに保持する

// config/recall.php
'cache_prefixes' => [
    'users:',      // ユーザーデータをローカルにキャッシュ
    'settings:',   // アプリケーション設定をキャッシュ
    'products:',   // 商品カタログをキャッシュ
],

これらのプレフィックスに一致しないキーもまだ機能しますが、ローカルキャッシングをバイパスし、直接Redisにアクセスします。

メモリに関する考慮事項

APCuメモリ

APCuはすべてのPHPプロセス間でメモリを共有します。メモリ制限は php.ini で設定してください：

; デフォルトは32MB、キャッシュニーズが大きい場合は増やす
apc.shm_size = 128M

apcu_cache_info() を使用してAPCuの使用状況を監視します：

$info = apcu_cache_info();
$memory = $info['mem_size']; // 現在のメモリ使用量（バイト）

Swoole Tableのサイズ設定

Swoole Tablesは作成時に定められた固定容量を持ちます。予想されるキャッシュサイズを計画してください：

'local_cache' => [
    // 最大エントリー数（2の冪である必要があります）
    'table_size' => 65536,  // 64Kエントリー
 
    // シリアル化された値の最大サイズ（バイト）
    'value_size' => 8192,   // 値あたり8KB
],

メモリ使用量：table_size × (value_size + overhead)。65536エントリーと8KBの値を持つテーブルは約512MBを使用します。

一般的なパターン

アプリケーション設定

// 機能フラグと設定をキャッシュ
$features = Cache::store('recall')->remember('config:features', 3600, function () {
    return Feature::all()->pluck('enabled', 'name')->toArray();
});
 
// 設定が変更されると、すべてのワーカーが自動的に更新を受け取る

頻繁にアクセスされる参照データ

// 商品カテゴリをキャッシュ
$categories = Cache::store('recall')->remember('categories:all', 3600, function () {
    return Category::with('children')->whereNull('parent_id')->get();
});
 
// 通貨の為替レートをキャッシュ
$rates = Cache::store('recall')->remember('rates:exchange', 300, function () {
    return ExchangeRate::all()->pluck('rate', 'currency')->toArray();
});

キャッシュタグの代替

Recallはキャッシュタグをサポートしていませんが、プレフィックスを使用することで同様の機能を実現できます：

// タグの代わりに、一貫したプレフィックスを使用
Cache::store('recall')->put("blog:posts:{$id}", $post, 3600);
Cache::store('recall')->put("blog:comments:{$postId}", $comments, 3600);
 
// プレフィックスによってすべてのブログ関連のキャッシュをクリア（手動の実装が必要）
// またはデータが変更されたときの自動無効化に依存する

制限事項

Redisクラスターモード

RecallはRedisクラスターモードをサポートしていません。CLIENT TRACKING コマンドの REDIRECT オプションは、データ接続と無効化サブスクライバー接続が同じRedisノードにある必要があります。クラスター内では、キーはハッシュスロットに基づいて複数のノードに分散されるため、異なるノードに保存されたキーの無効化を受け取ることができません。

クラスタでのRedis展開については、次のことを検討してください：

クライアントサイドキャッシングの恩恵を受けるキャッシュデータ用に単一のRedisインスタンスを使用
他のデータにRedisクラスターを使用し、頻繁に読み取られる安定したデータを単独のインスタンスに保持

サポートガイドライン

私たちのオープンソースパッケージを選んでいただきありがとうございます！これらのサポートガイドラインを確認するための時間を取ってください。プロジェクトを最大限に活用する助けになるでしょう。

コミュニティ主導のサポート

私たちのオープンソースプロジェクトは、素晴らしいコミュニティによって支えられています。質問がある場合や支援が必要な場合は、StackOverflowやその他のオンラインリソースが最良の選択です。

バグと機能の優先順位付け

オープンソースプロジェクトを管理する現実として、報告されたすべてのバグや機能リクエストに即座に対応することはできません。以下の順序で問題を優先します。

1. 有料製品に影響を与えるバグ

有料製品に影響を与えるバグは常に最優先事項となります。場合によっては、私たちに直接影響を与えるバグのみを扱うことがあります。

2. コミュニティのプルリクエスト

バグを特定し、解決策を持っている場合は、プルリクエストを提出してください。私たちの製品に影響を与える問題の次に、これらのコミュニティ主導の修正に対して最も高い優先順位を与えます。レビューと承認が行われた後、あなたの解決策をマージし、貢献を認めます。

3. 財政的サポート

上記のカテゴリー以外の問題については、その解決に資金を提供することができます。各オープンイシューには、財政的に貢献できる注文フォームへのリンクがあります。提供された資金額に基づいて、これらの問題を優先します。

コミュニティの貢献

オープンソースは、そのコミュニティが活発であるときに栄えます。バグを修正していない場合でも、コード改善、ドキュメントの更新、チュートリアルの作成、またはコミュニティチャネルで他の人を支援することで貢献を考えてください。私たちは、コミュニティとしてオープンソースの仕事を支援することを皆さんに強く奨励します。

繰り返しになりますが、DefectiveCodeは、有料製品にどのように影響を与えるか、コミュニティのプルリクエスト、そして問題に対して受け取った財政的サポートに基づいてバグを優先します.

ライセンス - MITライセンス

本ソフトウェア及び関連する文書ファイル（以下「ソフトウェア」）のコピーを取得したすべての人に対して、無償で本ソフトウェアを制限なく利用する権利、使用、複製、修正、統合、出版、配布、サブライセンス、及び／またはソフトウェアのコピーを販売する権利を許可し、ソフトウェアが提供される人々にもそれを行うことを許可します。ただし、以下の条件に従います：

上記の著作権表示とこの許可通知は、ソフトウェアのすべてのコピーまたは重要な部分に含まれるものとします。

ソフトウェアは「現状のまま」提供され、いかなる種類の保証もなく、明示または暗示を問わず、商業性、特定の目的への適合性および非侵害の保証を含むが、これに限定されない保証はありません。著作者または著作権者は、契約、不法行為、またはその他の方法によるいかなる請求、損害、またはその他の責任についても、ソフトウェアまたはソフトウェアの使用またはその他の取り扱いに起因する場合において、一切の責任を負わないものとします。

🔗はじめに

🔗主な機能

🔗例

🔗インストール

🔗要件

🔗使用法

🔗基本設定

🔗動作原理

🔗Octane統合

🔗設定

🔗有効/無効

🔗Redisストア

🔗キャッシュプレフィックス

🔗ローカルキャッシュの設定

APCuドライバ（デフォルト）

Swoole Tableドライバ

🔗Octaneリスナー

ウォーム接続

タイック処理

🔗高度な使用法

🔗手動無効化処理

🔗ローカルキャッシュのフラッシュ

🔗接続管理

🔗最適化

🔗ワーカーリクエスト制限

🔗プレフィックスによる選択的キャッシング

🔗メモリに関する考慮事項