Version 0.7

Author: Ronef

CHANGELOG.md

@@ -1,6 +1,21 @@
 # (MODX)EvolutionCMS.snippets.ddObjectTools changelog
 
 
+## Version 0.7 (2023-03-30)
+* \* Attention! (MODX)EvolutionCMS.libraries.ddTools >= 0.57 is required.
+* \+ Parameters → `getPropValue`: You can now get the value of an object property or an array element in any nesting level. Just use `.` to get nested properties (see `\DDTools\ObjectTools::getPropValue` for more info).
+* \* Parameters → `outputter` → Valid values:
+	* \+ The snippet can also return object as a native PHP object or array (it is convenient to call through `\DDTools\Snippet`). The following new values:
+		* \* `'objectAuto'`.
+		* \* `'objectStdClass'`.
+		* \* `'objectArray'`.
+	* \* The foillowing have been changed (with backward compatibility):
+		* \* `'jsonAuto'` → `'stringJsonAuto'`.
+		* \* `'jsonObject'` → `'stringJsonObject'`.
+		* \* `'jsonArray'` → `'stringJsonArray'`.
+		* \* `'queryFormated'` → `'stringQueryFormatted'`.
+
+
 ## Version 0.6 (2023-03-08)
 * \+ Parameters → `extend->objects`: Can also be set as [JSON](https://en.wikipedia.org/wiki/JSON), [HJSON](https://hjson.github.io/) or [Query string](https://en.wikipedia.org/wiki/Query_string).
 
@@ -26,7 +41,7 @@
 
 ## Version 0.3 (2020-06-03)
 * \* Attention! (MODX)EvolutionCMS.libraries.ddTools >= 0.38.1 is required.
-* \+ Parameters → `sourceObject`, `extend`: Can also be set as `stringQueryFormated`.
+* \+ Parameters → `sourceObject`, `extend`: Can also be set as `stringQueryFormatted`.
 * \* Refactoring.
 * \* README:
 	* \- Home page.

CHANGELOG_ru.md

@@ -1,6 +1,21 @@
 # (MODX)EvolutionCMS.snippets.ddObjectTools changelog
 
 
+## Версия 0.7 (2023-03-30)
+* \* Внимание! Требуется (MODX)EvolutionCMS.libraries.ddTools >= 0.57.
+* \+ Параметры → `getPropValue`: Теперь сниппет умеет получать значение свойства объекта или элемента массива на любом уровне вложенности. Просто используйте '.' в параметре для получения свойств вложенных элементов (больше информации см. `\DDTools\ObjectTools::getPropValue`).
+* \* Параметры → `outputter` → Допустимые значения:
+	* \+ Сниппет теперь также умеет возвращать объект в виде нативного PHP объекта или массива (удобно при вызове через `\DDTools\Snippet`). Новые значения:
+		* \* `'objectAuto'`.
+		* \* `'objectStdClass'`.
+		* \* `'objectArray'`.
+	* \* Следующие допустимые значения изменены (с обратной совместимостью):
+		* \* `'jsonAuto'` → `'stringJsonAuto'`.
+		* \* `'jsonObject'` → `'stringJsonObject'`.
+		* \* `'jsonArray'` → `'stringJsonArray'`.
+		* \* `'queryFormated'` → `'stringQueryFormatted'`.
+
+
 ## Версия 0.6 (2023-03-08)
 * \+ Параметры → `extend->objects`: Также может быть задан, как [JSON](https://ru.wikipedia.org/wiki/JSON), [HJSON](https://hjson.github.io/) или [Query string](https://en.wikipedia.org/wiki/Query_string).
 
@@ -26,7 +41,7 @@
 
 ## Версия 0.3 (2020-06-03)
 * \* Внимание! Требуется (MODX)EvolutionCMS.libraries.ddTools >= 0.38.1.
-* \+ Параметры → `sourceObject`, `extend`: Также может задаваться как `stringQueryFormated`.
+* \+ Параметры → `sourceObject`, `extend`: Также может задаваться как `stringQueryFormatted`.
 * \* Рефакторинг.
 * \* README:
 	* \- Home page.

README.md

@@ -7,7 +7,7 @@ Tools for modifying objects.
 
 * PHP >= 5.6
 * [(MODX)EvolutionCMS](https://github.com/evolution-cms/evolution) >= 1.1
-* [(MODX)EvolutionCMS.libraries.ddTools](https://code.divandesign.biz/modx/ddtools) >= 0.51
+* [(MODX)EvolutionCMS.libraries.ddTools](https://code.divandesign.biz/modx/ddtools) >= 0.57
 
 
 
@@ -20,7 +20,7 @@ Tools for modifying objects.
 #### 1. Elements → Snippets: Create a new snippet with the following data
 
 1. Snippet name: `ddObjectTools`.
-2. Description: `<b>0.6</b> Tools for modifying objects.`.
+2. Description: `<b>0.7</b> Tools for modifying objects.`.
 3. Category: `Core`.
 4. Parse DocBlock: `no`.
 5. Snippet code (php): Insert content of the `ddObjectTools_snippet.php` file from the archive.
@@ -63,7 +63,7 @@ require_once(
 		* `stringJsonArray` — as [JSON](https://en.wikipedia.org/wiki/JSON)
 		* `stringHjsonObject` — as [HJSON](https://hjson.github.io/)
 		* `stringHjsonArray` — as [HJSON](https://hjson.github.io/)
-		* `stringQueryFormated` — as [Query string](https://en.wikipedia.org/wiki/Query_string)
+		* `stringQueryFormatted` — as [Query string](https://en.wikipedia.org/wiki/Query_string)
 		* It can also be set as a native PHP object or array (e. g. for calls through `$modx->runSnippet`):
 			* `array`
 			* `object`
@@ -74,7 +74,7 @@ require_once(
 	* Valid values:
 		* `stringJsonObject` — as [JSON](https://en.wikipedia.org/wiki/JSON)
 		* `stringHjsonObject` — as [HJSON](https://hjson.github.io/)
-		* `stringQueryFormated` — as [Query string](https://en.wikipedia.org/wiki/Query_string)
+		* `stringQueryFormatted` — as [Query string](https://en.wikipedia.org/wiki/Query_string)
 		* It can also be set as a native PHP object or array (e. g. for calls through `$modx->runSnippet`):
 			* `arrayAssociative`
 			* `object`
@@ -86,7 +86,7 @@ require_once(
 		* `array`
 		* `stringJsonArray` — as [JSON](https://en.wikipedia.org/wiki/JSON)
 		* `stringHjsonArray` — as [HJSON](https://hjson.github.io/)
-		* `stringQueryFormated` — as [Query string](https://en.wikipedia.org/wiki/Query_string)
+		* `stringQueryFormatted` — as [Query string](https://en.wikipedia.org/wiki/Query_string)
 	* **Required**
 
 * `extend->objects[i]`
@@ -112,19 +112,25 @@ require_once(
 	* Default value: `true`
 
 * `getPropValue`
-	* Desctription: Object property name or array index / key to return.
+	* Desctription: Object property name or array index / key to return.  
+		You can also use `'.'` to get nested properties (see `\DDTools\ObjectTools::getPropValue` for more info).
 	* Valid values: `string`
 	* Default value: —
 
 * `outputter`
 	* Desctription: Output format (when result is an object or array).  
-		Values are case insensitive (the following values are equal: `'jsonauto'`, `'JsonAuto'`, `'JSONAUTO'`, etc).
+		Values are case insensitive (the following values are equal: `'stringjsonauto'`, `'stringJsonAuto'`, `'STRINGJSONAUTO'`, etc).
 	* Valid values:
-		* `'jsonAuto'` — `jsonObject` or `jsonArray` depends on result object
-		* `'jsonObject'`
-		* `'jsonArray'`
-		* `'queryFormated'` — [Query string](https://en.wikipedia.org/wiki/Query_string)
-	* Default value: `'jsonAuto'`
+		* The snippet can return object as string:
+			* `'stringJsonAuto'` — `stringJsonObject` or `stringJsonArray` depends on result object
+			* `'stringJsonObject'`
+			* `'stringJsonArray'`
+			* `'stringQueryFormatted'` — [Query string](https://en.wikipedia.org/wiki/Query_string)
+		* The snippet can also return object as a native PHP object or array (it is convenient to call through `\DDTools\Snippet`).
+			* `'objectAuto'` — `stdClass` or `array` depends on result object
+			* `'objectStdClass'` — `stdClass`
+			* `'objectArray'` — `array`
+	* Default value: `'stringJsonAuto'`
 
 
 ## Examples

README_ru.md

@@ -7,7 +7,7 @@
 
 * PHP >= 5.6
 * [(MODX)EvolutionCMS](https://github.com/evolution-cms/evolution) >= 1.1
-* [(MODX)EvolutionCMS.libraries.ddTools](https://code.divandesign.ru/modx/ddtools) >= 0.51
+* [(MODX)EvolutionCMS.libraries.ddTools](https://code.divandesign.ru/modx/ddtools) >= 0.57
 
 
 ## Документация
@@ -22,7 +22,7 @@
 ##### 1. Элементы → Сниппеты: Создайте новый сниппет со следующими параметрами
 
 1. Название сниппета: `ddObjectTools`.
-2. Описание: `<b>0.6</b> Tools for modifying objects.`.
+2. Описание: `<b>0.7</b> Tools for modifying objects.`.
 3. Категория: `Core`.
 4. Анализировать DocBlock: `no`.
 5. Код сниппета (php): Вставьте содержимое файла `ddObjectTools_snippet.php` из архива.
@@ -65,7 +65,7 @@ require_once(
 		* `stringJsonArray` — в виде [JSON](https://ru.wikipedia.org/wiki/JSON)
 		* `stringHjsonObject` — в виде [HJSON](https://hjson.github.io/)
 		* `stringHjsonArray` — в виде [HJSON](https://hjson.github.io/)
-		* `stringQueryFormated` — в виде [Query string](https://en.wikipedia.org/wiki/Query_string)
+		* `stringQueryFormatted` — в виде [Query string](https://en.wikipedia.org/wiki/Query_string)
 		* Также может быть задан, как нативный PHP объект или массив (например, для вызовов через `$modx->runSnippet`).
 			* `array`
 			* `object`
@@ -76,7 +76,7 @@ require_once(
 	* Допустимые значения:
 		* `stringJsonObject` — в виде [JSON](https://ru.wikipedia.org/wiki/JSON)
 		* `stringHjsonObject` — в виде [HJSON](https://hjson.github.io/)
-		* `stringQueryFormated` — в виде [Query string](https://en.wikipedia.org/wiki/Query_string)
+		* `stringQueryFormatted` — в виде [Query string](https://en.wikipedia.org/wiki/Query_string)
 		* Также может быть задан, как нативный PHP объект или массив (например, для вызовов через `$modx->runSnippet`).
 			* `arrayAssociative`
 			* `object`
@@ -88,7 +88,7 @@ require_once(
 		* `array`
 		* `stringJsonArray` — в виде [JSON](https://ru.wikipedia.org/wiki/JSON)
 		* `stringHjsonArray` — в виде [HJSON](https://hjson.github.io/)
-		* `stringQueryFormated` — в виде [Query string](https://en.wikipedia.org/wiki/Query_string)
+		* `stringQueryFormatted` — в виде [Query string](https://en.wikipedia.org/wiki/Query_string)
 	* **Обязателен**
 
 * `extend->objects[i]`
@@ -114,19 +114,25 @@ require_once(
 	* Значение по умолчанию: `true`
 
 * `getPropValue`
-	* Описание: Возврат значения поля объекта или элемента массива по имени свойства объекта или индексу / ключу массива.
+	* Описание: Возврат значения поля объекта или элемента массива по имени свойства объекта или индексу / ключу массива.  
+		Вы также можете использовать `'.'` для получения вложенных свойств (больше информации см. `\DDTools\ObjectTools::getPropValue`).
 	* Допустимые значения: `string`
 	* Значение по умолчанию: —
 
 * `outputter`
 	* Описание: Формат вывода (когда результат является объектом или массивом).  
-		Значения регистронезависимы (следующие значения равны: `jsonauto`, `JsonAuto`, `JSONAUTO` и т. п.).
+		Значения регистронезависимы (следующие значения равны: `stringjsonauto`, `stringJsonAuto`, `STRINGJSONAUTO` и т. п.).
 	* Допустимые значения:
-		* `'jsonAuto'` — автоматиески будет выбран `jsonObject` или `jsonArray`, в зависимости от результата
-		* `'jsonObject'`
-		* `'jsonArray'`
-		* `'queryFormated'` — [Query string](https://ru.wikipedia.org/wiki/Query_string)
-	* Значение по умолчанию: `'jsonAuto'`
+		* Сниппет умеет возвращать объект в виде строки:
+			* `'stringJsonAuto'` — автоматиески будет выбран `stringJsonObject` или `stringJsonArray`, в зависимости от результата
+			* `'stringJsonObject'`
+			* `'stringJsonArray'`
+			* `'stringQueryFormatted'` — [Query string](https://ru.wikipedia.org/wiki/Query_string)
+		* Сниппет также умеет возвращать объект в виде нативного PHP объекта или массива (удобно при вызове через `\DDTools\Snippet`):
+			* `'objectAuto'` — `stdClass` или `array` в зависимости от результата
+			* `'objectStdClass'` — `stdClass`
+			* `'objectArray'` — `array`
+	* Значение по умолчанию: `'stringJsonAuto'`
 
 
 ### Примеры

composer.json

@@ -1,7 +1,7 @@
 {
 	"name": "dd/evolutioncms-snippets-ddobjecttools",
 	"type": "modxevo-snippet",
-	"version": "0.6.0",
+	"version": "0.7.0",
 	"description": "Tools for modifying objects.",
 	"keywords": [
 		"modx",
@@ -44,6 +44,6 @@
 	],
 	"require": {
 		"php": ">=5.6.0",
-		"dd/evolutioncms-libraries-ddtools": ">=0.51.0"
+		"dd/evolutioncms-libraries-ddtools": ">=0.57.0"
 	}
 }

ddObjectTools_snippet.php

@@ -1,7 +1,7 @@
 <?php
 /**
  * ddObjectTools
- * @version 0.6 (2023-03-08)
+ * @version 0.7 (2023-03-30)
  * 
  * @see README.md
  * 

src/Snippet.php

@@ -3,31 +3,56 @@
 
 class Snippet extends \DDTools\Snippet {
 	protected
-		$version = '0.6.0',
+		$version = '0.7.0',
 
 		$params = [
 			//Defaults
 			'sourceObject' => '{}',
 			'extend' => null,
 			'getPropValue' => null,
-			'outputter' => 'jsonAuto'
+			'outputter' => 'stringJsonAuto'
 		],
 
 		$paramsTypes = [
 			'sourceObject' => 'objectAuto'
 		]
 	;
 
+	/**
+	 * prepareParams
+	 * @version 1.0 (2023-03-29)
+	 *
+	 * @param $params {stdClass|arrayAssociative|stringJsonObject|stringHjsonObject|stringQueryFormatted}
+	 *
+	 * @return {void}
+	 */
+	protected function prepareParams($params = []){
+		parent::prepareParams($params);
+		
+		//Backward compatibility
+		$outputterFirstChars = substr(
+			strtolower($this->params->outputter),
+			0,
+			4
+		);
+		if (
+			$outputterFirstChars == 'json' ||
+			$outputterFirstChars == 'quer'
+		){
+			$this->params->outputter =
+				'string' .
+				$this->params->outputter
+			;
+		}
+	}
+	
 	/**
 	 * run
-	 * @version 1.1 (2023-03-08)
+	 * @version 1.1.1 (2023-03-29)
 	 * 
 	 * @return {string}
 	 */
 	public function run(){
-		//The snippet must return an empty string even if result is absent
-		$result = '';
-		
 		//If need to extend
 		if (!is_null($this->params->extend)){
 			$this->params->extend = \DDTools\ObjectTools::convertType([
@@ -69,9 +94,7 @@ public function run(){
 		){
 			$result = \DDTools\ObjectTools::convertType([
 				'object' => $result,
-				'type' =>
-					'string' .
-					$this->params->outputter
+				'type' => $this->params->outputter
 			]);
 		}