Библиотека для взаимодействия с API проверки уникальности текстов сервиса text.ru

Все описываемые ниже классы пакета располагаются в пространстве имен TextMedia\PlagiarismApi, поэтому далее это не упоминается, и адресация классов ведётся относительно этого значения.

Установка

Для работы библиотеки требуется php версии 7.0 и выше и наличие расширения json (включено по умолчанию, начиная с версии PHP 5.2.0); все нижеперечисленные методы установки одинаково работоспособны, т.к. пакет не имеет каких-либо других зависимостей.

Из packagist

cd my-project-folder
composer require text-media/plagiarism-api

Далее в своем скрипте подключаем автозагрузчик классов:

require_once(__DIR__ . '/vendor/autoload.php');

Этот метод единственно гарантирует стабильность работы, т.к. в Packagist публикуются только стабильные версии, при использовании же нижеследующих способов можно получить нестабильную версию, находящуюся на стадии разработки/тестирования, либо же версия будет устаревшая, не включающая в себя весь функционал.

Обновление пакета до последней версии:

cd my-project-folder
composer update text-media/plagiarism-api

Установка composer - см. Download Composer; например:

wget -O composer-setup.php https://getcomposer.org/installer
sudo php composer-setup.php --install-dir=/bin --filename=composer
rm -f composer-setup.php

Из репозитория

cd my-project-folder
git clone git@bitbucket.org:text-media/plagiarism-api.git

Добавить автозагрузчик классов в свой скрипт:

require_once "{$my_project_folder}/plagiarism-api/autoload.php";

Обновление:

cd my-project-folder/plagiarism-api
git pull

Из архива

Обновление: повторить все перечисленные выше шаги (кроме последнего пункта).

Из phar

require_once "phar://{$path_to_phar}/tmpa.phar";

Обновление:

TMPA=cli /usr/bin/env php /path/to/tmpa.phar self_update

Данный архив так же может использоваться для отправки API запросов из командной строки (см. Консоль).

Для работы потребуются два расширения PHP: phar и bz2.

На php5

Библиотека написана под php версии 7.0 и выше. Тем не менее, она способна работать и с версией 5.x. Это возможно только, если устанавливать ее любым из перечисленных выше способов, кроме из packagist:

Установка при помощи composer так же возможна, но для этого потребуется вручную отредактировать composer.json в корне проекта, чтобы он включал в себя следующие настройки:

{
    "repositories": [
        {
            "type": "git",
            "url":  "git@bitbucket.org:text-media/plagiarism-api.git"
        }
    ],
    "require": {
        "text-media/plagiarism-api": "dev-php5"
    }
}

Применение

Проверка баланса пакетов

Внимание! В целях безопасности, чтобы ваш IP-адрес не заблокировался, не рекомендуется обращаться к данному методу чаще 2 раз в минуту.

use Exception;
use TextMedia\PlagiarismApi\Client;
use TextMedia\PlagiarismApi\Exception\ClientException;
use TextMedia\PlagiarismApi\Exception\RequestException;
use TextMedia\PlagiarismApi\Exception\ResponseException;
use TextMedia\PlagiarismApi\Exception\ServerException;
use TextMedia\PlagiarismApi\Exception\TransportException;

try {
    $client   = new Client('my-api-key');
    $response = $client->getPackageBalance();
    echo "Баланс: {$response->getSize()}\n";
} catch (ServerException $ex) {
    echo "Ошибка API: [{$ex->getCode()}] {$ex->getMessage()}.\n";
    if ($ex->requiresToStop()) {
        echo "Нужно прекратить выполнять любые запросы к серверу.\n";
    } elseif ($ex->requiresToWait()) {
        echo "Нужно подождать какое-то время.\n";
    } elseif ($ex->requiresToSkip()) {
        echo "Нужно прекратить пытаться выполнять данный запрос.\n";
    } else {
        echo "Прочие ошибки сервера.\n";
    }
} catch (ClientException $ex) {
    echo "Неправильно настроен клиент API.\n";
} catch (TransportException $ex) {
    echo "Либо неправильно настроен транспорт до сервера API,";
    echo "либо возможно просто сервер временно недоступен";
    echo "(ошибка обмена данными) - попробуем позже еще раз.\n";
} catch (RequestException $ex) {
    echo "Неправильно сформирован запрос - требуется правка скрипта!\n";
} catch (ResponseException $ex) {
    echo "Что-то не то с ответом от API - требуется отладка!\n";
} catch (Exception $ex) {
    echo "Все прочие ошибки, не связанные непосредственно с пакетом.\n";
}

Данный шаблон можно использовать для всех видов запросов для правильной реакции на ответы/ошибки, поэтому в последующих примерах все перечисленные операции перехвата исключений и проверки ошибок опускаются - даются только примеры отправки запросов и анализа ответов на них в случае успеха.

Отправка текста на проверку

use TextMedia\PlagiarismApi\Client;
use TextMedia\PlagiarismApi\Request;

$client = new Client('my-api-key');
$result = $client->sendTextToCheck([
    Request::OPT_TEXT           => file_get_contents('/path/to/file.txt'),
    Request::OPT_EXCEPT_DOMAINS => [
        'my.site.tld',
        'www.my.site.tld',
    ],
]);

echo "UID текста: {$result->getTextUid()}\n";

Получение результата проверки

use TextMedia\PlagiarismApi\Client;
use TextMedia\PlagiarismApi\Request;

$client = new Client('my-api-key');
$result = $client->getPlagiarismResult([
    Request::OPT_TEXT_UID        => 'text-uid',
    Request::OPT_DETAILED_RESULT => true,
]);

echo "Уникальность текста: {$result->getUniqueness()}%\n";

if ($result->isSeoAnalyzeComplete()) {
    $seo = $result->getSeoAnalyzeDetail();
    echo "Процент воды: {$seo->getWaterPercent()}%\n";
    echo "Процент спама: {$seo->getSpamPercent()}%\n";
} else {
    echo "SEO-анализ текста еще не выполнен.\n";
}

if ($result->isSpellingComplete()) {
    $spell = $result->getSpellingDetail();
    echo "Обнаружено орфографических ошибок: " . count($spell) . "\n";
} else {
    echo "Проверка орфографии еще не завершена.\n";
}

Клиент

Класс: Client.

Оба аргумента конструктора опциональны:

Параметр $data методов sendTextToCheck и getPlagiarismResult могут быть либо объектом-запросом соответствуещего класса, либо массивом для формирования такого объекта.

Транспорт

Интерфейс: Transport\TransportInterface.

Классы данного типа предназначены осуществлять обмен данными с API, т.е. собственно отправлять запрос, получать и возвращать ответ.

Пакет включает в себя три реализации транспорта:

Метод Transport\AbstractTransport::getDefault($timeout) сам определит, какой из перечисленных выше транспортов доступен и вернет его (перебирает в том же порядке до тех пор, пока не найдет подходящий); если не найдет - будет выброшено исключение Exception\TransportException.

Запросы

Интерфейс: Request\RequestInterface.

Формат описания запросов (полей массива, передаваемого в конструктор):

Проверка баланса пакетов

Класс: Request\PackageBalanceRequest.

Никаких параметров не требует.

Отправка текста на проверку

Класс: Request\CheckTextRequest.

Получение результата проверки

Класс: Request\PlagiarismResultRequest.

Ответы

Интерфейс: Response\ResponseInterface.

Проверка баланса пакетов

Класс: Response\PackageBalanceResponse.

Отправка текста на проверку

Класс: Response\CheckTextResponse.

Получение результата проверки

Класс: Response\PlagiarismResultResponse.

Детальная информация по результатам проверки (последние два метода и некоторые данные во втором) возвращается только при указании опции OPT_DETAILED_RESULT в запросе. Если опция была указана, но методы все еще возвращают NULL - значит соответствующие проверки еще не завершились, нужно подождать и отправить запрос повторно.

Сложные структуры данных ответа оборачиваются в специальные классы из пространтва имен Response\Detail, которые являясь по факту частью ответа, содержат в себе только геттеры.

Общие методы (кроме Response\Detail\PercentDetail):

Информация об уникальности

Класс: Response\Detail\PlagiarismDetail.

Очищенный текст (последний метод) возвращается только при указании опции OPT_DETAILED_RESULT в запросе. Параметр $cut этого метода отвечает за то, будет ли возвращена просто строка или массив слов.

Процент совпадения со ссылкой

Класс: Response\Detail\MatchLinkDetail.

Информация о правописании

Класс: Response\Detail\SpellingDetail.

Информация по SEO-анализу

Класс: Response\Detail\SeoAnalyzeDetail.

Информация о ключе в тексте.

Класс: Response\Detail\TextKeyDetail.

Ключи бываают простыми (состоят из одного слова) и сгруппированными по составу слов (представляют собой фразу). Список простых подключей имеется только в сгруппированном; в простом метод getSubKeys вернет NULL.

Процентные значения

Класс: Response\Detail\PercentDetail.

В этот класс оборачиваются все значения процентов чего бы то ни было. Доступные типы и их границы "плохой"/"хороший" перечислены в константах класса; границы аналогичны тем, которые используются на офсайте для подстветки результатов проверки:

Исключения

В случае возникновения любых ошибок выбрасываются исключения:

Метод getDebugInfo() возвращает информацию о том, при обработке чего произошла ошибка.

Exception\ServerException имеет дополнительно три метода, проверяющие тип Ошибки:

Коды ошибок на стороне сервера API ($serverException->getCode()) и их значение см. на странице описания API или в документе doc/api/ru.md репозитория.

Если текст ещё не проверен, и выброшено исключение Exception\ServerException с кодом 81, то для получения дополнительной информации доступны следующие два метода:

Callback

Callback\CallbackTemplate и Callback\CallbackTrait являются шаблонами основным методом которых является process(), принимающий необязательный параметр $rawData, и формирующий на основе его внутреннее свойство класса Response\PlagiarismResultResponse; если $rawData не передано, то автоматически по умолчанию данные берутся из $_POST.

Данные шаблоны имеют абстрактные protected-методы, которые должны реализовать их потомки:

Оба метода должны вернуть ответ типа:

Конструкторы первых двух классов аргументов не имеют; последнего - число секунд, сколько нужно подождать перед повтором.

Внимание! На данный момент сервером API реализовано правильное поведение только на ответ типа Callback\CallbackPassed; остальные - считаются ошибкой принимающей стороны, т.е. будут выполнены повторные запросы.

Пример реализации класса-callback-а:

use TextMedia\PlagiarismApi\Callback;

class MyTmauCallback extends Callback\CallbackTemplate
{
    /**
     * Анализируем $this->plagiarism.
     */
    protected function onReceipt(): Callback\CallbackResponse
    {
        // … собственно анализ и попытка сохранения

        if (/* все нормально - запрос проанализирован и результат сохранен */) {
            return new Callback\CallbackPassed;
        } elseif (/* что-то случилось - нет такого текста, например */) {
            return new Callback\CallbackFailed;
        } else /* временные проблемы - нужно повторить запрос позднее */ {
            return new Callback\CallbackRetry(
                /* сколько секунд подождать до повтора запроса */
            );
        }
    }

    /**
     * Анализируем $this->exception и $this->rawData.
     */
    protected function onError(): Callback\CallbackResponse
    {
        // Проверяем что-то в переданных данных, исключении,
        // из-за чего возникла ошибка; логируем, если надо и т.п.
        // В конце - ответ по типу как в onReceipt.
    }
}

Пример контроллера в CodeIgniter - это может быть файл в папке application/controller/ такого вида:

class tmau_callback extends CI_Controller
{
    public function __construct()
    {
        parent::__construct();
        (new MyTmauCallback)->process($this->input->post());
    }
}

Вместо создания двух раздельных классов - отдельно Callback-а, отдельно контроллера - можно скомбинировать их при помощи трейта Callback\CallbackTrait. В Symfony это может быть файл из папки src/Controller/ вида:

namespace App\Controller;

use Symfony\Bundle\FrameworkBundle\Controller\Controller;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\Routing\Annotation\Route;
use TextMedia\PlagiarismApi\Callback;

class TmauCallbackController extends Controller
{
    use Callback\CallbackTrait;

    /**
     * @param Symfony\Component\HttpFoundation\Request $request
     * @Route("/tmau_callback", methods={"POST"})
     */
    public function index(Request $request)
    {
        $this->process($request->request->all());
    }

    /**
     * Анализируем $this->plagiarism.
     */
    protected function onReceipt(): Callback\CallbackResponse
    {
        // … пример см. выше
    }

    /**
     * Анализируем $this->exception и $this->rawData.
     */
    protected function onError(): Callback\CallbackResponse
    {
        // … пример см. выше
    }
}

Консоль

Для этого понадобится phar-архив (см. установку Из phar).

Пример использования:

TMPA=cli /usr/bin/env php /path/to/tmpa.phar plagiarism_result\
    --userkey=my-api-key\
    --uid=my-text-uid\
    --jsonvisible=detail\
    --retun=result_json

Результат успешно выполненного запроса выводится в /dev/stdout; тексты ошибок выводятся в /dev/stderr в виде <имя класса исключения>[<код исключения>]: <описание исключения>.

Список доступных команд и их опций выводится при обращении к скрипту без параметров.