README

The PHP package to interact with Telegra.ph.

Telegra.ph is a minimalist publishing tool that allows you to create richly formatted posts and push them to the Web in just a click.

Requirements

PHP >= 5.6

Installation

composer require nullform/telegraphus

Usage examples

First you need to create an account and get an access token:

use Nullform\Telegraphus\ApiClient;
use Nullform\Telegraphus\Types\Account;

$client = new ApiClient();

$account = new Account();
$account->author_name = 'John Doe';
$account->author_url = 'https://www.google.com/';
$account->short_name = 'john';

try {

    $client->createAccount($account);
    $token = $account->access_token;

    $client->setToken($token);

    // ...

} catch (\Exception $exception) {
    // ...
}

Next, you can create pages using the parser to convert your HTML code into Telegra.ph format.

use Nullform\Telegraphus\ApiClient;
use Nullform\Telegraphus\Parser;

$token = 'token';
$client = new ApiClient($token);
$html = '<h1>Title</h1>'
    . '<div>First paragraph</div>'
    . '<div>Second <span>paragraph</span></div>'
    . '<footer>Copyright</footer>';

// Note that not all HTML tags are available in Telegra.ph.
// Available tags: a, aside, b, blockquote, br, code, em, figcaption, figure, h3, h4,
// hr, i, iframe, img, li, ol, p, pre, s, strong, u, ul, video.

$parser = new Parser();

// You can replace or delete tags
$parser->addTagReplaceRules([
    'h1'     => 'h3',  // Convert <h1> to <h3>
    'div'    => 'p',   // Convert <div> to <p>
    'span'   => 'b',   // Convert <span> to <b>
    'footer' => false, // Remove <footer>
]);

try {

    $page = $client->createPage(
        'Test page',
        $parser->htmlToTelegraphContent($html)
    );

    // ...

} catch (\Exception $exception) {
    // ...
}

After a successful request, Telegra.ph will create a page with the title "Test Page" and the following content:

<h3>Title</h3>
<p>First paragraph</p>
<p>Second <b>paragraph</b></p>

You can pass HTML code as content to the createPage() method. But then the HTML code will be converted to Telegra.ph format "as is", without replacing tags.

Don't forget that Telegra.ph doesn't support all tags, only the following: a, aside, b, blockquote, br, code, em, figcaption, figure, h3, h4, hr, i, iframe, img, li, ol, p, pre, s, strong, u, ul, video.

And now you can get a list of all your pages:

use Nullform\Telegraphus\ApiClient;

$token = 'token';
$client = new ApiClient($token);

try {

    $pageList = $client->getPageList();

    foreach ($pageList->pages as $page) {
        // ...
    }

} catch (\Exception $exception) {
    // ...
}

If you want to edit one:

use Nullform\Telegraphus\ApiClient;

$token = 'token';
$client = new ApiClient($token);
$html = '<p>New page content</p>';
$path = 'page path';

try {

    $page = $client->editPage($path, 'Test page', $html);

    // ...

} catch (\Exception $exception) {
    // ...
}

Methods

ApiClient

ApiClient::__construct(?string $token = null)
ApiClient::setToken(?string $token): ApiClient
ApiClient::getToken(): ?string
ApiClient::getCurlOptions(): array
ApiClient::setCurlOptions(array $curlOptions): ApiClient
ApiClient::setCurlOption(int $option, mixed $value): ApiClient
ApiClient::getCurlInfo(): array
ApiClient::createAccount(Account $account): Account
ApiClient::editAccountInfo(Account $account): Account
ApiClient::getAccountInfo(): Account
ApiClient::revokeAccessToken(): Account
ApiClient::createPage(string $title, NodeElement[]|string $content, ?string $authorName = null, ?string $authorUrl = null): Page
ApiClient::editPage(string $path, string $title, NodeElement[]|string $content, ?string $authorName = null, ?string $authorUrl = null): Page
ApiClient::getPage(string $path): Page
ApiClient::getPageList(int $offset = 0, int $limit = 50): PageList
ApiClient::getViews(string $path, ?GetViewsParams $params): PageViews

Parser

Parser::addTagReplaceRule(string $tag, string $toTag): Parser
Parser::addTagReplaceRules(array $rules): Parser
Parser::hasTagReplaceRule(string $tag): bool
Parser::getTagReplaceRule(string $tag): string|false|null
Parser::setAllowedAttributes(?string[] $attributes): Parser
Parser::setDisallowedAttributes(string[] $attributes): Parser
Parser::htmlToTelegraphContent(string $html): NodeElement[]|string[]
Parser::telegraphContentToHtml(NodeElement[] $content): string
Parser::decodeTelegraphContent(string $json): NodeElement[]

Tests

Tested on PHP 5.6, 7.2 and 8.0.

php composer.phar test tests

nullform / telegraphus

Maintainers

Details