commit a42ca771f59c691027c74078b1d8a0960ce79a0b
parent ba0ddd7f3dd1489ff1d257cc0483c97abaf6d5ce
Author: dankert <openrat@jandankert.de>
Date: Mon, 31 Jan 2022 00:00:48 +0100
Some documentation...
Diffstat:
10 files changed, 62 insertions(+), 56 deletions(-)
diff --git a/index.php b/index.php
@@ -1,14 +1,21 @@
<?php
-// Excecuting the CMS user interface (UI)
-require('modules/autoload.php');
+// Excecuting the CMS HTTP Endpoint
+// This is both for UI and API requests.
+
+
+require('modules/autoload.php'); // Autoloading all classes
use cms\base\Startup;
use cms\output\OutputFactory;
use cms\ui\UI;
+// - Validating the environment
+// - Initialize all constants
Startup::initialize();
+// Creates the output driver
+// Dependent on which data format is requested by the client.
$output = OutputFactory::createOutput();
-header('X-CMS-Output-Type: ' . get_class($output ) );
header('Content-Type: ' . $output->getContentType() . '; charset=' . Startup::CHARSET);
-$output->execute();
-\ No newline at end of file
+
+$output->execute(); // Outputs the data.
+\ No newline at end of file
diff --git a/modules/cms/output/BaseOutput.class.php b/modules/cms/output/BaseOutput.class.php
@@ -34,15 +34,16 @@ abstract class BaseOutput implements Output
{
$request = new RequestParams();
- $this->beforeAction( $request );
+ try {
+ $this->beforeAction( $request );
- $dispatcher = new Dispatcher();
- $dispatcher->request = $request;
+ $dispatcher = new Dispatcher();
+ $dispatcher->request = $request;
- try {
- $data = $dispatcher->doAction();
+ $data = $dispatcher->doAction(); // calling the action ...
+
+ $this->outputData( $request,$data ); // ... and output the data
- $this->outputData( $request,$data );
} catch (BadMethodCallException $e) {
// Action-Method does not exist.
Logger::debug( $e );
@@ -67,17 +68,23 @@ abstract class BaseOutput implements Output
}
}
+
+ /**
+ * This method is executed before the dispatcher is called.
+ * Subclasses may override this to prepare the response.
+ * @param $request RequestParams
+ * @return void
+ */
protected function beforeAction( $request )
{
}
+ /**
+ * Is called if an error is thrown.
+ *
+ * @param $text string a message
+ * @param $cause Exception
+ */
abstract protected function setError($text, $cause);
-
-
- protected function setStatus( $status, $text )
- {
- header('HTTP/1.0 ' . intval($status) . ' ' . $text);
- }
-
}
\ No newline at end of file
diff --git a/modules/cms/output/HtmlOutput.class.php b/modules/cms/output/HtmlOutput.class.php
@@ -20,12 +20,12 @@ use util\text\TextMessage;
/**
- * Executing the Openrat CMS User Interface.
+ * The HTML output is calling a template for the user interface.
*/
class HtmlOutput extends BaseOutput
{
/**
- * Shows the complete UI.
+ * Preparing the client...
*/
protected function beforeAction($request)
{
@@ -40,7 +40,7 @@ class HtmlOutput extends BaseOutput
}
if ( $request->isAction )
- throw new \RuntimeException('The UI does not accept POST requests');
+ throw new \RuntimeException('The HTML output driver does not accept POST requests');
if ( in_array( $request->action,['index','tree','title','usergroup']) )
$request->isUIAction = true;
diff --git a/modules/cms/output/HtmlPlainOutput.class.php b/modules/cms/output/HtmlPlainOutput.class.php
@@ -1,29 +0,0 @@
-<?php
-
-namespace cms\output;
-
-use cms\output\APIOutput;
-use util\json\JSON;
-
-/**
- * JSON Rendering.
- */
-class HtmlPlainOutput extends APIOutput
-{
- /**
- * Renders the output in JSON Format.
- */
- protected function renderOutput( $data )
- {
- $output = '<html><body><h1>API response:</h1><hr /><pre>';
- $output .= print_r($data,true);
- $output .= '</pre></body></html>';
-
- return $output;
- }
-
- public function getContentType()
- {
- return 'text/html';
- }
-}
diff --git a/modules/cms/output/Output.class.php b/modules/cms/output/Output.class.php
@@ -29,5 +29,10 @@ interface Output
*/
public function execute();
+ /**
+ * Gets the content type.
+ *
+ * @return string
+ */
public function getContentType();
}
diff --git a/modules/cms/output/OutputFactory.class.php b/modules/cms/output/OutputFactory.class.php
@@ -39,17 +39,24 @@ class OutputFactory {
'text/html' => self::OUTPUT_HTML,
];
+
+ /**
+ * Creates the output driver.
+ *
+ * Dependent on the HTTP request a output driver will be selected.
+ *
+ * @return Output
+ */
public static function createOutput() {
switch ( self::discoverOutputType() ) {
+
case self::OUTPUT_PHPARRAY:
return new PHPArrayOutput();
case self::OUTPUT_PHPSERIALIZE:
return new PHPSerializeOutput();
case self::OUTPUT_JSON:
return new JsonOutput();
- // case self::
- // return new HtmlPlainOutput();
case self::OUTPUT_XML:
return new XmlOutput();
case self::OUTPUT_YAML:
@@ -77,7 +84,7 @@ class OutputFactory {
if ( $reqOutput && array_key_exists( $reqOutput, self::MAP_OUTPUT ) )
return self::MAP_OUTPUT[ $reqOutput ];
- // Try 2: Lets check the HTTP request headers
+ // Try 2: Lets check the HTTP request "Accept" header.
foreach( Http::getAccept() as $acceptType )
if ( array_key_exists( $acceptType, self::MAP_ACCEPT ) )
return self::MAP_ACCEPT[ $acceptType ];
diff --git a/modules/cms/output/PHPArrayOutput.class.php b/modules/cms/output/PHPArrayOutput.class.php
@@ -6,7 +6,7 @@ use cms\output\APIOutput;
use util\json\JSON;
/**
- * JSON Rendering.
+ * Rendering as PHP array.
*/
class PHPArrayOutput extends APIOutput
{
diff --git a/modules/cms/output/PHPSerializeOutput.class.php b/modules/cms/output/PHPSerializeOutput.class.php
@@ -6,7 +6,8 @@ use cms\output\APIOutput;
use util\json\JSON;
/**
- * JSON Rendering.
+ * Renders as a internal serialized PHP array.
+ * A PHP powered client may simply unserialize it.
*/
class PHPSerializeOutput extends APIOutput
{
diff --git a/modules/cms/output/README.md b/modules/cms/output/README.md
@@ -0,0 +1,7 @@
+# Output drivers
+
+The created data must be send to the client.
+
+The data must be formatted in a pleasant way.
+
+The Output drivers take the data and render them.
+\ No newline at end of file
diff --git a/modules/cms/output/XmlOutput.class.php b/modules/cms/output/XmlOutput.class.php
@@ -7,7 +7,7 @@ use util\json\JSON;
use util\XML;
/**
- * JSON Rendering.
+ * XML Rendering.
*/
class XmlOutput extends APIOutput
{
