d4e867f240
Default bridges are currently statically defined in index.php, which is not the right place if we want to keep responsibilities separated. This commit introduces a new file whitelist.default.txt that holds the default bridges and which is loaded automatically, if whitelist.txt doesn't exist. Due to this it is also no longer necessary to have write permission for the root directory. References #1001
300 lines
8.6 KiB
PHP
300 lines
8.6 KiB
PHP
<?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 bridge objects from a given working
|
|
* directory, limited by a whitelist.
|
|
*
|
|
* This class is capable of:
|
|
* - Locating bridge classes in the specified working directory (see {@see Bridge::$workingDir})
|
|
* - 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::setWorkingDir(__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 a path to the working directory.
|
|
*
|
|
* Do not access this property directly!
|
|
* Use {@see Bridge::setWorkingDir()} and {@see Bridge::getWorkingDir()} instead.
|
|
*
|
|
* @var string|null
|
|
*/
|
|
protected static $workingDir = null;
|
|
|
|
/**
|
|
* Holds a list of whitelisted bridges.
|
|
*
|
|
* Do not access this property directly!
|
|
* Use {@see Bridge::getWhitelist()} instead.
|
|
*
|
|
* @var array
|
|
*/
|
|
protected 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('Use ' . __CLASS__ . '::create($name) to create bridge objects!');
|
|
}
|
|
|
|
/**
|
|
* Creates a new bridge object from the working directory.
|
|
*
|
|
* @throws \InvalidArgumentException if the requested bridge name is invalid.
|
|
* @throws \Exception if the requested bridge doesn't exist in the working
|
|
* directory.
|
|
* @param string $name Name of the bridge object.
|
|
* @return object|bool The bridge object or false if the class is not instantiable.
|
|
*/
|
|
public static function create($name){
|
|
if(!self::isBridgeName($name)) {
|
|
throw new \InvalidArgumentException('Bridge name invalid!');
|
|
}
|
|
|
|
$name = self::sanitizeBridgeName($name) . 'Bridge';
|
|
$filePath = self::getWorkingDir() . $name . '.php';
|
|
|
|
if(!file_exists($filePath)) {
|
|
throw new \Exception('Bridge file ' . $filePath . ' does not exist!');
|
|
}
|
|
|
|
require_once $filePath;
|
|
|
|
if((new \ReflectionClass($name))->isInstantiable()) {
|
|
return new $name();
|
|
}
|
|
|
|
return false;
|
|
}
|
|
|
|
/**
|
|
* Sets the working directory.
|
|
*
|
|
* @param string $dir 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.
|
|
* @throws \InvalidArgumentException if $dir is not a directory.
|
|
* @return void
|
|
*/
|
|
public static function setWorkingDir($dir){
|
|
self::$workingDir = null;
|
|
|
|
if(!is_string($dir)) {
|
|
throw new \InvalidArgumentException('Working directory is not a valid string!');
|
|
}
|
|
|
|
if(!file_exists($dir)) {
|
|
throw new \Exception('Working directory does not exist!');
|
|
}
|
|
|
|
if(!is_dir($dir)) {
|
|
throw new \InvalidArgumentException('Working directory is not a directory!');
|
|
}
|
|
|
|
self::$workingDir = realpath($dir) . '/';
|
|
}
|
|
|
|
/**
|
|
* Returns the working directory.
|
|
* The working directory must be specified with {@see Bridge::setWorkingDir()}!
|
|
*
|
|
* @throws \LogicException if the working directory is not set.
|
|
* @return string The current working directory.
|
|
*/
|
|
public static function getWorkingDir(){
|
|
if(is_null(self::$workingDir)) {
|
|
throw new \LogicException('Working directory is not set!');
|
|
}
|
|
|
|
return self::$workingDir;
|
|
}
|
|
|
|
/**
|
|
* Returns true if the provided name is a valid bridge name.
|
|
*
|
|
* A valid bridge name starts with a capital letter ([A-Z]), followed by
|
|
* zero or more alphanumeric characters or hyphen ([A-Za-z0-9-]).
|
|
*
|
|
* @param string $name The bridge name.
|
|
* @return bool true if the name is a valid bridge name, false otherwise.
|
|
*/
|
|
public static function isBridgeName($name){
|
|
return is_string($name) && preg_match('/^[A-Z][a-zA-Z0-9-]*$/', $name) === 1;
|
|
}
|
|
|
|
/**
|
|
* Returns the list of bridge names from the working directory.
|
|
*
|
|
* The list is cached internally to allow for successive calls.
|
|
*
|
|
* @return array List of bridge names
|
|
*/
|
|
public static function getBridgeNames(){
|
|
|
|
static $bridgeNames = array(); // Initialized on first call
|
|
|
|
if(empty($bridgeNames)) {
|
|
$files = scandir(self::getWorkingDir());
|
|
|
|
if($files !== false) {
|
|
foreach($files as $file) {
|
|
if(preg_match('/^([^.]+)Bridge\.php$/U', $file, $out)) {
|
|
$bridgeNames[] = $out[1];
|
|
}
|
|
}
|
|
}
|
|
}
|
|
|
|
return $bridgeNames;
|
|
}
|
|
|
|
/**
|
|
* 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(self::sanitizeBridgeName($name), self::getWhitelist());
|
|
}
|
|
|
|
/**
|
|
* Returns the whitelist.
|
|
*
|
|
* On first call this function reads the whitelist from {@see WHITELIST} if
|
|
* the file exists, {@see WHITELIST_DEFAULT} otherwise.
|
|
* * 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() {
|
|
|
|
static $firstCall = true; // Initialized on first call
|
|
|
|
if($firstCall) {
|
|
|
|
if(file_exists(WHITELIST)) {
|
|
$contents = trim(file_get_contents(WHITELIST));
|
|
} elseif(file_exists(WHITELIST_DEFAULT)) {
|
|
$contents = trim(file_get_contents(WHITELIST_DEFAULT));
|
|
} else {
|
|
$contents = '';
|
|
}
|
|
|
|
if($contents === '*') { // Whitelist all bridges
|
|
self::$whitelist = self::getBridgeNames();
|
|
} else {
|
|
//self::$whitelist = array_map('self::sanitizeBridgeName', explode("\n", $contents));
|
|
foreach(explode("\n", $contents) as $bridgeName) {
|
|
self::$whitelist[] = self::sanitizeBridgeName($bridgeName);
|
|
}
|
|
}
|
|
|
|
}
|
|
|
|
return self::$whitelist;
|
|
|
|
}
|
|
|
|
/**
|
|
* 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()) {
|
|
self::$whitelist = array_map('self::sanitizeBridgeName', $default);
|
|
}
|
|
|
|
/**
|
|
* 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.
|
|
*/
|
|
protected static function sanitizeBridgeName($name) {
|
|
|
|
if(is_string($name)) {
|
|
|
|
// Trim trailing '.php' if exists
|
|
if(preg_match('/(.+)(?:\.php)/', $name, $matches)) {
|
|
$name = $matches[1];
|
|
}
|
|
|
|
// Trim trailing 'Bridge' if exists
|
|
if(preg_match('/(.+)(?:Bridge)/i', $name, $matches)) {
|
|
$name = $matches[1];
|
|
}
|
|
|
|
// The name is valid if a corresponding bridge file is found on disk
|
|
if(in_array(strtolower($name), array_map('strtolower', self::getBridgeNames()))) {
|
|
$index = array_search(strtolower($name), array_map('strtolower', self::getBridgeNames()));
|
|
return self::getBridgeNames()[$index];
|
|
}
|
|
|
|
Debug::log('Invalid bridge name specified: "' . $name . '"!');
|
|
|
|
}
|
|
|
|
return null; // Bad parameter
|
|
|
|
}
|
|
}
|