Подключение Gotcha к Joomla: ошибки, производительность и метрики сайта

<extension type="package" method="upgrade">
    <name>PKG_GOTCHA</name>
    <packagename>gotcha</packagename>
    <version>1.2.1</version>
    <scriptfile>script.php</scriptfile>
    <files folder="packages">
        <file type="library" id="gotcha">lib_gotcha.zip</file>
        <file type="plugin" id="gotcha" group="system">plg_system_gotcha.zip</file>
    </files>
</extension>

<extension type="library" method="upgrade">
    <name>LIB_GOTCHA</name>
    <libraryname>gotcha</libraryname>
    <version>1.2.1</version>
    <files>
        <folder>vendor</folder>
    </files>
</extension>

// Зависимости живут в библиотеке пакета (libraries/gotcha), а не в
// папке плагина: так их можно обновлять отдельно и переиспользовать.
require_once JPATH_LIBRARIES . '/gotcha/vendor/autoload.php';

<?xml version="1.0" encoding="utf-8"?>
<extension type="plugin" group="system" method="upgrade">
    <name>PLG_SYSTEM_GOTCHA</name>
    <author>Gotcha</author>
    <authorUrl>https://getgotcha.ru</authorUrl>
    <creationDate>2026-08</creationDate>
    <license>MIT</license>
    <version>1.2.1</version>
    <description>PLG_SYSTEM_GOTCHA_XML_DESCRIPTION</description>
    <namespace path="src">Joomla\Plugin\System\Gotcha</namespace>
    <scriptfile>script.php</scriptfile>
    <files>
        <folder plugin="gotcha">services</folder>
        <folder>src</folder>
        <folder>language</folder>
    </files>
    <languages folder="language">
        <language tag="en-GB">en-GB/plg_system_gotcha.ini</language>
        <language tag="en-GB">en-GB/plg_system_gotcha.sys.ini</language>
        <language tag="ru-RU">ru-RU/plg_system_gotcha.ini</language>
        <language tag="ru-RU">ru-RU/plg_system_gotcha.sys.ini</language>
    </languages>
    <media destination="plg_system_gotcha" folder="media">
        <folder>js</folder>
    </media>
    <config>
        <fields name="params">
            <fieldset name="basic">
                <field name="dsn" type="text" size="60"
                       label="PLG_SYSTEM_GOTCHA_FIELD_DSN_LABEL"
                       description="PLG_SYSTEM_GOTCHA_FIELD_DSN_DESC"/>
                <field name="environment" type="text" default="production"
                       label="PLG_SYSTEM_GOTCHA_FIELD_ENVIRONMENT_LABEL"
                       description="PLG_SYSTEM_GOTCHA_FIELD_ENVIRONMENT_DESC"/>
                <field name="traces_sample_rate" type="text" default="0.2"
                       label="PLG_SYSTEM_GOTCHA_FIELD_TSR_LABEL"
                       description="PLG_SYSTEM_GOTCHA_FIELD_TSR_DESC"/>
                <field name="browser" type="radio" default="1"
                       label="PLG_SYSTEM_GOTCHA_FIELD_BROWSER_LABEL"
                       description="PLG_SYSTEM_GOTCHA_FIELD_BROWSER_DESC"
                       layout="joomla.form.field.radio.switcher">
                    <option value="0">JNO</option>
                    <option value="1">JYES</option>
                </field>
            </fieldset>
        </fields>
    </config>
</extension>

public function preflight(string $type, InstallerAdapter $adapter): bool
{
    if ($type === 'uninstall') {
        return true;
    }

    if (!(new Version())->isCompatible($this->minimumJoomla)) {
        $this->app->enqueueMessage(
            Text::sprintf('PLG_SYSTEM_GOTCHA_ERROR_COMPATIBLE_JOOMLA', $this->minimumJoomla),
            'error'
        );

        return false;
    }

    return true;
}

public function install(InstallerAdapter $adapter): bool
{
    // Включаем плагин сразу после установки: без DSN он полный no-op,
    // а пользователю остаётся только вписать DSN.
    $plugin          = new \stdClass();
    $plugin->type    = 'plugin';
    $plugin->element = $adapter->getElement();
    $plugin->folder  = (string) $adapter->getParent()->manifest->attributes()['group'];
    $plugin->enabled = 1;

    $this->db->updateObject('#__extensions', $plugin, ['type', 'element', 'folder']);

    return true;
}

public function postflight(string $type, InstallerAdapter $adapter): bool
{
    if ($type === 'uninstall') {
        return true;
    }

    $html = '<div class="row m-0">'
        . '<div class="col-12 col-md-8 p-0 pe-3">'
        . '<h2>' . Text::_('PLG_SYSTEM_GOTCHA_AFTER_' . strtoupper($type)) . '</h2>'
        . Text::_('PLG_SYSTEM_GOTCHA_POSTINSTALL_BODY')
        . '</div>'
        . '<div class="col-12 col-md-4 p-0">'
        . '<a class="btn btn-primary w-100" href="https://getgotcha.ru" target="_blank">getgotcha.ru</a>'
        . '<a class="btn btn-outline-primary w-100" href="' . Text::_('PLG_SYSTEM_GOTCHA_LINK_DOCS_URL') . '" target="_blank">'
        . Text::_('PLG_SYSTEM_GOTCHA_LINK_DOCS') . '</a>'
        . '</div></div>';

    $this->app->enqueueMessage($html, 'info');

    return true;
}

PLG_SYSTEM_GOTCHA="System - Gotcha"
PLG_SYSTEM_GOTCHA_AFTER_INSTALL="Спасибо за установку плагина Gotcha!"
PLG_SYSTEM_GOTCHA_POSTINSTALL_BODY="<p>Плагин отправляет в ваш инстанс Gotcha: <strong>ошибки PHP</strong>…</p>"
PLG_SYSTEM_GOTCHA_LINK_DOCS="Документация"
PLG_SYSTEM_GOTCHA_LINK_DOCS_URL="https://getgotcha.ru/docs/sdk/"
PLG_SYSTEM_GOTCHA_ERROR_COMPATIBLE_JOOMLA="Плагин Gotcha совместим с Joomla %s и выше."

<?php

defined('_JEXEC') or die;

use Joomla\CMS\Extension\PluginInterface;
use Joomla\CMS\Factory;
use Joomla\CMS\Plugin\PluginHelper;
use Joomla\DI\Container;
use Joomla\DI\ServiceProviderInterface;
use Joomla\Event\DispatcherInterface;
use Joomla\Plugin\System\Gotcha\Extension\Gotcha;

return new class () implements ServiceProviderInterface {
    public function register(Container $container): void
    {
        $container->set(
            PluginInterface::class,
            function (Container $container) {
                $plugin = new Gotcha(
                    $container->get(DispatcherInterface::class),
                    (array) PluginHelper::getPlugin('system', 'gotcha')
                );
                $plugin->setApplication(Factory::getApplication());

                return $plugin;
            }
        );
    }
};

<?php

namespace Joomla\Plugin\System\Gotcha\Extension;

use Joomla\CMS\Plugin\CMSPlugin;
use Joomla\Event\Event;
use Joomla\Event\SubscriberInterface;
use Sentry\SentrySdk;
use Sentry\Tracing\Transaction;
use Sentry\Tracing\TransactionContext;

\defined('_JEXEC') or die;

final class Gotcha extends CMSPlugin implements SubscriberInterface
{
    private ?Transaction $transaction = null;

    public static function getSubscribedEvents(): array
    {
        return [
            'onAfterInitialise'   => 'init',
            'onAfterRoute'        => 'startTransaction',
            'onError'             => 'captureError',
            'onBeforeCompileHead' => 'injectBrowserSdk',
            'onAfterRespond'      => 'finishTransaction',
        ];
    }

    public function init(): void
    {
        $dsn = trim((string) $this->params->get('dsn', ''));

        if ($dsn === '') {
            return; // пустой DSN — плагин полностью выключен
        }

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

        \Sentry\init([
            'dsn'                => $dsn,
            'environment'        => (string) $this->params->get('environment', 'production'),
            'release'            => 'joomla@' . JVERSION,
            'traces_sample_rate' => (float) $this->params->get('traces_sample_rate', 0.2),
        ]);
    }

    public function startTransaction(): void
    {
        if (!class_exists(SentrySdk::class)) {
            return; // init не отработал — DSN пуст
        }

        $input = $this->getApplication()->getInput();

        // Имя — по компоненту и view, а не по URL: SEF-адресов миллионы,
        // а "эндпойнтов" — десятки. Иначе раздел «Производительность»
        // превратится в свалку уникальных транзакций.
        $name = $input->getCmd('option', 'core') . '.' . $input->getCmd('view', 'default');

        $this->transaction = \Sentry\startTransaction(
            TransactionContext::make()->setName($name)->setOp('http.server')
        );
        SentrySdk::getCurrentHub()->setSpan($this->transaction);
    }

    public function captureError(Event $event): void
    {
        if (!class_exists(SentrySdk::class)) {
            return;
        }

        // В Joomla 4/5 это ErrorEvent с getError(); generic-доступ через
        // 'subject' работает и там, и в Joomla 6.
        $error = method_exists($event, 'getError')
            ? $event->getError()
            : $event->getArgument('subject');

        if (!$error instanceof \Throwable) {
            return;
        }

        // 401/403/404/405 — обычный веб-шум (сканеры, битые ссылки),
        // а не ошибки приложения.
        if (\in_array((int) $error->getCode(), [401, 403, 404, 405], true)) {
            return;
        }

        \Sentry\captureException($error);
    }

    public function injectBrowserSdk(): void
    {
        $app = $this->getApplication();
        $dsn = trim((string) $this->params->get('dsn', ''));

        if ($dsn === '' || !(bool) $this->params->get('browser', 1) || !$app->isClient('site')) {
            return;
        }

        $wa = $app->getDocument()->getWebAssetManager();
        $wa->registerAndUseScript('plg_system_gotcha.sdk', 'plg_system_gotcha/sentry.min.js');
        $wa->addInlineScript(
            'Sentry.init({'
            . 'dsn: ' . json_encode($dsn) . ','
            . 'environment: ' . json_encode((string) $this->params->get('environment', 'production')) . ','
            . 'integrations: [Sentry.browserTracingIntegration()],'
            . 'tracesSampleRate: ' . (float) $this->params->get('traces_sample_rate', 0.2)
            . '});',
            [],
            [],
            ['plg_system_gotcha.sdk']
        );
    }

    public function finishTransaction(): void
    {
        if ($this->transaction === null) {
            return;
        }

        $this->transaction->setHttpStatus(http_response_code());
        $this->transaction->finish();
    }
}

npm i @sentry/browser esbuild
npx esbuild <(echo "export * from '@sentry/browser'") \
  --bundle --minify --format=iife --global-name=Sentry \
  --outfile=media/js/sentry.min.js

// scoper.inc.php
return [
    'prefix' => 'Gotcha\\Vendor',
    'finders' => [
        Finder::create()->files()->in('vendor'),
        Finder::create()->files()->name('*.php')->in('plugin/src'),
    ],
    // Namespace самого плагина не трогаем — по нему Joomla его находит.
    // Ссылки на Sentry внутри наших файлов php-scoper перепишет сам.
    'exclude-namespaces' => ['Joomla'],
];

./build.sh          # composer install -> php-scoper -> два zip -> пакет

#!/bin/bash
USERS=$(mysql -N -e "SELECT COUNT(*) FROM j_users" joomla_db)
curl -s -X POST https://gotcha.example.com/v1/metrics \
  -H "Authorization: Bearer <public_key>" \
  -H "Content-Type: application/json" \
  -d '{"resourceMetrics":[{"resource":{"attributes":[
        {"key":"service.name","value":{"stringValue":"joomla-site"}}]},
      "scopeMetrics":[{"metrics":[{"name":"users_total","gauge":{"dataPoints":[
        {"asDouble":'"$USERS"',"timeUnixNano":"'"$(date +%s%N)"'"}]}}]}]}]}'