Version 0.56

CHANGELOG.md

@@ -1,6 +1,19 @@
 # (MODX)EvolutionCMS.libraries.ddTools changelog
 
 
+## Version 0.56 (2023-01-29)
+* \+ `\ddTools::sort2dArray` → Parameters → `$array[$i]`: Can also be set as object.
+* \* `\DDTools\Base\Base`:
+	* \* The class has been renamed from `\DDTools\BaseClass`. Backward compatibility is maintained (you can still use `\DDTools\BaseClass`, but it is not recommended).
+	* \* The class has become abstract.
+	* \- `createChildInstance`: The method has been removed, use `\DDTools\Base\AncestorTrait::createChildInstance` instead. Backward compatibility is maintained (you can still use `\DDTools\BaseClass::createChildInstance`, but it is not recommended).
+	* \+ `toJSON`: Returns JSON-array if `$this->toArray` returns indexed array.
+* \+ `\DDTools\Base\AncestorTrait`: The new trait.
+* \+ `\DDTools\ObjectCollection`:
+	* \+ `toJSON`, `__toString`: The new public methods. Get an JSON-array of all collection items.
+	* \+ `\DDTools\ObjectCollection::setOneItemData`, `getOneItemData`: The new protected methods.
+
+
 ## Version 0.55.1 (2022-12-03)
 * \* `\DDTools\FilesTools::modifyImage`: Included PHP.libraries.phpThumb has been updated from 1.7.15-202004301145 to 1.7.19-202210110924 (now supports WebP, PHP8, etc).
 

CHANGELOG_ru.md

@@ -1,6 +1,19 @@
 # (MODX)EvolutionCMS.libraries.ddTools changelog
 
 
+## Версия 0.56 (2023-01-29)
+* \+ `\ddTools::sort2dArray` → Параметры → `$array[$i]`: Также может быть задан, как объект.
+* \* `\DDTools\Base\Base`:
+	* \* Класс переименован из `\DDTools\BaseClass`. Обратная совместимость сохранена (множно использовать `\DDTools\BaseClass`, но не рекомендуется).
+	* \* Класс стал абстрактным.
+	* \- `createChildInstance`: Метод удалён, используйте вместо него `\DDTools\Base\AncestorTrait::createChildInstance`. Обратная совместимость сохранена (можно использовать `\DDTools\BaseClass::createChildInstance`, но не рекомендуется).
+	* \+ `toJSON`: Возвращает JSON-массив если `$this->toArray` возвращает индексированный массив.
+* \+ `\DDTools\Base\AncestorTrait`: Новый trait.
+* \+ `\DDTools\ObjectCollection`:
+	* \+ `toJSON`, `__toString`: Новые публичные методы. Возвращают JSON-массив всех элементов коллекции.
+	* \+ `\DDTools\ObjectCollection::setOneItemData`, `getOneItemData`: Новые protected методы.
+
+
 ## Версия 0.55.1 (2022-12-03)
 * \* `\DDTools\FilesTools::modifyImage`: PHP.libraries.phpThumb, включённая в репозиторий, обновлена с 1.7.15-202004301145 до 1.7.19-202210110924 (теперь поддерживает WebP, PHP8, etc).
 

README.md

@@ -760,15 +760,81 @@ Deletes required items from collection.
 	* Default value: `0`
 
 
-### `\DDTools\BaseClass`
+#### `\DDTools\ObjectCollection::toJSON()`, `\DDTools\ObjectCollection::__toString()`
 
-Simple class with some small methods facilitating your work.
+Gets an JSON-array of all collection items.
+
+
+##### Returns
+
+* `$result`
+	* Desctription: An JSON-array of items.
+	* Valid values: `stringJsonArray`
+
+
+#### `\DDTools\ObjectCollection::setOneItemData` (protected)
+
+Sets data of an item object. All setting of an item data inside the class must be use this method.
+It's convenient to override this method in child classes if items are not plain objects.
+
+* `$params`
+	* Desctription: Parameters, the pass-by-name style is used.
+	* Valid values:
+		* `stdClass`
+		* `arrayAssociative`
+	* **Required**
+
+* `$params->itemIndex`
+	* Desctription: Item index which data will be set.
+	* Valid values: `integer`
+	* **Required**
+
+* `$params->itemData`
+	* Desctription: New item data.
+	* Valid values:
+		* `array` — indexed arrays are supported as well as associative
+		* `object`
+	* **Required**
+
+
+#### `\DDTools\ObjectCollection::getOneItemData` (protected)
+
+Returns data of an item object. All getting of an item data inside the class must use this method.
+It's convenient to override this method in child classes if items are not plain objects.
+
+* `$params`
+	* Desctription: Parameters, the pass-by-name style is used.
+	* Valid values:
+		* `stdClass`
+		* `arrayAssociative`
+	* **Required**
+
+* `$params->itemObject`
+	* Desctription: An item object which data will be returned.
+	* Valid values:
+		* `array` — indexed arrays are supported as well as associative
+		* `object`
+	* **Required**
+
+
+##### Returns
+
+* `$result`
+	* Desctription: Data of an item object.
+	* Valid values:
+		* `array`
+		* `object`
+
+
+### `\DDTools\Base\Base`
+
+Simple abstract class with some small methods facilitating your work.
 It is convenient to inherit your classes from this.
 
 You can see an example of how it works in the [(MODX)EvolutionCMS.snippets.ddGetDocumentField](https://code.divandesign.biz/modx/ddgetdocumentfield) code.
 
 
-#### `\DDTools\BaseClass::setExistingProps($props)`
+#### `\DDTools\Base\Base::setExistingProps($props)`
 
 Sets existing object properties.
 
@@ -791,7 +857,7 @@ Sets existing object properties.
 	* **Required**
 
 
-#### `\DDTools\BaseClass::toArray()`
+#### `\DDTools\Base\Base::toArray()`
 
 Returns all properties of this object as an associative array independent of their visibility.
 
@@ -808,7 +874,7 @@ Returns all properties of this object as an associative array independent of the
 	* Valid values: `mixed`
 
 
-#### `\DDTools\BaseClass::toJSON()`
+#### `\DDTools\Base\Base::toJSON()`
 
 Returns all properties of this object as an JSON string independent of their visibility.
 
@@ -818,19 +884,28 @@ Returns all properties of this object as an JSON string independent of their vis
 * `$result`
 	* Desctription: An JSON string representation of this object.  
 		The method returns all existing properties: public, private and protected.
-	* Valid values: `stringJsonObject`
+	* Valid values:
+		* `stringJsonObject`
+		* `stringJsonArray` — if `$this->toArray` returns indexed array
 
 * `$result->{$propName}`
 	* Desctription: The key is the object field name and the value is the object field value.
 	* Valid values: `mixed`
 
 
-#### `\DDTools\BaseClass::__toString()`
+#### `\DDTools\Base\Base::__toString()`
+
+The same as `\DDTools\Base\Base::toJSON()`.
+
 
-The same as `\DDTools\BaseClass::toJSON()`.
+### `\DDTools\Base\AncestorTrait`
+
+Simple trait for ancestors with some small methods facilitating your work.
+
+You can see an example of how it works in the [(MODX)EvolutionCMS.snippets.ddGetDocumentField](https://code.divandesign.biz/modx/ddgetdocumentfield) code.
 
 
-#### `\DDTools\BaseClass::createChildInstance($params)`
+#### `\DDTools\Base\AncestorTrait::createChildInstance($params)`
 
 * `$params`
 	* Desctription: Parameters, the pass-by-name style is used.

composer.json

@@ -1,7 +1,7 @@
 {
 	"name": "dd/evolutioncms-libraries-ddtools",
 	"type": "modxevo-library-ddtools",
-	"version": "0.55.1",
+	"version": "0.56.0",
 	"description": "A library with various tools facilitating your work.",
 	"keywords": [
 		"modx",

modx.ddtools.class.php

@@ -1,11 +1,11 @@
 <?php
 /**
  * EvolutionCMS.libraries.ddTools
- * @version 0.55.1 (2022-12-03)
+ * @version 0.56 (2023-01-29)
  * 
  * @see README.md
  * 
- * @copyright 2012–2022 DD Group {@link https://DivanDesign.biz }
+ * @copyright 2012–2023 DD Group {@link https://DivanDesign.biz }
  */
 
 global $modx;
@@ -288,11 +288,12 @@ public static function explodeAssoc(
 
 	/**
 	 * sort2dArray
-	 * @version 1.2.1 (2021-03-09)
+	 * @version 1.3 (2022-12-23)
 	 * 
 	 * @desc Sorts 2-dimensional array by multiple columns (like in SQL) using Hoare's method, also referred to as quicksort. The sorting is stable.
 	 * 
 	 * @param $array {array} — Array to sort. Associative arrays are also supported. @required
+	 * @param $array[$i] {array|object} — Array to sort. Associative arrays are also supported. @required
 	 * @param $sortBy {array} — Columns (second level keys) by which the array is sorted. @required
 	 * @param $sortDir {1|-1} — Sort direction (1 == ASC; -1 == DESC). Default: 1.
 	 * @param $i {integer} — Count, an internal variable used during recursive calls. Default: 0.
@@ -306,8 +307,11 @@ public static function sort2dArray(
 		$i = 0
 	){
 		//В качестве эталона получаем сортируемое значение (по первому условию сортировки) первого элемента
-		$currentRow = array_values($array)[0][$sortBy[$i]];
-		$isCurrentRowNumeric = is_numeric($currentRow);
+		$currentItem_comparisonValue = \DDTools\ObjectTools::getPropValue([
+			'object' => array_values($array)[0],
+			'propName' => $sortBy[$i]
+		]);
+		$isCurrentItemComparisonValueNumeric = is_numeric($currentItem_comparisonValue);
 
 		$isArrayAssociative =
 			count(array_filter(
@@ -324,20 +328,25 @@ public static function sort2dArray(
 		//Перебираем массив
 		foreach (
 			$array as
-			$rowKey =>
-			$rowValue
+			$arrayItemKey =>
+			$arrayItem
 		){
+			$arrayItem_comparisonValue = \DDTools\ObjectTools::getPropValue([
+				'object' => $arrayItem,
+				'propName' => $sortBy[$i]
+			]);
+
 			//Если эталон и текущее значение — числа
 			if (
-				$isCurrentRowNumeric &&
-				is_numeric($rowValue[$sortBy[$i]])
+				$isCurrentItemComparisonValueNumeric &&
+				is_numeric($arrayItem_comparisonValue)
 			){
 				//Получаем нужную циферку
 				$cmpRes =
-					$rowValue[$sortBy[$i]] == $currentRow ?
+					$arrayItem_comparisonValue == $currentItem_comparisonValue ?
 					0 :
 					(
-						$rowValue[$sortBy[$i]] > $currentRow ?
+						$arrayItem_comparisonValue > $currentItem_comparisonValue ?
 						1 :
 						-1
 					)
@@ -346,8 +355,8 @@ public static function sort2dArray(
 			}else{
 				//Сравниваем текущее значение со значением эталонного
 				$cmpRes = strcmp(
-					$rowValue[$sortBy[$i]],
-					$currentRow
+					$arrayItem_comparisonValue,
+					$currentItem_comparisonValue
 				);
 			}
 
@@ -363,9 +372,9 @@ public static function sort2dArray(
 			}
 
 			if ($isArrayAssociative){
-				$resultArray[$rowKey] = $rowValue;
+				$resultArray[$arrayItemKey] = $arrayItem;
 			}else{
-				$resultArray[] = $rowValue;
+				$resultArray[] = $arrayItem;
 			}
 		}
 

require.php

@@ -1,5 +1,8 @@
 <?php
-require_once('src/BaseClass/BaseClass.php');
+require_once('src/Base/Base.php');
+require_once('src/Base/AncestorTrait.php');
+require_once('src/Base/BaseClass.php');
+
 require_once('src/ObjectTools/ObjectTools.php');
 require_once('src/FilesTools/FilesTools.php');
 require_once('src/ObjectCollection/ObjectCollection.php');

src/Base/AncestorTrait.php

@@ -0,0 +1,77 @@
+<?php
+namespace DDTools\Base;
+
+trait AncestorTrait {
+	/**
+	 * createChildInstance
+	 * @version 1.1.1 (2019-08-22)
+	 * 
+	 * @see README.md
+	 * 
+	 * @throws \Exception
+	 */
+	public static final function createChildInstance($params){
+		//Defaults
+		$params = (object) array_merge(
+			[
+				'params' => [],
+				'capitalizeName' => true
+			],
+			(array) $params
+		);
+
+		$thisClassName = get_called_class();
+
+		$thisNameSpace = substr(
+			$thisClassName,
+			0,
+			strrpos(
+				$thisClassName,
+				'\\'
+			)
+		);
+
+		//Current classname without namespace
+		$thisClassName = substr(
+			$thisClassName,
+			strrpos(
+				$thisClassName,
+				'\\'
+			) + 1
+		);
+
+		//Capitalize child name if needed
+		if ($params->capitalizeName){
+			$params->name = ucfirst(strtolower($params->name));
+		}
+
+		$filePath =
+			$params->parentDir .
+			DIRECTORY_SEPARATOR .
+			$params->name .
+			DIRECTORY_SEPARATOR .
+			$thisClassName .
+			'.php'
+		;
+
+		if(is_file($filePath)){
+			require_once($filePath);
+
+			$objectClass =
+				'\\' .
+				$thisNameSpace .
+				'\\' .
+				$params->name .
+				'\\' .
+				$thisClassName
+			;
+
+			return new $objectClass($params->params);
+		}else{
+			throw new \Exception(
+				$thisClassName . ' “' . $params->name . '” not found.',
+				500
+			);
+		}
+	}
+}