ddTools

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

Описание

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

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

Внимание

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

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

  • Метод «ddTools::verifyRenamedParams» обновлён до 1.1.1:
    • Добавлена возможность использования нескольких старых имён в параметре «$compliance».
    • Небольной рефакторинг, стиль кода и описание.

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

Установка

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

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

Вручную

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

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

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

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

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

Поле «$documentFields»

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

Поле «$tables»

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

Метод «screening»

Экранирует символы в строке (см. код).
$str* Строка для обработки. {string}

Метод «explodeAssoc»

Разбивает строку по двум разделителям в ассоциативный массив.
$str* Строка для обработки. {separated string}
$splY Разделитель между значениями (между парами ключ-значение). {string} '||'
$splX Разделитель между ключом и значением. {string} '::'

Метод «unfoldArray»

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

Метод «sort2dArray»

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

Метод «parseText»

Аналог модексовского parseChunk, только принимает текст (+ пара плюшек).
$chunk* Строка, которую нужно парсить. {string}
$chunkArr* Массив значений. Ключ — имя плэйсхолдера, значение — значение. {array: associative}
$prefix Префикс плэйсхолдеров. {string} '[+'
$suffix Суффикс плэйсхолдеров. {string} '+]'
$mergeAll Надо ли делать дополнительно обрабатывать поля документа, настроек, чанков. {boolean} true

Метод «parseSource»

Парсит ресурс (вызывается $modx->parseDocumentSource и $modx->rewriteUrls).
$source* Текст для парсинга. {string}

Метод «explodeFieldsArr»

Разбивает ассоциативный массив полей и TV документа на два отдельных массива.
$fields* Ассоциативный массив значений полей документа (в таблице site_content) и/или TV. {array: associative}

Метод «createDocument»

Создаёт новый документ.
$fields* Массив полей или TV документа. Ключ — название поля или TV, значение — значение. Обязательно должен присутствовать заголовок нового документа (элемент 'pagetitle'). {array: associative}
$groups Индексированный массив id групп, к которым должен принадлежать документ. {array}

Метод «updateDocument»

Обновляет информацию по документу.
$id* ID документа (или массив ID), который необходимо отредактировать. {integer|array} 0
$update* Массив значений полей или TV документа. Ключ — название поля или TV, значение — значение. {array: associative}
$where SQL условие WHERE. {string: sql}

Метод «getDocuments»

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

Отличие от родного метода:
  • Параметр published может принимать 'all', в этом случае будут получены и опубликованные и неопубликованные документы.
  • Параметр deleted может принимать 'all', в этом случае будут получены и удалённые и неудалённые документы.
$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}

Метод «getDocument»

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

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

Метод «getTemplateVars»

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

Отличие от родного метода:
  • Параметр published может принимать 'all', в этом случае будут получены и опубликованные и неопубликованные документы.
$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'

Метод «getTemplateVarOutput»

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

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

Метод «getDocumentChildren»

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

Отличие от родного метода:
  • Параметр published может принимать 'all', в этом случае будут получены и опубликованные и неопубликованные документы.
  • Параметр deleted может принимать 'all', в этом случае будут получены и удалённые и неудалённые документы.
$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}

Метод «getDocumentChildrenTVarOutput»

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

Отличие от родного метода:
  • Добавлен параметр $where, который позволяет указать условие WHERE SQL-запроса для получения документов (в условии могут участвовать только поля документа).
  • Добавлен параметр $resultKey, который позволяет определить, значение какого поля будет ключами результирующего массива.
  • В $modx->getDocumentChildren получается только id (ибо зачем всё остальное, дальше ведь всё равно получается).
  • Параметр $published может принимать 'all', в этом случае будут получены и опубликованные и неопубликованные документы.
$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'

Метод «parseFileNameVersion»

Разбирает строку файла, получая из неё его имя версию.
$file* Строка пути к файлу или распаршенный при помощи pathinfo() путь к файлу. {string|array}

Метод «regEmptyClientScript»

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

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

Параметры передаются в виде ассоциативного массива, где:
$name* Имя скрипта. {string}
$version Версия скрипта. {string} '0'
$startup Подключён ли скрипт в ? {boolean} false

Метод «getDocumentIdByUrl»

Получает id документа по его адресу.
$url* Адрес. {string}

Метод «verifyRenamedParams»

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

Метод «sendMail»

Отправляет e-mail.
$to* Addresses to mail. {array}
$text* E-mail text. {string}
$from Mailer address. {string} 'info@divandesign.biz'
$subject E-mail subject. {string} 'Mail from '.$modx->config['site_url']
$fileInputName “input” tags names from which accepted files are taken. {array}

Метод «removeDir»

Удаляет папку со всеми вложенными файлами и папками (рекурсивно)
$dir* Адрес папки, которую необходимо удалить {string}

Метод «generateRandomString»

Генерирует случайную строку нужной длины.
$length Размер строки на выходе. {integer} 8
$chars Набор символов для генерации. {string} 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ123456789'

Метод «getResponse»

Возвращает конкретную реализацию класса «ddTools\Response», которая соответствует версии переданной схемы.
$version Версия схемы. Если этот параметр не передан, то будет возвращен экземпляр класса самой новой версии. {string} null

Метод «copyDir»

Рекурсивно копирует папку вместе с её содержимым.
$sourceDir* Папка, содержимое которой надо скопировать. {string}
$destinationDir* Папка, куда будет скопировано содержимое. {string}

Примеры

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

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

Вернёт:

Array(
	'pagetitle' => 'Test pagetitle',
	'menuindex' => '2',
	'published' => '0'
);

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

$someArray = array(
	'a': '',
	'b': array(
		'b1': '',
		'b2': array(
			'b21': '',
			'b22': ''
		)
	),
	'c': ''
);

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

Вернёт:

array(
	'a': '',
	'b.b1': '',
	'b.b2.b21': '',
	'b.b2.b22': '',
	'c': ''
)

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

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

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

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

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

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

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

Вернёт:

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

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

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

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

Вернёт:

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

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

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

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

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

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

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

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

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

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

ddTools::getDocumentChildrenTVarOutput(
	15,
	array('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, array(
	//Новое имя => Старое имя
	'docField' => 'getEmail',
	'docId' => 'getId'
)));

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

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

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