Skip to content

API Reference

Jump to bottom
cyvax edited this page May 23, 2026 · 1 revision

API Reference

All clients delegate to the same core engine.

Multiple client classes are provided for different coding styles and preferences:

Class Style
Cyvax\Clients\Privatebin camelCase methods
Cyvax\Clients\PrivatebinSnakeCase snake_case methods
Cyvax\Clients\PrivatebinPipe functional pipe-style API (PHP 8.5+)

PrivatebinCore

Cyvax\Internal\PrivatebinCore is the underlying engine and can be extended or used directly to build custom clients.

Constructor:

new PrivatebinCore(
    array $options = [],
    ?HttpClientInterface $httpClient = null,
    ?PasteEncryptorInterface $encryptor = null,
)

Extending it lets you override only the methods you need:

use Cyvax\Internal\PrivatebinCore;

class MyCore extends PrivatebinCore
{
    public function post(array $data): array
    {
        // custom logic
        return parent::post($data);
    }
}

All clients already accept a custom HttpClientInterface and PasteEncryptorInterface via their constructor, no custom core needed just for that:

// Custom HTTP client
$client = new Privatebin([], new MyHttpClient());
// Custom encryptor
$client = new Privatebin([], null, new MyEncryptor());

Extending PrivatebinCore should only be done when you need to override operation logic.

$core = new MyCore(['url' => 'https://privatebin.net/']);
$result = $core->setText('Hello!')->encodeAndPost();

Writing

encode(): array

Encrypts the current payload and returns it ready to pass to post().

Returns:

[
    'data' => [
        'v' => 2,
        'adata' => [...], // auth data (nonce, salt, formatter, flags…)
        'ct' => '...',    // base64-encoded ciphertext + GCM tag
        'meta' => ['expire' => '1day'],
    ],
    'b58' => 'Base58EncodedKey', // decryption key - share alongside the paste URL
]

Throws: PrivatebinException if text and attachment are both empty, or if encryption fails.

post(array $data): array

Posts an encoded payload (from encode()) to the PrivateBin instance.

Parameters:

  • $data - the array returned by encode()

Returns:

[
    'requests_result' => object { ... }, // raw PrivateBin server response
    'b58' => 'Base58EncodedKey',
]

requests_result is the raw server response. See the PrivateBin API docs for the full response schema.

Throws: PrivatebinException on cURL failure or wrong input.

encodeAndPost(): array

Shorthand for post(encode()). Returns the same shape as post().

Reading

fetch(string $id): array

Fetches a paste's raw encrypted payload from the PrivateBin server via GET ?pasteid={id}.

Parameters:

  • $id - the paste ID (from requests_result->id)

Returns: The decoded JSON from the server (adata, ct, v, meta, …). See the PrivateBin API docs for the full payload schema.

Throws: PrivatebinException if the paste does not exist, has been burned, or the request fails.

decrypt(array $fetchResult, string $b58, ?string $password = null): array

Decrypts a raw payload returned by fetch().

Parameters:

  • $fetchResult - array returned by fetch()
  • $b58 - Base58-encoded decryption key (from the paste URL fragment or encode())
  • $password - optional password, if the paste was posted with one

Returns:

[
    'paste' => 'Hello, world!',
    'attachment' => null,      // or 'data:text/plain;base64,…'
    'attachment_name' => null, // or 'file.txt'
]

Throws: PrivatebinException if decryption fails (wrong key or password).

fetchAndDecrypt(string $id, string $b58, ?string $password = null): array

Shorthand for decrypt(fetch($id), $b58, $password). Returns the same shape as decrypt().

Setters

All setters return $this for fluent chaining.

camelCase snake_case Type Default Notes
setUrl() set_url() string https://paste.i2pd.xyz/
setText() set_text() string ''
setPassword() set_password() string null
setExpire() set_expire() string, bool '1day', false
setFormatter() set_formatter() string, bool 'plaintext', false
setCompression() set_compression() string 'zlib'
setDiscussion() set_discussion() bool false
setBurn() set_burn() bool false
setAttachment() set_attachment() string, ?string - Throws PrivatebinException if the file cannot be read
setDebug() set_debug() bool false
setSslVerify() set_ssl_verify() bool true Disable only for local or self-signed instances

Valid option values

expire

5min · 10min · 1hour · 1day · 1week · 1month · 1year · never

Pass $bypass = true to use a value outside this list.

formatter

plaintext · syntaxhighlighting · markdown

Pass $bypass = true to use a value outside this list.

compression

zlib · none

zlib requires ext-zlib. A PrivatebinException is thrown at encrypt/decrypt time if the extension is missing. Use none when ext-zlib is unavailable.

Exceptions

All methods that communicate with the server or perform cryptographic operations may throw Cyvax\Exceptions\PrivatebinException.

Cause Method
Empty paste (no text, no attachment) encode()
Burn and discussion both enabled encode()
Encryption failure encode()
File cannot be read setAttachment()
ext-zlib missing, compression=zlib encode(), decrypt()
cURL error post(), fetch()
Wrong data passed to post() post()
Paste not found / burned fetch()
Wrong key or password decrypt() 
use Cyvax\Exceptions\PrivatebinException;

try {
    $result = (new Privatebin())
        ->setUrl('https://privatebin.net/')
        ->setText('Hello!')
        ->encodeAndPost();
} catch (PrivatebinException $e) {
    echo $e->getMessage();
}

Encryption details

Parameter Value
Algorithm AES-256-GCM
Key derivation PBKDF2-SHA256, 100 000 iterations, 32-byte key
Nonce 16 random bytes
Salt 8 random bytes
GCM tag 16 bytes, appended to ciphertext
Key encoding Base58
Compression DEFLATE raw (zlib) or none
Payload format PrivateBin v2 ("v": 2)

Clone this wiki locally