Task: #53687 Add minimal --verbose mode and replace legacy var_dump debug points

bin/cfg

@@ -56,6 +56,11 @@ function readJsonInputFile(string $path): array
 	return $data;
 }
 
+function verboseLog(bool $enabled, string $message): void
+{
+	if ($enabled) fwrite(STDERR, "[verbose] $message".PHP_EOL);
+}
+
 $version = '0.4';
 
 $actions = [ 'show', 'write', 'help' ];
@@ -69,6 +74,11 @@ $collection = (new Input\InputCollection())
 		->description('Display help text')
 	) // }}}
 
+	->add( Input\InputTypeFactory::build('LongOption')->name('verbose')->short('v') // {{{
+		->flags(AbstractInputType::FLAG_OPTIONAL)
+		->description('Print debug details to STDERR')
+	) // }}}
+
 	->add( Input\InputTypeFactory::build('LongOption')->name('in')->short('i') // {{{
 		->flags(AbstractInputType::FLAG_OPTIONAL | Input\AbstractInputType::FLAG_VALUE_REQUIRED)
 		->description('Path to a JSON data file to read (for write)')
@@ -179,26 +189,37 @@ $usage = Cli\manpage( basename(__FILE__), $version,
 	$collection, Colour::FG_GREEN, Colour::FG_WHITE,
 		[
 			'Examples' =>
-			 'cfg write extension_name \'module:enabled=true\''
+				'Basic usage:'
 				.PHP_EOL
-			 .'# writes local config: config/extension_name.conf.php'
+				 .'cfg show VeruA db:host'
 				 .PHP_EOL
-			 .'cfg write extension_name -i /tmp/extension.json --siteDir=owner_xyz'
+				 .'cfg write VeruA \'db:host="newHost"\''
 				 .PHP_EOL
-			 .'# writes multiple settings from JSON to config/owner_xyz/extension_name.conf.php'
 				 .PHP_EOL
-			 .'cfg write extension_name \'feature_example:enabled=true\' --siteDir=owner_xyz'
+				.'Advance usage:'
             	 .PHP_EOL
-			 .'# writes instance config: config/owner_xyz/extension_name.conf.php'
+				 .'cfg write extension_name \'module:enabled=true\''
 				 .PHP_EOL
-			 .'cfg write extension_name \'feature_example={"enabled":true,"timeout":30,"label":"example"}\' --siteDir=owner_xyz'
 				 .PHP_EOL
-			 .'# writes multiple keys from one JSON string'
+				 .'#Instance write:'
+				 .PHP_EOL
+				 .'cfg write extension_name \'module:enabled=true\' --siteDir=owner_xyz'
+				 .PHP_EOL
+				 .PHP_EOL
+				 .'#Batch write from JSON file:'
+				 .PHP_EOL
+				 .'cfg write extension_name --siteDir=owner_xyz -i /tmp/extension.json'
+				 .PHP_EOL
+				 .PHP_EOL
+				 .'#Batch write from JSON string:'
+				 .PHP_EOL
+				 .'cfg write extension_name \'module={"enabled":true,"timeout":30,"label":"example"}\' --siteDir=owner_xyz'
+				 .PHP_EOL
+				 .PHP_EOL
+				 .'#Read merged value for an instance:'
 				 .PHP_EOL
 				 .'cfg show extension_name module:enabled --siteDir=owner_xyz'
 				 .PHP_EOL
-			 .'# reads merged config including config/owner_xyz/extension_name.conf.php'
-			 .PHP_EOL
 		]
 ).PHP_EOL;
 
@@ -231,13 +252,7 @@ if ($argv->find( 'help' ) || $argv->find('action') == 'help')
 
 
 $prefix = $argv->find('prefix');
-/* 
+$verbose = (bool)$argv->find('verbose');
-echo $argv->find('action').PHP_EOL;
-echo ($prefix).PHP_EOL;
-echo $argv->find('setting')['key'].PHP_EOL;
-echo $argv->find('setting')['value'].PHP_EOL;
- */
-// var_dump($cfg);
 $appPath = $argv->find('appPath');
 if (!$appPath) $appPath = getcwd().'/';
 $appPath = rtrim($appPath, '/').'/';
@@ -299,6 +314,7 @@ if ($siteInput !== null && $siteInput !== false)
 	$site = $siteInput;
 	// Reuse util-settings site resolution: config/<site>/<prefix>.conf.php
 	$cfg->site($site);
+	verboseLog($verbose, "siteDir resolved to '$site'");
 }
 
 try
@@ -315,7 +331,7 @@ catch (\Throwable $e)
 	fwrite(STDERR, "Error: ".$e->getMessage().PHP_EOL);
 	exit(1);
 }
-//var_dump($cfg);
+verboseLog($verbose, 'config bootstrap loaded');
 
 $result = $cfg;
 $settings = $argv->find('setting') ?? $settings;
@@ -340,6 +356,7 @@ if ($result instanceof Settings) $result = $result->toArray();
 switch ($argv->find('action'))
 {
 case 'show':
+	verboseLog($verbose, "show action for prefix '$prefix'");
 	$out = (is_string($result)) ? $result : json_encode($result, JSON_PRETTY_PRINT);
 	echo $out.PHP_EOL;
 	break;
@@ -361,6 +378,7 @@ case 'write':
 	}
 
 	$path = ($settings['key'] !== '') ? explode(':', $settings['key']) : [];
+	verboseLog($verbose, 'write source: '.($inputFile ? "--in ($inputFile)" : 'SETTING'));
 	if ($inputFile)
 	{
 		try
@@ -377,6 +395,7 @@ case 'write':
 	{
 		$setting2write = $settings['value'];
 	}
+	verboseLog($verbose, 'write path: '.json_encode($path));
 
 	while ( ! empty($path))
 	{
@@ -385,10 +404,12 @@ case 'write':
 
 	$writeType = ($site !== null) ? $siteFlag : null;
 	$file = $cfg->buildFileName($writeType);
+	verboseLog($verbose, "write target: $file");
 	if (is_readable($file))
 	{
 		$setting2write = array_replace_recursive(require($file), $setting2write);
 		copy($file, "$file.bak");
+		verboseLog($verbose, "existing config merged from: $file");
 	}
 
 	$targetDir = dirname($file);
@@ -399,7 +420,7 @@ case 'write':
 	}
 
 	$writeCfg = $cfg->create($setting2write);
-//	var_dump($writeCfg->toArray());
+	verboseLog($verbose, 'payload prepared for writer');
 	try
 	{
 		(new SettingsWriter($writeCfg, '', $writeType))->write();