Version 0.31

CHANGELOG.md

@@ -1,6 +1,11 @@
 # (MODX)EvolutionCMS.libraries.ddTools changelog
 
 
+## Version 0.31 (2020-04-23)
+* \+ `\DDTools\ObjectTools::extend`. Merge the contents of two or more objects together into the first object (see README.md).
+* \* README: Style improvements.
+
+
 ## Version 0.30 (2020-02-11)
 * \* Attention! (MODX)EvolutionCMS >= 1.1 is required.
 * \+ `\ddTools::getDocumentParentIds`. Gets the parent ID(s) of the required level.

README.md

@@ -3,28 +3,112 @@
 A library with various tools facilitating your work.
 
 
-## # Requires
+## Requires
+
 * PHP >= 5.4
 * [(MODX)EvolutionCMS](https://github.com/evolution-cms/evolution) >= 1.1
 * [PHP.libraries.phpThumb](http://phpthumb.sourceforge.net) 1.7.13-201406261000 (included)
 
 
-## # Documentation
+## Documentation
 
 
-### ## Installation
+### Installation
 
 
-#### ### Manual
+#### Manual
 
 1. Create a new folder `assets/libs/ddTools/`.
 2. Extract the archive to the folder.
 
 
-#### ### Using [Composer](https://getcomposer.org/)
+#### Using [Composer](https://getcomposer.org/)
 
 Just add `dd/modxevo-library-ddtools` to your `composer.json`.
 _ddTools version must be 0.14 or higher to use this method. If you use it, the compatibility with all your snippets, modules, etc. that use ddTools versions under 0.14 will be maintained._
 
 
-## # [Home page →](https://code.divandesign.biz/modx/ddtools)
+### Parameters description
+
+
+#### `\DDTools\ObjectTools::extend($params)`
+
+Merge the contents of two or more objects together into the first object.
+
+* `$params`
+	* Desctription: Parameters, the pass-by-name style is used.
+	* Valid values:
+		* `stdClass`
+		* `arrayAssociative`
+	* **Required**
+
+* `$params->objects`
+	* Desctription: Objects to merge.
+	* Valid values: `array`
+	* **Required**
+
+* `$params->objects[0]`
+	* Desctription: The object to extend. It will receive the new properties.
+	* Valid values:
+		* `object`
+		* `NULL` — pass `NULL` to create the new StdClass.
+	* **Required**
+
+* `$params->objects[i]`
+	* Desctription: An object containing additional properties to merge in.
+	* Valid values: `object`
+	* **Required**
+
+* `$params->deep`
+	* Desctription: If true, the merge becomes recursive (aka. deep copy).
+	* Valid values: `boolean`
+	* Default value: `true`
+
+
+### Examples
+
+
+#### `\DDTools\ObjectTools::extend($params)`
+
+Merge two objects, modifying the first.
+
+```php
+var_export(\DDTools\ObjectTools::extend([
+	'objects' => [
+		(object) [
+			'cat' => 'mew',
+			'dog' => (object) [
+				'name' => 'Floyd',
+				'weight' => 6
+			],
+			'rabbit' => 42
+		],
+		(object) [
+			'dog' => (object) [
+				'weight' => 10
+			],
+			'bird' => 0
+		]
+	]
+]));
+```
+
+Returns:
+
+```
+stdClass::__set_state(array(
+	'cat' => 'mew',
+	'dog' => stdClass::__set_state(array(
+		'name' => 'Floyd',
+		'weight' => 10,
+	)),
+	'rabbit' => 42,
+	'bird' => 0,
+))
+```
+
+
+## [Home page →](https://code.divandesign.biz/modx/ddtools)
+
+
+<link rel="stylesheet" type="text/css" href="https://DivanDesign.ru/assets/files/ddMarkdown.css" />

composer.json

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

modx.ddtools.class.php

@@ -1,7 +1,7 @@
 <?php
 /**
  * EvolutionCMS.libraries.ddTools
- * @version 0.30 (2020-02-11)
+ * @version 0.31 (2020-04-23)
  * 
  * @see README.md
  * 
@@ -163,11 +163,11 @@ public static function getInstance(){
 	 * 
 	 * @desc Convert list of ordered parameters to named. Method is public, but be advised that this is beta-version!
 	 * 
-	 * @param $params {arrayAssociative|stdClass} — The object of params. @required
-	 * @param $params['paramsList'] {array} — Parameters in ordered list (func_get_args). @required
-	 * @param $params['paramsList'][i] {mixed} — Parameter value. @required
-	 * @param $params['compliance'] {array} — The order of parameters. @required
-	 * @param $params['compliance'][i] {string} — Parameter name. @required
+	 * @param $params {stdClass|arrayAssociative} — Parameters, the pass-by-name style is used. @required
+	 * @param $params->paramsList {array} — Parameters in ordered list (func_get_args). @required
+	 * @param $params->paramsList[i] {mixed} — Parameter value. @required
+	 * @param $params->compliance {array} — The order of parameters. @required
+	 * @param $params->compliance[i] {string} — Parameter name. @required
 	 * 
 	 * @return {arrayAssociative}
 	 */
@@ -518,7 +518,7 @@ public static function parseFileNameVersion($file){
 	 * 
 	 * @desc Makes directory using `$modx->config['new_folder_permissions']`. Nested directories will be created too. Doesn't throw an exception if the folder already exists.
 	 * 
-	 * @param $params {arrayAssociative|stdClass} — The object of params. @required
+	 * @param $params {stdClass|arrayAssociative} — Parameters, the pass-by-name style is used. @required
 	 * @param $params->path {string} — The directory path. @required
 	 * 
 	 * @return {boolean} — Success status.
@@ -744,10 +744,10 @@ public static function encodedStringToArray($inputString){
 	 * 
 	 * @desc Finds all placeholders' names and returns them as an array.
 	 * 
-	 * @param $params {arrayAssociative|stdClass} — The object of params. @required
-	 * @param $params['text'] {string} — Source string. @required
-	 * @param $params['placeholderPrefix'] {string} — Placeholders prefix. Default: '[+'.
-	 * @param $params['placeholderSuffix'] {string} — Placeholders suffix. Default: '+]'.
+	 * @param $params {stdClass|arrayAssociative} — Parameters, the pass-by-name style is used. @required
+	 * @param $params->text {string} — Source string. @required
+	 * @param $params->placeholderPrefix {string} — Placeholders prefix. Default: '[+'.
+	 * @param $params->placeholderSuffix {string} — Placeholders suffix. Default: '+]'.
 	 * 
 	 * @return {array}
 	 */
@@ -790,12 +790,12 @@ public static function getPlaceholdersFromText($params = []){
 	 * 
 	 * @desc Add an alert message to the system event log with debug info (backtrace, snippet name, document id, etc).
 	 * 
-	 * @param $params {arrayAssociative|stdClass} — The object of params. @required
-	 * @param $params['message'] {string} — Message to be logged. Default: ''.
-	 * @param $params['source'] {string} — Source of the event (module, snippet name, etc). Default: $modx->currentSnippet || caller.
-	 * @param $params['eventId'] {integer} — Event ID. Default: 1.
-	 * @param $params['eventType'] {'information'|'warning'|'error'} — Event type. Default: 'warning'.
-	 * @param $params['backtraceArray'] {array} — Backtrace (if default is not suitable). See http://php.net/manual/en/function.debug-backtrace.php. Default: debug_backtrace().
+	 * @param $params {stdClass|arrayAssociative} — Parameters, the pass-by-name style is used. @required
+	 * @param $params->message {string} — Message to be logged. Default: ''.
+	 * @param $params->source {string} — Source of the event (module, snippet name, etc). Default: $modx->currentSnippet || caller.
+	 * @param $params->eventId {integer} — Event ID. Default: 1.
+	 * @param $params->eventType {'information'|'warning'|'error'} — Event type. Default: 'warning'.
+	 * @param $params->backtraceArray {array} — Backtrace (if default is not suitable). See http://php.net/manual/en/function.debug-backtrace.php. Default: debug_backtrace().
 	 * 
 	 * @return {void}
 	 */
@@ -918,14 +918,14 @@ public static function logEvent($params){
 	 * 
 	 * @desc Similar to $modx->parseChunk, but takes a text.
 	 * 
-	 * @param $params {arrayAssociative|stdClass} — The object of params. @required
-	 * @param $params['text'] {string} — String to parse. @required
-	 * @param $params['data'] {arrayAssociative|stdClass} — Array of values. Nested arrays are supported too: “['stringPlaceholder' = > 'one', 'arrayPlaceholder' => ['a' => 'one', 'b' => 'two']]” => “[+stringPlaceholder+]”, “[+arrayPlaceholder.a+]”, “[+arrayPlaceholder.b+]”. Default: [].
-	 * @param $params['data'][key] {string|arrayAssociative|stdClass} — Key — placeholder name, value — value.
-	 * @param $params['placeholderPrefix'] {string} — Placeholders prefix. Default: '[+'.
-	 * @param $params['placeholderSuffix'] {string} — Placeholders suffix. Default: '+]'.
-	 * @param $params['removeEmptyPlaceholders'] {boolean} — Do you need to remove empty placeholders? Default: false.
-	 * @param $params['mergeAll'] {boolean} — Additional parsing the document fields, settings, chunks. Default: true.
+	 * @param $params {stdClass|arrayAssociative} — Parameters, the pass-by-name style is used. @required
+	 * @param $params->text {string} — String to parse. @required
+	 * @param $params->data {stdClass|arrayAssociative} — Array of values. Nested arrays are supported too: “['stringPlaceholder' = > 'one', 'arrayPlaceholder' => ['a' => 'one', 'b' => 'two']]” => “[+stringPlaceholder+]”, “[+arrayPlaceholder.a+]”, “[+arrayPlaceholder.b+]”. Default: [].
+	 * @param $params->data->{$key} {string|stdClass|arrayAssociative} — Key — placeholder name, value — value.
+	 * @param $params->placeholderPrefix {string} — Placeholders prefix. Default: '[+'.
+	 * @param $params->placeholderSuffix {string} — Placeholders suffix. Default: '+]'.
+	 * @param $params->removeEmptyPlaceholders {boolean} — Do you need to remove empty placeholders? Default: false.
+	 * @param $params->mergeAll {boolean} — Additional parsing the document fields, settings, chunks. Default: true.
 	 * 
 	 * @return {string}
 	 */
@@ -1029,7 +1029,7 @@ public static function parseSource($source){
 	 * 
 	 * @desc Clears cache of required document(s) and their parents.
 	 * 
-	 * @param $params {arrayAssociative|stdClass} — The object of params. @required
+	 * @param $params {stdClass|arrayAssociative} — Parameters, the pass-by-name style is used. @required
 	 * @param $params->docIds {arrayAssociative|stringCommaSeparated} — Document ID(s). @required
 	 * @param $params->docIds[i] {integer} — Document ID. @required
 	 * @param $params->clearParentsCache {boolean} — Is need to clear parents cache? Default: true.
@@ -1109,11 +1109,11 @@ public static function clearCache($params){
 	 * 
 	 * @desc Prepare document data from single array of fields and TVs: separate them and get TV IDs if needed.
 	 * 
-	 * @param $params {arrayAssociative|stdClass} — The object of params. @required
-	 * @param $params['data'] {arrayAssociative} — Array of document fields (from table `site_content`) or TVs with values. @required
-	 * @param $params['data'][key] {mixed} — Field value (optional), when key is field name. The method use only keys, values just will be returned without changes. @required
-	 * @param $params['tvAdditionalFieldsToGet'] {array} — Fields of TVs to get if needed (e. g. 'id', 'type'). Default: [].
-	 * @param $params['tvAdditionalFieldsToGet'][i] {string} — TV field.
+	 * @param $params {stdClass|arrayAssociative} — Parameters, the pass-by-name style is used. @required
+	 * @param $params->data {arrayAssociative} — Array of document fields (from table `site_content`) or TVs with values. @required
+	 * @param $params->data[key] {mixed} — Field value (optional), when key is field name. The method use only keys, values just will be returned without changes. @required
+	 * @param $params->tvAdditionalFieldsToGet {array} — Fields of TVs to get if needed (e. g. 'id', 'type'). Default: [].
+	 * @param $params->tvAdditionalFieldsToGet[i] {string} — TV field.
 	 * 
 	 * @return $result {stdClass}
 	 * @return $result->fieldsData {arrayAssociative} — Document fields data (like 'id', 'pagetitle', etc). @required
@@ -2316,10 +2316,10 @@ public static function getDocumentChildrenTVarOutput(
 	 * 
 	 * @see ddRegJsCssLinks snippet (http://code.divandesign.biz/modx/ddregjscsslinks), предназначенный для «правильного» подключения js и css. Даже при «ручном» подключении сниппет регистрирует то, что подключил, используя данный метод.
 	 * 
-	 * @param $params {arrayAssociative|stdClass} — The object of params. @required
-	 * @param $params['name'] {string} — Script name. @required
-	 * @param $params['version'] {string} — Script version. Default: '0'.
-	 * @param $params['startup'] {boolean} — Is the script connected in the <head>? Default: false.
+	 * @param $params {stdClass|arrayAssociative} — Parameters, the pass-by-name style is used. @required
+	 * @param $params->name {string} — Script name. @required
+	 * @param $params->version {string} — Script version. Default: '0'.
+	 * @param $params->startup {boolean} — Is the script connected in the <head>? Default: false.
 	 * 
 	 * @return $result {arrayAssociative|''} — empty string if $name is not set or an array of:
 	 * @return $result['name'] {string} — Script name.
@@ -2449,7 +2449,7 @@ public static function regEmptyClientScript($params = []){
 	 * 
 	 * @desc Gets the parent ID(s) of the required level.
 	 * 
-	 * @param $params {arrayAssociative|stdClass} — The object of params. Default: —.
+	 * @param $params {stdClass|arrayAssociative} — Parameters, the pass-by-name style is used. Default: —.
 	 * @param $params->docId {integer} — Document Id. Default: $modx->documentIdentifier.
 	 * @param $params->level {integer} — Parent level (1 — the immediate parent; 2 — the parent of the immediate parent; -1 — the last parent; -2 — the parent before the last; etc). Default: 1.
 	 * @param $params->totalResults {integer|'all'} — The number of parents that will be returned. Default: 'all'.
@@ -2639,14 +2639,14 @@ public static function verifyRenamedParams(
 	 * 
 	 * @desc Method for sending e-mails.
 	 * 
-	 * @param $params {arrayAssociative|stdClass} — The object of params. @required
-	 * @param $params['to'] {array} — Addresses to mail. @required
-	 * @param $params['to'][i] {string_email} — An address. @required
-	 * @param $params['text'] {string} — E-mail text. @required
-	 * @param $params['from'] {string} — Mailer address. Default: $modx->getConfig('emailsender').
-	 * @param $params['subject'] {string} — E-mail subject. Default: 'Mail from '.$modx->config['site_url'].
-	 * @param $params['fileInputNames'] {array} — “input” tags names from which accepted files are taken. Default: [].
-	 * @param $params['fileInputNames'][i] {string} — Input name. @required
+	 * @param $params {stdClass|arrayAssociative} — Parameters, the pass-by-name style is used. @required
+	 * @param $params->to {array} — Addresses to mail. @required
+	 * @param $params->to[i] {string_email} — An address. @required
+	 * @param $params->text {string} — E-mail text. @required
+	 * @param $params->from {string} — Mailer address. Default: $modx->getConfig('emailsender').
+	 * @param $params->subject {string} — E-mail subject. Default: 'Mail from '.$modx->config['site_url'].
+	 * @param $params->fileInputNames {array} — “input” tags names from which accepted files are taken. Default: [].
+	 * @param $params->fileInputNames[i] {string} — Input name. @required
 	 * 
 	 * @return $result {array} — Returns the array of email statuses.
 	 * @return $result[i] {0|1} — Status.

require.php

@@ -1,5 +1,6 @@
 <?php
 require_once('src/BaseClass/BaseClass.php');
+require_once('src/ObjectTools/ObjectTools.php');
 require_once('src/FilesTools/FilesTools.php');
 require_once('src/Response.php');
 ?>

src/BaseClass/BaseClass.php

@@ -8,7 +8,7 @@ class BaseClass {
 	 * 
 	 * @desc Sets existing object properties.
 	 * 
-	 * @param $params {arrayAssociative|stdClass} — The object properties. @required
+	 * @param $params {stdClass|arrayAssociative} — The object properties. @required
 	 * 
 	 * @return {void}
 	 */
@@ -34,7 +34,7 @@ public function setExistingProps($props){
 	 * 
 	 * @throws \ReflectionException
 	 * 
-	 * @param $params {arrayAssociative|stdClass} — The object of params. @required
+	 * @param $params {stdClass|arrayAssociative} — Parameters, the pass-by-name style is used. @required
 	 * @param $params->object {object} — Объект для модификации. @required
 	 * @param $params->propName {string} — Имя поля. @required
 	 * @param $params->propValue {mixed} — Значение. @required
@@ -88,10 +88,10 @@ private function setProp($params){
 	 * 
 	 * @throws \Exception
 	 * 
-	 * @param $params {arrayAssociative|stdClass} — The object of params. @required
+	 * @param $params {stdClass|arrayAssociative} — Parameters, the pass-by-name style is used. @required
 	 * @param $params->parentDir {string} — Directory of the parent file (e. g. __DIR__). @required
 	 * @param $params->name {string} — Class name. @required
-	 * @param $params->params {arrayAssociative|stdClass} — Params to be passed to object constructor. Default: [].
+	 * @param $params->params {stdClass|arrayAssociative} — Params to be passed to object constructor. Default: [].
 	 * @param $params->capitalizeName {boolean} — Need to capitalize child name? Default: true.
 	 * 
 	 * @return {object}