README

Tools for modifying objects.

Requires

• PHP >= 5.6
• (MODX)EvolutionCMS >= 1.1
• (MODX)EvolutionCMS.libraries.ddTools >= 0.62

Installation

Using (MODX)EvolutionCMS.libraries.ddInstaller

Just run the following PHP code in your sources or Console:

//Include (MODX)EvolutionCMS.libraries.ddInstaller
require_once(
	$modx->getConfig('base_path') .
	'assets/libs/ddInstaller/require.php'
);

//Install (MODX)EvolutionCMS.snippets.ddObjectTools
\DDInstaller::install([
	'url' => 'https://github.com/DivanDesign/EvolutionCMS.snippets.ddObjectTools',
	'type' => 'snippet',
]);

• If ddObjectTools is not exist on your site, ddInstaller will just install it.
• If ddObjectTools is already exist on your site, ddInstaller will check it version and update it if needed.

Manually

1. Elements → Snippets: Create a new snippet with the following data

1. Snippet name: ddObjectTools.
2. Description: <b>1.0</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.

2. Elements → Manage Files

1. Create a new folder assets/snippets/ddObjectTools/.
2. Extract the archive to the folder (except ddObjectTools_snippet.php).

Parameters description

• sourceObject

  • Description: Source object or array.
  • Valid values:
    • stringJsonObject — as JSON
    • stringJsonArray — as JSON
    • stringHjsonObject — as HJSON
    • stringHjsonArray — as HJSON
    • stringQueryFormatted — as Query string
    • It can also be set as a native PHP object or array (e. g. for calls through $modx->runSnippet):
      • array
      • object
  • Default value: '{}'

• extend

  • Description: Merge the contents of two or more objects / arrays together into sourceObject (it will receive the new properties).
  • Valid values:
    • stringJsonObject — as JSON
    • stringHjsonObject — as HJSON
    • stringQueryFormatted — as Query string
    • It can also be set as a native PHP object or array (e. g. for calls through $modx->runSnippet):
      • arrayAssociative
      • object
  • Default value: —

• extend->objects

  • Description: Objects or arrays to merge. Moreover, objects can extend arrays and vice versa.
  • Valid values:
    • array
    • stringJsonArray — as JSON
    • stringHjsonArray — as HJSON
    • stringQueryFormatted — as Query string
  • Required

• extend->objects[i]

  • Description: An object or array containing additional properties to merge in.
  • Valid values:
    • object
    • array
  • Required

• extend->deep

  • Description: If true, the merge becomes recursive (aka “deep copy”).
  • Valid values: boolean
  • Default value: true

• extend->overwriteWithEmpty

  • Description: Overwrite fields with empty values.
    The following values are considered to be empty:
    • '' — an empty string
    • [] — an empty array
    • (object) [] — an empty object
    • NULL
  • Valid values: boolean
  • Default value: true

• getPropValue

  • Description: This parameter allows you to return required property of an object.
  • Valid values:
    • string — just name of a property or array index / key to return, use as getPropValue->name in this case
    • An object of additional parameters:
      • stringJsonObject — as JSON
      • stringHjsonObject — as HJSON
      • stringQueryFormatted — as Query string
      • It can also be set as native PHP object or array (e. g. for calls through \DDTools\Snippet::runSnippet or $modx->runSnippet):
        • arrayAssociative
        • object
  • Default value: —

• getPropValue->name

  • Description: 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
  • Required

• getPropValue->notFoundResult

  • Description: What will be returned when the property is not found.
  • Valid values: mixed
  • Default value: null

• outputter

  • Description: Output format (when result is an object or array).
    Values are case insensitive (the following values are equal: 'stringjsonauto', 'stringJsonAuto', 'STRINGJSONAUTO', etc).
  • Valid values:
    • The snippet can return object as string:
      • 'stringJsonAuto' — stringJsonObject or stringJsonArray depends on result object
      • 'stringJsonObject'
      • 'stringJsonArray'
      • 'stringQueryFormatted' — 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

All examples are written using HJSON, but if you want you can use vanilla JSON instead.

Merge the contents of two or more objects together into the first object (the extend parameter)

[[ddObjectTools?
	&sourceObject=`{
		cat: mew
		dog: {
			name: Floyd
			weight: 6
		}
		rabbit: 42
	}`
	&extend=`{
		objects: [
			{
				dog: {
					weight: 10
				}
				bird: 0
			}
		]
	}`
]]

Returns:

{
	"cat": "mew",
	"dog": {
		"name": "Floyd",
		"weight": 10,
	},
	"rabbit": 42,
	"bird": 0
}

Get an object property

[[ddObjectTools?
	&sourceObject=`{
		firstName: Chuck
		lastName: Norris
	}`
	&getPropValue=`firstName`
]]

Returns: Chuck.

Custom results when the property is not found

[[ddObjectTools?
	&sourceObject=`{
		firstName: Viktor
		lastName: Tsoi
		dates: {
			born: 1962.06.21
		}
	}`
	&getPropValue=`{
		name: dates.death
		notFoundResult: forever alive
	}`
]]

Returns: forever alive.

Get an array element

[[ddObjectTools?
	&sourceObject=`[
		Pink Floyd
		The Beatles
		Queen
	]`
	&getPropValue=`2`
]]

Returns: Queen.

Convert a JSON object to an array

[[ddObjectTools?
	&sourceObject=`{
		firstName: Angus
		lastName: Young
	}`
	&outputter=`jsonArray`
]]

Returns:

[
	"Angus",
	"Young"
]

Run the snippet through \DDTools\Snippet::runSnippet without DB and eval

//Include (MODX)EvolutionCMS.libraries.ddTools
require_once(
	$modx->getConfig('base_path') .
	'assets/libs/ddTools/modx.ddtools.class.php'
);

//Run (MODX)EvolutionCMS.snippets.ddObjectTools
\DDTools\Snippet::runSnippet([
	'name' => 'ddObjectTools',
	'params' => [
		'sourceObject' => [
			'cat' => 'mew',
			'dog' => [
				'name' => 'Floyd',
				'weight' => 6,
			],
			'rabbit' => 42,
		],
		'extend' => [
			'objects' => [
				[
					'dog' => [
						'weight' => 11,
					],
					'bird' => 0,
				],
			],
		],
	],
]);

Links

• Home page
• Telegram chat
• Packagist
• GitHub