Helper example

Helper.php

<?php
namespace EvolutionCMS\Main;

//положить файл в папку core/custom/packages/Main/src/
//для использования в любом другом месте добавить use EvolutionCMS\Main\Helper;

use Illuminate\Support\Carbon;
use Illuminate\Support\Facades\Cache;
use Illuminate\Support\Facades\DB;
use Illuminate\Support\Str;


class Helper
{

    public static function productTvList()
    {
        // для списков продуктов (в каталоге, в слайдере, в похожих продуктах, в новых продуктах)
        // в общем для каких угодно списков, чтобы не прописывать 100 раз одно и то же
        return 'image,price,oldprice,label';
    }

    public static function prepareProductList($data, $modx, $DL, $extDL)
    {
        //ну тут что-то можно написать про prepare DocLister
        return $data;
    }

    public static function DocLister($key, $params, $lifetime = false)
    {
        //зачем писать api=1 в каждом вызове доклистера, если можно задать его один раз тут
        $params['api'] = 1;
        if($key) {
            //если есть ключ - кэшируем, иначе - не кэшируем
            if(empty($lifetime) || !is_numeric($lifetime)) {
                //если время кэширования не задано  - кэшируем "навсегда"
                $arr = Cache::rememberForever($key, function() use($params){
                    $arr = [];
                    $json = evo()->runSnippet("DocLister", $params);
                    if(!empty($json)) {
                        $arr = json_decode($json, 1);
                    }
                    return $arr;
                });
            } else {
                //иначе кэшируем "на время"
                $arr = Cache::remember($key, $lifetime, function() use($params){
                    $arr = [];
                    $json = evo()->runSnippet("DocLister", $params);
                    if(!empty($json)) {
                        $arr = json_decode($json, 1);
                    }
                    return $arr;
                });
            }

        } else {
            //если ключа нет - не кэшируем
            $arr = [];
            $json = evo()->runSnippet("DocLister", $params);
            if(!empty($json)) {
                $arr = json_decode($json, 1);
            }
        }
        return $arr;
    }

    public static function DLMenu($key, $params)
    {
        //аналогично и для DLMenu
        $params['api'] = 1;
        $arr = [];
        if($key === false) {//не кэшируем
            $json = evo()->runSnippet("DLMenu", $params);
            if(!empty($json)) {
                $arr = json_decode($json, 1);
                if(!empty($arr[0]) && is_array($arr[0])) {
                    $arr = $arr[0];
                } else if(is_array($arr)) {
                    $arr = $arr;
                } else {
                    $arr = [];
                }
            }
        } else {
            $arr = Cache::rememberForever($key, function () use ($params) {
                $arr = [];
                $json = evo()->runSnippet("DLMenu", $params);
                if (!empty($json)) {
                    $arr = json_decode($json, 1);
                    if (!empty($arr[0]) && is_array($arr[0])) {
                        $arr = $arr[0];
                    } else if (is_array($arr)) {
                        $arr = $arr;
                    } else {
                        $arr = [];
                    }
                }
                return $arr;
            });
        }
        return $arr;
    }

    public static function plural($n, $forms = [ 'товар', 'товара', 'товаров' ]) {
        //склонение
        // Helper::plural($productCount)
        // Helper::plural($reviewsCount, ['отзыв', 'отзыва', 'отзывов'])
        $n = $n ?: 0;
        return $n%10==1&&$n%100!=11?$forms[0]:($n%10>=2&&$n%10<=4&&($n%100<10||$n%100>=20)?$forms[1]:$forms[2]);
    }

    public static function webp($image, $options = '')
    {
        // если вдруг понадобилось преобразовать изображение в формат webp без всяких обрезок и пребразований
        // сокращенная запись того же через thumb плюс фикс пустых options
        // Helper::webp($image);
        return !empty($image) ? evo()->runSnippet("phpthumb", [ 'input' => $image, 'options' => $options, 'webp' => 1 ]) : '';
    }
  
    public static function thumb($image, $options = '', $webp = false)
    {
        // чтобы долго не писать $modx->runSnippet и всякие параметры не перечислять
        // плюс при желании можно быстро сменить со сниппета на хелпер Thumb
        $params = [ 'input'=> $image, 'options' => $options ];
        if($webp) {
            $params['webp'] = 1;
        }
        return evo()->runSnippet("phpthumb", $params);
    }

}

Вступление

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

Cache::rememberForever($key, function() use($params){
   ......
})

и прочие
if(!empty($json)) {$docs = json_decode($json, 1)}
после получения результата из доклистера в режиме API изрядно напрягают, отнимают много времени и не соответствуют принципам ООП

Чтобы сосредоточиться на разработке и забыть все эти проблемы с кэшем и преобразованием данных и используются вспомогательные классы и отдельные методы, в частности класс Helper.

Мы просто задаем параметры, с которыми нам нужно вызывать DocLister и стратегию кэширования. На выходе имеем готовый к использованию массив.

Примеры использования

Главные отзывы (единый для всего сайта кэш с ключом MainReviews)

        $documents = evo()->documentObject['main_reviews'][1] ?? false;//берем список id отзывов на главную страницу
        if(empty($documents)) return [];

        $params = [
            'documents' => $documents,
            'sortType' => 'doclist',
            'tvList' => 'avatar',
        ];
        return Helper::DocLister('MainReviews', $params);

Похожие товары (с ключом кэширования, включающим id страницы, т.к. у каждого товара свои "похожие")

тут мы дополнительно получаем список тв (общий для всех списков товаров) и проводим обработку в prepare
получаем товары в случайном порядке, время жизни кэша 1 час (третий параметр в вызове хелпера - 3600 сек)

   ```
    $docid = evo()->documentObject['id']
    $documents = evo()->documentObject['related_products'][1] ?? false; //берем список id "похожих товаров" конкретного товара
    if(empty($documents)) return [];

    $params = [
        'documents' => $documents,
        'tvList' => Helper::productTvList(),
        'prepare' => '\\EvolutionCMS\\Main\\Helper::prepareProductList',
        'orderBy' => 'RAND()',
    ];
    return Helper::DocLister('RelatedProducts_' .  $docid, $params, 3600);

### Некэшированный вызов доклистера (например, 5 случайных новостей на главную)

       ```
        $params = [
            'parents' => 2, //папка с новостями
            'tvList' => 'image',
            'display' => 5,
            'orderBy' => 'RAND()',
        ];
        return Helper::DocLister(false, $params);