From 4f8d8173651e3ed2a9977b546c567bcba62a84cd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ste=CC=81phane=20Goetz?= Date: Fri, 17 Jul 2015 23:38:06 +0200 Subject: [PATCH] Code Style and documentation --- libs/Config.php | 23 +++- libs/Daux.php | 11 +- libs/DauxHelper.php | 67 +++++---- .../Base/CommonMark/CommonMarkConverter.php | 2 +- libs/Format/Base/CommonMark/LinkRenderer.php | 6 +- libs/Format/Confluence/Api.php | 111 +++++++-------- .../CommonMark/IndentedCodeRenderer.php | 2 +- .../Confluence/CommonMark/LinkRenderer.php | 2 +- libs/Format/Confluence/MarkdownPage.php | 4 +- libs/Format/Confluence/Publisher.php | 13 +- libs/Format/HTML/Generator.php | 13 +- libs/Format/HTML/MarkdownPage.php | 2 +- libs/Format/HTML/Template.php | 17 ++- libs/Generator/Command.php | 11 +- libs/Generator/Helper.php | 37 +++-- libs/Processor.php | 19 +++ libs/Server/ErrorPage.php | 17 ++- libs/Server/Server.php | 30 +++- libs/Tree/Builder.php | 25 +++- libs/Tree/Content.php | 43 ++++-- libs/Tree/Entry.php | 129 ++++++++++++++---- templates/content.php | 8 +- 22 files changed, 415 insertions(+), 177 deletions(-) diff --git a/libs/Config.php b/libs/Config.php index a32aabb..9e26872 100644 --- a/libs/Config.php +++ b/libs/Config.php @@ -2,11 +2,18 @@ use ArrayObject; -class Config extends ArrayObject { - - public function merge($newValues, $override = true) { +class Config extends ArrayObject +{ + /** + * Merge an array into the object + * + * @param array $newValues + * @param bool $override + */ + public function merge($newValues, $override = true) + { foreach ($newValues as $key => $value) { - if (array_key_exists($key, $this) && $override == false) { + if ($override === false && array_key_exists($key, $this)) { continue; } @@ -14,7 +21,13 @@ class Config extends ArrayObject { } } - public function conservativeMerge($newValues) { + /** + * Merge an array into the object, ignore already added keys. + * + * @param $newValues + */ + public function conservativeMerge($newValues) + { $this->merge($newValues, false); } } diff --git a/libs/Daux.php b/libs/Daux.php index f48151c..4d578bc 100644 --- a/libs/Daux.php +++ b/libs/Daux.php @@ -19,9 +19,10 @@ class Daux protected $processor; /** - * @var Tree\Entry + * @var Tree\Directory */ public $tree; + /** * @var Config */ @@ -84,6 +85,14 @@ class Daux $this->options->merge($default_config); } + /** + * Load the configuration files, first, "config.json" + * in the documentation and then the file specified + * when running the configuration + * + * @param string $override_file + * @throws Exception + */ private function loadConfigOverrides($override_file) { // Read documentation overrides diff --git a/libs/DauxHelper.php b/libs/DauxHelper.php index cd04c24..6b6d0eb 100644 --- a/libs/DauxHelper.php +++ b/libs/DauxHelper.php @@ -4,6 +4,11 @@ use Todaymade\Daux\Tree\Directory; class DauxHelper { + /** + * @param Config $params + * @param string $current_url + * @return array + */ public static function getTheme($params, $current_url) { $theme_folder = $params['local_base'] . DS . 'resources' . DS . 'themes' . DS . $params['theme-name']; @@ -39,21 +44,19 @@ class DauxHelper $theme['templates'] = strtr($theme['templates'], $substitutions); $theme['favicon'] = utf8_encode(strtr($theme['favicon'], $substitutions)); - foreach ($theme['css'] as $key => $css) { - $theme['css'][$key] = utf8_encode(strtr($css, $substitutions)); - } - - foreach ($theme['fonts'] as $key => $font) { - $theme['fonts'][$key] = utf8_encode(strtr($font, $substitutions)); - } - - foreach ($theme['js'] as $key => $js) { - $theme['js'][$key] = utf8_encode(strtr($js, $substitutions)); + foreach (['css', 'js', 'fonts'] as $element) { + foreach ($theme[$element] as $key => $value) { + $theme[$element][$key] = utf8_encode(strtr($value, $substitutions)); + } } return $theme; } + /** + * @param string $path + * @return string + */ public static function getCleanPath($path) { $path = str_replace(array('/', '\\'), DIRECTORY_SEPARATOR, $path); @@ -72,24 +75,31 @@ class DauxHelper return implode(DIRECTORY_SEPARATOR, $absolutes); } + /** + * Get pathinfo for a file + * + * @param string $path + * @return array + */ public static function pathinfo($path) { preg_match('%^(.*?)[\\\\/]*(([^/\\\\]*?)(\.([^\.\\\\/]+?)|))[\\\\/\.]*$%im', $path, $m); - if (isset($m[1])) { - $ret['dir']=$m[1]; - } - if (isset($m[2])) { - $ret['basename']=$m[2]; - } - if (isset($m[5])) { - $ret['extension']=$m[5]; - } - if (isset($m[3])) { - $ret['filename']=$m[3]; + $ret = []; + foreach (['dir' => 1, 'basename' => 2, 'filename' => 3, 'extension' => 5] as $key => $group) { + if (isset($m[$group])) { + $ret[$key] = $m[$group]; + } } return $ret; } + /** + * Locate a file in the tree. Returns the file if found or false + * + * @param Directory $tree + * @param string $request + * @return Tree\Entry|false + */ public static function getFile($tree, $request) { $request = explode('/', $request); @@ -148,11 +158,14 @@ class DauxHelper $separator = '_'; // Convert all dashes into underscores - $title = preg_replace('!['.preg_quote("-").']+!u', $separator, $title); + $title = preg_replace('![' . preg_quote("-") . ']+!u', $separator, $title); + // Remove all characters that are not the separator, letters, numbers, or whitespace. - $title = preg_replace('![^'.preg_quote($separator).'\pL\pN\s]+!u', '', $title); + $title = preg_replace('![^' . preg_quote($separator) . '\pL\pN\s]+!u', '', $title); + // Replace all separator characters and whitespace by a single separator - $title = preg_replace('!['.preg_quote($separator).'\s]+!u', $separator, $title); + $title = preg_replace('![' . preg_quote($separator) . '\s]+!u', $separator, $title); + return trim($title, $separator); } @@ -167,7 +180,9 @@ class DauxHelper { static $charsArray; - if (isset($charsArray)) return $charsArray; + if (isset($charsArray)) { + return $charsArray; + } return $charsArray = array( 'a' => array( @@ -238,7 +253,7 @@ class DauxHelper 'Ἇ', 'ᾈ', 'ᾉ', 'ᾊ', 'ᾋ', 'ᾌ', 'ᾍ', 'ᾎ', 'ᾏ', 'Ᾰ', 'Ᾱ', 'Ὰ', 'Ά', 'ᾼ', 'А'), 'B' => array('Б', 'Β'), - 'C' => array('Ç','Ć', 'Č', 'Ĉ', 'Ċ'), + 'C' => array('Ç', 'Ć', 'Č', 'Ĉ', 'Ċ'), 'D' => array('Ď', 'Ð', 'Đ', 'Ɖ', 'Ɗ', 'Ƌ', 'ᴅ', 'ᴆ', 'Д', 'Δ'), 'E' => array('É', 'È', 'Ẻ', 'Ẽ', 'Ẹ', 'Ê', 'Ế', 'Ề', 'Ể', 'Ễ', 'Ệ', 'Ë', 'Ē', 'Ę', 'Ě', 'Ĕ', 'Ė', 'Ε', 'Έ', 'Ἐ', diff --git a/libs/Format/Base/CommonMark/CommonMarkConverter.php b/libs/Format/Base/CommonMark/CommonMarkConverter.php index 41c4d9f..b918c4c 100644 --- a/libs/Format/Base/CommonMark/CommonMarkConverter.php +++ b/libs/Format/Base/CommonMark/CommonMarkConverter.php @@ -27,7 +27,7 @@ class CommonMarkConverter extends \League\CommonMark\CommonMarkConverter protected function getLinkRenderer(Environment $environment) { - return new LinkRenderer($environment->getConfig('daux')); + return new LinkRenderer($environment->getConfig('daux')); } protected function extendEnvironment(Environment $environment) diff --git a/libs/Format/Base/CommonMark/LinkRenderer.php b/libs/Format/Base/CommonMark/LinkRenderer.php index 26e75c4..3411dfd 100644 --- a/libs/Format/Base/CommonMark/LinkRenderer.php +++ b/libs/Format/Base/CommonMark/LinkRenderer.php @@ -22,12 +22,12 @@ class LinkRenderer extends \League\CommonMark\Inline\Renderer\LinkRenderer } /** - * @param $url + * @param string $url * @return Entry * @throws Exception */ - protected function resolveInternalFile($url) { - + protected function resolveInternalFile($url) + { $file = DauxHelper::getFile($this->daux['tree'], $url); if ($file) { return $file; diff --git a/libs/Format/Confluence/Api.php b/libs/Format/Confluence/Api.php index 23309df..54347af 100644 --- a/libs/Format/Confluence/Api.php +++ b/libs/Format/Confluence/Api.php @@ -3,11 +3,9 @@ use GuzzleHttp\Client; use GuzzleHttp\Exception\BadResponseException; use GuzzleHttp\Exception\ParseException; -use GuzzleHttp\Exception\TransferException; class Api { - protected $base_url; protected $user; protected $pass; @@ -75,61 +73,24 @@ class Api } /** - * /rest/api/content/{id}/child/{type} + * Get a list of pages * - * @param $rootPage - * @return mixed + * @param integer $rootPage + * @param bool $recursive + * @return array */ - public function getList($rootPage) + public function getList($rootPage, $recursive = false) { - //We do a limit of 15 as it appears that confluence has - //a bug when retrieving more than 20 entries with "body.storage" - $url = "content/$rootPage/child/page?expand=version,body.storage&limit=15"; + $increment = 15; + + // We set a limit of 15 as it appears that + // Confluence fails silently when retrieving + // more than 20 entries with "body.storage" + $base_url = $url = "content/$rootPage/child/page?expand=version,body.storage&limit=$increment"; + $start = 0; $pages = []; - do { - try { - $list = $this->getClient()->get($url)->json(); - } catch (BadResponseException $e) { - throw $this->handleError($e); - } - - foreach ($list['results'] as $result) { - $pages[$result['title']] = [ - "id" => $result['id'], - "title" => $result['title'], - "version" => $result['version']['number'], - "content" => $result['body']['storage']['value'], - ]; - } - - if (array_key_exists('next', $list['_links'])) { - $url = $list['_links']['next']; - } - - } while (array_key_exists('next', $list['_links'])); - - return $pages; - } - - /** - * /rest/api/content/{id}/child/{type} - * - * @param $rootPage - * @return mixed - */ - public function getHierarchy($rootPage) - { - $increment = 15; - - //We do a limit of 15 as it appears that confluence has - //a bug when retrieving more than 20 entries with "body.storage" - $base_url = $url = "content/$rootPage/child/page?expand=version,body.storage&limit=$increment"; - $start = 0; - - $children = []; - do { try { $hierarchy = $this->getClient()->get($url)->json(); @@ -138,24 +99,35 @@ class Api } foreach ($hierarchy['results'] as $result) { - $children[$result['title']] = [ + $pages[$result['title']] = [ "id" => $result['id'], "title" => $result['title'], "version" => $result['version']['number'], "content" => $result['body']['storage']['value'], - "children" => $this->getHierarchy($result['id']) ]; + + if ($recursive) { + $pages[$result['title']]['children'] = $this->getList($result['id'], true); + } } - - //We don't use _links->next as after ~30 elements it doesn't show any new elements - $start += $increment; - $url = "$base_url&start=$start"; + + // We don't use _links->next as after ~30 elements + // it doesn't show any new elements. This seems + // to be a bug in Confluence + $start += $increment; + $url = "$base_url&start=$start"; } while (!empty($hierarchy['results'])); - return $children; + return $pages; } + /** + * @param integer $parent_id + * @param string $title + * @param string $content + * @return integer + */ public function createPage($parent_id, $title, $content) { $body = [ @@ -167,7 +139,7 @@ class Api ]; try { - $response = $this->getClient()->post('content', [ 'json' => $body ])->json(); + $response = $this->getClient()->post('content', ['json' => $body])->json(); } catch (BadResponseException $e) { throw $this->handleError($e); } @@ -175,6 +147,13 @@ class Api return $response['id']; } + /** + * @param integer $parent_id + * @param integer $page_id + * @param integer $newVersion + * @param string $title + * @param string $content + */ public function updatePage($parent_id, $page_id, $newVersion, $title, $content) { $body = [ @@ -193,6 +172,12 @@ class Api } } + /** + * Delete a page + * + * @param integer $page_id + * @return mixed + */ public function deletePage($page_id) { try { @@ -202,6 +187,10 @@ class Api } } + /** + * @param integer $id + * @param array $attachment + */ public function uploadAttachment($id, $attachment) { //get if attachment is uploaded @@ -211,13 +200,13 @@ class Api throw $this->handleError($e); } - $url = "content/$id/child/attachment" . (count($result['results'])? "/{$result['results'][0]['id']}/data" : ""); + $url = "content/$id/child/attachment" . count($result['results']) ? "/{$result['results'][0]['id']}/data" : ""; try { $this->getClient()->post( $url, [ - 'body' => ['file' => fopen($attachment['file']->getPath(), 'r')] , + 'body' => ['file' => fopen($attachment['file']->getPath(), 'r')], 'headers' => ['X-Atlassian-Token' => 'nocheck'], ] ); diff --git a/libs/Format/Confluence/CommonMark/IndentedCodeRenderer.php b/libs/Format/Confluence/CommonMark/IndentedCodeRenderer.php index 87a2244..a63d9ac 100644 --- a/libs/Format/Confluence/CommonMark/IndentedCodeRenderer.php +++ b/libs/Format/Confluence/CommonMark/IndentedCodeRenderer.php @@ -24,7 +24,7 @@ class IndentedCodeRenderer implements BlockRendererInterface return new HtmlElement( 'ac:structured-macro', ['ac:name' => 'code'], - new HtmlElement('ac:plain-text-body', [], 'getStringContent().']]>') + new HtmlElement('ac:plain-text-body', [], 'getStringContent() . ']]>') ); } } diff --git a/libs/Format/Confluence/CommonMark/LinkRenderer.php b/libs/Format/Confluence/CommonMark/LinkRenderer.php index 2e1371d..2ae066f 100644 --- a/libs/Format/Confluence/CommonMark/LinkRenderer.php +++ b/libs/Format/Confluence/CommonMark/LinkRenderer.php @@ -30,7 +30,7 @@ class LinkRenderer extends \Todaymade\Daux\Format\Base\CommonMark\LinkRenderer 'ri:space-key' => $this->daux['confluence']['space_id'] ]; - $page = strval(new HtmlElement('ri:page', $link_props, '', true)); + $page = strval(new HtmlElement('ri:page', $link_props, '', true)); $children = $htmlRenderer->renderInlines($inline->getChildren()); if (strpos($children, "<") !== false) { $children = '' . $children . ''; diff --git a/libs/Format/Confluence/MarkdownPage.php b/libs/Format/Confluence/MarkdownPage.php index 93bb4a2..e8b1d5f 100644 --- a/libs/Format/Confluence/MarkdownPage.php +++ b/libs/Format/Confluence/MarkdownPage.php @@ -21,7 +21,7 @@ class MarkdownPage extends \Todaymade\Daux\Format\Base\MarkdownPage // We do it after generation so we can catch the images that were in html already $page = preg_replace_callback( "/]*src=['\"]([^\"]*)['\"][^>]*>/", - function ($matches) { + function($matches) { if ($result = $this->findImage($matches[1], $matches[0])) { return $result; @@ -84,7 +84,7 @@ class MarkdownPage extends \Todaymade\Daux\Format\Base\MarkdownPage $img = " $value) { - $img .= ' ac:' . $name.'="'.htmlentities($value, ENT_QUOTES, 'UTF-8', false).'"'; + $img .= ' ac:' . $name . '="' . htmlentities($value, ENT_QUOTES, 'UTF-8', false) . '"'; } $img .= ">"; diff --git a/libs/Format/Confluence/Publisher.php b/libs/Format/Confluence/Publisher.php index 332f459..7851aae 100644 --- a/libs/Format/Confluence/Publisher.php +++ b/libs/Format/Confluence/Publisher.php @@ -45,11 +45,12 @@ class Publisher $this->client->setSpace($confluence['space_id']); } - public function run($title, $closure) { + public function run($title, $closure) + { try { return $this->runAction($title, $this->output, $this->width, $closure); } catch (BadResponseException $e) { - $this->output->writeLn(" " . $e->getMessage() . ""); + $this->output->writeLn(" " . $e->getMessage() . ""); } } @@ -69,7 +70,7 @@ class Publisher "Getting already published pages...", function() use (&$published) { if ($published != null) { - $published['children'] = $this->client->getHierarchy($published['id']); + $published['children'] = $this->client->getList($published['id'], true); } } ); @@ -149,7 +150,7 @@ class Publisher protected function createRecursive($parent_id, $entry, $published) { - $callback = function ($parent_id, $entry, $published) { + $callback = function($parent_id, $entry, $published) { //TODO :: remove deleted pages @@ -173,7 +174,7 @@ class Publisher protected function updateRecursive($parent_id, $entry, $published) { - $callback = function ($parent_id, $entry, $published) { + $callback = function($parent_id, $entry, $published) { if (array_key_exists('id', $published) && array_key_exists('page', $entry)) { $this->updatePage($parent_id, $entry, $published); } @@ -246,7 +247,7 @@ class Publisher foreach ($entry['page']->attachments as $attachment) { $this->run( " With attachment: $attachment[filename]", - function() use($published, $attachment) { + function() use ($published, $attachment) { $this->client->uploadAttachment($published['id'], $attachment); } ); diff --git a/libs/Format/HTML/Generator.php b/libs/Format/HTML/Generator.php index 3f41f84..14854ac 100644 --- a/libs/Format/HTML/Generator.php +++ b/libs/Format/HTML/Generator.php @@ -32,6 +32,17 @@ class Generator $this->generateRecursive($daux->tree, $destination, $params, $output, $width); } + /** + * Recursively generate the documentation + * + * @param \Todaymade\Daux\Tree\Entry $tree + * @param string $output_dir + * @param \Todaymade\Daux\Config $params + * @param OutputInterface $output + * @param integer $width + * @param string $base_url + * @throws \Exception + */ private function generateRecursive($tree, $output_dir, $params, $output, $width, $base_url = '') { $params['base_url'] = $params['base_page'] = $base_url; @@ -46,7 +57,7 @@ class Generator foreach ($tree->value as $key => $node) { if ($node instanceof Directory) { $new_output_dir = $output_dir . DS . $key; - @mkdir($new_output_dir); + mkdir($new_output_dir); $this->generateRecursive($node, $new_output_dir, $params, $output, $width, '../' . $base_url); } elseif ($node instanceof Content) { $this->runAction( diff --git a/libs/Format/HTML/MarkdownPage.php b/libs/Format/HTML/MarkdownPage.php index f96608e..5d4150c 100644 --- a/libs/Format/HTML/MarkdownPage.php +++ b/libs/Format/HTML/MarkdownPage.php @@ -79,6 +79,6 @@ class MarkdownPage extends \Todaymade\Daux\Format\Base\MarkdownPage } $template = new Template($params['templates'], $params['theme']['templates']); - return $template->render($this->homepage? 'home' : 'content', ['page' => $page, 'params' => $params]); + return $template->render($this->homepage ? 'home' : 'content', ['page' => $page, 'params' => $params]); } } diff --git a/libs/Format/HTML/Template.php b/libs/Format/HTML/Template.php index a150729..501c3a5 100644 --- a/libs/Format/HTML/Template.php +++ b/libs/Format/HTML/Template.php @@ -7,6 +7,10 @@ class Template { protected $engine; + /** + * @param string $base + * @param string $theme + */ public function __construct($base, $theme) { // Create new Plates instance @@ -19,6 +23,11 @@ class Template $this->registerFunctions(); } + /** + * @param string $name + * @param array $data + * @return string + */ public function render($name, array $data = array()) { $this->engine->addData([ @@ -94,7 +103,7 @@ class Template $nav[] = [ 'title' => $node->getTitle(), 'href' => $base_page . $link, - 'class' => ($current_url === $link)? 'active' : '' + 'class' => ($current_url === $link) ? 'active' : '' ]; } if ($node instanceof \Todaymade\Daux\Tree\Directory) { @@ -102,7 +111,7 @@ class Template $folder = [ 'title' => $node->getTitle(), - 'class' => (strpos($current_url, $link) === 0)? 'open' : '', + 'class' => (strpos($current_url, $link) === 0) ? 'open' : '', ]; if ($mode === Daux::STATIC_MODE) { @@ -123,6 +132,10 @@ class Template return $nav; } + /** + * @param string $separator + * @return string + */ private function getSeparator($separator) { switch ($separator) { diff --git a/libs/Generator/Command.php b/libs/Generator/Command.php index 0bca99d..a18636e 100644 --- a/libs/Generator/Command.php +++ b/libs/Generator/Command.php @@ -4,7 +4,6 @@ use Symfony\Component\Console\Command\Command as SymfonyCommand; use Symfony\Component\Console\Input\InputArgument; use Symfony\Component\Console\Input\InputInterface; use Symfony\Component\Console\Output\OutputInterface; - use Todaymade\Daux\Daux; use Todaymade\Daux\Format\HTML\Generator as HTMLGenerator; use Todaymade\Daux\Format\Confluence\Generator as ConfluenceGenerator; @@ -31,20 +30,20 @@ class Command extends SymfonyCommand $width = $this->getApplication()->getTerminalDimensions()[0]; - $processor = $input->getOption('processor'); - if (!empty($processor) && $processor != 'none') { + $processor = $input->getOption('processor'); + if (!empty($processor) && $processor != 'none') { $class = "\\Todaymade\\Daux\\Extension\\" . $processor; if (class_exists($class)) { $daux->setProcessor(new $class($daux, $output, $width)); - } else if (file_exists($processor)) { + } elseif (file_exists($processor)) { include $processor; } - } + } // Improve the tree with a processor $daux->getProcessor()->manipulateTree($daux->tree); - switch(strtolower($input->getOption('format'))) { + switch (strtolower($input->getOption('format'))) { case 'confluence': (new ConfluenceGenerator())->generate($daux, $output, $width); break; diff --git a/libs/Generator/Helper.php b/libs/Generator/Helper.php index fbc91ae..5161f26 100644 --- a/libs/Generator/Helper.php +++ b/libs/Generator/Helper.php @@ -2,15 +2,26 @@ class Helper { + /** + * Copy all files from $path to $local_base + * + * @param string $path + * @param string $local_base + */ public static function copyAssets($path, $local_base) { - @mkdir($path); + mkdir($path); static::rmdir($path); - @mkdir($path . DS . 'resources'); + mkdir($path . DS . 'resources'); static::copyRecursive($local_base . DS . 'resources', $path . DS . 'resources'); } + /** + * Remove a directory recursively + * + * @param string $dir + */ private static function rmdir($dir) { $it = new \RecursiveDirectoryIterator($dir); @@ -27,16 +38,22 @@ class Helper } } - private static function copyRecursive($src, $dst) + /** + * Copy files recursively + * + * @param string $source + * @param string $destination + */ + private static function copyRecursive($source, $destination) { - $dir = opendir($src); - @mkdir($dst); - while (false !== ( $file = readdir($dir))) { - if (( $file != '.' ) && ( $file != '..' )) { - if (is_dir($src . '/' . $file)) { - static::copyRecursive($src . '/' . $file, $dst . '/' . $file); + $dir = opendir($source); + mkdir($destination); + while (false !== ($file = readdir($dir))) { + if ($file != '.' && $file != '..') { + if (is_dir($source . '/' . $file)) { + static::copyRecursive($source . '/' . $file, $destination . '/' . $file); } else { - copy($src . '/' . $file, $dst . '/' . $file); + copy($source . '/' . $file, $destination . '/' . $file); } } } diff --git a/libs/Processor.php b/libs/Processor.php index 1005f32..b5cd2b0 100644 --- a/libs/Processor.php +++ b/libs/Processor.php @@ -21,6 +21,11 @@ class Processor */ protected $width; + /** + * @param Daux $daux + * @param OutputInterface $output + * @param integer $width + */ public function __construct(Daux $daux, OutputInterface $output, $width) { $this->daux = $daux; @@ -28,10 +33,24 @@ class Processor $this->width = $width; } + /** + * With this connection point, you can transform + * the tree as you want, move pages, modify + * pages and even add new ones. + * + * @param Directory $root + */ public function manipulateTree(Directory $root) { } + /** + * This connection point provides + * a way to extend the Markdown + * parser and renderer. + * + * @param Environment $environment + */ public function extendCommonMarkEnvironment(Environment $environment) { } diff --git a/libs/Server/ErrorPage.php b/libs/Server/ErrorPage.php index bf1ef15..74439a9 100644 --- a/libs/Server/ErrorPage.php +++ b/libs/Server/ErrorPage.php @@ -9,19 +9,32 @@ class ErrorPage extends SimplePage const MISSING_PAGE_ERROR_TYPE = 'MISSING_PAGE_ERROR'; const FATAL_ERROR_TYPE = 'FATAL_ERROR'; + /** + * @var \Todaymade\Daux\Config + */ private $params; + /** + * @param string $title + * @param string $content + * @param \Todaymade\Daux\Config $params + */ public function __construct($title, $content, $params) { parent::__construct($title, $content); $this->params = $params; } + /** + * @return string + */ protected function generatePage() { $params = $this->params; - $page['title'] = $this->title; - $page['content'] = $this->content; + $page = [ + 'title' => $this->title, + 'content' => $this->content, + ]; $template = new Template($params['templates'], $params['theme']['templates']); return $template->render('error', ['page' => $page, 'params' => $params]); diff --git a/libs/Server/Server.php b/libs/Server/Server.php index e3c15ed..2740339 100644 --- a/libs/Server/Server.php +++ b/libs/Server/Server.php @@ -6,7 +6,6 @@ use Todaymade\Daux\Exception; use Todaymade\Daux\Format\HTML\MarkdownPage; use Todaymade\Daux\Format\HTML\RawPage; use Todaymade\Daux\Format\HTML\SimplePage; -use Todaymade\Daux\Tree\Directory; use Todaymade\Daux\Tree\Raw; class Server @@ -16,6 +15,11 @@ class Server private $host; private $base_url; + /** + * Serve the documentation + * + * @throws Exception + */ public static function serve() { $daux = new Daux(Daux::LIVE_MODE); @@ -63,6 +67,9 @@ class Server } } + /** + * @return \Todaymade\Daux\Config + */ public function getParams() { $params = $this->daux->getParams(); @@ -83,6 +90,14 @@ class Server return $params; } + /** + * Handle an incoming request + * + * @param array $query + * @return \Todaymade\Daux\Tree\Entry + * @throws Exception + * @throws NotFoundException + */ public function handle($query = []) { $this->params = $this->getParams(); @@ -108,6 +123,14 @@ class Server } } + /** + * @param string $request + * @param string $content + * @return SimplePage + * + * @throws Exception + * @throws NotFoundException + */ private function saveFile($request, $content) { $file = $this->getFile($request); @@ -123,6 +146,11 @@ class Server return new SimplePage('Success', 'Successfully Edited'); } + /** + * @param string $request + * @return \Todaymade\Daux\Tree\Entry + * @throws NotFoundException + */ private function getPage($request) { $file = DauxHelper::getFile($this->daux->tree, $request); diff --git a/libs/Tree/Builder.php b/libs/Tree/Builder.php index cc5636f..c4657f8 100644 --- a/libs/Tree/Builder.php +++ b/libs/Tree/Builder.php @@ -5,6 +5,15 @@ use Todaymade\Daux\DauxHelper; class Builder { + /** + * Build the initial tree + * + * @param string $dir + * @param array $ignore + * @param \Todaymade\Daux\Config $params + * @param array $parents + * @return Directory|void + */ public static function build($dir, $ignore, $params, $parents = null) { if (!$dh = opendir($dir)) { @@ -62,7 +71,13 @@ class Builder return $node; } - public static function getOrCreateDir($parent, $title) { + /** + * @param Entry $parent + * @param String $title + * @return Directory + */ + public static function getOrCreateDir($parent, $title) + { $slug = DauxHelper::slug($title); if (array_key_exists($slug, $parent->value)) { @@ -77,7 +92,13 @@ class Builder return $dir; } - public static function getOrCreatePage($parents, $title) { + /** + * @param array $parents + * @param string $title + * @return Content + */ + public static function getOrCreatePage($parents, $title) + { $slug = DauxHelper::slug($title); $uri = $slug . ".html"; diff --git a/libs/Tree/Content.php b/libs/Tree/Content.php index b28ad53..fc73b19 100644 --- a/libs/Tree/Content.php +++ b/libs/Tree/Content.php @@ -4,7 +4,10 @@ use Todaymade\Daux\DauxHelper; class Content extends Entry { - protected $content; + /** + * @var string + */ + protected $content; public function __construct($path = '', $parents = array()) { @@ -12,21 +15,31 @@ class Content extends Entry $this->value = $this->uri; } - - public function getContent() - { - if (!$this->content) { - $this->content = file_get_contents($this->getPath()); - } - - return $this->content; - } - - public function setContent($content) - { - $this->content = $content; - } + /** + * @return string + */ + public function getContent() + { + if (!$this->content) { + $this->content = file_get_contents($this->getPath()); + } + + return $this->content; + } + + /** + * @param string $content + */ + public function setContent($content) + { + $this->content = $content; + } + + /** + * @param string $file + * @return string + */ protected function getFilename($file) { return DauxHelper::pathinfo($file)['filename']; diff --git a/libs/Tree/Entry.php b/libs/Tree/Entry.php index cf47ed5..9815adf 100644 --- a/libs/Tree/Entry.php +++ b/libs/Tree/Entry.php @@ -4,53 +4,90 @@ use Todaymade\Daux\DauxHelper; abstract class Entry { + /** @var string */ protected $title; + + /** @var string */ protected $name; + + /** @var Content */ protected $index_page; + + /** @var Content */ protected $first_page; + + /** @var string */ protected $uri; + + /** @var string */ protected $local_path; + + /** @var integer */ protected $last_modified; + + /** @var array */ protected $parents; + /** + * @param string $path + * @param array $parents + */ public function __construct($path = '', $parents = array()) { - $this->setPath($path); - $this->setParents($parents); + $this->setPath($path); + $this->setParents($parents); } - + + /** + * @return string + */ public function getName() { return $this->name; } - - public function setName($name) - { - $this->name = $name; - } - + + /** + * @param string $name + */ + public function setName($name) + { + $this->name = $name; + } + + /** + * @return string + */ public function getUri() { return $this->uri; } + /** + * @param string $uri + */ public function setUri($uri) { $this->uri = $uri; } + /** + * @return Content + */ public function getIndexPage() { return $this->index_page; } + /** + * @param Content $index_page + */ public function setIndexPage($index_page) { $this->index_page = $index_page; } /** - * @return Entry + * @return Content */ public function getFirstPage() { @@ -65,7 +102,7 @@ abstract class Entry //the homepage should not count as first page continue; } - + $this->first_page = $node; return $node; } @@ -80,38 +117,59 @@ abstract class Entry return false; } + /** + * @param Content $first_page + */ public function setFirstPage($first_page) { $this->first_page = $first_page; } + /** + * @return string + */ public function getTitle() { return $this->title; } - - public function setTitle($title) - { - $this->title = $title; - } + /** + * @param string $title + */ + public function setTitle($title) + { + $this->title = $title; + } + + /** + * @return array + */ public function getParents() { return $this->parents; } - - public function setParents($parents) - { - $this->parents = $parents; - } + /** + * @param array $parents + */ + public function setParents($parents) + { + $this->parents = $parents; + } + + /** + * @return string + */ public function getPath() { return $this->local_path; } - - public function setPath($path) - { + + /** + * @param string $path + */ + public function setPath($path) + { if (!isset($path) || $path == '' || !file_exists($path)) { return; } @@ -121,8 +179,12 @@ abstract class Entry $this->title = $this->getTitleInternal($this->name); $this->uri = $this->getUrlInternal($this->getFilename($path)); $this->index_page = false; - } + } + /** + * @param string $content + * @return bool + */ public function write($content) { if (!is_writable($this->local_path)) { @@ -132,7 +194,10 @@ abstract class Entry file_put_contents($this->local_path, $content); return true; } - + + /** + * @return string + */ public function getUrl() { $url = ''; @@ -143,12 +208,20 @@ abstract class Entry return $url; } + /** + * @param string $file + * @return string + */ protected function getFilename($file) { $parts = explode('/', $file); return end($parts); } + /** + * @param string $filename + * @return string + */ protected function getTitleInternal($filename) { $filename = explode('_', $filename); @@ -164,6 +237,10 @@ abstract class Entry return $filename; } + /** + * @param string $filename + * @return string + */ protected function getUrlInternal($filename) { $filename = explode('_', $filename); diff --git a/templates/content.php b/templates/content.php index 6bbcf62..29ee280 100644 --- a/templates/content.php +++ b/templates/content.php @@ -9,10 +9,10 @@ Edit this page'; ?> - + - + @@ -28,14 +28,14 @@ -
+

You are editing  Close

- +