[Bridge] Add and rewrite documentation compatible to phpDocumentor

This is the first step in adding documentation to the core library
of RSS-Bridge. The documentation is not yet extracted by phpdoc,
yet may prove useful to anyone interested in starting with RSS-Bridge.
This commit is contained in:
logmanoriginal 2018-11-13 20:26:56 +01:00
parent 5f867c00b4
commit 4a6b3654eb

View file

@ -1,24 +1,80 @@
<?php
/**
* This file is part of RSS-Bridge, a PHP project capable of generating RSS and
* Atom feeds for websites that don't have one.
*
* For the full license information, please view the UNLICENSE file distributed
* with this source code.
*
* @package Core
* @license http://unlicense.org/ UNLICENSE
* @link https://github.com/rss-bridge/rss-bridge
*/
/**
* Factory class responsible for creating new instances of bridges from a given
* working directory, limited by a whitelist.
*
* This class is capable of:
* - Locating bridges in the specified working directory (see {@see Bridge::$dirBridge})
* - Filtering bridges based on a whitelist (see {@see Bridge::$whitelist})
* - Creating new bridge instances based on the bridge's name (see {@see Bridge::create()})
*
* The following example illustrates the intended use for this class.
*
* ```PHP
* require_once __DIR__ . '/rssbridge.php';
*
* // Step 1: Set the working directory
* Bridge::setDir(__DIR__ . '/../bridges/');
*
* // Step 2: Add bridges to the whitelist
* Bridge::setWhitelist(array('GitHubIssue', 'GoogleSearch', 'Facebook', 'Twitter'));
*
* // Step 3: Create a new instance of a bridge (based on the name)
* $bridge = Bridge::create('GitHubIssue');
* ```
*/
class Bridge {
/**
* Holds the working directory.
* Do not access this property directly!
* Use {@see Bridge::setDir()} and {@see Bridge::getDir()} instead.
*
* @var string
*/
static protected $dirBridge;
/**
* Holds the active whitelist.
* Use Bridge::getWhitelist() instead of accessing this parameter directly!
* Holds the whitelist.
* Do not access this property directly!
* Use {@see Bridge::getWhitelist()} instead.
*
* @var array
*/
private static $whitelist = array();
/**
* Throws an exception when trying to create a new instance of this class.
* Use {@see Bridge::create()} to instanciate a new bridge from the working
* directory.
*
* @throws LogicException if called.
*/
public function __construct(){
throw new \LogicException('Please use ' . __CLASS__ . '::create for new object.');
}
/**
* Create a new bridge object
* @param string $nameBridge Defined bridge name you want use
* @return Bridge object dedicated
*/
* Creates a new instance of a bridge in the working directory.
*
* @throws InvalidArgumentException if the provided bridge name is invalid.
* @throws Exception if a bridge with the given name does not exist in the
* working directory.
* @param string $nameBridge Name of the bridge.
* @return object|bool Instance of the bridge or false if the bridge is not instantiable.
*/
public static function create($nameBridge){
if(!preg_match('@^[A-Z][a-zA-Z0-9-]*$@', $nameBridge)) {
$message = <<<EOD
@ -45,6 +101,14 @@ EOD;
return false;
}
/**
* Sets the current working directory.
*
* @param string $dirBridge Path to the directory containing bridges.
* @throws LogicException if the provided path is not a valid string.
* @throws Exception if the provided path does not exist.
* @return void
*/
public static function setDir($dirBridge){
if(!is_string($dirBridge)) {
throw new \InvalidArgumentException('Dir bridge must be a string.');
@ -57,6 +121,13 @@ EOD;
self::$dirBridge = $dirBridge;
}
/**
* Returns the current working directory.
* The working directory must be specified with {@see Bridge::setDir()}!
*
* @throws LogicException if the working directory was not specified.
* @return string The current working directory.
*/
public static function getDir(){
if(is_null(self::$dirBridge)) {
throw new \LogicException(__CLASS__ . ' class need to know bridge path !');
@ -66,9 +137,12 @@ EOD;
}
/**
* Lists the available bridges.
* @return array List of the bridges
*/
* Returns the list of bridge names based on the working directory.
*
* The list is cached internally to allow for successive calls.
*
* @return array List of bridge names
*/
public static function listBridges(){
static $listBridge = array(); // Initialized on first call
@ -89,18 +163,29 @@ EOD;
}
/**
* @return bool Returns true if the given bridge is whitelisted.
* Checks if a bridge is whitelisted.
*
* @param string $name Name of the bridge.
* @return bool True if the bridge is whitelisted.
*/
public static function isWhitelisted($name){
return in_array(Bridge::sanitizeBridgeName($name), Bridge::getWhitelist());
}
/**
* On first call reads the whitelist from WHITELIST. Each line in the file
* specifies one bridge that will be placed on the whitelist. An empty file
* disables all bridges. '*' enables all bridges.
* Returns the whitelist.
*
* @return array Returns a list of whitelisted bridges
* On first call this function reads the whitelist from {@see WHITELIST}.
* * Each line in the file specifies one bridge on the whitelist.
* * An empty file disables all bridges.
* * If the file only only contains `*`, all bridges are whitelisted.
*
* Use {@see Bridge::setWhitelist()} to specify a default whitelist **before**
* calling this function! The list is cached internally to allow for
* successive calls. If {@see Bridge::setWhitelist()} gets called after this
* function, the whitelist is **not** updated again!
*
* @return array Array of whitelisted bridges
*/
public static function getWhitelist() {
@ -129,13 +214,40 @@ EOD;
}
/**
* Sets the (default) whitelist.
*
* If this function is called **before** {@see Bridge::getWhitelist()}, the
* provided whitelist will be replaced by a custom whitelist specified in
* {@see WHITELIST} (if it exists).
*
* If this function is called **after** {@see Bridge::getWhitelist()}, the
* provided whitelist is taken as is (not updated by the custom whitelist
* again).
*
* @param array $default The whitelist as array of bridge names.
* @return void
*/
public static function setWhitelist($default = array()) {
Bridge::$whitelist = array_map('Bridge::sanitizeBridgeName', $default);
}
/**
* @return string Returns a sanitized bridge name if the given name has been
* found valid, null otherwise.
* Returns the sanitized bridge name.
*
* The bridge name can be specified in various ways:
* * The PHP file name (i.e. `GitHubIssueBridge.php`)
* * The PHP file name without file extension (i.e. `GitHubIssueBridge`)
* * The bridge name (i.e. `GitHubIssue`)
*
* Casing is ignored (i.e. `GITHUBISSUE` and `githubissue` are the same).
*
* A bridge file matching the given bridge name must exist in the working
* directory!
*
* @param string $name The bridge name
* @return string|null The sanitized bridge name if the provided name is
* valid, null otherwise.
*/
private static function sanitizeBridgeName($name) {