bitrix-caching

キャッシュ

基準：main 23.0+ · 検証済み：main 26.800.0

レベル	API	無効化
データキャッシュ	Data\Cache (initCache/startDataCache)	TTL、cleanDir($dir)、タグ
管理キャッシュ	Application::getInstance()->getManagedCache()	clean() / cleanDir()
タグ	Application::getInstance()->getTaggedCache()	clearByTag($tag)
ORM クエリーキャッシュ	setCacheTtl() / 'cache' => ['ttl' => …]	ORM の書き込み時に自動で無効化（bitrix-orm）
コンポーネントの結果	$this->startResultCache()	CACHE_TIME、タグ、clearResultCache()
ページ全体	Composite	bitrix-performance

エンジン設定（.settings.php）

'cache' => [
    'value' => [
        'type' => 'redis',                               // files | redis | memcached | memcache | apcu
        'redis' => ['host' => '127.0.0.1', 'port' => 6379],
        'serializer' => \Redis::SERIALIZER_IGBINARY,
        'sid' => 'site1',                                // key prefix: unique per site copy on a shared server
    ],
    'readonly' => false,
],
'cache_flags' => [                                       // separate top-level section
    'value' => [
        'config_options' => 3600,                        // b_option cache TTL
        'vendor_module_post_max_ttl' => 600,             // ORM TTL clamp per table (0 disables)
    ],
],

• カスタムエンジン：'type' => ['class_name' => MyEngine::class, 'extension' => 'redis']。複数サーバーの場合：'servers' => [['host' => …, 'port' => …]]。
• 不明な type 文字列（誤字や大文字・小文字の誤り）は、警告なしで「キャッシュなし」を意味します。カスタムクラスが見つからない場合やエンジンを利用できない場合（拡張機能がない、サーバーがダウンしている）は、E_USER_WARNING のみが出力され、「キャッシュなし」にフォールバックします。

データキャッシュとタグ

use Bitrix\Main\Application;
use Bitrix\Main\Data\Cache;

$cache = Cache::createInstance();
$cacheDir = '/vendor_blog/posts';
$cacheId = 'list_' . md5(serialize([$filter, LANGUAGE_ID]));

if ($cache->initCache(3600, $cacheId, $cacheDir))
{
    $data = $cache->getVars();
}
elseif ($cache->startDataCache())
{
    $tagged = Application::getInstance()->getTaggedCache();
    $tagged->startTagCache($cacheDir);                   // same dir as the data cache
    $data = PostTable::query()->setSelect(['ID', 'TITLE'])->setFilter($filter)->fetchAll();

    if ($data === [])
    {
        $tagged->abortTagCache();
        $cache->abortDataCache();
    }
    else
    {
        $tagged->registerTag('vendor_blog_posts');
        $tagged->endTagCache();
        $cache->endDataCache($data);
    }
}

Application::getInstance()->getTaggedCache()->clearByTag('vendor_blog_posts'); // in the write path / ORM OnAfter* handler

• clearByTag() は、タグに登録されたキャッシュのディレクトリをすべて削除します。そのため、独自の $cacheDir を使うデータキャッシュにもタグを付けられます。
• キーには、結果を変えるすべての要素（フィルター、言語、サイト、ユーザーグループ）を含めます。キャッシュ対象のブロック内で $_SESSION/$USER を読み取る場合は、必ずキーに含めてください。
• タグ名は独自に設定します。ORM_<TABLE> のような自動タグはありません。ORM キャッシュは管理キャッシュの orm_<table> ディレクトリに保存され、XxxTable::cleanCache() でクリアされます。

管理キャッシュ

$managed = Application::getInstance()->getManagedCache();
if ($managed->read(86400, 'rates', 'vendor_rates'))
{
    $rates = $managed->get('rates');
}
else
{
    $rates = $this->loadRates();
    $managed->set('rates', $rates);          // setImmediate() writes now, set() at the end of the hit
}
$managed->cleanDir('vendor_rates');

read() していない ID に対する set()/setImmediate() は何も行いません。

コンポーネントキャッシュ

if ($this->startResultCache(false, [$userGroupsKey]))  // CACHE_TIME from params; extra key parts
{
    $this->arResult['ITEMS'] = $this->loadItems();
    if (!$this->arResult['ITEMS'])
    {
        $this->abortResultCache();
    }
    else
    {
        Application::getInstance()->getTaggedCache()->registerTag('vendor_blog_posts');
    }
    $this->setResultCacheKeys(['TITLE']);              // arResult keys kept for component_epilog.php
    $this->includeComponentTemplate();
}

• パラメーター：CACHE_TYPE（A はグローバルスイッチに従い、Y、N を指定）、CACHE_TIME。キーにはサイト、言語、テンプレート、すべてのパラメーター、ユーザーの TZ オフセットがすでに含まれています。CACHE_GROUPS は慣例にすぎないため、ユーザーグループは自分で追加キーに含めてください。
• コンポーネントがキャッシュパスのタグスコープを開くのは、BX_COMP_MANAGED_CACHE が定義されている場合のみです。

チェックリスト

• キャッシュキーにすべての入力値が含まれていること。結果が空、またはエラーの場合は abort*Cache() を呼び出すこと。
• データを変更するコードパスで、それぞれのタグをクリアすること。
• タグスコープに、データキャッシュと同じディレクトリを使用すること。
• 生 SQL による書き込みの後、cleanCache() で ORM キャッシュをクリアすること。
• 本番環境では Redis/Memcached を使用し、サイトのコピーごとに sid を一意にすること。