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

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

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(), getPublishedTranslations(), getPublishedByIds() и countPublished().

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

Исключения

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

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

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