Source for file application-defs.php

Documentation is available at application-defs.php

  1. <?php
  2. /* ******************************************************************** */
  3. /* CATALYST PHP Source Code */
  4. /* -------------------------------------------------------------------- */
  5. /* This program is free software; you can redistribute it and/or modify */
  6. /* it under the terms of the GNU General Public License as published by */
  7. /* the Free Software Foundation; either version 2 of the License, or */
  8. /* (at your option) any later version. */
  9. /* */
  10. /* This program is distributed in the hope that it will be useful, */
  11. /* but WITHOUT ANY WARRANTY; without even the implied warranty of */
  12. /* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the */
  13. /* GNU General Public License for more details. */
  14. /* */
  15. /* You should have received a copy of the GNU General Public License */
  16. /* along with this program; if not, write to: */
  17. /* The Free Software Foundation, Inc., 59 Temple Place, Suite 330, */
  18. /* Boston, MA 02111-1307 USA */
  19. /* -------------------------------------------------------------------- */
  20. /* */
  21. /* Filename: application-defs.php */
  22. /* Author: Paul Waite */
  23. /* Description: Basic definitions pertaining to application config. */
  24. /* */
  25. /* ******************************************************************** */
  26. /** @package core */
  27. include_once("xml-defs.php");
  28. /** Filesystem access */
  29. ("file-defs.php");
  30. // ----------------------------------------------------------------------
  31. /**
  32. * A parameter class to contain setting parameter information. Every
  33. * parameter has an idetifying name, and a type. The value of a
  34. * parameter can be an array of name=>value pairs, or a scalar type
  35. * such as a string, integer or boolean.
  36. * @package core
  37. */
  38. class parameter {
  39. /** Parameter name */
  40.  
  41. var $name = "";
  42. /** Parameter type */
  43.  
  44. var $type = "";
  45. /** Parameter value */
  46.  
  47. var $value = "";
  48. // .....................................................................
  49. /**
  50. * Make a new parameter.
  51. * @param string $name Name of this parameter
  52. * @param string $type Parameter type eg: 'array', 'string' etc.
  53. */
  54. function parameter($name, $type) {
  55. $this->name = $name;
  56. $this->type = $type;
  57. if ($type == "array") {
  58. $this->value = array();
  59. }
  60. }
  61. // .....................................................................
  62. /**
  63. * Set the parameter to given value. If the parameter has an
  64. * array of values, the name is also given.
  65. * @param mixed $value Value to assign to this parameter
  66. * @param string $ename Name of this value (arrayed parameters only)
  67. */
  68. function setvalue($value, $ename="") {
  69. if ($this->type == "array") {
  70. $this->value[$ename] = $value;
  71. }
  72. elseif ($this->type == "boolean") {
  73. $this->value = (($value === "true"||$value === "t"||$value === true) ? true : false);
  74. }
  75. else {
  76. $this->value = $value;
  77. }
  78. }
  79. // .....................................................................
  80. /**
  81. * Get the parameter value. If the element name is given (for an
  82. * array type parameter) then we return the value of that element.
  83. * @param string $ename Name of this value (arrayed parameters only)
  84. */
  85. function getvalue($ename="") {
  86. if ($this->type == "array") {
  87. return $this->value[$ename];
  88. }
  89. else {
  90. return $this->value;
  91. }
  92. }
  93. // .....................................................................
  94. /**
  95. * Return decoded value (or array of values) so that applications can use
  96. * the data unencumbered with URL encoding etc.
  97. * @return mixed Value or array of values which have been urldecoded
  98. */
  99. function get_decodedvalue() {
  100. switch ($this->type) {
  101. case "array":
  102. $rar = array();
  103. foreach ($this->value as $name => $value) {
  104. $rar[$name] = rawurldecode($value);
  105. }
  106. return $rar;
  107. break;
  108.  
  109. case "boolean":
  110. return $this->value;
  111. break;
  112.  
  113. default:
  114. return rawurldecode($this->value);
  115. }
  116. }
  117. // .....................................................................
  118. /** Dump this parameter */
  119.  
  120. function htmldump() {
  121. $s = "";
  122. $s .= "parameter: $this->name ($this->type) ";
  123. if ($this->type == "array") {
  124. $s .= "values:";
  125. foreach ($this->value as $ename => $val) {
  126. $s .= " [$ename = '$val']";
  127. }
  128. }
  129. else {
  130. $s .= "value = '$this->value'";
  131. }
  132. return $s . "<br>";
  133. }
  134. } // parameter class
  135. // .......................................................................
  136.  
  137. /**
  138. * Application settings class. This class contains one or more parameters.
  139. * A setting can also have an 'agent' defined which will action it. This
  140. * can, for example, be the name of a function, if used.
  141. * @package core
  142. */
  143. class setting {
  144. /** Name of this setting */
  145.  
  146. var $name = "";
  147. /** Agent which will action this setting */
  148.  
  149. var $agent = "";
  150. /* Array of parameters for this setting */
  151. var $parameters = array();
  152. // .....................................................................
  153. /** Make a new setting */
  154.  
  155. function setting($name="", $agent="") {
  156. $this->name = $name;
  157. $this->agent = $agent;
  158. }
  159. // .....................................................................
  160. /**
  161. * Add the given parameter to this setting.
  162. * @param string $name Name of the parameter to add
  163. * @param object $parm Parameter object to add to this setting
  164. */
  165. function addparameter($name, $parm) {
  166. $this->parameters[$name] = $parm;
  167. }
  168. // .....................................................................
  169. /**
  170. * Set the value of a parameter which already exists in this
  171. * setting.
  172. * @param string $pname Name of the parameter to set value of
  173. * @param mixed $value Value to set in the parameter
  174. * @param string $ename Name of this value (arrayed parameters only)
  175. */
  176. function setparameter($pname, $value, $ename="") {
  177. if (isset($this->parameters[$pname])) {
  178. $this->parameters[$pname]->setvalue($value, $ename);
  179. }
  180. }
  181. // .....................................................................
  182. /**
  183. * Get the value of a named parameter.
  184. * @param string $name Name of the parameter to get value of
  185. * @param string $ename Name of element (arrayed parameters only)
  186. */
  187. function getparameter($name, $ename="") {
  188. $val = false;
  189. if (isset($this->parameters) && isset($this->parameters[$name])) {
  190. $parm = $this->parameters[$name];
  191. $val = $parm->getvalue($ename);
  192. }
  193. return $val;
  194. }
  195. // .....................................................................
  196. /** Dump setting */
  197.  
  198. function htmldump() {
  199. $s = "";
  200. $s .= "Setting: agent = '$this->agent'<br>";
  201. foreach ($this->parameters as $parm) {
  202. $s .= $parm->htmldump();
  203. }
  204. return $s;
  205. }
  206. } // setting class
  207. // ----------------------------------------------------------------------
  208.  
  209. /**
  210. * Class comprising the functionality of an application. This is used
  211. * to contain and manage the basic configuration properties of an
  212. * application. This class knows how to read the configuration in,
  213. * store the values, and write it out again.
  214. * @package core
  215. */
  216. class application extends xmlparser {
  217. /** Path to application configuration file */
  218.  
  219. var $configpath = "";
  220. /** State of processing */
  221.  
  222. var $state = "";
  223. /** Current/last tag opened */
  224.  
  225. var $tag = "";
  226. /** Attributes array for current/last tag */
  227.  
  228. var $attr = array();
  229. /** True if response was valid, ie. no errors */
  230.  
  231. var $valid = false;
  232. // .....................................................................
  233. // Application configuration..
  234. var $definitions = array();
  235. var $globals = array();
  236. var $settings = array();
  237. // .....................................................................
  238. /**
  239. * Construct a new application. Creating the application will also attempt
  240. * to read in the XML configuration file as specified (or defaulted). If
  241. * the file is read successfully, then the valid flag is set true.
  242. * @param string $configpath Path to XML configuration file for application
  243. */
  244. function application($configpath="application.xml") {
  245. $this->configpath = $configpath;
  246. $this->xmlparser();
  247. if (file_exists($this->configpath)) {
  248. $xmlfile = new inputfile($this->configpath);
  249. if ($xmlfile->opened) {
  250. $xmlfile->readall();
  251. $xmlfile->closefile();
  252. $this->parse($xmlfile->content);
  253. $this->valid = $this->valid_xml;
  254. }
  255. }
  256. }
  257. // .....................................................................
  258. /**
  259. * Make this current application object the same structure as the
  260. * given application. This process checks that the definitions, globals,
  261. * and settings of this application match those of the given one. If
  262. * a given item is missing, it is created. If an item is not present
  263. * in the given application, it is deleted in this one. Existing items
  264. * retain their current values - only structure is checked.
  265. * @param object $refapp The reference application to synchronize to
  266. * @return boolean True if changes were made, else false.
  267. */
  268. function synchronize($refapp) {
  269. if ($refapp->valid) {
  270. $synced = false;
  271. // Definitions..
  272. foreach ($refapp->definitions as $name => $val) {
  273. if (!isset($this->definitions[$name])) {
  274. $this->definitions[$name] = $val;
  275. $synced = true;
  276. }
  277. }
  278. foreach ($this->definitions as $name => $val) {
  279. if (!isset($refapp->definitions[$name])) {
  280. unset($this->definitions[$name]);
  281. $synced = true;
  282. }
  283. }
  284.  
  285. // Globals..
  286. foreach ($refapp->globals as $name => $val) {
  287. if (!isset($this->globals[$name])) {
  288. $this->globals[$name] = $val;
  289. $synced = true;
  290. }
  291. }
  292. foreach ($this->globals as $name => $val) {
  293. if (!isset($refapp->globals[$name])) {
  294. unset($this->globals[$name]);
  295. $synced = true;
  296. }
  297. }
  298.  
  299. // Settings..
  300. foreach ($refapp->settings as $ref_setting) {
  301. if ($ref_setting->name != "database") {
  302. if ($this->get_setting($ref_setting->name) === false) {
  303. $this->settings[] = $ref_setting;
  304. error_log("adding new setting $ref_setting->name");
  305. $synced = true;
  306. }
  307. }
  308. }
  309. $newsettings = array();
  310. for ($ix = 0; $ix < count($this->settings); $ix++) {
  311. $setting = $this->settings[$ix];
  312. if ($setting->name == "database") {
  313. $newsettings[] = $setting;
  314. }
  315. else {
  316. if ($setting->name != "") {
  317. if ($refapp->get_setting($setting->name) !== false) {
  318. $newsettings[] = $setting;
  319. }
  320. else {
  321. error_log("removing setting $setting->name");
  322. $synced = true;
  323. }
  324. }
  325. }
  326. }
  327. $this->settings = $newsettings;
  328. }
  329. return $synced;
  330. }
  331. // .....................................................................
  332. /**
  333. * Return setting by name. NB: some settings can have multiple entries
  334. * under the same name, eg. 'database'. In this case we return an
  335. * array of setting objects, otherwise the single setting object.
  336. * We return false if not found.
  337. * @param string $name Name of the setting(s) to return
  338. * @return mixed Single setting object, array of settings, or false
  339. */
  340. function get_setting($name) {
  341. $got = array();
  342. foreach ($this->settings as $setting) {
  343. if ($setting->name == $name) {
  344. $got[] = $setting;
  345. }
  346. }
  347. if (count($got) == 0) {
  348. return false;
  349. }
  350. elseif (count($got) == 1) {
  351. return $got[0];
  352. }
  353. else {
  354. return $got;
  355. }
  356. }
  357. // .....................................................................
  358. /**
  359. * Get the value of a named parameter from a named setting. This only
  360. * works for settings which are unique - ie. it won't work well for
  361. * parms which can occur multiple times, eg: 'database'. Option to
  362. * specify the element name for arrayed parameters.
  363. * @param string $name Name of the setting which contains the parameter
  364. * @param string $pname Name of the parameter to get value of
  365. * @param string $ename Name of element (arrayed parameters only)
  366. */
  367. function getparameter($name, $pname, $ename="") {
  368. $parm = "";
  369. if (isset($this->settings)) {
  370. if ($setting = $this->get_setting($name)) {
  371. $parm = $setting->getparameter($pname, $ename);
  372. }
  373. }
  374. return $parm;
  375. }
  376. // .....................................................................
  377. /**
  378. * Set the value of a named parameter for a named setting. Optionally
  379. * provide the element name for arrayed parameters.
  380. * @param mixed $value Value of the parameter setting
  381. * @param string $name Name of the setting which contains the parameter
  382. * @param string $pname Name of the parameter to get value of
  383. * @param string $ename Name of element (arrayed parameters only)
  384. */
  385. function setparameter($value, $name, $pname, $ename="") {
  386. $parm = "";
  387. if (isset($this->settings)) {
  388. $pix = -1;
  389. for ($ix = 0; $ix < count($this->settings); $ix++) {
  390. if ($this->settings[$ix]->name == $name) {
  391. $pix = $ix;
  392. break;
  393. }
  394. }
  395. if ($pix > -1) {
  396. $this->settings[$pix]->setparameter($pname, $value, $ename);
  397. }
  398. }
  399. return $parm;
  400. }
  401. // .....................................................................
  402. /**
  403. * Return dump of the application content as a string. Useful for
  404. * diagnostics mainly.
  405. * @return string Dump of the application content as html string.
  406. */
  407. function htmldump() {
  408. $s = "APPLICATION<br>";
  409. $s .= "Definitions:<br>";
  410. foreach ($this->definitions as $name => $val) {
  411. $s .= "$name = '$val'<br>";
  412. }
  413. $s .= "Globals:<br>";
  414. foreach ($this->globals as $name => $val) {
  415. $s .= "$name = '$val'<br>";
  416. }
  417. $s .= "Settings:<br>";
  418. foreach ($this->settings as $setting) {
  419. $s .= $setting->htmldump();
  420. }
  421. return $s;
  422. }
  423. // .....................................................................
  424. /**
  425. * Save the application as XML file back to the same filename it was
  426. * read in from, ie. after changes have been made. This generates
  427. * the whole file as fresh XML, and writes it out.
  428. */
  429. function save() {
  430. if ($this->valid) {
  431. $xmlfile = new outputfile($this->configpath);
  432. if ($xmlfile->opened) {
  433. $xml = new xmltag("application");
  434.  
  435. // DEFINITIONS
  436. $xmldefs = new xmltag("definitions");
  437. foreach ($this->definitions as $name => $val) {
  438. $xmldef = new xmltag("definition", $val);
  439. $xmldef->setattribute("name", $name);
  440. $xmldefs->childtag($xmldef);
  441. }
  442. $xml->childtag($xmldefs);
  443.  
  444. // GLOBALS
  445. $xmlglobs = new xmltag("globals");
  446. foreach ($this->globals as $name => $val) {
  447. $xmlglob = new xmltag("global", $val);
  448. $xmlglob->setattribute("name", $name);
  449. $xmlglobs->childtag($xmlglob);
  450. }
  451. $xml->childtag($xmlglobs);
  452.  
  453. // RESPONSE SETTINGS
  454. $xmlsettings = new xmltag("settings");
  455. foreach ($this->settings as $setting) {
  456. $xmlsetting = new xmltag("setting");
  457. $xmlsetting->setattribute("name", $setting->name);
  458. $xmlsetting->setattribute("agent", $setting->agent);
  459. foreach ($setting->parameters as $parameter) {
  460. $xmlparm = new xmltag("parameter");
  461. $xmlparm->setattribute("name", $parameter->name);
  462. $xmlparm->setattribute("type", $parameter->type);
  463. if ($parameter->type == "array") {
  464. if (is_array($parameter->value) && count($parameter->value) > 0) {
  465. foreach ($parameter->value as $ename => $evalue) {
  466. $xmlelem = new xmltag("element", $evalue);
  467. $xmlelem->setattribute("name", $ename);
  468. $xmlparm->childtag($xmlelem);
  469. }
  470. }
  471. }
  472. else {
  473. $xmlparm->value = $parameter->value;
  474. }
  475. $xmlsetting->childtag($xmlparm);
  476. }
  477. $xmlsettings->childtag($xmlsetting);
  478. }
  479. $xml->childtag($xmlsettings);
  480.  
  481. // Write the file content..
  482. $xmlfile->writeln( xmlheader() );
  483. $xmlfile->writeln("<!-- Axyl XML Configuration File - Please do not edit this file directly. -->");
  484. $xmlfile->writeln("<!-- The settings in this file determine how your application will run. -->");
  485. $xmlfile->writeln("<!-- Generation timestamp: " . timestamp_to_displaydate(NICE_FULLDATETIME, time()) . " -->");
  486. $xmlfile->write( $xml->render() );
  487. $xmlfile->closefile();
  488. } // if file opened
  489. } // if valid
  490. }
  491. // .....................................................................
  492. /** Method invoked when a tag is opened */
  493.  
  494. function tag_open($parser, $tag, $attributes) {
  495. $this->tag = $tag;
  496. if (is_array($attributes) && count($attributes) > 0) {
  497. foreach ($attributes as $key => $value ) {
  498. $this->attr[$key] = $value;
  499. }
  500. }
  501. switch ($this->tag) {
  502. case "definition":
  503. $this->definitions[ $this->attr["name"] ] = "";
  504. break;
  505. case "global":
  506. $this->globals[ $this->attr["name"] ] = "";
  507. break;
  508. case "setting":
  509. $this->setting = new setting( $this->attr["name"], $this->attr["agent"] );
  510. break;
  511. case "parameter":
  512. $this->parameter = new parameter( $this->attr["name"], $this->attr["type"] );
  513. break;
  514. } // switch
  515. }
  516. // .....................................................................
  517. /** Method invoked when character data is available */
  518.  
  519. function cdata($parser, $cdata) {
  520. switch ($this->tag) {
  521. case "definition":
  522. $this->definitions[ $this->attr["name"] ] = $cdata;
  523. break;
  524. case "global":
  525. $this->globals[ $this->attr["name"] ] = $cdata;
  526. break;
  527. case "parameter":
  528. if (isset($this->parameter) && $this->attr["type"] != "array") {
  529. $this->parameter->setvalue( $cdata, $this->attr["name"] );
  530. }
  531. break;
  532. case "element":
  533. if (isset($this->parameter)) {
  534. $this->parameter->setvalue( $cdata, $this->attr["name"] );
  535. }
  536. break;
  537. } // switch
  538. }
  539. // .....................................................................
  540. /** Method invoked when a tag is closed */
  541.  
  542. function tag_close($parser, $tag) {
  543. switch ($tag) {
  544. case "setting":
  545. $this->settings[] = $this->setting;
  546. unset($this->setting);
  547. break;
  548. case "parameter":
  549. if (isset($this->setting) && isset($this->parameter)) {
  550. $this->setting->addparameter($this->parameter->name, $this->parameter);
  551. unset($this->parameter);
  552. }
  553. break;
  554. } // switch
  555. $this->tag = "";
  556. $this->attr = array();
  557. }
  558. // .....................................................................
  559. /**
  560. * Parse the application XML which is provided.
  561. * @param string $xml The XML content to parse for the application.
  562. */
  563. function parse($xml) {
  564. xmlparser::parse($xml);
  565. if (!$this->valid_xml) {
  566. $this->valid = false;
  567. }
  568. }
  569.  
  570. } // application class
  571. // ----------------------------------------------------------------------
  572.  
  573. /**
  574. * Return the index of the given named setting, or -1 if not found.
  575. * @param object $app The application object to scan
  576. * @param string $settingname The name of the setting in $app
  577. * @return integer The index of the setting in $app
  578. */
  579. function get_settingindex($app, $settingname) {
  580. $theix = -1;
  581. for ($ix = 0; $ix < count($app->settings); $ix++) {
  582. $setting = $app->settings[$ix];
  583. if (is_object($setting)) {
  584. if ($setting->getparameter("name") == $settingname) {
  585. $theix = $ix;
  586. break;
  587. }
  588. }
  589. }
  590. return $theix;
  591. }
  592. // ----------------------------------------------------------------------
  593. ?>

Documentation generated by phpDocumentor 1.3.0RC3