plugin.php

<?php

/**
 * Keyword Gap Analyzer plugin for Bludit: analyzes configured keywords across content
 * and offers quick links to create missing posts.
 *
 * MIT License
 * Copyright (c) 2025 magimarcy
 *
 * Permission is hereby granted, free of charge, to any person obtaining a copy
 * of this software and associated documentation files (the "Software"), to deal
 * in the Software without restriction, including without limitation the rights
 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 * copies of the Software, and to permit persons to whom the Software is
 * furnished to do so, subject to the following conditions:
 *
 * The above copyright notice and this permission notice shall be included in
 * all copies or substantial portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 * THE SOFTWARE.
 */
class pluginKeywordGapAnalyzer extends Plugin
{
  /**
   * Initialize default configuration fields.
   */
  public function init()
  {
    // Plugin configuration fields
    $this->dbFields = array(
      'rawKeywords'      => '',
      'matchMode'        => 'phrase', // phrase | all | any
      'includeScheduled' => '1',      // '1' = include scheduled posts, '0' = only published
      'goodThreshold'    => '3',      // minimum hits to mark a keyword as "well covered"
      'sortMode'         => 'input'   // input | status
    );
  }

  /**
   * Add navigation link in the admin sidebar.
   *
   * @return string
   */
  public function adminSidebar()
  {
    global $L;

    $pluginName = $this->className();
    $url = HTML_PATH_ADMIN_ROOT . 'configure-plugin/' . $pluginName;

    $html  = '<a class="nav-link" href="' . $url . '">';
    $html .= '<span class="oi oi-share-boxed" aria-hidden="true"></span> ';
    $html .= $L->get('kga-sidebar-label');
    $html .= '</a>';

    // https://magicmarcy.de/admin/configure-plugin/pluginkeywordgapanalyzer
    // https://magicmarcy.de/admin/configure-plugin/pluginKeywordGapAnalyzer

    return $html;
  }

  /**
   * Prefill tags on the new-content page when a keyword was selected in the table.
   *
   * @return string JavaScript injected into the admin head
   */
  public function adminHead()
  {
    $cssPath = $this->domainPath() . 'css/keyword-gap-analyzer.css';
    $jsPath  = $this->domainPath() . 'js/keyword-gap-analyzer.js';
    $html = '<link rel="stylesheet" href="' . $cssPath . '">';
    $html .= '<script src="' . $jsPath . '"></script>';

    return $html;
  }

  /**
   * Render the admin configuration form and the keyword analysis table.
   *
   * @return string
   */
  public function form()
  {
    global $L;

    // Load current settings
    $rawKeywords = $this->getValue('rawKeywords');
    $matchMode   = $this->getValue('matchMode');
    if (empty($matchMode)) {
      $matchMode = 'phrase';
    }

    $includeScheduled = $this->getValue('includeScheduled');
    if ($includeScheduled === '') {
      $includeScheduled = '1';
    }

    $goodThreshold = (int)$this->getValue('goodThreshold');
    if ($goodThreshold <= 0) {
      $goodThreshold = 3;
    }

    $sortMode = $this->getValue('sortMode');
    if ($sortMode === '') {
      $sortMode = 'input';
    }

    // Parse keywords and groups
    $parsed      = $this->parseKeywords($rawKeywords);
    $keywords    = $parsed['keywords'];
    $groups      = $parsed['groups'];
    $priorities  = isset($parsed['priorities']) ? $parsed['priorities'] : array();
    $orders      = isset($parsed['order']) ? $parsed['order'] : array();
    $groupOrder  = isset($parsed['groupOrder']) ? $parsed['groupOrder'] : array();

    $results = array();
    $tableData = $this->prepareResultsTableData(
      $results,
      $groups,
      $orders,
      $groupOrder,
      $priorities,
      $goodThreshold,
      $sortMode
    );

    if (!empty($keywords)) {
      $results = $this->analyzeKeywords($keywords, $matchMode);
      $tableData = $this->prepareResultsTableData(
        $results,
        $groups,
        $orders,
        $groupOrder,
        $priorities,
        $goodThreshold,
        $sortMode
      );
    }

    $viewPath = __DIR__ . '/views/keyword-gap-analyzer.php';
    if (!is_file($viewPath)) {
      return '<p><em>View file missing: views/keyword-gap-analyzer.php</em></p>';
    }

    $importAlert = $L->get('kga-import-alert');

    $context = compact(
      'L',
      'rawKeywords',
      'matchMode',
      'includeScheduled',
      'goodThreshold',
      'sortMode',
      'keywords',
      'groups',
      'priorities',
      'orders',
      'groupOrder',
      'results',
      'tableData',
      'importAlert'
    );

    ob_start();
    extract($context, EXTR_SKIP);
    include $viewPath;
    return ob_get_clean();
  }

    // ---------------------------------------------------------------------
    // Helper functions
    // ---------------------------------------------------------------------

  /**
   * Convert the raw textarea content into a sorted, unique keyword list and assign groups.
   *
   * Syntax:
   * [Group name]
   * keyword one
   * keyword two
   *
   * @param string $raw Raw textarea input
   * @return array{keywords:array,groups:array,priorities:array,order:array,groupOrder:array}
   */
  private function parseKeywords($raw)
  {
    $lines = preg_split('/\R/', (string)$raw);

    $keywords    = array();
    $groups      = array();
    $priorities  = array();
    $order       = array();
    $groupOrder  = array();

    $currentGroup  = 'Allgemein';
    $orderCounter  = 0;
    $groupCounter  = 0;

    foreach ($lines as $line) {
      $lineTrimmed = trim($line);
      if ($lineTrimmed === '') {
        continue;
      }

      // Group definition lines look like [Name]
      if ($lineTrimmed[0] === '[' && substr($lineTrimmed, -1) === ']') {
        $groupName = trim(substr($lineTrimmed, 1, -1));
        if ($groupName === '') {
          $groupName = 'Allgemein';
        }
        if (!isset($groupOrder[$groupName])) {
          $groupOrder[$groupName] = $groupCounter++;
        }
        $currentGroup = $groupName;
        continue;
      }

      // Detect priority: leading "!" marks high priority
      $priority = 'normal';
      if ($lineTrimmed[0] === '!') {
        $priority    = 'high';
        $lineTrimmed = ltrim(substr($lineTrimmed, 1));
        if ($lineTrimmed === '') {
          // Ignore lines that are only "!"
          continue;
        }
      }

      // Normal keyword
      $keyword = strtolower($lineTrimmed);

      if (!in_array($keyword, $keywords, true)) {
        $keywords[]           = $keyword;
        $groups[$keyword]     = $currentGroup;
        $priorities[$keyword] = $priority;
        $order[$keyword]      = $orderCounter++;

        if (!isset($groupOrder[$currentGroup])) {
          $groupOrder[$currentGroup] = $groupCounter++;
        }
      } else {
        // Duplicate entry: high priority wins
        if ($priority === 'high') {
          $priorities[$keyword] = 'high';
        }
      }
    }

    // Keep existing behavior: alphabetical list for display/validation
    sort($keywords);

    return array(
      'keywords'   => $keywords,
      'groups'     => $groups,
      'priorities' => $priorities,
      'order'      => $order,
      'groupOrder' => $groupOrder
    );
  }

  /**
   * Count how often each keyword appears across relevant pages.
   *
   * @param array  $keywords  List of normalized keywords
   * @param string $matchMode Matching mode (phrase|all|any)
   * @return array
   */
  private function analyzeKeywords($keywords, $matchMode = 'phrase')
  {
    // Prepare result structure: counter and page list per keyword
    $results = array();

    foreach ($keywords as $keyword) {
      $results[$keyword] = array(
        'count' => 0,
        'pages' => array() // will hold title + permalink (+status for context)
      );
    }

    // Load all relevant pages (published + optional scheduled, excluding drafts/autosaves)
    $pagesMeta = $this->loadPagesForKeywordAnalysis();

    foreach ($pagesMeta as $pageMeta) {
      if (!isset($pageMeta['key'])) {
        continue;
      }

      $key = $pageMeta['key'];

      // Build Page object via Bludit API so title, permalink etc. are authoritative
      $page = buildPage($key);
      if (!($page instanceof Page)) {
        continue;
      }

      // Only consider published pages or, if enabled, scheduled ones
      $includeScheduled = ($this->getValue('includeScheduled') !== '0');
      $isPublished      = $page->published();
      $isScheduled      = $page->scheduled();

      if (!$isPublished && !($includeScheduled && $isScheduled)) {
        continue;
      }

      $title       = strtolower((string)$page->title());
      $content     = strtolower((string)$page->content());
      $description = strtolower((string)$page->description());

      // Include tags as plain text
      $tagsText  = '';
      $tagsArray = $page->tags(true);
      if (is_array($tagsArray)) {
        $tagsText = strtolower(implode(' ', array_values($tagsArray)));
      }

      // Aggregate everything into one large text blob
      $text = $title . ' ' . $description . ' ' . $content . ' ' . $tagsText;

      // Keyword matching
      foreach ($keywords as $keyword) {
        if ($this->matchesKeyword($text, $keyword, $matchMode)) {
          $results[$keyword]['count']++;
          $results[$keyword]['pages'][] = array(
            'title'     => $page->title(),
            'permalink' => $page->scheduled()
              ? (DOMAIN_ADMIN . 'edit-content/' . $page->key())
              : $page->permalink()
          );
        }
      }
    }

    return $results;
  }

  /**
   * Load page metadata directly from the database file for keyword analysis.
   *
   * @return array
   */
  private function loadPagesForKeywordAnalysis()
  {
    $result = array();
    $dbFile = PATH_DATABASES . 'pages.php';

    if (!file_exists($dbFile) || !is_readable($dbFile)) {
      return $result;
    }

    $lines = file($dbFile, FILE_IGNORE_NEW_LINES);
    if ($lines === false || count($lines) <= 1) {
      return $result;
    }

    // Remove the PHP guard line; the remaining content is JSON
    array_shift($lines);
    $json = implode("\n", $lines);
    $data = json_decode($json, true);

    if (!is_array($data)) {
      return $result;
    }

    $todayMidnight = strtotime('today');

    foreach ($data as $key => $row) {
      if (!is_array($row)) {
        continue;
      }

      // Read date field
      if (!isset($row['date'])) {
        continue;
      }

      $dateRaw = $row['date'];
      $timestamp = strtotime($dateRaw);
      if ($timestamp === false) {
        $timestamp = null;
      }

      // Fields used to detect status and draft state
      $statusField = isset($row['status']) ? (string)$row['status'] : '';
      $typeField   = isset($row['type']) ? (string)$row['type'] : '';
      $draftFlag   = isset($row['draft']) ? $row['draft'] : null;

      // Draft detection (mirrors calendar plugin)
      $isDraft = false;

      if ($statusField === 'draft' || $typeField === 'draft') {
        $isDraft = true;
      } elseif ($draftFlag !== null) {
        if (
          $draftFlag === true
          || $draftFlag === 1
          || $draftFlag === '1'
          || $draftFlag === 'true'
        ) {
          $isDraft = true;
        }
      }

      // Skip drafts entirely
      if ($isDraft) {
        continue;
      }

      // Title
      $title = isset($row['title']) ? (string)$row['title'] : (string)$key;

      // Filter autosave versions (same approach as calendar plugin)
      if (
        strpos($title, '[Automatische Speicherung]') !== false
        || strpos($key, 'autosave') !== false
      ) {
        continue;
      }

      // Derive scheduled vs. published (same principle as file-based logic)
      $isExplicitScheduled = ($statusField === 'scheduled' || $typeField === 'scheduled');
      $isScheduled = $isExplicitScheduled
        || ($timestamp !== null && $timestamp >= $todayMidnight);

      $status = $isScheduled ? 'scheduled' : 'published';

      // Content and other fields relevant for the analysis
      $content     = isset($row['content']) ? (string)$row['content'] : '';
      $description = isset($row['description']) ? (string)$row['description'] : '';
      $tags        = (isset($row['tags']) && is_array($row['tags']))
        ? $row['tags']
        : array();

      $result[] = array(
        'key'         => $key,
        'title'       => $title,
        'content'     => $content,
        'description' => $description,
        'tags'        => $tags,
        'date'        => $dateRaw,
        'timestamp'   => $timestamp,
        'status'      => $status // 'scheduled' or 'published'
      );
    }

    return $result;
  }

  /**
   * Check whether a keyword occurs in text using the configured mode.
   *
   * $mode:
   * - phrase: exact phrase
   * - all   : all words must be present (AND)
   * - any   : at least one word is enough (OR)
   *
   * @param string $text
   * @param string $keyword
   * @param string $mode
   * @return bool
   */
  private function matchesKeyword($text, $keyword, $mode)
  {
    $text    = (string)$text;
    $keyword = trim((string)$keyword);

    if ($keyword === '') {
      return false;
    }

    // Normalize to lowercase
    $text    = strtolower($text);
    $keyword = strtolower($keyword);

    // Exact phrase
    if ($mode === 'phrase') {
      return (strpos($text, $keyword) !== false);
    }

    // Split into words (simple whitespace)
    $words = preg_split('/\s+/', $keyword);
    $words = array_filter($words, function ($w) {
      return $w !== '';
    });

    if (empty($words)) {
      return false;
    }

    if ($mode === 'all') {
      // All words must appear (AND)
      foreach ($words as $word) {
        if (strpos($text, $word) === false) {
          return false;
        }
      }
      return true;
    }

    if ($mode === 'any') {
      // Any word is sufficient (OR)
      foreach ($words as $word) {
        if (strpos($text, $word) !== false) {
          return true;
        }
      }
      return false;
    }

    // Fallback: behave like phrase
    return (strpos($text, $keyword) !== false);
  }

  /**
   * Render the analysis table including status, grouping, and priority markers.
   *
   * @param array $results     Keyword counts and page lists
   * @param array $groups      Keyword => group map
   * @param array $orders      Keyword => input order
   * @param array $groupOrder  Group => input order
   * @param array $priorities  Keyword => priority
   * @return string
   */
  private function prepareResultsTableData($results, $groups = array(), $orders = array(), $groupOrder = array(), $priorities = array(), $goodThreshold = 3, $sortMode = 'input')
  {
    global $L;

    $labels = array(
      'statusGap'       => $L->get('kga-status-gap'),
      'statusUnder'     => $L->get('kga-status-under'),
      'statusGood'      => $L->get('kga-status-good'),
      'legendLabel'     => $L->get('kga-legend-label'),
      'legendGap'       => $L->get('kga-legend-gap'),
      'legendUnder'     => $L->get('kga-legend-under'),
      'legendGood'      => $L->get('kga-legend-good'),
      'legendPrio'      => $L->get('kga-legend-prio'),
      'colKeyword'      => $L->get('kga-table-header-keyword'),
      'colPrio'         => $L->get('kga-table-header-prio'),
      'colStatus'       => $L->get('kga-table-header-status'),
      'colCount'        => $L->get('kga-table-header-count'),
      'colExamples'     => $L->get('kga-table-header-examples'),
      'colAction'       => $L->get('kga-table-header-action'),
      'analysisHead'    => $L->get('kga-analysis-title'),
      'summaryKeywords' => $L->get('kga-summary-keywords'),
      'summaryGaps'     => $L->get('kga-summary-gaps'),
      'summaryUnder'    => $L->get('kga-summary-under'),
      'summaryGood'     => $L->get('kga-summary-good'),
      'noExamples'      => $L->get('kga-no-examples'),
      'createLabel'     => $L->get('kga-create-post')
    );

    if (empty($results)) {
      return array(
        'rows'       => array(),
        'groupStats' => array(),
        'labels'     => $labels
      );
    }

    $rows = array();
    foreach ($results as $keyword => $data) {
      $groupName       = isset($groups[$keyword]) ? $groups[$keyword] : 'Allgemein';
      $orderIndex      = isset($orders[$keyword]) ? (int)$orders[$keyword] : 0;
      $groupOrderIndex = isset($groupOrder[$groupName]) ? (int)$groupOrder[$groupName] : 0;
      $priority        = isset($priorities[$keyword]) ? $priorities[$keyword] : 'normal';

      $rows[] = array(
        'keyword'     => $keyword,
        'group'       => $groupName,
        'order'       => $orderIndex,
        'groupOrder'  => $groupOrderIndex,
        'priority'    => $priority,
        'count'       => isset($data['count']) ? (int)$data['count'] : 0,
        'pages'       => isset($data['pages']) && is_array($data['pages']) ? $data['pages'] : array()
      );
    }

    if ($sortMode === '') {
      $sortMode = 'input';
    }

    usort($rows, function ($a, $b) use ($sortMode) {
      if ($sortMode === 'input') {
        if ($a['groupOrder'] === $b['groupOrder']) {
          if ($a['order'] === $b['order']) {
            return 0;
          }
          return ($a['order'] < $b['order']) ? -1 : 1;
        }
        return ($a['groupOrder'] < $b['groupOrder']) ? -1 : 1;
      }

      if ($a['group'] === $b['group']) {
        if ($a['count'] === $b['count']) {
          return strcmp($a['keyword'], $b['keyword']);
        }
        return ($a['count'] < $b['count']) ? -1 : 1;
      }
      return strcmp($a['group'], $b['group']);
    });

    $rowsEnhanced = array();
    $groupStats   = array();

    if ($goodThreshold <= 1) {
      $goodThreshold = 3;
    }

    foreach ($rows as $row) {
      $group    = $row['group'];
      $count    = $row['count'];
      $priority = isset($row['priority']) ? $row['priority'] : 'normal';

      if ($count === 0) {
        $statusLabel = $labels['statusGap'];
        $rowClass    = 'kga-gap';
        $statKey     = 'gap';
      } elseif ($count < $goodThreshold) {
        $statusLabel = $labels['statusUnder'];
        $rowClass    = 'kga-under';
        $statKey     = 'under';
      } else {
        $statusLabel = $labels['statusGood'];
        $rowClass    = 'kga-good';
        $statKey     = 'good';
      }

      if (!isset($groupStats[$group])) {
        $groupStats[$group] = array(
          'total' => 0,
          'gap'   => 0,
          'under' => 0,
          'good'  => 0
        );
      }

      $groupStats[$group]['total']++;
      $groupStats[$group][$statKey]++;

      $rowsEnhanced[] = array(
        'keyword'       => $row['keyword'],
        'group'         => $group,
        'count'         => $count,
        'statusLabel'   => $statusLabel,
        'rowClass'      => $rowClass,
        'priority'      => $priority,
        'priorityClass' => ($priority === 'high') ? 'kga-prio-high' : '',
        'pages'         => $row['pages']
      );
    }

    return array(
      'rows'       => $rowsEnhanced,
      'groupStats' => $groupStats,
      'labels'     => $labels
    );
  }
}