Основная схема — blocks.php¶

settings (array)¶

В массиве settings хранятся настройки, которые будут задаваться на странице редактирования блока в панели администрирования на вкладке “Настройки блока”.

Список настроек представляет собой набор пар типа ключ-значение, где ключ — идентификатор настройки, а значение — массив, описывающий тип и поведение настройки. Соответственно идентификатору настройки должна быть определена языковая переменная, которая определяет текст названия этой настройки на странице редактирования блока.

Перечисление настроек блока выглядит так:

'settings' => array(
    'ip_address' => array(
        'type' => 'text',
        'default_value' => '127.0.0.1',
    ),
    ...
),

Возможные значения¶

• false — блок не будет кешироваться;
• true — блок будет кешироваться согласно глобальным настройкам кеширования блоков, взятыми из схемы block_cache_properties;
• array — массив с настройками кеширования блока. Параметры, описанные в этом массиве, будут объединены с глобальными настройками кеширования блоков из схемы block_cache_properties.

Доступные параметры¶

Доступны несколько параметров, с помощью которых можно настроить то, как будет кешироваться блок. Все параметры необязательны, если не указано иное.

• update_handlers (array) — список таблиц БД (без префиксов), при изменении которых кеш блока будет инвалидирован. Под изменением подразумевается модификация таблицы (добавление, изменение и удаление записей; изменение структуры), с использованием инструментов CS-Cart (функции и методы для работы с БД). Например, для блока, выводящего список пользователей имеет смысл перечислить таблицы users и user_profiles.

При генерации ключа записи в кеше для этого блока могут быть использованы сериализованные значения различных переменных и параметров. Это поведение настраивается перечислением названий требуемых параметров в нижеописанных массивах:

• request_handlers (array) — список названий параметров HTTP-запроса (ключей в массиве $_REQUEST). Например, при указании параметров category_id и sort_by к ключу будет добавлена строка в виде ...|category_id=10|sort_by=price;, что позволяет использовать разные записи в кеше для каждой из комбинаций значений указанных параметров;
• session_handlers (array) — список названий переменных в сессии пользователя (ключей в массиве $_SESSION). Например, при указании параметра items_per_page запись в кеше будет отдельной для каждого значения $_SESSION['items_per_page'];
• cookie_handlers (array) — список названий параметров в куках пользователя (ключей в массиве, возвращаемом функцией fn_get_session_data());
• auth_handlers (array) — список ключей в массиве $_SESSION['auth'];

Для request_handlers, session_handlers, cookie_handlers и auth_handlers существуют специальные формы записи значений:

• Dot-syntax для доступа ко вложенным элементам. Запись вида 'session_handlers' => array('auth.user_id') выберет значение $_SESSION['auth']['user_id'];

• Выбор всех значений с помощью *. Запись вида 'session_handlers' => array('*') выберет все значения в массиве $_SESSION. Это означает, что при генерации ключа кеша будет использован сериализованый массив $_SESSION целиком.

• Операторы сравнения. Запись вида:

  'auth_handlers' => array(
      'user_id' => array('gt', 0),
  ),
  

  выберет значение (и добавит к ключу кеша) $_SESSION['auth']['user_id'] только в случае, если оно будет больше нуля.

  Доступные операторы сравнения:

  • gt - больше
  • eq - равно
  • neq - не равно
  • lte - меньше или равно
  • lt - меньше
  • gte - больше или равно
  • cont - вхождение подстроки
  • ncont - невхождение подстроки
  • in - содержится в массиве
  • nin - не содержится в массиве

Кроме того, для большей гибкости при генерации ключа кеша, он может содержать результат вызова функций и методов:

• callable_handlers (array) — список названий параметров и соответствующих им функций, результат вызова которых будет использован в качестве значений этих параметров. Например, запись вида:

  'callable_handlers' => array(
      'currency' => array('fn_get_secondary_currency'),
  ),
  

  добавит к ключу кеша строку: |currency=RUB.

  Формат описания функции, которую нужно вызвать, выглядит так: array(Callable[, Args]), где Callable это строка с именем функции или любое другое выражение, которое можно вызвать с помощью call_user_func() (http://php.net/manual/ru/language.types.callable.php), а Args - необязательный массив с перечислением аргументов, которые должны быть переданы в функцию. Если аргумент - это строка, начинающаяся с символа $, то она будет интерпретирована как название переменной, в случае если это глобальная переменная ($_REQUEST, ...) или одна из переменных $block_schema и $block_data.

  • $block_schema — содержит схему блока
  • $block_data — содержит данные о блоке из БД

  Пример:

  'callable_handlers' => array(
      'layout' => array('fn_get_products_layout', array('$_REQUEST')),
      'settings' => array('fn_foo_addon_cache_key_handlers', array('$block_data')),
  ),
  

  В этом случае к ключу записи в кеше будет добавлены результаты вызова этих функций.

• disable_cache_when (array) — позволяет описывать правила отключения кеша данного блока. Может принимать параметры request_handlers, session_handlers, cookie_handlers, auth_handlers и callable_handlers в том же формате, что и сама секция настроек кеша cache, хотя работают они по-другому.

  Пример:

  'cache' => array(
      'request_handlers' => array('sort_by', 'items_per_page'),
      'auth_handlers' => array(
          'user_id' => array('gt', 0)
      ),
      'disable_cache_when' => array(
          'request_handlers' => array('sort_by', 'items_per_page'),
          'auth_handlers' => array(
              'user_id' => array('gt', 0)
          ),
      ),
  ),
  

  Рассмотрим на примере, как работают эти параметры в сравнении с секцией cache:

  • в секции cache: значения $_REQUEST['sort_by'] и $_REQUEST['items_per_page'] будут сериализованы и добавлены к ключу кеша блока. Значение $auth['user_id'] будет сериализовано и добавлено к ключу, только если оно больше нуля;

  • в секции cache.disable_cache_when: если массив $_REQUEST содержит хотя бы один из ключей: sort_by или items_per_page, то блок не будет кешироваться. Если массив $auth содержит ключ user_id, и значение, соответствующее этому ключу, больше нуля, то блок тоже не будет кешироваться.

    Поведение параметра callable_handlers тоже отличается в секции cache.disable_cache_when: если функция возвращает true, блок не будет кешироваться, и наоборот.

• regenerate_cache_when (array) — позволяет описывать правила инвалидации кеша данного блока. Схема работы идентична параметру cache.disable_cache_when.

• cache_overrides_by_dispatch (array) - позволяет описывать параметры работы кеша блока для каждого dispatch по отдельности в формате array('dispatch' => cache_params, ...), где cache_params - массив параметров кеширования для конкретного dispatch.

  Если в этом массиве есть запись для текущего dispatch, то параметры кеширования блока будут браться именно из неё, а не из общих настроек кеша блока в секции cache. Каждый вложенный массив параметров кеширования для отдельного dispatch может принимать все те же параметры, что принимает секция общих настроек кеша cache.

  Пример:

  'cache' => array(
      // Эти параметры кеширования будут использованы везде, кроме страницы категории
      'update_handlers' => array('users'),
  ),
  'cache_overrides_by_dispatch' => array(
      // Эти параметры кеширования будут использованы на странице категории
      'categories.view' => array(
          'update_handlers' => array('users', 'products'),
      ),
  ),
  

• hide_on_locations (array) - список dispatch, на которых блок не может быть использован. Например, следующий код актуален, если необходимо запретить возможность добавлять блок на странице корзины:

  'hide_on_locations' => array('checkout.cart'),
  

• single_for_location (bool) - если установлено в true, то на каждом dispatch блок может присутствовать только в единственном числе. Ситуация, когда параметр не указан, трактуется как значение false.

• multilanguage (bool) - необходима ли возможность мультиязычности содержимого блока. Если установлено в true, содержимое блока будет разделено по языкам. Ситуация, когда параметр не указан, трактуется как значение false.