diff --git a/lib/Authentication.php b/lib/Authentication.php index da247630..f9683940 100644 --- a/lib/Authentication.php +++ b/lib/Authentication.php @@ -1,6 +1,48 @@ items; } /** - * Sets the input values for a given context. Existing values are - * overwritten. + * Sets the input values for a given context. * * @param array $inputs Associative array of inputs - * @param string $context The context name + * @param string $queriedContext The context name + * @return void */ protected function setInputs(array $inputs, $queriedContext){ // Import and assign all inputs to their context @@ -103,9 +183,15 @@ abstract class BridgeAbstract implements BridgeInterface { } /** - * Defined datas with parameters depending choose bridge - * @param array array with expected bridge paramters - */ + * Set inputs for the bridge + * + * Returns errors and aborts execution if the provided input parameters are + * invalid. + * + * @param array List of input parameters. Each element in this list must + * relate to an item in {@see BridgeAbstract::PARAMETERS} + * @return void + */ public function setDatas(array $inputs){ if(empty(static::PARAMETERS)) { @@ -148,7 +234,7 @@ abstract class BridgeAbstract implements BridgeInterface { * Returns the value for the provided input * * @param string $input The input name - * @return mixed Returns the input value or null if the input is not defined + * @return mixed|null The input value or null if the input is not defined */ protected function getInput($input){ if(!isset($this->inputs[$this->queriedContext][$input]['value'])) { @@ -157,30 +243,37 @@ abstract class BridgeAbstract implements BridgeInterface { return $this->inputs[$this->queriedContext][$input]['value']; } + /** {@inheritdoc} */ public function getDescription(){ return static::DESCRIPTION; } + /** {@inheritdoc} */ public function getMaintainer(){ return static::MAINTAINER; } + /** {@inheritdoc} */ public function getName(){ return static::NAME; } + /** {@inheritdoc} */ public function getIcon(){ return ''; } + /** {@inheritdoc} */ public function getParameters(){ return static::PARAMETERS; } + /** {@inheritdoc} */ public function getURI(){ return static::URI; } + /** {@inheritdoc} */ public function getCacheTimeout(){ return static::CACHE_TIMEOUT; } diff --git a/lib/BridgeCard.php b/lib/BridgeCard.php index 28e74fe6..cb7e607b 100644 --- a/lib/BridgeCard.php +++ b/lib/BridgeCard.php @@ -1,6 +1,33 @@ @@ -31,6 +65,17 @@ This bridge is not fetching its content through a secure connection'; return $form; } + /** + * Get the form body for a bridge + * + * @param string $bridgeName The bridge name + * @param array $formats A list of supported formats + * @param bool $isActive Indicates if a bridge is enabled or not + * @param bool $isHttps Indicates if a bridge uses HTTPS or not + * @param string $parameterName Sets the bridge context for the current form + * @param array $parameters The bridge parameters + * @return string The form body + */ private static function getForm($bridgeName, $formats, $isActive = false, @@ -88,6 +133,12 @@ This bridge is not fetching its content through a secure connection'; return $form . '' . PHP_EOL; } + /** + * Get input field attributes + * + * @param array $entry The current entry + * @return string The input field attributes + */ private static function getInputAttributes($entry) { $retVal = ''; @@ -103,6 +154,14 @@ This bridge is not fetching its content through a secure connection'; return $retVal; } + /** + * Get text input + * + * @param array $entry The current entry + * @param string $id The field ID + * @param string $name The field name + * @return string The text input field + */ private static function getTextInput($entry, $id, $name) { return ''; . PHP_EOL; } + /** + * Get number input + * + * @param array $entry The current entry + * @param string $id The field ID + * @param string $name The field name + * @return string The number input field + */ private static function getNumberInput($entry, $id, $name) { return ''; . PHP_EOL; } + /** + * Get list input + * + * @param array $entry The current entry + * @param string $id The field ID + * @param string $name The field name + * @return string The list input field + */ private static function getListInput($entry, $id, $name) { $list = ''; . PHP_EOL; } + /** + * Gets a single bridge card + * + * @param string $bridgeName The bridge name + * @param array $formats A list of formats + * @param bool $isActive Indicates if the bridge is active or not + * @return string The bridge card + */ static function displayBridgeCard($bridgeName, $formats, $isActive = true){ $bridge = Bridge::create($bridgeName); diff --git a/lib/BridgeInterface.php b/lib/BridgeInterface.php index f2ff11d5..bc48fe04 100644 --- a/lib/BridgeInterface.php +++ b/lib/BridgeInterface.php @@ -1,4 +1,57 @@ @@ -22,6 +47,15 @@ final class BridgeList { EOD; } + /** + * Get the document body for all bridge cards + * + * @param bool $showInactive Inactive bridges are visible on the home page if + * enabled. + * @param int $totalBridges (ref) Returns the total number of bridges. + * @param int $totalActiveBridges (ref) Returns the number of active bridges. + * @return string The document body for all bridge cards. + */ private static function getBridges($showInactive, &$totalBridges, &$totalActiveBridges) { $body = ''; @@ -54,6 +88,11 @@ EOD; return $body; } + /** + * Get the document header + * + * @return string The document header + */ private static function getHeader() { $warning = ''; @@ -80,6 +119,11 @@ EOD; EOD; } + /** + * Get the searchbar + * + * @return string The searchbar + */ private static function getSearchbar() { $query = filter_input(INPUT_GET, 'q'); @@ -93,6 +137,16 @@ EOD; EOD; } + /** + * Get the document footer + * + * @param int $totalBridges The total number of bridges, shown in the footer + * @param int $totalActiveBridges The total number of active bridges, shown + * in the footer. + * @param bool $showInactive Sets the 'Show active'/'Show inactive' text in + * the footer. + * @return string The document footer + */ private static function getFooter($totalBridges, $totalActiveBridges, $showInactive) { $version = Configuration::getVersion(); @@ -131,6 +185,13 @@ EOD; EOD; } + /** + * Create the entire home page + * + * @param bool $showInactive Inactive bridges are displayed on the home page, + * if enabled. + * @return string The home page + */ static function create($showInactive = true) { $totalBridges = 0; diff --git a/lib/CacheInterface.php b/lib/CacheInterface.php index 5753c0eb..bd2d5613 100644 --- a/lib/CacheInterface.php +++ b/lib/CacheInterface.php @@ -1,7 +1,51 @@ @@ -124,6 +153,17 @@ function buildHeader($e, $bridge){ EOD; } +/** + * Builds a new HTML section + * + * @param object $e The exception object + * @param object $bridge The bridge object + * @param string $message The message to display + * @param string $link The link to include in the anchor + * @return string The HTML section + * + * @todo This function belongs inside a class + */ function buildSection($e, $bridge, $message, $link){ return << @@ -142,6 +182,16 @@ function buildSection($e, $bridge, $message, $link){ EOD; } +/** + * Builds a new HTML page + * + * @param string $title The HTML title + * @param string $header The HTML header + * @param string $section The HTML section + * @return string The HTML page + * + * @todo This function belongs inside a class + */ function buildPage($title, $header, $section){ return << diff --git a/lib/FeedExpander.php b/lib/FeedExpander.php index 893c3ba1..04f835aa 100644 --- a/lib/FeedExpander.php +++ b/lib/FeedExpander.php @@ -1,11 +1,74 @@ {'collect_' . $this->feedType . '_data'}($rssContent, $maxItems); } + /** + * Collect data from a RSS 1.0 compatible feed + * + * @link http://web.resource.org/rss/1.0/spec RDF Site Summary (RSS) 1.0 + * + * @param string $rssContent The RSS content + * @param int $maxItems Maximum number of items to collect from the feed + * (`-1`: no limit). + * @return void + * + * @todo Instead of passing $maxItems to all functions, just add all items + * and remove excessive items later. + */ protected function collect_RSS_1_0_data($rssContent, $maxItems){ $this->load_RSS_2_0_feed_data($rssContent->channel[0]); foreach($rssContent->item as $item) { @@ -56,6 +132,19 @@ abstract class FeedExpander extends BridgeAbstract { } } + /** + * Collect data from a RSS 2.0 compatible feed + * + * @link http://www.rssboard.org/rss-specification RSS 2.0 Specification + * + * @param object $rssContent The RSS content + * @param int $maxItems Maximum number of items to collect from the feed + * (`-1`: no limit). + * @return void + * + * @todo Instead of passing $maxItems to all functions, just add all items + * and remove excessive items later. + */ protected function collect_RSS_2_0_data($rssContent, $maxItems){ $rssContent = $rssContent->channel[0]; Debug::log('RSS content is ===========\n' @@ -73,6 +162,19 @@ abstract class FeedExpander extends BridgeAbstract { } } + /** + * Collect data from a Atom 1.0 compatible feed + * + * @link https://tools.ietf.org/html/rfc4287 The Atom Syndication Format + * + * @param object $content The Atom content + * @param int $maxItems Maximum number of items to collect from the feed + * (`-1`: no limit). + * @return void + * + * @todo Instead of passing $maxItems to all functions, just add all items + * and remove excessive items later. + */ protected function collect_ATOM_1_0_data($content, $maxItems){ $this->load_ATOM_feed_data($content); foreach($content->entry as $item) { @@ -85,16 +187,35 @@ abstract class FeedExpander extends BridgeAbstract { } } + /** + * Convert RSS 2.0 time to timestamp + * + * @param object $item A feed item + * @return int The timestamp + */ protected function RSS_2_0_time_to_timestamp($item){ return DateTime::createFromFormat('D, d M Y H:i:s e', $item->pubDate)->getTimestamp(); } - // TODO set title, link, description, language, and so on + /** + * Load RSS 2.0 feed data into RSS-Bridge + * + * @param object $rssContent The RSS content + * @return void + * + * @todo set title, link, description, language, and so on + */ protected function load_RSS_2_0_feed_data($rssContent){ $this->name = trim((string)$rssContent->title); $this->uri = trim((string)$rssContent->link); } + /** + * Load Atom feed data into RSS-Bridge + * + * @param object $content The Atom content + * @return void + */ protected function load_ATOM_feed_data($content){ $this->name = (string)$content->title; @@ -114,6 +235,16 @@ abstract class FeedExpander extends BridgeAbstract { } } + /** + * Parse the contents of a single Atom feed item into a RSS-Bridge item for + * further transformation. + * + * @param object $feedItem A single feed item + * @return object The RSS-Bridge item + * + * @todo To reduce confusion, the RSS-Bridge item should maybe have a class + * of its own? + */ protected function parseATOMItem($feedItem){ // Some ATOM entries also contain RSS 2.0 fields $item = $this->parseRSS_2_0_Item($feedItem); @@ -139,6 +270,16 @@ abstract class FeedExpander extends BridgeAbstract { return $item; } + /** + * Parse the contents of a single RSS 0.91 feed item into a RSS-Bridge item + * for further transformation. + * + * @param object $feedItem A single feed item + * @return object The RSS-Bridge item + * + * @todo To reduce confusion, the RSS-Bridge item should maybe have a class + * of its own? + */ protected function parseRSS_0_9_1_Item($feedItem){ $item = array(); if(isset($feedItem->link)) $item['uri'] = (string)$feedItem->link; @@ -150,6 +291,16 @@ abstract class FeedExpander extends BridgeAbstract { return $item; } + /** + * Parse the contents of a single RSS 1.0 feed item into a RSS-Bridge item + * for further transformation. + * + * @param object $feedItem A single feed item + * @return object The RSS-Bridge item + * + * @todo To reduce confusion, the RSS-Bridge item should maybe have a class + * of its own? + */ protected function parseRSS_1_0_Item($feedItem){ // 1.0 adds optional elements around the 0.91 standard $item = $this->parseRSS_0_9_1_Item($feedItem); @@ -164,6 +315,16 @@ abstract class FeedExpander extends BridgeAbstract { return $item; } + /** + * Parse the contents of a single RSS 2.0 feed item into a RSS-Bridge item + * for further transformation. + * + * @param object $feedItem A single feed item + * @return object The RSS-Bridge item + * + * @todo To reduce confusion, the RSS-Bridge item should maybe have a class + * of its own? + */ protected function parseRSS_2_0_Item($feedItem){ // Primary data is compatible to 0.91 with some additional data $item = $this->parseRSS_0_9_1_Item($feedItem); @@ -211,9 +372,11 @@ abstract class FeedExpander extends BridgeAbstract { } /** - * Method should return, from a source RSS item given by lastRSS, one of our Items objects - * @param $item the input rss item - * @return a RSS-Bridge Item, with (hopefully) the whole content) + * Parse the contents of a single feed item, depending on the current feed + * type, into a RSS-Bridge item. + * + * @param object $item The current feed item + * @return object A RSS-Bridge item, with (hopefully) the whole content */ protected function parseItem($item){ switch($this->feedType) { @@ -230,14 +393,17 @@ abstract class FeedExpander extends BridgeAbstract { } } + /** {@inheritdoc} */ public function getURI(){ return !empty($this->uri) ? $this->uri : parent::getURI(); } + /** {@inheritdoc} */ public function getName(){ return !empty($this->name) ? $this->name : parent::getName(); } + /** {@inheritdoc} */ public function getIcon(){ return !empty($this->icon) ? $this->icon : parent::getIcon(); } diff --git a/lib/FormatAbstract.php b/lib/FormatAbstract.php index 8fb642c0..3315666d 100644 --- a/lib/FormatAbstract.php +++ b/lib/FormatAbstract.php @@ -1,41 +1,95 @@ charset = $charset; return $this; } + /** {@inheritdoc} */ public function getCharset(){ $charset = $this->charset; return is_null($charset) ? static::DEFAULT_CHARSET : $charset; } + /** + * Set the content type + * + * @param string $contentType The content type + * @return self The format object + */ protected function setContentType($contentType){ $this->contentType = $contentType; return $this; } + /** + * Set the last modified time + * + * @param int $lastModified The last modified time + * @return void + */ public function setLastModified($lastModified){ $this->lastModified = $lastModified; } + /** + * Send header with the currently specified content type + * + * @return void + * @todo This should throw an error if no content type is set + */ protected function callContentType(){ header('Content-Type: ' . $this->contentType); } + /** {@inheritdoc} */ public function display(){ if ($this->lastModified) { header('Last-Modified: ' . gmdate('D, d M Y H:i:s ', $this->lastModified) . 'GMT'); @@ -45,12 +99,18 @@ abstract class FormatAbstract implements FormatInterface { return $this; } + /** + * {@inheritdoc} + * + * @param array $items {@inheritdoc} + */ public function setItems(array $items){ $this->items = array_map(array($this, 'array_trim'), $items); return $this; } + /** {@inheritdoc} */ public function getItems(){ if(!is_array($this->items)) throw new \LogicException('Feed the ' . get_class($this) . ' with "setItems" method before !'); @@ -59,10 +119,10 @@ abstract class FormatAbstract implements FormatInterface { } /** - * Define common informations can be required by formats and set default value for unknown values - * @param array $extraInfos array with know informations (there isn't merge !!!) - * @return this - */ + * {@inheritdoc} + * + * @param array $extraInfos {@inheritdoc} + */ public function setExtraInfos(array $extraInfos = array()){ foreach(array('name', 'uri', 'icon') as $infoName) { if(!isset($extraInfos[$infoName])) { @@ -75,10 +135,7 @@ abstract class FormatAbstract implements FormatInterface { return $this; } - /** - * Return extra infos - * @return array See "setExtraInfos" detail method to know what extra are disponibles - */ + /** {@inheritdoc} */ public function getExtraInfos(){ if(is_null($this->extraInfos)) { // No extra info ? $this->setExtraInfos(); // Define with default value @@ -88,12 +145,17 @@ abstract class FormatAbstract implements FormatInterface { } /** - * Sanitized html while leaving it functionnal. - * The aim is to keep html as-is (with clickable hyperlinks) - * while reducing annoying and potentially dangerous things. - * Yes, I know sanitizing HTML 100% is an impossible task. - * Maybe we'll switch to http://htmlpurifier.org/ - * or http://www.bioinformatics.org/phplabware/internal_utilities/htmLawed/index.php + * Sanitize HTML while leaving it functional. + * + * Keeps HTML as-is (with clickable hyperlinks) while reducing annoying and + * potentially dangerous things. + * + * @param string $html The HTML content + * @return string The sanitized HTML content + * + * @todo This belongs into `html.php` + * @todo Maybe switch to http://htmlpurifier.org/ + * @todo Maybe switch to http://www.bioinformatics.org/phplabware/internal_utilities/htmLawed/index.php */ protected function sanitizeHtml($html) { @@ -104,6 +166,17 @@ abstract class FormatAbstract implements FormatInterface { return $html; } + /** + * Trim each element of an array + * + * This function applies `trim()` to all elements in the array, if the element + * is a valid string. + * + * @param array $elements The array to trim + * @return array The trimmed array + * + * @todo This is a utility function that doesn't belong here, find a new home. + */ protected function array_trim($elements){ foreach($elements as $key => $value) { if(is_string($value)) diff --git a/lib/FormatInterface.php b/lib/FormatInterface.php index f99d214f..d59a4ef9 100644 --- a/lib/FormatInterface.php +++ b/lib/FormatInterface.php @@ -1,11 +1,84 @@ invalid[] = array( 'name' => $name, @@ -13,13 +38,23 @@ class ParameterValidator { } /** - * Returns an array of invalid parameters, where each element is an - * array of 'name' and 'reason'. + * Return list of invalid parameters. + * + * Each element is an array of 'name' and 'reason'. + * + * @return array List of invalid parameters */ public function getInvalidParameters() { return $this->invalid; } + /** + * Validate value for a text input + * + * @param string $value The value of a text input + * @param string|null $pattern (optional) A regex pattern + * @return string|null The filtered value or null if the value is invalid + */ private function validateTextValue($value, $pattern = null){ if(!is_null($pattern)) { $filteredValue = filter_var($value, @@ -38,6 +73,12 @@ class ParameterValidator { return $filteredValue; } + /** + * Validate value for a number input + * + * @param int $value The value of a number input + * @return int|null The filtered value or null if the value is invalid + */ private function validateNumberValue($value){ $filteredValue = filter_var($value, FILTER_VALIDATE_INT); @@ -47,10 +88,23 @@ class ParameterValidator { return $filteredValue; } + /** + * Validate value for a checkbox + * + * @param bool $value The value of a checkbox + * @return bool The filtered value + */ private function validateCheckboxValue($value){ return filter_var($value, FILTER_VALIDATE_BOOLEAN, FILTER_NULL_ON_FAILURE); } + /** + * Validate value for a list + * + * @param string $value The value of a list + * @param array $expectedValues A list of expected values + * @return string|null The filtered value or null if the value is invalid + */ private function validateListValue($value, $expectedValues){ $filteredValue = filter_var($value); @@ -69,9 +123,11 @@ class ParameterValidator { } /** - * Checks if all required parameters are supplied by the user - * @param $data An array of parameters provided by the user - * @param $parameters An array of bridge parameters + * Check if all required parameters are satisfied + * + * @param array $data (ref) A list of input values + * @param array $parameters The bridge parameters + * @return bool True if all parameters are satisfied */ public function validateData(&$data, $parameters){ @@ -122,11 +178,11 @@ class ParameterValidator { } /** - * Returns the name of the context matching the provided inputs + * Get the name of the context matching the provided inputs * * @param array $data Associative array of user data * @param array $parameters Array of bridge parameters - * @return mixed Returns the context name or null if no match was found + * @return string|null Returns the context name or null if no match was found */ public function getQueriedContext($data, $parameters){ $queriedContexts = array(); diff --git a/lib/contents.php b/lib/contents.php index fbd93f1b..127638bc 100644 --- a/lib/contents.php +++ b/lib/contents.php @@ -1,4 +1,31 @@ ` tags + * when returning plaintext. + * @param string $defaultSpanText Specifies the replacement text for `` + * tags when returning plaintext. + * @return string Contents as simplehtmldom object. + */ function getSimpleHTMLDOM($url, $header = array(), $opts = array(), @@ -94,10 +147,34 @@ $defaultSpanText = DEFAULT_SPAN_TEXT){ } /** - * Maintain locally cached versions of pages to avoid multiple downloads. - * @param url url to cache - * @param duration duration of the cache file in seconds (default: 24h/86400s) - * @return content of the file as string + * Gets contents from the Internet as simplhtmldom object. Contents are cached + * and re-used for subsequent calls until the cache duration elapsed. + * + * _Notice_: Cached contents are forcefully removed after 24 hours (86400 seconds). + * + * @param string $url The URL. + * @param int $duration Cache duration in seconds. + * @param array $header (optional) A list of cURL header. + * For more information follow the links below. + * * https://php.net/manual/en/function.curl-setopt.php + * * https://curl.haxx.se/libcurl/c/CURLOPT_HTTPHEADER.html + * @param array $opts (optional) A list of cURL options as associative array in + * the format `$opts[$option] = $value;`, where `$option` is any `CURLOPT_XXX` + * option and `$value` the corresponding value. + * + * For more information see http://php.net/manual/en/function.curl-setopt.php + * @param bool $lowercase Force all selectors to lowercase. + * @param bool $forceTagsClosed Forcefully close tags in malformed HTML. + * + * _Remarks_: Forcefully closing tags is great for malformed HTML, but it can + * lead to parsing errors. + * @param string $target_charset Defines the target charset. + * @param bool $stripRN Replace all occurrences of `"\r"` and `"\n"` by `" "`. + * @param string $defaultBRText Specifies the replacement text for `
` tags + * when returning plaintext. + * @param string $defaultSpanText Specifies the replacement text for `` + * tags when returning plaintext. + * @return string Contents as simplehtmldom object. */ function getSimpleHTMLDOMCached($url, $duration = 86400, @@ -142,9 +219,12 @@ $defaultSpanText = DEFAULT_SPAN_TEXT){ } /** - * Parses the provided response header into an associative array + * Parses the cURL response header into an associative array * * Based on https://stackoverflow.com/a/18682872 + * + * @param string $header The cURL response header. + * @return array An associative array of response headers. */ function parseResponseHeader($header) { @@ -177,10 +257,18 @@ function parseResponseHeader($header) { } /** - * Determine MIME type from URL/Path file extension - * Remark: Built-in functions mime_content_type or fileinfo requires fetching remote content - * Remark: A bridge can hint for a MIME type by appending #.ext to a URL, e.g. #.image + * Determines the MIME type from a URL/Path file extension. + * + * _Remarks_: + * + * * The built-in functions `mime_content_type` and `fileinfo` require fetching + * remote contents. + * * A caller can hint for a MIME type by appending `#.ext` to the URL (i.e. `#.image`). + * * Based on https://stackoverflow.com/a/1147952 + * + * @param string $url The URL or path to the file. + * @return string The MIME type of the file. */ function getMimeType($url) { static $mime = null; diff --git a/lib/error.php b/lib/error.php index abf3c2db..8546f6cd 100644 --- a/lib/error.php +++ b/lib/error.php @@ -1,12 +1,43 @@ Hello World!

` becomes `Hello World!`). + * @return object A simplehtmldom object of the remaining contents. + * + * @todo Check if this implementation is still necessary, because simplehtmldom + * already removes some of the tags (search for `remove_noise` in simple_html_dom.php). + * @todo Rename parameters to make more sense. `$textToSanitize` must be HTML, + * `$removedTags`, `$keptAttributes` and `$keptText` are past tense. + * @todo Clarify the meaning of `*[!b38fd2b1fe7f4747d6b1c1254ccd055e]`, which + * looks like a SHA1 hash (does simplehtmldom not support `find('*')`?). + */ function sanitize($textToSanitize, $removedTags = array('script', 'iframe', 'input', 'form'), $keptAttributes = array('title', 'href', 'src'), @@ -21,6 +51,35 @@ $keptText = array()){ return $htmlContent; } +/** + * Replace background by image + * + * Replaces tags with styles of `backgroud-image` by `` tags. + * + * For example: + * + * ```HTML + * + * + *

Hello world!

+ * + * + * ``` + * + * results in this output: + * + * ```HTML + * + * + * + * ``` + * + * @param string $htmlContent The HTML content + * @return string The HTML content with all ocurrences replaced + * + * @todo Clarify the meaning of `*[!b38fd2b1fe7f4747d6b1c1254ccd055e]`, which + * looks like a SHA1 hash (does simplehtmldom not support `find('*')`?). + */ function backgroundToImg($htmlContent) { $regex = '/background-image[ ]{0,}:[ ]{0,}url\([\'"]{0,}(.*?)[\'"]{0,}\)/'; @@ -42,9 +101,17 @@ function backgroundToImg($htmlContent) { /** * Convert relative links in HTML into absolute links - * @param $content HTML content to fix. Supports HTML objects or string objects - * @param $server full URL to the page containing relative links - * @return content with fixed URLs, as HTML object or string depending on input type + * + * This function is based on `php-urljoin`. + * + * @link https://github.com/plaidfluff/php-urljoin php-urljoin + * + * @param string|object $content The HTML content. Supports HTML objects or string objects + * @param string $server Fully qualified URL to the page containing relative links + * @return object Content with fixed URLs. + * + * @todo If the input type was a string, this function should return a string as + * well. This is currently done implicitly by how the simplehtmldom object works. */ function defaultLinkTo($content, $server){ $string_convert = false; @@ -70,10 +137,14 @@ function defaultLinkTo($content, $server){ /** * Extract the first part of a string matching the specified start and end delimiters - * @param $string input string, e.g. '
Post author: John Doe
' - * @param $start start delimiter, e.g. 'author: ' - * @param $end end delimiter, e.g. '<' - * @return extracted string, e.g. 'John Doe', or false if the delimiters were not found. + * + * @param string $string Input string, e.g. `
Post author: John Doe
` + * @param string $start Start delimiter, e.g. `author: ` + * @param string $end End delimiter, e.g. `<` + * @return string|bool Extracted string, e.g. `John Doe`, or false if the + * delimiters were not found. + * + * @todo This function can possibly be simplified to use a single `substr` command. */ function extractFromDelimiters($string, $start, $end) { if (strpos($string, $start) !== false) { @@ -85,10 +156,13 @@ function extractFromDelimiters($string, $start, $end) { /** * Remove one or more part(s) of a string using a start and end delmiters - * @param $string input string, e.g. 'foobar' - * @param $start start delimiter, e.g. '' - * @return cleaned string, e.g. 'foobar' + * + * @param string $string Input string, e.g. `foobar` + * @param string $start Start delimiter, e.g. `` + * @return string Cleaned string, e.g. `foobar` + * + * @todo This function can possibly be simplified to use a single `substr` command. */ function stripWithDelimiters($string, $start, $end) { while(strpos($string, $start) !== false) { @@ -101,10 +175,13 @@ function stripWithDelimiters($string, $start, $end) { /** * Remove HTML sections containing one or more sections using the same HTML tag - * @param $string input string, e.g. 'foo
ads
ads
bar' - * @param $tag_name name of the HTML tag, e.g. 'div' - * @param $tag_start start of the HTML tag to remove, e.g. '
' - * @return cleaned string, e.g. 'foobar' + * + * @param string $string Input string, e.g. `foo
ads
ads
bar` + * @param string $tag_name Name of the HTML tag, e.g. `div` + * @param string $tag_start Start of the HTML tag to remove, e.g. `
` + * @return string Cleaned String, e.g. `foobar` + * + * @todo This function needs more documentation to make it maintainable. */ function stripRecursiveHTMLSection($string, $tag_name, $tag_start){ $open_tag = '<' . $tag_name; @@ -131,9 +208,13 @@ function stripRecursiveHTMLSection($string, $tag_name, $tag_start){ } /** - * Convert Markdown tags into HTML tags. Only a subset of the Markdown syntax is implemented. - * @param $string input string in Markdown format - * @return output string in HTML format + * Convert Markdown into HTML. Only a subset of the Markdown syntax is implemented. + * + * @link https://daringfireball.net/projects/markdown/ Markdown + * @link https://github.github.com/gfm/ GitHub Flavored Markdown Spec + * + * @param string $string Input string in Markdown format + * @return string output string in HTML format */ function markdownToHtml($string) {