README

Brush 是 Pastebin API 的一个完整的面向对象的 PHP 包装器。

特性

• 直接从文件创建粘贴，自动检测语言。
• 轻松将默认账户设置应用到新粘贴。
• 高性能，具有积极缓存。
• 端到端 UTF-8 支持。

依赖项

• PHP 5.3.0+
• cURL

安装

不需要 Composer，但是 Brush 在 Packagist 上，并且可以通过以下方式添加到项目中：

composer require gebn/brush "1.*"

入门指南

创建匿名粘贴

以下是一个最小示例，展示了如何提交新的粘贴

require 'Brush/Brush.php';

use \Brush\Pastes\Draft;
use \Brush\Accounts\Developer;
use \Brush\Exceptions\BrushException;

$draft = new Draft(); // drafts represent unsent pastes
$draft->setContent('Some random content'); // set the paste content

// the Developer class encapsulates a developer API key; an instance
// needs to be provided whenever Brush might interact with Pastebin
$developer = new Developer('<developer key>');

try {
	// send the draft to Pastebin; turn it into a full blown Paste object
	$paste = $draft->paste($developer);

	// print out the URL of the new paste
	echo $paste->getUrl(); // e.g. https://pastebin.com/JYvbS0fC
}
catch (BrushException $e) {
	// some sort of error occurred; check the message for the cause
	echo $e->getMessage();
}

以下几点需要注意

• 您只需要 require Brush.php；Brush 有一个自动加载器，它会为您处理其他包含。
• Draft 类代表尚未提交到 Pastebin 的粘贴。它具有设置器，允许您为新粘贴配置所有可能的选项，包括过期、格式和可见性。
• Developer 类代表开发者账户。在 Brush 可能与 Pastebin API 交互的所有情况下，都需要传递一个实例。
• 当在草稿上调用 paste() 时，Brush 会检查基本错误，然后尝试将草稿发送到 Pastebin。如果检测到错误（例如没有内容设置），则会抛出 ValidationException。
• Brush 抛出的所有异常都扩展了 BrushException。这允许您在单个 catch 子句中轻松处理所有可能的错误，或者使用多个子句进行更细致的处理。
• 一旦草稿被 paste()，Brush 将自动创建并返回一个 Paste 对象，无需与 Pastebin API 进行任何进一步交互。该对象包含有关粘贴的所有信息，包括其密钥、URL 和过期日期。
• Draft 的 paste() 方法可以安全地多次调用，如果需要，可以在调用之间更改草稿。
• 有关完整的方法参考，请参阅 METHODS.md。

创建私有粘贴

私有粘贴必须与账户相关联，但 Brush 使其设置变得简单

require 'Brush/Brush.php';

use \Brush\Accounts\Developer;
use \Brush\Accounts\Account;
use \Brush\Accounts\Credentials;
use \Brush\Pastes\Draft;
use \Brush\Pastes\Options\Visibility;
use \Brush\Exceptions\BrushException;

// this time, create a draft directly from a file
$draft = Draft::fromFile('passwords.txt');

// an Account object represents a Pastebin user account
$account = new Account(new Credentials('<username>', '<password>'));

// link the draft to the account
$draft->setOwner($account);

// specify that we don't want this paste to be publicly accessible
$draft->setVisibility(Visibility::VISIBILITY_PRIVATE);

// the Developer class manages a developer key
$developer = new Developer('<developer key>');

try {
	// submit the draft and retrieve the final paste in the same way as above
	$paste = $draft->paste($developer);

	// print out the key of the newly created paste
	echo $paste->getKey();
}
catch (BrushException $e) {
	echo $e->getMessage();
}

Account 类代表 Pastebin 账户。在最基本的层面上，它管理用户会话密钥，在执行影响特定账户的操作时必须提供。可以通过两种方式创建实例

1. 通过一组凭证，如上所述。当首次需要时，Brush 将向 Pastebin 发送 HTTP 请求以检索新的用户密钥，并将其缓存到执行结束。
2. 直接通过将一个会话密钥字符串作为 Account 构造函数的唯一参数传递。这可以节省请求，如果您始终想与同一个账户一起工作，这是一种推荐的方法。

在上面的示例中，我们不是手动编写草稿，而是要求 Brush 从本地文件自动创建一个。Brush 将草稿标题设置为文件名，内容为文件内容，并尝试从文件的扩展名识别格式。它用于此目的的映射在 Configuration/extensions.ini 中。这是设计给您编辑的，所以请随意根据您的需求添加行。如果您添加了大量的映射，请考虑通过拉取请求贡献它们，以便其他人也能从中受益！

您还可以使用 fromOwner(Account, Developer) 方法创建一个继承账户默认设置的草稿。这将检索提供的账户的默认设置，应用于新的草稿，并将账户设置为所有者。

检索账户的粘贴

检索属于账户的粘贴很简单

require 'Brush/Brush.php';

use \Brush\Accounts\Account;
use \Brush\Accounts\Developer;
use \Brush\Exceptions\BrushException;

$account = new Account('<user session key>');
$developer = new Developer('<developer key>');

try {
	// retrieve the first 50 (see below) account pastes
	$pastes = $account->getPastes($developer);

	// print out the name of each paste followed by a line feed
	foreach ($pastes as $paste) {
		echo $paste->getTitle(), "\n";
	}
}
catch (BrushException $e) {
	echo $e->getMessage();
}

Account 的 getPastes() 方法返回一个代表由该账户提交的粘贴的 Paste 对象数组。它接受一个可选的第二个参数，即要检索的粘贴的最大数量，默认为 50。

删除粘贴

通过上述方式检索到的粘贴可以通过调用其上的 delete() 方法来删除。

require 'Brush/Brush.php';

use \Brush\Accounts\Account;
use \Brush\Accounts\Developer;
use \Brush\Exceptions\BrushException;

$account = new Account('<user session key>');
$developer = new Developer('<developer key>');

try {
	// retrieve up to 10 account pastes
	$pastes = $account->getPastes($developer, 10);

	// delete each one
	foreach ($pastes as $paste) {
		$paste->delete($developer);
		echo 'Deleted ', $paste->getKey(), "\n";
	}
}
catch (BrushException $e) {
	echo $e->getMessage();
}

注意。由于认证原因，只能删除从账户中检索到的粘贴。如果您尝试删除通过其他方式获得的粘贴（例如热门粘贴），Brush 会检测到这一点并抛出 ValidationException，因为 Pastebin 会简单地拒绝请求。Brush 总会尝试在麻烦 Pastebin 之前警告您错误。

检索热门粘贴

require 'Brush/Brush.php';

use \Brush\Accounts\Developer;
use \Brush\Pastes\Trending;
use \Brush\Exceptions\BrushException;

$developer = new Developer('<developer key>');

try {
	// retrieve an array of the top 18 currently trending pastes
	$pastes = Trending::getPastes($developer);

	// print out the titles and hit counts of each one
	foreach ($pastes as $paste) {
		printf("%-70s%d\n", $paste->getTitle(), $paste->getHits());
	}
}
catch (BrushException $e) {
	echo $e->getMessage();
}

贡献

欢迎提出建议和拉取请求。请通过正常的 GitHub 通道提交这些内容。

如果您发现了一个错误，请打开新问题。

许可

Brush 在 MIT 许可证下发布 - 有关详细信息，请参阅 LICENSE 文件。有关如何使用此许可证的更多信息，请参阅 维基百科文章。