README

一些核心PHP类，最初是为网站和RSS元数据解析创建的。

快速参考

CountryCode - ISO3166代码及其相关数据
CountryFlag - ISO3166国家的所有尺寸的国旗
Cryptor - 对称加密
DataStore - 抽象SQL存储（基类）
HttpResponse - 官方响应字符串
MIMEType - 处理ContentTypes
PageParser - 解析HTML页面以获取元数据
QRCode - 创建QR码
RateLimiter - 多事务处理节流
SiteIcon - 获取（可选存储）网站图标（'favicons'）
URL - CURL接口，主要是
UUID - 生成唯一ID
Utilities - 其他工具

安装工具库

建议使用composer安装此库。如果您尚未安装composer，请从此处获取。要安装此库，请使用composer要求它

composer require guardianproject/core_utilities

配置您的安装

在开始使用此库之前，请熟悉配置文件UtilitiesConfig.php，根据您的使用情况进行编辑，特别关注您希望存储加密密钥的位置。

初始化工具库

此库中的一些PHP对象将信息存储和检索到小的SQLite3数据库中。这些数据库需要从提供的平面文件中进行初始化。初始化过程由init.php脚本处理。此外，如果尚未存在，将创建用于Cryptor的加密密钥 - 在配置的目录中使用配置的名称。此外，如果不存在，将创建用于日志文件、数据文件和数据库的目录。

在使用此库之前运行此脚本。

php init.php

测试您的安装

此脚本测试了大多数提供的函数（除了DataStore和Utilities）。

php test/lib_test.php

使用此库

要在自己的软件中使用此库中的类，您只需要设置默认时区（对于扩展DataStore的类）并要求库的包含文件

date_default_timezone_set('UTC');
require_once './inc.php';

使用PHP的use语句使类可用

use guardianproject\core_utilities\CountryCode as CountryCode;
try {
	$cc = new CountryCode();
	print "The country name for ISO3166 code [FR] is" . $cc->getCountryName('FR') . "\n";
} catch (Exception $e) {
	print "Error: " . $e->getMessage() . "\n";
}

API描述

CountryCode

使用ISO3166数字代码、ISO3166 3字符代码或ISO3166英语语言名称检索一个国家的ISO3166 2字符代码。然后使用ISO3166 2字符代码检索数据。数据集包括

ISO3166数字代码
ISO3166 3字符代码
ISO3166英语语言名称
互联网顶级域名
首都名称（如果有的话）
联合国会员资格
独立/领土状态
ITU标准拨号代码

以get或retrieve开头的名称的方法是同义的。

用法

try {
	$cc = new CountryCode($force); // force=true rebuilds database table from provided CSV

	$ccode->countryCodeExists($cc);
	$ccode->countryNameExists($name);
	
	// retrieve useful lists
	
	$ccode->allCountryCodes();
	$ccode->allAlpha3Codes();
	$ccode->allNumericCodes();
	$ccode->allTerritories();
	$ccode->allIndependentNations();
	
	// retrieve full data set using any ISO3166 code
	
	$ccode->getCountryData($cc, $asJSON = null);
	$ccode->retrieveCountryData($cc, $asJSON = null);
	$ccode->getCountryDataUsingAlpha3Code($alpha3) { 
	$ccode->retrieveCountryDataUsingAlpha3Code($alpha3);
	$ccode->getCountryDataUsingNumericCode($num); 
	$ccode->retrieveCountryDataUsingNumericCode($num);

	// if all you have is the country name...
	
	$ccode->getCountryCode($name); 
	$ccode->retrieveCountryCode($name);
	$ccode->retrieveCountryCodeFuzzy($name);
	$ccode->retrieveCountryNamesLike($str);

	// retrieve individual data items via the ISO3166 2-character code
	
	$ccode->getCountryName($cc);
	$ccode->retrieveCountryName($cc);
	$ccode->getNumericCode($cc);
	$ccode->retrieveNumericCode($cc);
	$ccode->getAlpha3Code($cc);
	$ccode->retrieveAlpha3Code($cc);
	$ccode->getCountryCapital($cc);
	$ccode->retrieveCountryCapital($cc);
	$ccode->getInternetTLDForCountryCode($cc);
	$ccode->retrieveInternetTLDForCountryCode($cc);
	$ccode->callingCodesForCountryCode($cc);
	$ccode->ITUCodesForCountryCode($cc);
	$ccode->isUNMember($cc);
	$ccode->isIndependent($cc);
	$ccode->hasCapital($cc);
	$ccode->territoryOf($cc);

	// database maintenance
	$ccode->rebuild();
	$ccode->dump($to_file = null);
}

CountryFlag

检索所有ISO3166国家、联合国（UN）和南极洲（AQ）的国家国旗图像（PNG）。图标大小的文件本地缓存；其他尺寸在请求时从CDN检索。所有国旗数据以base64编码返回。允许的size如下：

icon - 40像素宽度
mini - 160像素宽度
normal - 640像素宽度
big - 1280像素宽度
ultra - 2560像素宽度

注意：在某些情况下，表情符号国旗可能比图标大小的图像更有用。使用方法getEmojiForCountryCode()获取正确的字符。

用法

try {
	$cf = new CountryFlag($force);	// force=true rebuilds database table from provided CSV

	$cc->getFlagForCountryCode($code, $size = 'icon');
	$cc->getFlagForCountryName($name, $size = 'icon');
	$cc->getEmojiForCountryCode($code);
	$cc->updateFlagIcon($cc);
	$cc->rebuild();					// rebuild icon cache from CDN source
	$cc->dump($to_file = null);
}

加密器

对称加密函数。本工作使用PHP的OpenSSL实现。

用法

try {
	$cryptor = new Cryptor($bool); // true/false chunked mode

	// before executing any action methods, create an encryption key, to be stored
	// in the location provided in UtilitiesConfig.php
    public static function generateKey($seed_string = null) {

	// use a provided initialization vector instead of an auto-generated one
	$cryptor->setInitializationVector($iv);
	$iv = $cryptor->getInitializationVector();

	// chunked mode
	$cryptor = setChunkMode($boolean);
	
	// encrypt/decrypted provided data
	$blob = $cryptor->encrypt($data);
	$data = $cryptor->decrypt($blob);
	
	// same, but with file artifacts
	$cryptor->encryptFile($fn);
	$cryptor->encryptToFile($fn, $data);
	$cryptor->decryptFile($fn);
	$cryptor->decryptToFile($fn, $blob);
}

MIME类型

在MIME类型标识符（MIME字符串和相关文件扩展名）之间进行转换。

用法

try {
	$mime = new MIMEType();

	$str = $mime->getFileExtensionForType($mime);
	$str = $mime->getTypeforFileExtension($fext);
	$str = $mime->getApplicationForType($mime);
	$bool = $mime->isSimpleContentType($simple_type, $fext);
}

UUID

唯一标识符非常有用。《code>UUID类根据您的特定需求综合了多种标准类型，或者如果您没有需求，则提供支持。

用法

$namespace = '1546058f-5a25-4334-85ae-e68f2a44bbaf';
$str = sha1(mt_rand(0,100000) . "PHP");

// using provided namespace and randomization string

$v3uuid = UUID::v3($namespace, $str);
print "v3: " . $v3uuid . "\n";
$v5uuid = UUID::v5($namespace, $str);
print "v5: " . $v5uuid . "\n";

// using provided namespace

$v3uuid = UUID::v3($namespace);
print "v3: " . $v3uuid . "\n";
$v5uuid = UUID::v5($namespace);
print "v5: " . $v5uuid . "\n";

// using defaults 

$v3uuid = UUID::v3();
print "v3: " . $v3uuid . "\n";
$v5uuid = UUID::v5();
print "v5: " . $v5uuid . "\n";

$v4uuid = UUID::v4();
print "v4: " . $v4uuid . "\n";

print "PHP uniqid: " . uniqid() . "\n";

$ruuid = UUID::next();
print " r: " . $ruuid . "\n";

HttpResponse

了解官方HTTP响应消息文本有时很有帮助，尤其是在记录或报告错误时。提供长文本和短文本的响应字符串。

用法

try {
	$hr = new HttpResponse($force);
	
	if ($hr->httpCodeExists(500)) {
			print "500: " . json_encode($hr->retrieveDescriptions(500)) . "\n";
	}

	// Need to find out if a URL exists and/or has content? Get the descriptive response
	// strings for the URL provided
	$descriptions = $hr->urlResponse($url);
}

URL

PHP的CURL对象的包装。

用法

try {
	$url = new URL();

	// optional on ping(), get(), acquire(); ineffective with post(), put()	
	$uh->setUrl($url);
	
	// useful setters
	$uh->setRequestHeader($name, $content);
	$uh->setCredentials($user, $pass);
	$uh->setTimeout($secs);
	
	$bool = $uh->isLikelyAUrl($string);
	$bool = $uh->lastRequestTimedOut();
	
	// page metadata returned
	$info = $uh->ping($url, $follow = false, $with_hdrs = false);	
	print_r($info);
	
	// 'body' element contains result, other elements are informational
	$res = $uh->get($url, $follow = false, $with_hdrs = false);
	$res = $uh->acquire($url, $follow = false, $with_hdrs = false);

	$res = $uh->post($url, $params, $follow = false);
	$res = $uh->put($url, $params, $follow = false);
	print_r($res);
}

QRCode

生成QRCode图像。请参阅此处的文档。

用法

try {
	$qr = new QRCode();

	// optional setters
	$qr->setCustomProtocol($p);			// to use an app-dependent scheme like 'foo://'
	$qr->setFile($name);				// name of output file
	$qr->setDirectory($directory);		// directory into which output file is loaded
	$qr->setSizeInPixels($size);
	$qr->setFormat($format);			// file type
	$qr->setECC($ecc);
	$qr->setCharset($charset);	
	
	$qr->setData('https://guardianproject.info'); // if custom protocol, just data, no scheme
	$qr->generateQRCode();
}

SiteIcon

检查、获取并存储网站图标（favicons）。使用网站的首页URL进行索引。将提供的URL映射到正确的图标。

用法

try {
	$si = new SiteIcon();
	
	$si->setVerboseMode($bool);

	// get icon for specified site URL, either from local storage (if available) or
	// direct from site.  Store result if found remotely.
	$si->acquireIcon($url, $direct = null);

	// for a given URL, find the website's icon URL
	$si->findIconUrl($url);
		
	// is there a locally-stored icon for this site URL?  If so retrieve it
	if ($si->iconExists($url)) {
		$si->retrieveIcon($url);
		// alternative name
		$si->getIcon($url);
	}
	
	// retrieve icon from site; supply the bits as output
	$bits = $si->captureIcon($url);

	// convert icon bits to base64
	$b64dat = $si->asBase64($icon, $ext);
	
	// save icon bits locally
	$si->saveIcon($url, $ext, $icon_bits);
	
}

PageParser

获取有关网页或网站的有用信息，尤其是RSS feed和meta内容。

用法

try {
	$pp = new PageParser();
	
	$pp->setUrl($url);
	$data = $pp->acquire($url = null);
	
	// does this site offer RSS/Atom feeds?  If so, iterate through them
	if ($pp->hasFeeds()) {
		$feed_url = $pp->getNextFeed();
	} 
	
	// site has meta keywords
	$pp->hasMetas();
	
	// all the information available for the site, as JSON 
	$json = $pp->asJson();
}

RateLimiter

许多服务的提供商禁止用户在给定时间期限内执行过多的请求。此类“限制”API调用的一种简单方式。

注意：对此对象的pause()方法的第一次调用不会被惩罚。pause()算法生成一个“破坏者”列表 - 在这里插入较大的惩罚（1-3秒）以进一步限制访问。但这些相对于MaxCalls速率发生“很少”。

用法

try {
	$throttler = new RateLimiter(true);  // turn it ON
	$throttler->setMaxCallsPerSecond(5); // set rate limit

	$huge = big_long_list_of_requests(); //...your code
	foreach ($huge as $one) {
		$result = $this->my_retriever($one); // your action method
	}
}

private function my_retriever($data) {
	if ($this->throttler->isThrottling()) { $this->throttler->throttle(); }
		//...
		//... your code here
		//...
	}
}

Utilities

一组有用的静态方法。

用法

// log to configured log file using PHP-defined error levels
Utilities::logger($str, $level = E_USER_NOTICE);

// so many hash algorithms to choose, odd assortment supported, figure it out
$bool = Utilities::hashAlgorithmExists($algo);

// reformat (many common) date strings into RFC822 format
$rfc822_str = Utilities::munge_date($str);

DataStore

简化SQL数据库和表的基类（抽象类）。提供的HttpResponse、MIMEType、CountryCode和CountryFlag类是使用示例。

抽象方法

abstract public function __construct($force = false);
abstract public function dump($to_file = null);
abstract protected function load_table();

try {

	$sql->setDatabase($db);
	$sql->setDatafile($file);
	$sql->setTable($table);
	$sql->setDbUser($u);
	$sql->setDbPassword($p);
	$sql->setDbHost($host)
	$sql->setDbPort($port);
	$sql->setDbOptions($options_array);

	// get data from specified column ($field), similar to $str_arg (using SQL LIKE)	
	$data = $sql->retrieveInfoLike($field, $str_arg);

	$sql->rebuild();
	$sql->reload();
	$column_names = $sql->columns();

	// output entire table, or selected columns, as JSON
 	$json = $sql->asJSON($columns = null) {
}

guardianproject / core_utilities

维护者

详细信息