Version 2.3

CHANGELOG.md

@@ -1,73 +1,91 @@
 # (MODX)EvolutionCMS.snippets.ddGetFileInfo changelog
 
+
+## Version 2.3 (2019-12-12)
+* \+ If `file` doesn't contain base path, the snippet will add it.
+* \* `fopen` is not used anymore because `@` operator doesn't always work.
+* \* `filesize` is used only for local files, not for URLs. `@` steel used because not only URLs will generate errors.
+
+
 ## Version 2.2.1 (2018-11-24)
 * \* Critical variable name error was fixed.
 
+
 ## 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.
+* \+ 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:
+	* \* `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.
+	* \+ Added `EnFull` value.
+	* \* Is equal to `EnShort` by default.
+
 
 ## Version 2.1 (2015-12-28)
-* \+ Добавлен вывод типа файла (плэйсхолдер «[+type+]» при выводе через «tpl» и «type» в «output» соответственно). Удобно использовать с [Font Awesome](http://fontawesome.io/).
+* \+ Добавлен вывод типа файла (плэйсхолдер `[+type+]` при выводе через `tpl` и `type` в `output` соответственно). Удобно использовать с [Font Awesome](http://fontawesome.io/).
 * \* Нулевой размер файла выводится (не считается ошибкой filesize).
-* \* Сниппет «ddGetDocumentField» больше не используется, значение поля документа получается при помощи метода «ddTools::getTemplateVarOutput».
-* \* Вместо прямого обращения к полю «$modx->config» используется метод «$modx->getConfig».
-* \* Внимание! Сниппет использует библиотеку «modx.ddTools» версии 0.15.
+* \* Сниппет `ddGetDocumentField` больше не используется, значение поля документа получается при помощи метода `ddTools::getTemplateVarOutput`.
+* \* Вместо прямого обращения к полю `$modx->config` используется метод `$modx->getConfig`.
+* \* Внимание! Сниппет использует библиотеку `modx.ddTools` версии 0.15.
+
 
 ## Version 2.0 (2014-03-25)
-* \* Сниппет переименован в «ddGetFileInfo».
+* \* Сниппет переименован в `ddGetFileInfo`.
 * \* Следующие параметры были переименованы:
-	* \* «$getField» → «$docField».
-	* \* «$getId» → «$docId».
-	* \* «$type» → «$sizeType».
-	* \* «$prec» → «$sizePrec».
+	* \* `getField` → `docField`.
+	* \* `getId` → `docId`.
+	* \* `type` → `sizeType`.
+	* \* `prec` → `sizePrec`.
 * \* При выводе через шаблон следующие плэйсхолдеры были переименованы:
-	* \* «[+filesize+]» → «[+size+]».
-	* \* «[+fileext+]» → «[+extension+]».
-	* \* «[+filename+]» → «[+name+]».
-	* \* «[+filepath+]» → «[+path+]».
-* \+ Добавлен параметр «$output», позволяющий задать, что именно будет выводиться, если не задан шаблон.
+	* \* `[+filesize+]` → `[+size+]`.
+	* \* `[+fileext+]` → `[+extension+]`.
+	* \* `[+filename+]` → `[+name+]`.
+	* \* `[+filepath+]` → `[+path+]`.
+* \+ Добавлен параметр `$output`, позволяющий задать, что именно будет выводиться, если не задан шаблон.
+
 
 ## Version 1.6.1 (2013-10-23)
-* \+ Существование файла теперь проверяется через «fopen», что позволяет работать с удалёнными файлами.
-* \* Если имя файла начинается с сивола «/», он всегда вырезается.
-* \* Если размер файла получить не удалось (например, файл где-то в интернетах), плэйсхолдер «filesize» в чанке «tpl» будет содержать пустую строку.
+* \+ Существование файла теперь проверяется через `fopen`, что позволяет работать с удалёнными файлами.
+* \* Если имя файла начинается с сивола `/`, он всегда вырезается.
+* \* Если размер файла получить не удалось (например, файл где-то в интернетах), плэйсхолдер `filesize` в чанке `tpl` будет содержать пустую строку.
 * \* Рефакторинг.
 
+
 ## Version 1.6 (2013-08-14)
 * \* Внимание! Нарушена обратная совместимость.
-* \+ При выводе через шаблон добавлен плэйсхолдер «[+file+]» (полный адрес файла).
-* \* При выводе через шаблон плэйсхолдер «[+ext+]» переименован в «[+fileext+]» (для однообразности).
-* \- Удалён параметр «getPublished» за ненадобностью.
+* \+ При выводе через шаблон добавлен плэйсхолдер `[+file+]` (полный адрес файла).
+* \* При выводе через шаблон плэйсхолдер `[+ext+]` переименован в `[+fileext+]` (для однообразности).
+* \- Удалён параметр `getPublished` за ненадобностью.
+
 
 ## Version 1.5 (2013-01-17)
-* \+ Добавлена возможность передавать дополнительные (параметр «placeholders») в чанк «tpl».
-* \* Внимание! Сниппет теперь использует библиотеку ddTools 0.4 (при использовании параметра «placeholders»).
+* \+ Добавлена возможность передавать дополнительные (параметр `placeholders`) в чанк `tpl`.
+* \* Внимание! Сниппет теперь использует библиотеку ddTools 0.4 (при использовании параметра `placeholders`).
+
 
 ## Version 1.4 (2012-08-13)
-* \+ При выводе через шаблон добавлены плэйсхолдеры: «[+filename+]» (имя файла), «[+filepath+]» (путь к файлу).
+* \+ При выводе через шаблон добавлены плэйсхолдеры: `[+filename+]` (имя файла), `[+filepath+]` (путь к файлу).
+
 
 ## Version 1.3 (2011-06-07)
-* \+ Добавлена возможность получения адреса файла из поля заданного документа (добавлены параметры «getId», «getField», «getPublished»).
+* \+ Добавлена возможность получения адреса файла из поля заданного документа (добавлены параметры `getId`, `getField`, `getPublished`).
+
 
 ## Version 1.2 (2011-04-20)
 * \+ Если файл получить не удалось, пробуем отрезать '/' от начала имени.
-* \+ Добавлен плейсхолдер «[+ext+]», в который записывается расширение файла при выводе через шаблон.
+* \+ Добавлен плейсхолдер `[+ext+]`, в который записывается расширение файла при выводе через шаблон.
+
 
 ## Version 1.0 (2010)
 * \+ The first release.
 
+
 <style>ul{list-style:none;}</style>

README.md

@@ -1,2 +1,100 @@
 # (MODX)EvolutionCMS.snippets.ddGetFileInfo
-Выводит информацию о фале: размер, имя, расширение и пр.
+
+Выводит информацию о фале: размер, имя, расширение и пр.
+
+
+## # Requires
+* PHP >= 5.4
+* [(MODX)EvolutionCMS](https://github.com/evolution-cms/evolution) >= 1.1
+* [(MODX)EvolutionCMS.libraries.ddTools](https://code.divandesign.biz/modx/ddtools) >= 0.18
+
+
+## # Documentation
+
+
+### ## Installation
+
+Elements → Snippets: Create a new snippet with the following data:
+1. Snippet name: `ddGetFileInfo`.
+2. Description: `<b>2.3</b> Выводит информацию о фале: размер, имя, расширение и пр.`.
+3. Category: `Core`.
+4. Parse DocBlock: `no`.
+5. Snippet code (php): Insert content of the `ddGetFileInfo_snippet.php` file from the archive.
+
+
+### ## Parameters description
+
+* `file`
+	* Desctription: Имя файла (путь).
+	* Valid values:
+		* `string_filePath` — путь к файлу можно указать относительно корня сайта (`/` в начале не играет роли, поддерживаются оба варианта), а можно и полный (включая `$modx->config['base_path']`)
+		* `string_url` — можно указать не только локальный файл, но и адрес в интернете, но в этом случае по объективным причинам поддерживаются не все функции
+	* **Required**
+
+* `file_docField`
+	* Desctription: Поле документа (включая TV), содержащее путь к файлу (если вы хотите, чтобы сниппет получил адрес файла из поля документа).
+	* Valid values: `string`
+	* Default value: —
+
+* `file_docId`
+	* Desctription: ID документа, из поля которого нужно получить адрес файла.
+	* Valid values: `integer_docId`
+	* Default value: —
+
+* `sizeNameFormat`
+	* Desctription: Формат вывода названия размера файла.
+	* Valid values:
+		* `'none'`
+		* `'EnShort'` — e. g. `MB`
+		* `'EnFull'` — e. g. `Megabyte`
+		* `'RuShort'` — e. g. `Мб`
+		* `'RuFull'` — e. g. `Мегабайт`
+	* Default value: `'EnShort'`
+
+* `sizePrecision`
+	* Desctription: Количество цифр после запятой.
+	* Valid values: `integer`
+	* Default value: `2`
+
+* `output`
+	* Desctription: Что нужно вернуть, если не задан шаблон `tpl`.
+	* Valid values:
+		* `'size'`
+		* `'extension'`
+		* `'type'`
+		* `'name'`
+		* `'path'`
+	* Default value: `'size'`
+
+* `tpl`
+	* Desctription: Шаблон для вывода (без шаблона возвращает согласно параметру `output`).
+		
+		Available placeholders:
+		* `[+file+]` — полный адрес файла
+		* `[+name+]` — имя файла
+		* `[+path+]` — путь к файлу
+		* `[+size+]` — размер файла
+		* `[+extension+]` — расширение файла
+		* `[+type+]` — тип файла:
+			* `'archive'`
+			* `'image'`
+			* `'video'`
+			* `'audio'`
+			* `'text'`
+			* `'pdf'`
+			* `'word'`
+			* `'excel'`
+			* `'powerpoint'`
+			* `''`
+		
+	* Valid values:
+		* `string_chunkName`
+		* `string` — use inline templates starting with `@CODE:`
+	* Default value: —
+
+* `tpl_placeholders`
+	* Desctription: Additional data has to be passed into the `tpl`. Arrays are supported too: `some[a]=one&some[b]=two` => `[+some.a+]`, `[+some.b+]`; `some[]=one&some[]=two` => `[+some.0+]`, `[some.1]`.
+	* Valid values:
+		* `stirng_json` — as [JSON](https://en.wikipedia.org/wiki/JSON)
+		* `string_queryFormated` — as [Query string](https://en.wikipedia.org/wiki/Query_string)
+	* Default value: —

composer.json

@@ -0,0 +1,19 @@
+{
+	"name": "dd/evolutioncms-snippets-ddgetfileinfo",
+	"type": "modxevo-snippet",
+	"version": "2.3",
+	"description": "Выводит информацию о фале: размер, имя, расширение и пр.",
+	"keywords": [
+		"modx",
+		"modx evo",
+		"modx evolution",
+		"evo",
+		"evo cms",
+		"evolution cms",
+		"ddgetfileinfo"
+	],
+	"require": {
+		"php": ">=5.4",
+		"dd/modxevo-library-ddtools": ">=0.18"
+	}
+}