PostManager

Для работы с одним типом создаётся экземпляр менеджера. Общий список нескольких типов можно получить статическим методом.

Быстрый старт

$postManager = new PostManager('news');

$posts = $postManager->getPublishedList(
    orderBy: 'publish_date',
    limit: 10,
    columns: [
        'id',
        'title',
        'url',
        'content',
    ]
);

foreach ($posts as $post) {
    ?>
    <article>
        <h2>
            <a href="<?php echo $post['post_url']; ?>">
                <?php echo $post['title']; ?>
            </a>
        </h2>
        <p><?php echo $post['short_description']; ?></p>
    </article>
    <?php
}

Поля post_url и short_description создаются менеджером на основе выбранных url и content.

Создание менеджера

__construct(string $postType, ?Database $db = null)

Первым параметром передаётся системное имя типа записей:

$postManager = new PostManager('news');

Допустимы латинские буквы, цифры, _ и -.

Если имя имеет недопустимый формат, выбрасывается InvalidArgumentException.

Без второго аргумента используется основная база данных CMS. При необходимости можно передать другой экземпляр Database:

$postManager = new PostManager(
    'news',
    $database
);

Получение записи по URL

getPublishedByUrl(string $url, ?string $language = null): ?array

Возвращает опубликованную запись по её URL и языку:

$post = $postManager->getPublishedByUrl('release-notes');
$englishPost = $postManager->getPublishedByUrl('release-notes', 'en');

Если язык не передан, используется текущий язык CMS, а при его отсутствии — язык сайта по умолчанию. Передаётся код языка, а не URL-префикс.

Начальные и конечные / удаляются. Вложенные сегменты не поддерживаются.

Метод возвращает null, если URL пустой, содержит вложенные сегменты, запись не найдена, не опубликована или её дата публикации ещё не наступила.

Результат получает поля post_type, post_url и, при наличии content, short_description. Структурированные поля возвращаются в исходном формате базы данных.

Формирование URL

getUrl(string $slug, ?string $language = null): string

Формирует локализованный публичный URL записи:

$url = $postManager->getUrl('release-notes');
$englishUrl = $postManager->getUrl('release-notes', 'en');

Если язык не передан, используется текущий язык CMS, а при его отсутствии — язык сайта по умолчанию.

Если идентификатор пустой или содержит /, выбрасывается InvalidArgumentException.

RuntimeException выбрасывается, если для типа записей не настроен публичный URL или ссылка недоступна для выбранного языка.

Получение списка

getPublishedList(string $orderBy = 'id', string $order = 'DESC', ?int $limit = null, int $offset = 0, array $columns = ..., ?string $language = null, bool $allLanguages = false): array

Возвращает список опубликованных записей:

$posts = $postManager->getPublishedList(
    orderBy: 'publish_date',
    order: 'DESC',
    limit: 10,
    offset: 0
);

Параметры

Если язык не передан, используется текущий язык CMS, а при его отсутствии — язык сайта по умолчанию:

$englishPosts = $postManager->getPublishedList(
    limit: 10,
    language: 'en'
);

Чтобы получить записи всех языков, передайте true в $allLanguages:

$posts = $postManager->getPublishedList(
    limit: 10,
    allLanguages: true
);

$allLanguages отключает фильтрацию по языку и имеет приоритет над $language. При явном выборе полей менеджер автоматически добавляет поле language.

Допустимые поля сортировки:

• id
• title
• date
• publish_date
• modified_date
• views

По умолчанию из базы данных выбираются:

• id
• title
• url
• img
• author
• date
• publish_date
• modified_date
• views

Каждый результат дополнительно получает поле post_type.

Если выбранное поле url содержит корректный идентификатор записи, результат также получает post_url.

Чтобы получить дополнительные поля, передайте их последним параметром:

$posts = $postManager->getPublishedList(
    limit: 10,
    columns: [
        'id',
        'title',
        'url',
        'content',
        'meta',
    ]
);

При выборе content менеджер добавляет поле short_description.

Если выбраны структурированные поля, они преобразуются в массивы:

• meta
• category
• global_meta
• global_category
• comment
• seo

Получение записей нескольких типов

getPublishedListByTypes(array $postTypes, string $orderBy = 'id', string $order = 'DESC', ?int $limit = null, int $offset = 0, array $columns = ..., ?string $language = null, bool $allLanguages = false, ?Database $db = null): array

Статический метод возвращает общий список опубликованных записей нескольких типов:

$columns = ['id', 'title', 'url'];
$posts = PostManager::getPublishedListByTypes(['news', 'articles'], orderBy: 'publish_date', limit: 10, columns: $columns);

Создавать отдельные экземпляры PostManager для этого вызова не нужно.

Первым параметром передаётся массив системных имён типов записей. Повторяющиеся имена учитываются один раз. Если передан пустой массив, метод возвращает пустой список.

Остальные параметры сортировки, ограничения, выбора полей и языка работают так же, как в getPublishedList().

Каждая запись дополнительно получает поле post_type, содержащее системное имя её типа. Передавать post_type в $columns не нужно: менеджер добавляет его автоматически.

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

При необходимости последним параметром можно передать другой экземпляр Database.

Переводы записи

getPublishedTranslations(string $translationKey): array

Возвращает опубликованные языковые варианты, объединённые одним значением translation_key:

$translations = $postManager->getPublishedTranslations(
    $post['translation_key']
);

Каждый элемент содержит id, url, language, seo и добавленное поле post_type. Поле seo преобразуется в массив. Если для языка можно сформировать ссылку, также добавляется post_url.

Результат сортируется по id по возрастанию. Если ключ пустой, имеет недопустимый формат или опубликованные варианты не найдены, метод возвращает пустой массив.

Получение записей по ID

getPublishedByIds(array $ids, array $columns = ..., ?string $language = null): array

Возвращает опубликованные записи по идентификаторам:

$posts = $postManager->getPublishedByIds([
    15,
    27,
    42,
]);

Идентификаторы приводятся к целым числам. Нулевые, отрицательные и повторяющиеся значения исключаются.

Результат сортируется по id по возрастанию.

Если язык не передан, используется текущий язык CMS, а при его отсутствии — язык сайта по умолчанию.

Для получения записей определённого языка передайте его код:

$englishPosts = $postManager->getPublishedByIds(
    [15, 27],
    language: 'en'
);

Для выбора дополнительных полей передайте второй параметр:

$posts = $postManager->getPublishedByIds(
    [15, 27],
    [
        'id',
        'title',
        'url',
        'content',
        'meta',
    ]
);

Правила добавления post_url, short_description и преобразования структурированных полей совпадают с правилами списка.

Если после проверки не осталось допустимых идентификаторов, метод возвращает пустой массив.

Дополнительные поля

post_type

Добавляется к каждой записи и содержит системное имя типа:

$postType = $post['post_type'];

post_url

Добавляется, если в результате присутствует поле url с непустым идентификатором без вложенных сегментов:

$url = $post['post_url'];

URL учитывает публичный путь типа записей и язык, выбранный при вызове метода. При выборке всех языков или переводов используется язык каждой отдельной записи.

short_description

Добавляется, если в результате присутствует поле content:

$description = $post['short_description'];

При подготовке краткого описания:

• декодируются HTML-сущности
• удаляются HTML-теги
• удаляется содержимое script, style, noscript и template
• переносы и повторяющиеся пробелы заменяются одним пробелом
• текст сокращается примерно до 180 символов
• при сокращении текст по возможности завершается на границе слова
• к сокращённому тексту добавляется ...

Если текст короче установленного ограничения, многоточие не добавляется.

Подсчёт записей

countPublished(?string $language = null): int

Возвращает количество опубликованных записей выбранного типа и языка:

$count = $postManager->countPublished();
$englishCount = $postManager->countPublished('en');

Если язык не передан, используется текущий язык CMS, а при его отсутствии — язык сайта по умолчанию.

При подсчёте учитываются статус и дата публикации.

Учёт просмотров

recordView(int $id): void

Увеличивает значение views указанной записи на единицу:

$postManager->recordView(15);

Метод ничего не возвращает. Если идентификатор меньше 1, выбрасывается InvalidArgumentException.

Правила публикации

Запись считается опубликованной, если:

• поле status содержит publish
• publish_date не задана или не превышает текущее время

Эти правила используются в getPublishedByUrl(), getPublishedList(), getPublishedListByTypes(), getPublishedTranslations(), getPublishedByIds() и countPublished().

recordView() только увеличивает счётчик просмотров и не проверяет статус или дату публикации.

Исключения

RuntimeException также может возникнуть при получении записей с полем url, поскольку менеджер автоматически формирует для них post_url.

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

• один экземпляр работает только с одним типом записей
• методы получения и подсчёта учитывают только опубликованные записи
• без явного языка используется текущий язык CMS или язык сайта по умолчанию
• списки индексируются начиная с 0
• каждый результат получает поле post_type
• post_url добавляется только при наличии корректного поля url и доступной ссылки для языка записи
• short_description добавляется только при наличии поля content
• recordView() не проверяет статус публикации записи
• произвольные SQL-условия не поддерживаются
• для данных записи текущего запроса используйте PageData