Version 2.2

DivanDesign · Nov 24, 2018 · 53449e7 · 53449e7
2 parents 089fe6b + 7036ecd
commit 53449e7
Show file tree

Hide file tree

Showing 3 changed files with 229 additions and 96 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -0,0 +1,70 @@
+# (MODX)EvoCMS.snippets.ddGetFileSize changelog
+
+## Version 2.2 (2018-11-24)
+* \* Attention! PHP >= 5.4 is required.
+* \* Attention! MODXEvo >= 1.1 is required.
+* \* Attention! MODXEvo.libraries.ddTools >= 0.18 is required.
+* \+ Added JSON and Query string formats support for the “tpl_placeholders” parameter (with backward compatibility).
+* \+ Added support of the “@CODE:” keyword prefix in the “tpl” parameter.
+* \* The following parameters were renamed (with backward compatibility):
+	* \* “docField” → “file_docField”.
+	* \* “docId” → “file_docId”.
+	* \* “sizeType” → “sizeNameFormat”.
+	* \* “sizePrec” → “sizePrecision”.
+	* \* “placeholders” → “tpl_placeholders”.
+* \* The “sizeNameFormat” parameter changes:
+	* \* User-friendly values.
+	* \+ Added “EnFull” value.
+	* \* Is equal to “EnShort” by default.
+
+## Version 2.1 (2015-12-28)
+* \+ Добавлен вывод типа файла (плэйсхолдер «[+type+]» при выводе через «tpl» и «type» в «output» соответственно). Удобно использовать с [Font Awesome](http://fontawesome.io/).
+* \* Нулевой размер файла выводится (не считается ошибкой filesize).
+* \* Сниппет «ddGetDocumentField» больше не используется, значение поля документа получается при помощи метода «ddTools::getTemplateVarOutput».
+* \* Вместо прямого обращения к полю «$modx->config» используется метод «$modx->getConfig».
+* \* Внимание! Сниппет использует библиотеку «modx.ddTools» версии 0.15.
+
+## Version 2.0 (2014-03-25)
+* \* Сниппет переименован в «ddGetFileInfo».
+* \* Следующие параметры были переименованы:
+	* \* «$getField» → «$docField».
+	* \* «$getId» → «$docId».
+	* \* «$type» → «$sizeType».
+	* \* «$prec» → «$sizePrec».
+* \* При выводе через шаблон следующие плэйсхолдеры были переименованы:
+	* \* «[+filesize+]» → «[+size+]».
+	* \* «[+fileext+]» → «[+extension+]».
+	* \* «[+filename+]» → «[+name+]».
+	* \* «[+filepath+]» → «[+path+]».
+* \+ Добавлен параметр «$output», позволяющий задать, что именно будет выводиться, если не задан шаблон.
+
+## Version 1.6.1 (2013-10-23)
+* \+ Существование файла теперь проверяется через «fopen», что позволяет работать с удалёнными файлами.
+* \* Если имя файла начинается с сивола «/», он всегда вырезается.
+* \* Если размер файла получить не удалось (например, файл где-то в интернетах), плэйсхолдер «filesize» в чанке «tpl» будет содержать пустую строку.
+* \* Рефакторинг.
+
+## Version 1.6 (2013-08-14)
+* \* Внимание! Нарушена обратная совместимость.
+* \+ При выводе через шаблон добавлен плэйсхолдер «[+file+]» (полный адрес файла).
+* \* При выводе через шаблон плэйсхолдер «[+ext+]» переименован в «[+fileext+]» (для однообразности).
+* \- Удалён параметр «getPublished» за ненадобностью.
+
+## Version 1.5 (2013-01-17)
+* \+ Добавлена возможность передавать дополнительные (параметр «placeholders») в чанк «tpl».
+* \* Внимание! Сниппет теперь использует библиотеку ddTools 0.4 (при использовании параметра «placeholders»).
+
+## Version 1.4 (2012-08-13)
+* \+ При выводе через шаблон добавлены плэйсхолдеры: «[+filename+]» (имя файла), «[+filepath+]» (путь к файлу).
+
+## Version 1.3 (2011-06-07)
+* \+ Добавлена возможность получения адреса файла из поля заданного документа (добавлены параметры «getId», «getField», «getPublished»).
+
+## Version 1.2 (2011-04-20)
+* \+ Если файл получить не удалось, пробуем отрезать '/' от начала имени.
+* \+ Добавлен плейсхолдер «[+ext+]», в который записывается расширение файла при выводе через шаблон.
+
+## Version 1.0 (2010)
+* \+ The first release.
+
+<style>ul{list-style:none;}</style>
diff --git a/README.md b/README.md
@@ -1,55 +1,2 @@
-# ddGetFileSize
-Выводит размер файла.
-
-## Changelog
-### 2.1 (2015-12-28)
-* \+ Добавлен вывод типа файла (плэйсхолдер «[+type+]» при выводе через «tpl» и «type» в «output» соответственно). Удобно использовать с [Font Awesome](http://fontawesome.io/).
-* \* Нулевой размер файла выводится (не считается ошибкой filesize).
-* \* Сниппет «ddGetDocumentField» больше не используется, значение поля документа получается при помощи метода «ddTools::getTemplateVarOutput».
-* \* Вместо прямого обращения к полю «$modx->config» используется метод «$modx->getConfig».
-* \* Внимание! Сниппет использует библиотеку «modx.ddTools» версии 0.15.
-
-### 2.0 (2014-03-25)
-* \* Сниппет переименован в «ddGetFileInfo».
-* \* Следующие параметры были переименованы:
-	* \* «$getField» → «$docField».
-	* \* «$getId» → «$docId».
-	* \* «$type» → «$sizeType».
-	* \* «$prec» → «$sizePrec».
-* \* При выводе через шаблон следующие плэйсхолдеры были переименованы:
-	* \* «[+filesize+]» → «[+size+]».
-	* \* «[+fileext+]» → «[+extension+]».
-	* \* «[+filename+]» → «[+name+]».
-	* \* «[+filepath+]» → «[+path+]».
-* \+ Добавлен параметр «$output», позволяющий задать, что именно будет выводиться, если не задан шаблон.
-
-### 1.6.1 (2013-10-23)
-* \+ Существование файла теперь проверяется через «fopen», что позволяет работать с удалёнными файлами.
-* \* Если имя файла начинается с сивола «/», он всегда вырезается.
-* \* Если размер файла получить не удалось (например, файл где-то в интернетах), плэйсхолдер «filesize» в чанке «tpl» будет содержать пустую строку.
-* \* Рефакторинг.
-
-### 1.6 (2013-08-14)
-* \* Внимание! Нарушена обратная совместимость.
-* \+ При выводе через шаблон добавлен плэйсхолдер «[+file+]» (полный адрес файла).
-* \* При выводе через шаблон плэйсхолдер «[+ext+]» переименован в «[+fileext+]» (для однообразности).
-* \- Удалён параметр «getPublished» за ненадобностью.
-
-### 1.5 (2013-01-17)
-* \+ Добавлена возможность передавать дополнительные (параметр «placeholders») в чанк «tpl».
-* \* Внимание! Сниппет теперь использует библиотеку ddTools 0.4 (при использовании параметра «placeholders»).
-
-### 1.4 (2012-08-13)
-* \+ При выводе через шаблон добавлены плэйсхолдеры: «[+filename+]» (имя файла), «[+filepath+]» (путь к файлу).
-
-### 1.3 (2011-06-07)
-* \+ Добавлена возможность получения адреса файла из поля заданного документа (добавлены параметры «getId», «getField», «getPublished»).
-
-### 1.2 (2011-04-20)
-* \+ Если файл получить не удалось, пробуем отрезать '/' от начала имени.
-* \+ Добавлен плейсхолдер «[+ext+]», в который записывается расширение файла при выводе через шаблон.
-
-### 1.0
-* \+ Первая версия.
-
-<style>ul{list-style:none;}</style>
+# (MODX)EvoCMS.snippets.ddGetFileSize
+Выводит информацию о фале: размер, имя, расширение и пр.
diff --git a/ddGetFileInfo.php b/ddGetFileInfo.php
@@ -1,28 +1,49 @@
 <?php
 /**
- * ddGetFileInfo.php
- * @version 2.1 (2015-12-28)
+ * ddGetFileInfo
+ * @version 2.2 (2018-11-24)
  * 
  * @desc Выводит информацию о фале: размер, имя, расширение и пр.
  * 
- * @uses The library modx.ddTools 0.15.
+ * @uses PHP >= 5.4.
+ * @uses MODXEvo >= 1.1.
+ * @uses MODXEvo.libraries.ddTools >= 0.18.
  * 
  * @param $file {string} — Имя файла (путь). @required
- * @param $docField {string} — Поле документа, содержащее путь к файлу. Default: —.
- * @param $docId {integer} — Id документа из которого берётся поле. Default: —.
- * @param $sizeType {-1|0|1|2} — Тип вывода размера файла. Default: 0.
- * @param $sizePrec {integer} — Количество цифр после запятой. Default: 2.
+ * @param $file_docField {string} — Поле документа, содержащее путь к файлу. Default: —.
+ * @param $file_docId {integer} — Id документа из которого берётся поле. Default: —.
+ * @param $sizeNameFormat {'none'|'EnShort'|'EnFull'|'RuShort'|'RuFull'} — Формат вывода названия размера файла (MB || Megabyte || Мб || Мегабайт). Default: 'EnShort'.
+ * @param $sizePrecision {integer} — Количество цифр после запятой. Default: 2.
  * @param $output {'size'|'extension'|'type'|'name'|'path'} — Что нужно вернуть, если не задан шаблон. Default: 'size'.
- * @param $tpl {string: chunkName} — Шаблон для вывода, без шаблона возвращает просто размер. Доступные плэйсхолдеры: [+file+] (полный адрес файла), [+name+] (имя файла), [+path+] (путь к файлу), [+size+] (размер файла), [+extension+] (расширение файла), [+type+] (тип файла: 'archive', 'image', 'video', 'audio', 'text', 'pdf', 'word', 'excel', 'powerpoint', ''). Default: —.
- * @param $placeholders {separated string} — Дополнительные данные, которые необходимо передать в чанк «tpl». Формат: строка, разделённая '::' между парой ключ-значение и '||' между парами. Default: ''.
+ * @param $tpl {string_chunkName|string} — Шаблон для вывода, без шаблона возвращает просто размер (chunk name or code via “@CODE:” prefix). Доступные плэйсхолдеры: [+file+] (полный адрес файла), [+name+] (имя файла), [+path+] (путь к файлу), [+size+] (размер файла), [+extension+] (расширение файла), [+type+] (тип файла: 'archive', 'image', 'video', 'audio', 'text', 'pdf', 'word', 'excel', 'powerpoint', ''). Default: —.
+ * @param $tpl_placeholders {stirng_json|string_queryFormated} — Additional data as JSON (https://en.wikipedia.org/wiki/JSON) or Query string (https://en.wikipedia.org/wiki/Query_string) has to be passed into “tpl”. Default: ''.
+ * @example &tpl_placeholders=`{"pladeholder1": "value1", "pagetitle": "My awesome pagetitle!"}`
  * 
- * @copyright 2010–2015 DivanDesign {@link http://www.DivanDesign.biz }
+ * @copyright 2010–2018 DivanDesign {@link http://www.DivanDesign.biz }
  */
 
+//Include MODXEvo.libraries.ddTools
+require_once $modx->getConfig('base_path').'assets/libs/ddTools/modx.ddtools.class.php';
+
+//Backward compatibility
+extract(ddTools::verifyRenamedParams(
+	$params,
+	[
+		'file_docField' => 'docField',
+		'file_docId' => 'docId',
+		'sizeNameFormat' => 'sizeType',
+		'sizePrecision' => 'sizePrec',
+		'tpl_placeholders' => 'placeholders'
+	]
+));
+
 //Получаем имя файла из заданного поля
-if (isset($docField)){
-	$file = ddTools::getTemplateVarOutput(array($docField), $docId);
-	$file = $file[$docField];
+if (isset($file_docField)){
+	$file = ddTools::getTemplateVarOutput(
+		[$file_docField],
+		$file_docId
+	);
+	$file = $file[$file_docField];
 }
 
 $result = '';
@@ -31,29 +52,93 @@
 	$output = isset($output) ? $output : 'size';
 
 	//Всегда удаляем слэш слева
-	$file = ltrim($file, '/');
+	$file = ltrim(
+		$file,
+		'/'
+	);
 
 	//Пытаемся открыть файл
-	$fileHandle = @fopen($file, 'r');
+	$fileHandle = @fopen(
+		$file,
+		'r'
+	);
 
 	if ($fileHandle){
 		fclose($fileHandle);
 
-		$sizeType = isset($sizeType) ? intval($sizeType) : 0;
-		$sizePrec = isset($sizePrec) ? intval($sizePrec) : 2;
+		$sizeNameFormat = isset($sizeNameFormat) ? $sizeNameFormat : 'EnShort';
+		$sizePrecision = isset($sizePrecision) ? intval($sizePrecision) : 2;
+
+		//Backward compatibility
+		if (is_numeric($sizeNameFormat)){
+			$sizeNameFormat = strtr(
+				$sizeNameFormat,
+				[
+					'-1' => 'none',
+					'0' => 'RuShort',
+					'1' => 'RuFull',
+					'2' => 'EnShort',
+				]
+			);
+		}
 
-		//TODO: Переделать на какие-то человеко-понятные ключи
 		if (!function_exists('ddfsize_format')){
-			function ddfsize_format($size, $type, $prec){
+			function ddfsize_format(
+				$size,
+				$type,
+				$prec
+			){
 				//устанавливаем конфигурацию вывода приставок, надеюсь разберетесь
-				if ($type == -1){
-					$mas = array('', '', '', '', '', '', '');
-				}else if ($type == 0){
-					$mas = array(' б', ' Кб', ' Мб', ' Гб', ' Тб', ' Пб', ' Эб');
-				}else if ($type == 1){
-					$mas = array(' байт', ' Килобайт', ' Мегабайт', ' Гигабайт', ' Терабайт', ' Петабайт', ' Эксабайт');
-				}else if ($type == 2){
-					$mas = array(' B', ' KB', ' MB', ' GB', ' TB', ' PB', ' EB');
+				if ($type == 'none'){
+					$mas = [
+						'',
+						'',
+						'',
+						'',
+						'',
+						'',
+						''
+					];
+				}else if ($type == 'RuShort'){
+					$mas = [
+						' б',
+						' Кб',
+						' Мб',
+						' Гб',
+						' Тб',
+						' Пб',
+						' Эб'
+					];
+				}else if ($type == 'RuFull'){
+					$mas = [
+						' байт',
+						' Килобайт',
+						' Мегабайт',
+						' Гигабайт',
+						' Терабайт',
+						' Петабайт',
+						' Эксабайт'
+					];
+				}else if ($type == 'EnShort'){
+					$mas = [
+						' B',
+						' KB',
+						' MB',
+						' GB',
+						' TB',
+						' PB',
+						' EB'
+					];
+				}else if ($type == 'EnFull'){
+					$mas = [
+						' Bytes',
+						' Kilobytes',
+						' Megabytes',
+						' Gigabytes',
+						' Terabytes',
+						' Petabytes',
+						' Exabytes'
+					];
 				}
 
 				$i = 0;
@@ -62,35 +147,59 @@ function ddfsize_format($size, $type, $prec){
 					$i++;
 				}
 
-				return round($size, $prec).$mas[$i];
+				return round(
+					$size,
+					$prec
+				).$mas[$i];
 			}
 		}
 
-		$extPos = strrpos($file, '.');
-		$folPos = strrpos($file, '/');
+		$extPos = strrpos(
+			$file,
+			'.'
+		);
+		$folPos = strrpos(
+			$file,
+			'/'
+		);
 
 		//TODO: Использовать класс «SplFileInfo»
-		$resArr = array(
+		$resArr = [
 			//Полный адрес файла
 			'file' => $file,
 			//Размер
 			'size' => '',
 			//Расширение
-			'extension' => substr($file, $extPos + 1),
+			'extension' => substr(
+				$file,
+				$extPos + 1
+			),
 			//«Тип» файла
 			'type' => '',
 			//Имя файла
-			'name' => substr($file, $folPos + 1, $extPos - $folPos - 1),
+			'name' => substr(
+				$file,
+				$folPos + 1,
+				$extPos - $folPos - 1
+			),
 			//Путь к файлу
-			'path' => substr($file, 0, $folPos),
-		);
+			'path' => substr(
+				$file,
+				0,
+				$folPos
+			),
+		];
 
 		//Пробуем получить размер файла
 		$filesize = @filesize($file);
 		//Если вышло
 		if ($filesize !== false){
 			//Формируем строку размера файла
-			$resArr['size'] = ddfsize_format($filesize, $sizeType, $sizePrec);
+			$resArr['size'] = ddfsize_format(
+				$filesize,
+				$sizeNameFormat,
+				$sizePrecision
+			);
 		}
 
 		//Пытаемся определить тип файла
@@ -168,15 +277,22 @@ function ddfsize_format($size, $type, $prec){
 		//Если есть tpl, то парсим или возвращаем размер
 		if (isset($tpl)){
 			//Если есть дополнительные данные
-			if (isset($placeholders)){
-				//Подключаем modx.ddTools
-				require_once $modx->getConfig('base_path').'assets/libs/ddTools/modx.ddtools.class.php';
+			if (isset($tpl_placeholders)){
+				$tpl_placeholders = ddTools::encodedStringToArray($tpl_placeholders);
+				//Unfold for arrays support (e. g. “{"somePlaceholder1": "test", "somePlaceholder2": {"a": "one", "b": "two"} }” => “[+somePlaceholder1+]”, “[+somePlaceholder2.a+]”, “[+somePlaceholder2.b+]”; “{"somePlaceholder1": "test", "somePlaceholder2": ["one", "two"] }” => “[+somePlaceholder1+]”, “[+somePlaceholder2.0+]”, “[somePlaceholder2.1]”)
+				$tpl_placeholders = ddTools::unfoldArray($tpl_placeholders);
 
 				//Разбиваем их
-				$resArr = array_merge($resArr, ddTools::explodeAssoc($placeholders));
+				$resArr = array_merge(
+					$resArr,
+					$tpl_placeholders
+				);
 			}
 
-			$result = $modx->parseChunk($tpl, $resArr, '[+', '+]');
+			$resultStr = ddTools::parseText([
+				'text' => $modx->getTpl($tpl),
+				'data' => $resArr
+			]);
 		}else{
 			$result = $resArr[$output];
 		}