ddTools

Library
  • Версия: 0.16
  • Выпущено:
  • Метки: General
  • Использует:
    • PHP >= 5.4
    • MODX Evo >= 1.0.10
Скачать 14 скачиваний

Описание

Библиотека с различными инструментами, облегчающими работу. Умеет:

  • Создавать новый документ;
  • Обновлять информацию о существующем документе;
  • Получать необходимые дочерние документы (с TV и пр.);
  • Парсить текст (почти как modx->parseChunk, только принимает текст, а не имя чанка);
  • Парсить ресурс (вызывается $modx->parseDocumentSource и $modx->rewriteUrls);
  • Разбивать строку в ассоциативный массив по двум разделителям;
  • Разбивать ассоциативный массив полей и TV документа на два отдельных массива;
  • Удалять необходимую папку со всеми вложенными папками и файлами;
  • Регистрировать необходимые JavaScript во внутреннем массиве $modx без подключения кода (полезно при ручном подключении скриптов);
  • Генерировать случайную строку нужной длины;
  • И ещё несколько мелочей (см. код).

Внимание

Изменён путь установки для бибилотеки. Теперь она должна находиться здесь assets/libs/ddTools, а не в assets/snippets/ddTools. Это значит, что совместимость всех продуктов, которые используют версии ddTools ниже 0.14, будет нарушена. Чтобы этого избежать, устанавливайте новые версии через Composer.

Список изменений

  • Внимание! Требуется PHP >= 5.4.
  • Метод «ddTools::parseText» обновлён до 1.3.1:
    • Рефакторинг, метод теперь использует именованные параметры (с сохранением обратной совместимости).
    • Добавлена возможность удаления пустых плэйсхолдеров (см. «$params['removeEmptyPlaceholders']»).
    • Параметр «$params['data']» теперь не обязателен.
  • Метод «ddTools::sendMail» обновлён до to 2.1:
    • Рефакторинг, метод теперь использует именованные параметры (с сохранением обратной совместимости).
    • Значение по умолчанию параметра «$params['from']» берётся из «$modx->getConfig('emailsender')» (спасибо, MrSwed!).
  • Метод «ddTools::regEmptyClientScript» обновлён до 1.1:
    • Параметры теперь могут передаваться и в виде объекта stdClass.
  • Рефакторинг: Используется короткий синтаксис объявления массивов. Это удобней и проще для визуальной идентификации.

Документация

Установка

Composer (рекомендуется)

Просто добавьте зависимость «dd/modxevo-library-ddtools» в composer. json вашего проекта. Для установки через Composer доступны версии ddTools выше 0.14. Если вы используете этот метод, то совместимость с продуктами, которые исползьуют версии ddTools ниже 0.14, будет сохранена.

Вручную

Хотя установка через Composer крайне рекомендуется, вы можете установить библиотеку вручную. Для установки распакуйте архив в ваш проект (файл modx.ddtools.class.php должен находиться в папке assets/libs/ddTools/).

Библиотека очень проста, так что, если что, посмотрите в исходный код и вы всё поймёте.

Все методы и поля являются публичными, статичными и объявляются в классе «ddTools».

Описание параметров

Название Описание Допустимые значения Значение по умолчанию

Поле «ddTools::$documentFields»

Содержит массив имён полей документа.

Поле «ddTools::$tables»

Содержит полные имена некоторых таблиц БД (см. код).

Метод «ddTools::screening»

Экранирует символы в строке (см. код).

ddTools::screening($str);
$str * Строка для обработки. {string}

Метод «ddTools::explodeAssoc»

Разбивает строку по двум разделителям в ассоциативный массив.

ddTools::explodeAssoc($str, $splY = '||', $splX = '::');
$str * Строка для обработки. {separated string}
$splY Разделитель между значениями (между парами ключ-значение). {string} '||'
$splX Разделитель между ключом и значением. {string} '::'

Метод «ddTools::unfoldArray»

Преобразует многомерный массив в одномерный, при этом ключи результирующего массива сливаются через '.'. Может быть полезно при необходимости использования «вложенных плэйсхолдеров» ([+size.width+]). См. примеры ниже.

ddTools::unfoldArray($arr, $keyPrefix = '');
$arr * Массив для обработки. {array}
$keyPrefix Префикс ключей объекта (внутренняя переменная, но можно и поюзать при необходимости). {string} ''

Метод «ddTools::sort2dArray»

Сортирует двумерный массив по нескольким колонкам (как в SQL) по методу Хоара. Сортировка устойчивая.

ddTools::sort2dArray($array, $sortBy, $sortDir = 1, $i = 0);
$array * Исходный массив. {array}
$sortBy * Колонки, по которым нужно сортировать (ключи массивов второго уровня) в необходимом порядке. {array}
$sortDir Направление сортировки (1 == ASC; -1 == DESC). {1|-1} 1
$i Счётчик (внутренняя переменная для рекурсии). {integer} 0

Метод «ddTools::parseText»

Аналог $modx->parseChunk, только принимает текст (+ пара плюшек).

ddTools::parseText($params = [
	'text' => '',
	'data' => [],
	'placeholderPrefix' => '[+',
	'placeholderSuffix' => '+]',
	'removeEmptyPlaceholders' => false,
	'mergeAll' => true
]);
$params * Объект параметров. {array_associative|stdClass}
$params['text'] * Строка, которую нужно парсить. {string}
$params['data'] Массив значений. Ключ — имя плэйсхолдера, значение — значение. {array_associative}
$params['placeholderPrefix'] Префикс плэйсхолдеров. {string} '[+'
$params['placeholderSuffix'] Суффикс плэйсхолдеров. {string} '+]'
$params['removeEmptyPlaceholders'] Удалять пустые плэйсхолдеры? {boolean} false
$params['mergeAll'] Надо ли делать дополнительно обрабатывать поля документа, настроек, чанков. {boolean} true

Метод «ddTools::parseSource»

Парсит ресурс (вызывается $modx->parseDocumentSource и $modx->rewriteUrls).

ddTools::parseSource($source);
$source * Текст для парсинга. {string}

Метод «ddTools::explodeFieldsArr»

Разбивает ассоциативный массив полей и TV документа на два отдельных массива.

ddTools::explodeFieldsArr($fields);
$fields * Ассоциативный массив значений полей документа (в таблице site_content) и/или TV. {array_associative}

Метод «ddTools::createDocument»

Создаёт новый документ.

ddTools::createDocument($fields = [
	'pagetitle' => ''
], $groups = false);
$fields * Массив полей или TV документа. Ключ — название поля или TV, значение — значение. Обязательно должен присутствовать заголовок нового документа (элемент 'pagetitle'). {array_associative}
$groups Индексированный массив id групп, к которым должен принадлежать документ. {array}

Метод «ddTools::updateDocument»

Обновляет информацию по документу.

ddTools::updateDocument($id, $update, $where = '');
$id * ID документа (или массив ID), который необходимо отредактировать. {integer|array} 0
$update * Массив значений полей или TV документа. Ключ — название поля или TV, значение — значение. {array_associative}
$where SQL условие WHERE. {string_sql}

Метод «ddTools::getDocuments»

Получает необходимые документы (поля документов).

Отличие от родного метода:

  • Параметр published может принимать 'all', в этом случае будут получены и опубликованные и неопубликованные документы.
  • Параметр deleted может принимать 'all', в этом случае будут получены и удалённые и неудалённые документы.
ddTools::getDocuments(
	$ids,
	$published = 'all',
	$deleted = 0,
	$fields = '*',
	$where = '',
	$sort = 'menuindex',
	$dir = 'ASC',
	$limit = ''
);
$ids * Id документов, которые надо получить. {array}
$published Опубликованы ли документы, которые надо получить. При значении == 'all' — без разницы. {'all'|0|1} 'all'
$deleted Удалены ли документы, которые надо получить. При значении == 'all' — без разницы. {'all'|0|1} 0
$fields Поля документа, которые надо получить. {comma separated string|'*'} '*'
$where Условие WHERE SQL-запроса для получения документов. {string}
$sort Поле документа, по которому необходимо сортировать результаты. {string} 'menuindex'
$dir Направление сортировки результатов. {'ASC'|'DESC'} 'ASC'
$limit SQL LIMIT (слово LIMIT включать не надо). {string}

Метод «ddTools::getDocument»

Получает данные о необходимом документе (поля документа).

Отличие от родного метода:

  • Параметр published может принимать 'all', в этом случае без разницы, опубликован ли документ, он всё равно будет получен.
  • Параметр deleted может принимать 'all', в этом случае без разницы, удалён ли документ, он всё равно будет получен.
ddTools::getDocument(
	$id,
	$fields = '*',
	$published = 'all',
	$deleted = 0
);
$id * Id документа, данные которого надо получить. {integer}
$fields Поля документа, которые надо получить. {comma separated string|'*'} '*'
$published Опубликован ли документ, данные которого надо получить. При значении == 'all' — без разницы. {'all'|0|1} 'all'
$deleted Удален ли документ, данные которого надо получить. При значении == 'all' — без разницы. {'all'|0|1} 0

Метод «ddTools::getTemplateVars»

Получает массив TV и полей заданного документа.

Отличие от родного метода:

  • Параметр published может принимать 'all', в этом случае будут получены и опубликованные и неопубликованные документы.
ddTools::getTemplateVars(
	$idnames,
	$fields = '*',
	$docid = '',
	$published = 'all',
	$sort = 'rank',
	$dir = 'ASC'
);
$idnames * Id или имена TV, или имена полей документа, которые надо получить. {array|'*'}
$fields Поля базы данных таблицы TV, которые надо получать. {comma separated string|'*'} '*'
$docid Id документа, данные которого надо получить. {integer|''} Текущий документ
$published Опубликован ли документ, данные которого надо получить. При значении == 'all' — без разницы. {'all'|0|1} 'all'
$sort Поля базы данных таблицы TV, по которым необходимо сортировать результаты. {comma separated string} 'rank'
$dir Направление сортировки результатов. {'ASC'|'DESC'} 'ASC'

Метод «ddTools::getTemplateVarOutput»

Получает ассоциативный массив значений TV и полей заданного документа.

Отличие от родного метода:

  • Параметр published может принимать 'all', в этом случае будут получены и опубликованные и неопубликованные документы.
ddTools::getTemplateVarOutput(
	$idnames,
	$docid = '',
	$published = 'all',
	$sep = ''
);
$idnames * Id или имена TV или имена полей документа, которые надо получить. {array|'*'}
$docid Id документа, данные которого получить. {integer|''} Текущий документ
$published Опубликован ли документ, данные которого надо получить. При значении == 'all' — без разницы. {'all'|0|1} 'all'
$sep Разделитель, используемый при склейке в getTVDisplayFormat(). {string} ''

Метод «ddTools::getDocumentChildren»

Получает необходимые дочерние документы (значения их полей).

Отличие от родного метода:

  • Параметр published может принимать 'all', в этом случае будут получены и опубликованные и неопубликованные документы.
  • Параметр deleted может принимать 'all', в этом случае будут получены и удалённые и неудалённые документы.
ddTools::getDocumentChildren(
	$parentid = 0,
	$published = 1,
	$deleted = 0,
	$fields = '*',
	$where = '',
	$sort = 'menuindex',
	$dir = 'ASC',
	$limit = ''
);
$parentid Id родителя, дочерние документы которого необходимо получить. {integer} 0
$published Опубликованы ли документы, которые надо получить. При значении == 'all' — без разницы. {'all'|0|1} 1
$deleted Удалены ли документы, которые надо получить. При значении == 'all' — без разницы. {'all'|0|1} 0
$fields Поля документа, которые надо получить. При значении == '*' — все поля. {comma separated string} '*'
$where Условие WHERE SQL-запроса для получения документов (в условии могут участвовать только поля документа). {string}
$sortBy По какому полю сортировать документы. Для множественной сортировки можно передавать несколько с указанием направления через запятую (как в sql), в этом случае «sortDir» следует передать как пустую строку. {string|comma separated string} 'menuindex'
$sortDir Направление сортировки документов. {'ASC'|'DESC'|''} 'ASC'
$limit SQL LIMIT (слово LIMIT включать не надо). {string}

Метод «ddTools::getDocumentChildrenTVarOutput»

Получает необходимые дочерние документы (значения их полей и TV).

Отличие от родного метода:

  • Добавлен параметр $where, который позволяет указать условие WHERE SQL-запроса для получения документов (в условии могут участвовать только поля документа).
  • Добавлен параметр $resultKey, который позволяет определить, значение какого поля будет ключами результирующего массива.
  • В $modx->getDocumentChildren получается только id (ибо зачем всё остальное, дальше ведь всё равно получается).
  • Параметр $published может принимать 'all', в этом случае будут получены и опубликованные и неопубликованные документы.
ddTools::getDocumentChildrenTVarOutput(
	$parentid = 0,
	$tvidnames = [],
	$published = 1,
	$sortBy = 'menuindex',
	$sortDir = 'ASC',
	$where = '',
	$resultKey = 'id'
);
$parentid Id родителя, дочерние документы которого необходимо получить. {integer} 0
$fields Массив названий полей документа и/или TV, которые нужно получить. {array} array($resultKey)
$published Опубликованны ли документы? При == 'all' — без разницы. {'all'|0|1} 1
$sortBy По какому полю сортировать документы. Для множественной сортировки можно передавать несколько с указанием направления через запятую (как в sql), в этом случае «sortDir» следует передать как пустую строку. {string|comma separated string} 'menuindex'
$sortDir Направление сортировки документов. {'ASC'|'DESC'|''} 'ASC'
$where Условие WHERE SQL-запроса для получения документов (в условии могут участвовать только поля документа). {string}
$resultKey Значение какого поля должно быть ключами результирующего массива? Если передать false, то ключи будут просто по порядку. {string|boolean} 'id'

Метод «ddTools::parseFileNameVersion»

Разбирает строку файла, получая из неё его имя версию.

ddTools::parseFileNameVersion($file);
$file * Строка пути к файлу или распаршенный при помощи pathinfo() путь к файлу. {string|array}

Метод «ddTools::regEmptyClientScript»

Добавляет необходимый файл JavaScript в нужный внутренний список MODx в соответствии с его именем и версией. Предназначен для регистрации скриптов, которые уже были подключены в ручную.

Внимание! Метод не добавляет код скрипта, только регистрирует его имя и версию, чтобы дальнейшие вызовы $modx->regClientScript или $modx->regClientStartupScript не приводили к повторному подключению того, что уже было подключено руками. Более того, если скрипт был ранее подключен при помощи $modx->regClientScript или $modx->regClientStartupScript, его код будет очищен, т.к. предполагается, что вы его подключили в ручную.

ddTools::regEmptyClientScript($params = [
	'name' => '',
	'version' => '0',
	'startup' => false
]);
$params * Объект параметров. {array_associative|stdClass}
$params['name'] * Имя скрипта. {string}
$params['version'] Версия скрипта. {string} '0'
$params['startup'] Подключён ли скрипт в ? {boolean} false

Метод «ddTools::getDocumentIdByUrl»

Получает id документа по его адресу.

ddTools::getDocumentIdByUrl($url);
$url * Адрес. {string}

Метод «ddTools::verifyRenamedParams»

Проверяет наличие устаревших названий параметров и записывает предупреждение в журнал событий MODX. Возвращает ассоциативный массив, где ключ — правильное имя параметра, а значение — значение. Используйте функцию «extract», чтобы извлечь результат в переменные.

ddTools::verifyRenamedParams($params, $compliance);
$params * Ассоциативный массив параметров, где ключ — имя параметра, значение — значение. В коде любого сниппета можете просто использовать переменную «$params». {array_associative}
$compliance * Массив соответствия старых имён параметров новым, где ключ — новое имя, значение — старое. {array_associative}
$compliance[i] * Старое имя. Поддерживается несколько старых имён, для этого передавайте массив. {string|array}

Метод «ddTools::sendMail»

Отправляет e-mail.

ddTools::sendMail($params = [
	'to' => ['code@DivanDesign.biz'],
	'text' => '',
	'from' => $modx->getConfig('emailsender'),
	'subject' => 'Mail from '.$modx->getConfig('site_url'),
	'fileInputNames' => []
]);
$params * Объект параметров. {array_associative|stdClass}
$params['to'] * Адреса получателей. {array}
$params['to'][i] * Адрес. {string_email}
$params['text'] * Текст сообщения. {string}
$params['from'] Адрес отправителя. {string} $modx->getConfig('emailsender')
$params['subject'] Тема письма. {string} 'Mail from '.$modx->config['site_url']
$params['fileInputNames'] “input” tags names from which accepted files are taken. {array}
$params['fileInputNames'][i] * Input name. {string}

Метод «ddTools::copyDir»

Рекурсивно копирует папку вместе с её содержимым.

ddTools::copyDir($sourceDir, $destinationDir);
$sourceDir * Папка, содержимое которой надо скопировать. {string}
$destinationDir * Папка, куда будет скопировано содержимое. {string}

Метод «ddTools::removeDir»

Удаляет папку со всеми вложенными файлами и папками (рекурсивно).

ddTools::removeDir($dir);
$dir * Адрес папки, которую необходимо удалить. {string}

Метод «ddTools::generateRandomString»

Генерирует случайную строку нужной длины.

ddTools::generateRandomString(
	$length = 8,
	$chars = 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ123456789'
);
$length Размер строки на выходе. {integer} 8
$chars Набор символов для генерации. {string} 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ123456789'

Метод «ddTools::getResponse»

Возвращает конкретную реализацию класса «ddTools\Response», которая соответствует версии переданной схемы.

ddTools::getResponse($version = null);
$version Версия схемы. Если этот параметр не передан, то будет возвращен экземпляр класса самой новой версии. {string} null

Примеры

Разбивка строки в ассоциативный массив по двум разделителям

ddTools::explodeAssoc('pagetitle::Test pagetitle||menuindex::2||published::0');

Вернёт:

[
	'pagetitle' => 'Test pagetitle',
	'menuindex' => '2',
	'published' => '0'
];

Развёртка ассоциативного массива

$someArray = [
	'a' => '',
	'b' => [
		'b1' => '',
		'b2' => [
			'b21' => '',
			'b22' => ''
		]
	],
	'c' => ''
];

$someArray = ddTools::unfoldArray($someArray);

Вернёт:

[
	'a' => '',
	'b.b1' => '',
	'b.b2.b21' => '',
	'b.b2.b22' => '',
	'c' => ''
]

Сортировка двумерного массива по нескольким колонкам

Пусть у нас есть табличка фруктов:

Ключи 'name' 'count'
0 'Груши' 3
1 'Мандарины' 2
2 'Бананы' 3
3 'Яблоки' 1

В виде массива она будет выглядеть так:

$fruits = [
	0 => ['name' => 'Груши', 'count' => 3],
	1 => ['name' => 'Мандарины', 'count' => 2],
	2 => ['name' => 'Бананы', 'count' => 3],
	3 => ['name' => 'Яблоки', 'count' => 1]
];

Отсортируем по количеству, затем по названию:

$fruits = ddTools::sort2dArray($fruits, ['count', 'name']);

Вернёт:

[
	0 => ['name' => 'Яблоки', 'count' => 1]
	1 => ['name' => 'Мандарины', 'count' => 2],
	3 => ['name' => 'Бананы', 'count' => 3],
	4 => ['name' => 'Груши', 'count' => 3],
];

У бананов и груш одинаковое количество, так что между собой они отсортированы по названию.

Разделение ассоциативного массива, содержащего значения полей документа и TV на два разных

ddTools::explodeFieldsArr([
	'pagetitle' => 'Test',
	'some_image' => 'assets/images/some_image.png',
	'another_tv' => 'Test tv'
	'longtitle' => 'Long test',
]);

Вернёт:

[
	[
		'pagetitle' => 'Test',
		'longtitle' => 'Long test'
	],
	[
		'some_image' => [
			'val' => 'assets/images/some_image.png',
			'id' => 123
		],
		'another_tv' => [
			'val' => 'Test tv',
			'id' => 321
		]
	]
];

Парсинг произовльного текста (замена плэйсхолдеров на значения)

ddTools::parseText([
	'text' => '<div>[+test1+], [+test2+]</div>',
	'data' => [
		'test1' => 'Hello',
		'test2' => 'world'
	]
]);

Вернёт:

'<div>Hello, world</div>';

Создание опубликованного документа с шаблоном 36 в корне сайта (+ запомним id созданного документа)

$id = ddTools::createDocument([
	'pagetitle' => 'Test document',
	'template' => 36,
	'published' => 1
]);

Обновление заголовка документа и заголовка меню у документа

ddTools::udateDocument($id, [
	'pagetitle' => 'Tested document',
	'menutitle' => 'Omg'
]);

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

ddTools::getDocumentChildrenTVarOutput(
	15,
	['pagetitle', 'someTv'],
	1,
	'menuindex',
	'ASC',
	'sc.template = 5'
);

Получение индексированного массива необходимых дочерних документов с сортировкой по дате публикации в обратном порядке и заголовку

ddTools::getDocumentChildrenTVarOutput(
	15,
	['pagetitle', 'someTv', 'content'],
	1,
	'pub_date DESC, pagetitle ASC',
	'',
	'',
	'all'
);

Обработка устаревших названий параметров в сниппете

Пусть у нас был сниппет, например «ddSendFeedback», были у него параметры «getEmail» и «getId», но со временем мы решили их переименовать в «docField» и «docId» соответственно (как произошло в версии 1.9). При этом, мы не хотим нарушать обратную совместимость, старые имена надо поддерживать, но надо поругаться в лог событий MODX, о том, что параметры переименованы.

Просто вызываем где-то вначале сниппета:

//Подключаем MODX.ddTools
require_once $modx->getConfig('base_path').'assets/libs/ddTools/modx.ddtools.class.php';

//Для обратной совместимости
extract(ddTools::verifyRenamedParams($params, [
	//Новое имя => Старое имя
	'docField' => 'getEmail',
	'docId' => 'getId'
]));

Даже при вызовах со старыми названиями дальше по коду будут доступны переменные с новыми именами «$docField» и «$docId», содержащие необходимые значения. Метод сам всё проверит и сообщит в лог о том, что параметры переименованы при необходимости.

Спустя некоторое время мы решили ещё раз переименовать эти параметры в «email_docField» и «email_docId». Не беда, метод поддерживает как строки, так и массивы, перечисляем все устаревшие имена:

extract(ddTools::verifyRenamedParams($params, [
	//Новое имя => Старые имена
	'email_docField' => ['docField', 'getEmail'],
	'email_docId' => ['docId', 'getId']
]));