Inside Mod Manager v12 Modbase
Class Modbase
Purpose
Provide common data and functions to the extending Mod Manager classes.
Options Used (Set in mmconfig.php)
$this->sortby $this->modlogfile $this->maxloglines
Data
- Object Initialization Data
- Constants
Initialization Data
Data required by mod objects to perform their tasks is provided in the form of an array ($objinits) when the object is instantiated. The array is defined and maintained in an 'include' file, classes/modobjinits.php, as follows:
$objinits = array (
'rootpath' => $rootpath,
'subroot' => $subroot,
'modspath' => $modspath,
'extspath' => $extspath,
'options' => $options,
'time_offset' => $time_offset,
'sitever' => $sitever,
'currentuserdesc' => $mhuser,
'admtext' => $admtext,
'templatenum' => $templatenum,
'tng_version' => $tng_version
);Notice the array is a combination of single values like $subroot, and other arrays like $admtext. Modbase receives them from extending (children) classes and its constructor loads them into its data cache, making them available to all extending objects such as Modparser and Modlister.
The user $options array is stored as individual options. For example, $options['maxloglines'] is stored and accessed as $this->maxloglines inside Modbase and its extending classes.
The language support array, $admtext can be accessed inside a class/function using $this->admtext['welcome'].
Example of initializing an extending class:
include 'classes/modlister.class.php';
include 'classes/modobjinits.php';
$oList = new modlister( $objinits );
$oList->list_mods();Above we initialize and instantiate a Modlister class object -- $oList, which extends from two other classes, Modbase and Modparser.
How initialization data is passed to Modbase
Inside each class there is a constructor, a function that can call functions or assign data as the object is being created. When instantiated, the $objinit data is passed to its parent class (Modbase) using its constructor as follows:
function __construct($objinit) { // modparser
parent::__construct($objinit); // modbase
}The Modbase constructor then assigns them to its data cache as the object is being created.
Modbase Functions
Public functions are available externally to a script that instantiates a Modbase object or an object whose class extends Modbase.
Public and Protected functions are available to all classes that extend Modbase.
public function get_modfile_names()
Returns a sorted list of mod files (.cfg) in the mods directory.
We use PHP opendir() and readdir() to create a list of of files with .cfg extension. Then we alpha sort the list and return it.
public function get_modlist_sorted()
Returns sorted array, $mod_list, with mod file-names as array indexes, and mod names as array values. For example,
$mod_list[0]['mymod_v12.0.cfg'] = 'my_modname';
Function opens and reads each cfg file in the mods directory into a buffer to get its mod-name (%name:) value.
The returned array is sorted by file-name or by mod-name according to the user-selected $options['sortby'] setting.
If an error code is returned in the $buffer from $this->file_read_buffer() indicating the file does not exist, or is empty, we return 'no access' in place of a mod-name in the $mod_list. The error text will not be seen because the parser will also discover the file does not exist and will report it with a more detailed error -- file missing, empty or ends unexpectedly.
protected function fix_eol( $buffer )
@param buffer: string containing the content of a text file.
Uses a simple regex to standardize line endings in a file buffer. The Mod Manager standard ending is \r\n.
preg_replace( "#(?:\r\n|\r\r\n|[\r\n])#", "\r\n", $buffer );Line endings become a major issue when comparing text from one file with another, so we standardize them in buffers for both mod cfg files and in target files.
This regex checks for \r\n pairs and replaces them with \r\n to prevent the \r or \n being individually replaced with \r\n. Then \r\r\n is replaced with \r\n (probably unnecessary.) Finally, we replace an individual \r or \n with \r\n.
If we had \n\r we would end up with a pair of line endings -- \r\n\r\n. Haven't found any of those yet.
Note 1: All saved files are converted to standard line endings.
Note 2 from the Internet: Windows, and DOS before it, uses a pair of CR and LF characters to terminate lines. UNIX (Including Linux and FreeBSD) uses an LF character only. OS X also uses a single LF character, but the classic Mac operating system used a single CR character for line breaks. In other words: a complete mess.
@param buffer: string containing the entire content of a text file.
This function removes spaces and tabs from the buffer that appear immediately before a line ending using the following.
Mod Manager does exact comparisons of code between a cfg file and a target file. Sometimes text strings look the same, but the comparison fails because there are unseen spaces or tabs just before a line ending; This function removes them from the file buffers for both mod cfg files and TNG target files. Hidden spaces and tabs serve no purpose; some editors silently even remove them. So here is the code that does this:
preg_replace( "#[ \t]*\r\n#", "\r\n", $buffer );Note 1: This regex can be made more efficient.
Note 2: Saved files have any hidden white space removed, so they may not exactly match factory files. We are not aware of any downside for doing this.
protected file_read_buffer($filepath, $flag)
@param filepath: path of the file to be read.<br /> @param flag: flags the file as Optional (@) or Provisioal (^).
Reads file at $filepath into a string buffer, standardizes line endings and removes hidden spaces and tabs, does basic error checking and returns a buffer containing either the file content or a code. If the file is not found or cannot be opened, an error code is returned instead of the buffer. If a file is missing, but has an Optional or Provisional flag, the returned code indicates an exception. Different mod classes will handle these differently. For example, Modinstaller will bypass an Optional file if it is missing, but will throw an error if a Provisional file is missing -- it is supposed to have been installed by the mod prior to executing an operation on it.
protected function write_file_buffer($filepath, $buffer)
@param filepath: path of the file to be read.<br /> @param buffer: string containing the entire content of a text file.
Writes modified string $buffer to $filepath. Uses low level PHP file writing routines to obtain a protective lock while writing.
Returns false if file write fails; otherwise returns the number of bytes written.
Note: File is written with standardized MM line endings -- \r\n
protected function resolve_file_path($filepath, $relative = self::ROOT_DIR)
@param filepath: string containing a file path.<br /> @param relative: flag determines if the returned file path should be relative to the TNG root (default) or to the Mods directory.
Replaces TNG path vars -- $modspath and $extspath -- in $filepath with value from the TNG config file.
Returns absolute file path relative to the TNG root directory (default) or relative to the mods directory (second argument).
Notes: Even though file paths are relative to the TNG rootpath or mods directory, they can still find or deliver files to other locations. The following is a valid path for a source file not in the mods directory:
../$extspath/myfile.php
Which would result in a valid absolute source path like this:
/home6/user4/public_html/mods/../extensions/myfile.php
This would only work if the mods directory is immediately below the TNG root.
Future programmers might consider also resolving $rootpath, $mediapath, $headstonepath, $historypath, etc.
protected function resolve_path vars($str)
@param str: string with path to be resolved.
Returns $str with TNG path variables $modspath and $extspath replaced with their actual values from the TNG config.php file.
Notes: In earlier test versions of Mod Manager we ran this function on the entire buffer. That caused problems with actual target/replacement code that needed to use these variables as-is in target scripts. Now paths are only resolved for private, notes and description tags and for file paths used as arguments in target, newfile and copyfile operations.
protected function version2integer($version)
@param version: string containing a TNG version number.
Used by the %tng_version: conditional tag.
This functions returns a TNG version number as a four-digit integer for comparison - greater than, less than or the same as other version numbers.
protected function add_logevent($string)
@param string: log event to be added to the Log file.
$this->eventlog is a string in the Modbase data cache that will be written to the log file to memorialize results when processing a mod.
This function appends $string to the event log string.
protected function new_logevent($string)
@param string: text to start a new log event
Initializes the event log ($this->eventlog) with date, time and an event title -- Install, Uninstall, Clean up, Edit Parameters and Delete.
protected function write_eventlog($error=false)
@param error: true if the event to be logged shows an error.
- Creates log file if one does not exist.
- Collects $this->mod_status
- Collects $this->eventlog and formats/styles it (error or success)
- Writes it to $this->logfile, keeping the file size less than or equal to Mod Manager option $this->maxloglines.
Notes: This function does it's own write operation (instead of using write_file_buffer()) because it needs to manage the number of lines written to the log.
private function create_logfile()
Creates a new Mod Manager logfile as specified in Mod Manager option $this->modlogfile.
Inside Mod Manager v12 Directory
| Chapters |
|---|