fusionpbx/resources/classes/service.php

<?php

/*
 * FusionPBX
 * Version: MPL 1.1
 *
 * The contents of this file are subject to the Mozilla Public License Version
 * 1.1 (the "License"); you may not use this file except in compliance with
 * the License. You may obtain a copy of the License at
 * http://www.mozilla.org/MPL/
 *
 * Software distributed under the License is distributed on an "AS IS" basis,
 * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
 * for the specific language governing rights and limitations under the
 * License.
 *
 * The Original Code is FusionPBX
 *
 * The Initial Developer of the Original Code is
 * Mark J Crane <markjcrane@fusionpbx.com>
 * Portions created by the Initial Developer are Copyright (C) 2008-2024
 * the Initial Developer. All Rights Reserved.
 *
 * Contributor(s):
 * Mark J Crane <markjcrane@fusionpbx.com>
 * Tim Fry <tim@fusionpbx.com>
 */

/**
 * Service class
 * @version 1.00
 * @author Tim Fry <tim@fusionpbx.com>
 */
abstract class service {

	const VERSION = "1.00";

	/**
	 * Track the internal loop. It is recommended to use this variable to control the loop inside the run function. See the example
	 * below the class for a more complete explanation
	 * @var bool
	 */
	protected $running;

	/**
	 * current debugging level for output to syslog
	 * @var int Syslog level
	 */
	protected static $log_level = LOG_INFO;

	/**
	 * config object
	 * @var config config object
	 */
	protected static $config;

	/**
	 * Holds the parsed options from the command line
	 * @var array
	 */
	protected static $parsed_command_options;

	/**
	 * Operating System process identification file
	 * @var string
	 */
	private static $pid_file = "";

	/**
	 * Cli Options Array
	 * @var array
	 */
	protected static $available_command_options = [];

	/**
	 * Holds the configuration file location
	 * @var string
	 */
	protected static $config_file = "";

	/**
	 * Fork the service to it's own process ID
	 * @var bool
	 */
	protected static $forking_enabled = true;

	/**
	 * Child classes must provide a mechanism to reload settings
	 */
	abstract protected function reload_settings(): void;

	/**
	 * Method to start the child class internal loop
	 */
	abstract public function run(): int;

	/**
	 * Display version notice
	 */
	abstract protected static function display_version(): void;

	/**
	 * Called when the display_help_message is run in the base class for extra command line parameter explanation
	 */
	abstract protected static function set_command_options();

	/**
	 * Open a log when created.
	 * <p>NOTE:<br>
	 * This is a protected function so it can not be called using the keyword 'new' outside of this class or a child
	 * class. This is due to the requirement to set signal handlers for the POSIX system outside of the constructor.
	 * PHP seems to have an issue on some versions where setting a signal handler while in the constructor (even
	 * calling another method from the constructor) will fail to register the signal handlers.</p>
	 */
	protected function __construct() {
		openlog('[php][' . self::class . ']', LOG_CONS | LOG_NDELAY | LOG_PID, LOG_DAEMON);
	}

	public function __destruct() {
		//ensure we unlink the correct PID file if needed
		if (self::is_running()) {
			unlink(self::$pid_file);
			self::log("Initiating Shutdown...", LOG_NOTICE);
			$this->running = false;
		}
		//this should remain the last statement to execute before exit
		closelog();
	}

	/**
	 * Shutdown process gracefully
	 */
	public static function shutdown() {
		exit();
	}

	public static function send_shutdown() {
		if (self::is_any_running()) {
			self::send_signal(SIGTERM);
		} else {
			die("Service Not Started\n");
		}
	}

	// register signal handlers
	private function register_signal_handlers() {
		// Allow the calls to be made while the main loop is running
		pcntl_async_signals(true);

		// A signal listener to reload the service for any config changes in the database
		pcntl_signal(SIGUSR1, [$this, 'reload_settings']);
		pcntl_signal(SIGHUP, [$this, 'reload_settings']);

		// A signal listener to stop the service
		pcntl_signal(SIGUSR2, [self::class, 'shutdown']);
		pcntl_signal(SIGTERM, [self::class, 'shutdown']);
	}

	/**
	 * Extracts the short options from the cli options array and returns a string. The resulting string must
	 * return a single string with all options in the string such as 'rxc:'.
	 * This can be overridden by the child class.
	 * @return string
	 */
	protected static function get_short_options(): string {
		return implode('' , array_map(function ($option) { return $option['short_option']; }, self::$available_command_options));
	}

	/**
	 * Extracts the long options from the cli options array and returns an array. The resulting array must
	 * return a single dimension array with an integer indexed key but does not have to be sequential order.
	 * This can be overridden by the child class.
	 * @return array
	 */
	protected static function get_long_options(): array {
		return array_map(function ($option) { return $option['long_option']; }, self::$available_command_options);
	}

	/**
	 * Method that will retrieve the callbacks from the cli options array
	 * @param string $set_option
	 * @return array
	 */
	protected static function get_user_callbacks_from_available_options(string $set_option): array {
		//match the available option to the set option and return the callback function that needs to be called
		foreach(self::$available_command_options as $option) {
			$short_option = $option['short_option'] ?? '';
			if (str_ends_with($short_option, ':')) {
				$short_option = rtrim($short_option, ':');
			}
			$long_option = $option['long_option'] ?? '';
			if (str_ends_with($long_option, ':')) {
				$long_option = rtrim($long_option, ':');
			}
			if ($short_option === $set_option ||
				$long_option  === $set_option) {
					return $option['functions'] ?? [$option['function']] ?? [];
			}
		}
		return [];
	}

	/**
	 *  Parse CLI options using getopt()
	 * @return void
	 */
	protected static function parse_service_command_options(): void {

		//ensure we have a PID so that reload and exit send commands work
		if (empty(self::$pid_file)) {
			self::$pid_file = self::get_pid_filename();
		}

		//base class short options
		self::$available_command_options = self::base_command_options();

		//get the options from the child class
		static::set_command_options();

		//collapse short options to a string
		$short_options = self::get_short_options();

		//isolate long options
		$long_options = self::get_long_options();

		//parse the short and long options
		$options = getopt($short_options, $long_options);

		//make the options available to the child object
		if ($options !== false) {
			self::$parsed_command_options = $options;
		} else {
			//make sure the command_options are reset
			self::$parsed_command_options = [];
			//if the options are empty there is nothing left to do
			return;
		}

		//notify user
		self::log("CLI Options detected: " . implode(",", self::$parsed_command_options), LOG_DEBUG);

		//loop through the parsed options given on the command line
		foreach ($options as $option_key => $option_value) {

			//get the function responsible for handling the cli option
			$funcs = self::get_user_callbacks_from_available_options($option_key);

			//ensure it was found before we take action
			if (!empty($funcs)) {
				//check for more than one function to be called is permitted
				if (is_array($funcs)) {
					//call each one
					foreach($funcs as $func) {
						//use the best method to call the function
						self::call_function($func, $option_value);
					}
				} else {
					//single function call
					self::call_function($func, $option_value);
				}
			}
		}
	}

	//
	// Calls a function using the best suited PHP method
	//
	private static function call_function($function, $args) {
		if ($function === 'exit') {
			//check for exit
			exit($args);
		} elseif ($function instanceof Closure || function_exists($function)) {
			//globally available function or closure
			$function($args);
		} else {
			static::$function($args);
		}
	}

	/**
	 * Checks the file system for a pid file that matches the process ID from this running instance
	 * @return bool true if pid exists and false if not
	 */
	public static function is_running(): bool {
		return posix_getpid() === self::get_service_pid();
	}

	public static function is_any_running(): bool {
		return self::get_service_pid() !== false;
	}

	/**
	 * Returns the operating system service PID or false if it is not yet running
	 * @return bool|int PID or false if not running
	 */
	protected static function get_service_pid() {
		if (file_exists(self::$pid_file)) {
			$pid = file_get_contents(self::$pid_file);
			if (function_exists('posix_getsid')) {
				if (posix_getsid($pid) !== false) {
					//return the pid for reloading configuration
					return $pid;
				}
			} else {
				if (file_exists('/proc/' . $pid)) {
					//return the pid for reloading configuration
					return $pid;
				}
			}
		}
		return false;
	}

	/**
	 * Create an operating system PID file removing any existing PID file
	 */
	private function create_service_pid() {
		// Set the pid filename
		$basename = basename(self::$pid_file, '.pid');
		$pid = getmypid();

		// Remove the old pid file
		if (file_exists(self::$pid_file)) {
			unlink(self::$pid_file);
		}

		// Show the details to the user
		self::log("Service   : $basename", LOG_INFO);
		self::log("Process ID: $pid", LOG_INFO);
		self::log("PID File  : " . self::$pid_file, LOG_INFO);

		// Save the pid file
		file_put_contents(self::$pid_file, $pid);
	}

	/**
	 * Creates the service directory to store the PID
	 * @throws Exception thrown when the service directory is unable to be created
	 */
	private function create_service_directory() {
		//make sure the /var/run/fusionpbx directory exists
		if (!file_exists('/var/run/fusionpbx')) {
			$result = mkdir('/var/run/fusionpbx', 0777, true);
			if (!$result) {
				throw new Exception('Failed to create /var/run/fusionpbx');
			}
		}
	}

	/**
	 * Parses the debug level to an integer and stores it in the class for syslog use
	 * @param string $debug_level Debug level with any of the Linux system log levels
	 */
	protected static function set_debug_level(string $debug_level) {
		// Map user input log level to syslog constant
		switch ($debug_level) {
			case '0':
			case 'emergency':
				self::$log_level = LOG_EMERG; // Hardware failures
				break;
			case '1':
			case 'alert':
				self::$log_level = LOG_ALERT; // Loss of network connection or a condition that should be corrected immediately
				break;
			case '2':
			case 'critical':
				self::$log_level = LOG_CRIT; // Condition like low disk space
				break;
			case '3':
			case 'error':
				self::$log_level = LOG_ERR;  // Database query failure, file not found
				break;
			case '4':
			case 'warning':
				self::$log_level = LOG_WARNING; // Deprecated function usage, approaching resource limits
				break;
			case '5':
			case 'notice':
				self::$log_level = LOG_NOTICE; // Normal conditions
				break;
			case '6':
			case 'info':
				self::$log_level = LOG_INFO; // Informational
				break;
			case '7':
			case 'debug':
				self::$log_level = LOG_DEBUG; // Debugging
				break;
			default:
				self::$log_level = LOG_NOTICE; // Default to NOTICE if invalid level
		}
	}

	/**
	 * Show memory usage to the user
	 */
	protected static function show_mem_usage() {
		//current memory
		$memory_usage = memory_get_usage();
		//peak memory
		$memory_peak = memory_get_peak_usage();
		self::log('Current memory: ' . round($memory_usage / 1024) . " KB", LOG_INFO);
		self::log('Peak memory: ' . round($memory_peak / 1024) . " KB", LOG_INFO);
	}

	/**
	 * Logs to the system log
	 * @param string $message
	 * @param int $level
	 */
	protected static function log(string $message, int $level = null) {
		// Use default log level if not provided
		if ($level === null) {
			$level = self::$log_level;
		}

		//enable sending message to the console directly
		if (self::$log_level === LOG_DEBUG || !self::$forking_enabled) {
			echo $message . "\n";
		}

		// Log the message to syslog
		syslog($level, 'fusionpbx[' . posix_getpid() . ']: ['.static::class.'] '.$message);
	}

	/**
	 * Returns a file safe class name with \ from namespaces converted to _
	 * @return string file safe name
	 */
	protected static function base_file_name(): string {
		return str_replace('\\', "_", static::class);
	}

	/**
	 * Returns only the name of the class without namespace
	 * @return string base class name
	 */
	protected static function base_class_name(): string {
		$class_and_namespace = explode('\\', static::class);
		return array_pop($class_and_namespace);
	}

	/**
	 * Write a standard copyright notice to the console
	 * @return void
	 */
	public static function display_copyright(): void {
		echo "FusionPBX\n";
		echo "Version: MPL 1.1\n";
		echo "\n";
		echo "The contents of this file are subject to the Mozilla Public License Version\n";
		echo "1.1 (the \"License\"); you may not use this file except in compliance with\n";
		echo "the License. You may obtain a copy of the License at\n";
		echo "http://www.mozilla.org/MPL/\n";
		echo "\n";
		echo "Software distributed under the License is distributed on an \"AS IS\" basis,\n";
		echo "WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License\n";
		echo "for the specific language governing rights and limitations under the\n";
		echo "License.\n";
		echo "\n";
		echo "The Original Code is FusionPBX\n";
		echo "\n";
		echo "The Initial Developer of the Original Code is\n";
		echo "Mark J Crane <markjcrane@fusionpbx.com>\n";
		echo "Portions created by the Initial Developer are Copyright (C) 2008-2023\n";
		echo "the Initial Developer. All Rights Reserved.\n";
		echo "\n";
		echo "Contributor(s):\n";
		echo "Mark J Crane <markjcrane@fusionpbx.com>\n";
		echo "Tim Fry <tim@fusionpbx.com>\n";
		echo "\n";
	}

	/**
	 * Sends the shutdown signal to the service using a posix signal.
	 * <p>NOTE:<br>
	 * The signal will not be received from the service if the
	 * command is sent from a user that has less privileges then
	 * the running service. For example, if the service is started
	 * by user root and then the command line option '-r' is given
	 * as user www-data, the service will not receive this signal
	 * because the OS will not allow the signal to be passed to a
	 * more privileged user due to security concerns. This would
	 * be the main reason why you must run a 'systemctl' or a
	 * 'service' command as root user. It is possible to start the
	 * service with user www-data and then the web UI would in fact
	 * be able to send the reload signal to the running service.</p>
	 */
	public static function send_signal($posix_signal) {
		$signal_name = "";
		switch ($posix_signal) {
			case SIGHUP:
			case SIGUSR1:
				$signal_name = "Reload";
				break;
			case SIGTERM:
			case SIGUSR2:
				$signal_name = "Shutdown";
				break;
		}
		$pid = self::get_service_pid();
		if ($pid === false) {
			self::log("service not running", LOG_EMERG);
		} else {
			if (posix_kill((int) $pid, $posix_signal) ) {
				echo "Sent $signal_name\n";
			} else {
				$err = posix_strerror(posix_get_last_error());
				echo "Failed to send $signal_name: $err\n";
			}
		}
	}

	/**
	 * Display a basic help message to the user for using service
	 */
	protected static function display_help_message(): void {
		//get the classname of the child class
		$class_name = self::base_class_name();

		//get the widest options for proper alignment
		$width_short = max(array_map(function ($arr) { return strlen($arr['short_description'] ?? ''); }, self::$available_command_options));
		$width_long  = max(array_map(function ($arr) { return strlen($arr['long_description' ] ?? ''); }, self::$available_command_options));

		//display usage help using the class name of child
		echo "Usage: php $class_name [options]\n";

		//display the options aligned to the widest short and long options
		echo "Options:\n";
		foreach (self::$available_command_options as $option) {
			printf("%-{$width_short}s %-{$width_long}s %s\n",
				$option['short_description'],
				$option['long_description'],
				$option['description']
			);
		}
	}

	public static function send_reload() {
		if (self::is_any_running()) {
			self::send_signal(SIGUSR1);
		} else {
			die("Service Not Started\n");
		}
		exit();
	}

	//
	// Options built-in to the base service class. These can be overridden with the child class
	// or they can be extended using the array
	//
	private static function base_command_options(): array {
		//put the display for help in an array so we can calculate width
		$help_options = [];
		$index = 0;
		$help_options[$index]['short_option'] = 'v';
		$help_options[$index]['long_option'] = 'version';
		$help_options[$index]['description'] = 'Show the version information';
		$help_options[$index]['short_description'] = '-v';
		$help_options[$index]['long_description'] = '--version';
		$help_options[$index]['functions'][] = 'display_version';
		$help_options[$index]['functions'][] = 'shutdown';
		$index++;
		$help_options[$index]['short_option'] = 'h';
		$help_options[$index]['long_option'] = 'help';
		$help_options[$index]['description'] = 'Show the version and help message';
		$help_options[$index]['short_description'] = '-h';
		$help_options[$index]['long_description'] = '--help';
		$help_options[$index]['functions'][] = 'display_version';
		$help_options[$index]['functions'][] = 'display_help_message';
		$help_options[$index]['functions'][] = 'shutdown';
		$index++;
		$help_options[$index]['short_option'] = 'a';
		$help_options[$index]['long_option'] = 'about';
		$help_options[$index]['description'] = 'Show the version and copyright information';
		$help_options[$index]['short_description'] = '-a';
		$help_options[$index]['long_description'] = '--about';
		$help_options[$index]['functions'][] = 'display_version';
		$help_options[$index]['functions'][] = 'display_copyright';
		$help_options[$index]['functions'][] = 'shutdown';
		$index++;
		$help_options[$index]['short_option'] = 'r';
		$help_options[$index]['long_option'] = 'reload';
		$help_options[$index]['description'] = 'Reload settings for an already running service';
		$help_options[$index]['short_description'] = '-r';
		$help_options[$index]['long_description'] = '--reload';
		$help_options[$index]['functions'][] = 'send_reload';
		$index++;
		$help_options[$index]['short_option'] = 'd:';
		$help_options[$index]['long_option'] = 'debug:';
		$help_options[$index]['description'] = 'Set the syslog level between 0 (EMERG) and 7 (DEBUG). 5 (INFO) is default';
		$help_options[$index]['short_description'] = '-d <level>';
		$help_options[$index]['long_description'] = '--debug <level>';
		$help_options[$index]['functions'][] = 'set_debug_level';
		$index++;
		$help_options[$index]['short_option'] = 'c:';
		$help_options[$index]['long_option'] = 'config:';
		$help_options[$index]['description'] = 'Full path and file name of the configuration file to use. /etc/fusionpbx/config.conf or /usr/local/etc/fusionpbx/config.conf on FreeBSD is default';
		$help_options[$index]['short_description'] = '-c <path>';
		$help_options[$index]['long_description'] = '--config <path>';
		$help_options[$index]['functions'][] = 'set_config_file';
		$index++;
		$help_options[$index]['short_option'] = '1';
		$help_options[$index]['long_option'] = 'no-fork';
		$help_options[$index]['description'] = 'Do not fork the process';
		$help_options[$index]['short_description'] = '-1';
		$help_options[$index]['long_description'] = '--no-fork';
		$help_options[$index]['functions'][] = 'set_no_fork';
		$index++;
		$help_options[$index]['short_option'] = 'x';
		$help_options[$index]['long_option'] = 'exit';
		$help_options[$index]['description'] = 'Exit the service gracefully';
		$help_options[$index]['short_description'] = '-x';
		$help_options[$index]['long_description'] = '--exit';
		$help_options[$index]['functions'][] = 'send_shutdown';
		$help_options[$index]['functions'][] = 'shutdown';
		return $help_options;
	}

	/**
	 * Set to not fork when started
	 */
	public static function set_no_fork() {
		echo "Running in forground\n";
		self::$forking_enabled = false;
	}

	/**
	 * Set the configuration file location to use for a config object
	 */
	public static function set_config_file(string $file = '/etc/fusionpbx/config.conf') {
		if (empty(self::$config_file)) {
			self::$config_file = $file;
		}
		self::$config = new config(self::$config_file);
	}

	/**
	 * Appends the CLI option to the list given to the user as a command line argument.
	 * @param command_option $option
	 * @return int The index of the item added
	 */
	public static function append_command_option(command_option $option): int {
		$index = count(self::$available_command_options);
		self::$available_command_options[$index] = $option->to_array();
		return $index;
	}

	/**
	 * Adds an option to the command line parameters
	 * @param string $short_option
	 * @param string $long_option
	 * @param string $description
	 * @param string $short_description
	 * @param string $long_description
	 * @param string $callback
	 * @return int The index of the item added
	 */
	public static function add_command_option(string $short_option, string $long_option, string $description, string $short_description = '', string $long_description = '', ...$callback): int {
		//use the option as the description if not filled in
		if (empty($short_description)) {
			$short_description = '-' . $short_option;
			if (str_ends_with($short_option, ':')) {
				$short_description .= " <setting>";
			}
		}
		if (empty($long_description)) {
			$long_description = '-' . $long_option;
			if (str_ends_with($long_option, ':')) {
				$long_description .= " <setting>";
			}
		}
		$index = count(self::$available_command_options);
		self::$available_command_options[$index]['short_option'] = $short_option;
		self::$available_command_options[$index]['long_option'] = $long_option;
		self::$available_command_options[$index]['description'] = $description;
		self::$available_command_options[$index]['short_description'] = $short_description;
		self::$available_command_options[$index]['long_description'] = $long_description;
		self::$available_command_options[$index]['functions'] = $callback;
		return $index;
	}

	/**
	 * Returns the process ID filename used for a service
	 * @return string file name used for the process identifier
	 */
	public static function get_pid_filename(): string {
		return '/var/run/fusionpbx/' . self::base_file_name() . '.pid';
	}

	/**
	 * Sets the following:
	 *   - execution time to unlimited
	 *   - location for PID file
	 *   - parses CLI options
	 *   - ensures folder structure exists
	 *   - registers signal handlers
	 */
	private function init() {

		// Increase limits
		set_time_limit(0);
		ini_set('max_execution_time', 0);
		ini_set('memory_limit', '512M');

		//set the PID file
		self::$pid_file = self::get_pid_filename();

		//register the shutdown function
		register_shutdown_function([$this, 'shutdown']);

		// Ensure we have only one instance
		if (self::is_any_running()) {
			self::log("Service already running", LOG_ERR);
			exit();
		}

		// Ensure directory creation for pid location
		$this->create_service_directory();

		// Create a process identifier file
		$this->create_service_pid();

		// Set the signal handlers for reloading
		$this->register_signal_handlers();

		// We are now considered running
		$this->running = true;
	}

	/**
	 * Creates a system service that will run in the background
	 * @return self
	 */
	public static function create(): self {
		//can only start from command line
		defined('STDIN') or die('Unauthorized');

		//parse the cli options and store them statically
		self::parse_service_command_options();

		//fork process
		if (self::$forking_enabled) {
			echo "Running in daemon mode\n";
			//force launching in a seperate process
			if ($pid = pcntl_fork()) {
				exit;
			}

			if ($cid = pcntl_fork()) {
				exit;
			}
		}

		//TODO remove updated settings object after merge
		if (file_exists( __DIR__ . '/settings.php')) {
			require_once __DIR__ . '/settings.php';
		}

		//TODO remove global functions after merge
		if (file_exists(dirname(__DIR__).'/functions.php')) {
			require_once dirname(__DIR__).'/functions.php';
		}

		//create the config object if not already created
		if (self::$config === null) {
			self::$config = new config(self::$config_file);
		}

		//get the name of child object
		$class = self::base_class_name();

		//create the child object
		$service = new $class();

		//initialize the service
		$service->init();

		//return the initialized object
		return $service;
	}

}

/*
 * Example
 *
 * The child_service class must be used to demonstrate the base_service because base_service is abstract. This means that you
 * cannot use the syntax of:
 *   $service = new service();		//throws fatal error
 *   $service->run();				//never reaches this statement
 *
 * Instead, you must use a class that will extend the service class like this:
 *   $service = child_service::create();
 *   $service->run();
 * (make the code below more readable by putting)
 * ( in the '/' line below to complete the comment section )
 *

//
// A class that extends base_service must implement 4 functions:
//   - run()               This is the entry point called from an external source after the create method is called
//   - reload_settings     This is called when the CLI option -r or --reload is used
//   - display_version
//   - command_options
//
// Using the class below use the commands
//   $simple_example = simple_example::create();
//   $simple_example->run();
//
// This will create the class and then run it once and exit with a success code.
//
//
class simple_example extends service {

	protected function reload_settings(): void {

	}

	protected static function display_version(): void {
		echo "Version 1.00\n";
	}

	protected static function set_command_options() {

	}

	public function run(): int {
		echo "Successfully ran child service\n";
		echo "Try command line options -h or -v\n";
		return 0;
	}
}

//*/
/*
//
// This class is more complex in that it will continue to run with a connection to a database
//
// The service class is divided between static and non-static methods. The static methods are
// used and called before the service is run allowing the CLI options to be read and parsed
// before the object is initialized. This allows for configuration options to be available
// when the child class is first started up. Keep in mind that these are called statically
// so that all callback functions declared in the cli options must be static.
//
class child_service extends service {

	//
	// Using a version constant is ideal for tracking and reporting
	//
	const CHILD_SERVICE_VERSION = '1.00';

	//
	// The parent service does not create a database connection as the child service may not need it. This example
	// demonstrates how the config object is passed from the parent and then used in the child service to connect
	// to other resources or use other settings the base class loaded so the child class automatically inherits.
	//
	private $database;

	// This example uses a settings object to demonstrate how the config is passed through to the child class
	// and is then used again in the reload_settings to demonstrate how the settings could be reloaded
	// with changes in the configuration, database connection, and default settings without the need to create
	// new instances of the config object.
	private $settings;

	//
	// This function is required from the base service class because it is used when the reload command line option is used
	//
	protected function reload_settings(): void {
		//informing the user in this example is simple but can use the parent class log functions
		echo "Reloading settings\n";

		//
		// Reload the configuration file
		//
		self::$config->read();

		//
		// If services have their own configuration file that was passed in using the -c or --config option, the options
		// would be available here as well to the child class
		// By allowing the config file to be specified, it is possible for services to have a configuration specific to them
		// while it could still be possible to allow access to the original making it very flexible with a wide degree of
		// choices.
		//
		// For example, specifying a configuration file that could be used for an archive or backup server would allow
		// the backup service to connect to another system remotely.
		//
		// It could also be used to separate the web configuration from system services to keep them organized and allow for
		// configuration settings to be available should the database fail. One possible scenario where this could be useful
		// is to send an email if the database stops responding. Currently, this is not possible as the database class uses
		// the 'die' command to immediately exit. I think it would be good to remove that and instead set the error message
		// to be something that would reflect the error allowing a system service to detect and even possibly correct that.
		//
		$alert_email = self::$config->get('alert_email', '');
		$smtp_host = self::$config->get('smtp_host', '');
		$smtp_port = self::$config->get('smtp_port', '');

		//
		// Ensure the database is connected with the new configuration parameters
		//
		$this->database->connect();

		//
		// The reload settings here completes the chain
		//
		$this->settings->reload();

	}

	//
	// This run function is required as it is called to launch child_service. This
	// is the entry point for the child class.
	//
	public function run(): int {

		//
		// Create the database object once passing a reference to the config object
		//
		$this->database = new database(['config' => self::$config]);

		//
		// Create the settings object using the database connection
		//
		$this->settings = new settings(['database' => $this->database]);

		//
		// In this example I have used the reload_settings because it is required by the parent class
		// whenever the '-r' or '--reload' option is given on the CLI. The base class is responsible for
		// parsing the information given on the CLI. Whenever the base class detects a '-r' option, the
		// reload_settings method in the child class is called. This gives the responsibility to the the
		// child class to reload any settings that might be needed during long execution of the service
		// without stopping and starting the service. The method is called here to initialize any and all
		// objects within the child service.
		//
		$this->reload_settings();

		//
		// The $running property is declared in the base service class as a boolean and it is responsible
		// to enable this so that the child class can run. The base service class will set this to false
		// if it receives a shutdown command from either the OS, PHP, or a posix signal allowing the child
		// class to respond or clean up after the while loop.
		//
		while($this->running) {
			//
			// This is where the actual heart of the code for the new service will be created
			//
			echo "Doing something..." . date("Y-m-d H:i:s") . "\n";
			sleep(1);
		}


		//
		// Returning a non-zero value would indicate there was an issue. Here we return zero to indicate graceful shutdown.
		//
		return 0;
	}

	//
	// This is the version that will be displayed when the option '-v' or '--version' is used on the command line.
	// This run function is required
	//
	protected static function display_version(): void {
		echo "Child service example version " . self::CHILD_SERVICE_VERSION . "\n";
	}

	//
	// set_command_options can either add to or replace options. Replacing the base options would allow an override for default behaviour.
	// This run function is required
	//
	protected static function set_command_options() {

		//
		// The options below are added to the CLI options and displayed whenever the -h or --help option is used.
		// There are multiple methods are used to suite the style of the creator
		//

		//
		// The callbacks set here are used to demonstrate multiple calls can be used
		//

		//using the parameter in the function
		self::add_command_option(
			't:'
			, 'template:'
			, 'Full path and file name of the template file to use'
			, '-t <path>'
			, '--template <path>'
			, ['set_template_path']
		);
		//using a container object
		self::append_command_option(command_option::new()
			->short_option('n')
			->long_option('null')
			->description('This option is to demonstrate using a cli object to create cli options')
			->functions(['null_function_method'])
		);
		//using an array of key/value pairs
		self::append_command_option(command_option::new([
			'short_option' => 'z:'
			,'long_option' => 'zero:'
			,'description' => 'This has zero effect on behavior'
			,'function' => 'call_single_function'
		]));

		//
		// These options are here but are commented out to allow the functionality to still exist in the parent
		//
//
//		//replace cli options in the parent class using array
//		$index = 0;
//		$arr_options = [];
//		$arr_options[$index]['short_option'] = 'z';
//		$arr_options[$index]['long_option'] = 'zero';
//		$arr_options[$index]['description'] = 'This has zero effect on behavior';
//		$arr_options[$index]['short_description'] = '-z';
//		$arr_options[$index]['long_description'] = '--zero';
//		$arr_options[$index]['function'][] = 'call_single_function';
//		self::$available_command_options = $arr_options;
//
//		//replace all cli options using container object
//		$arr_options = [];
//		self::$available_command_options = [];
//		$arr_options[0] = command_option::new()
//			->short_option('z')
//			->short_description('-z')
//			->function('call_a_function')
//			->function('call_another_function_after_first')
//			->description('This option does nothing')
//			->to_array();
//
//		$arr_options[1] = command_option::new([
//			'short_option' => 'z'
//			,'long_option' => '--zero'
//			,'description' => 'This option does nothing'
//			,'functions' => ['call_a_function', 'call_another_function']
//		])->to_array();
		//self::$available_command_options = $arr_options;
	}
} // class child_service

//*/

/*
//
// Standard includes do not apply for the base class because the require.php has included many other php files. These other files
// or objects may not be required for some services. Thus, only the config is required for base_service. Child services may then
// create a database class and use it by passing the config object to the database constructor. This is why the 'require.php' is
// left out of the initial setup class.
//

// Use the auto_loader to find any classes needed so we don't have a lot of include statements
// In this example, the auto_loader should not be using the PROJECT_ROOT or any other defined constants
// because they are not needed in the initial stage of loading
require_once __DIR__ . '/auto_loader.php';

// We don't need to ever reference the object so don't assign a variable. It
// would be a good idea to remove the auto_loader as a class declaration so
// that there would only need to be one line. It seems illogical to have an
// object that never needs to be referenced.
new auto_loader();

// The base_service class has a 'protected' constructor, meaning you are not able to use "new" to create the object. Instead, you
// must use the 'create' static method to create an object. This technique is employed because some PHP versions have an issue with
// registering signal listeners in the constructor. See the link https://www.php.net/manual/en/function.pcntl-signal.php in the user
// comments section.
// The child_service class does not override the parent constructor so parent constructor is used. If the child_service class does
// have a constructor then the child class must call:
//   parent::__construct($config);
// as the first line of the child constructor. This is because the parent constructor uses the config class. This also means
// that the child class must receive the config object in the constructor as a minimum.
$service = child_service::create();

// The run class is declared as abstract in the parent. So the child class must have one.
$service->run();
//*/