|
| 1 | +<?php |
| 2 | +/** |
| 3 | + * |
| 4 | + * Knowledge Base extension for the phpBB Forum Software package |
| 5 | + * |
| 6 | + * @copyright (c) 2026, phpBB Modders, https://www.phpbbmodders.com/ |
| 7 | + * @license GNU General Public License, version 2 (GPL-2.0) |
| 8 | + * |
| 9 | + */ |
| 10 | + |
| 11 | +namespace phpbbmodders\knowledgebase\inc; |
| 12 | + |
| 13 | +use phpbb\config\config; |
| 14 | +use phpbb\config\db_text; |
| 15 | +use phpbb\template\template; |
| 16 | +use phpbbmodders\knowledgebase\textformatter\article_text; |
| 17 | + |
| 18 | +/** |
| 19 | + * The introduction text shown at the top of the Knowledge Base index. |
| 20 | + * |
| 21 | + * An administrator switches it on and edits it on the ACP configuration page, |
| 22 | + * in BBCode or Markdown like an article. It is stored parsed, in the |
| 23 | + * kb_intro_text config_text entry, with its BBCode uid (kb_intro_uid) and |
| 24 | + * whether it is Markdown (kb_intro_markdown); kb_intro_enabled switches it on. |
| 25 | + * Migration version_2_0_33 adds it switched off, holding KB_INTRO_DEFAULT_TEXT |
| 26 | + * from language/<lang>/default_content.php (the text kinerity/knowledgebase |
| 27 | + * showed on its index) in the board's default language. |
| 28 | + */ |
| 29 | +class intro |
| 30 | +{ |
| 31 | + protected config $config; |
| 32 | + protected db_text $config_text; |
| 33 | + protected article_text $article_text; |
| 34 | + protected template $template; |
| 35 | + |
| 36 | + /** |
| 37 | + * @param config $config |
| 38 | + * @param db_text $config_text |
| 39 | + * @param article_text $article_text |
| 40 | + * @param template $template |
| 41 | + */ |
| 42 | + public function __construct(config $config, db_text $config_text, article_text $article_text, template $template) |
| 43 | + { |
| 44 | + $this->config = $config; |
| 45 | + $this->config_text = $config_text; |
| 46 | + $this->article_text = $article_text; |
| 47 | + $this->template = $template; |
| 48 | + } |
| 49 | + |
| 50 | + /** |
| 51 | + * The stored form of plain text with no BBCode, as phpBB's parser would |
| 52 | + * store it, for the default text a migration writes. |
| 53 | + * |
| 54 | + * @param string $text Plain text, not escaped |
| 55 | + * @return string |
| 56 | + */ |
| 57 | + public static function stored_plain_text(string $text): string |
| 58 | + { |
| 59 | + return '<t>' . htmlspecialchars($text, ENT_COMPAT, 'UTF-8') . '</t>'; |
| 60 | + } |
| 61 | + |
| 62 | + /** |
| 63 | + * Whether the introduction is switched on. |
| 64 | + * |
| 65 | + * @return bool |
| 66 | + */ |
| 67 | + public function is_enabled(): bool |
| 68 | + { |
| 69 | + return !empty($this->config['kb_intro_enabled']); |
| 70 | + } |
| 71 | + |
| 72 | + /** |
| 73 | + * Whether the stored text is Markdown. |
| 74 | + * |
| 75 | + * @return bool |
| 76 | + */ |
| 77 | + public function is_markdown(): bool |
| 78 | + { |
| 79 | + return !empty($this->config['kb_intro_markdown']); |
| 80 | + } |
| 81 | + |
| 82 | + /** |
| 83 | + * Put the introduction on the page being built, when it is switched on |
| 84 | + * and not empty: KB_INTRO (HTML) and S_KB_INTRO. |
| 85 | + * |
| 86 | + * @return void |
| 87 | + */ |
| 88 | + public function assign(): void |
| 89 | + { |
| 90 | + $html = $this->is_enabled() ? $this->html() : ''; |
| 91 | + |
| 92 | + $this->template->assign_vars([ |
| 93 | + 'S_KB_INTRO' => $html !== '', |
| 94 | + 'KB_INTRO' => $html, |
| 95 | + ]); |
| 96 | + } |
| 97 | + |
| 98 | + /** |
| 99 | + * The introduction as HTML, whether or not it is switched on. |
| 100 | + * |
| 101 | + * @return string Empty when there is no text |
| 102 | + */ |
| 103 | + public function html(): string |
| 104 | + { |
| 105 | + $stored = (string) $this->config_text->get('kb_intro_text'); |
| 106 | + if (trim(strip_tags($stored)) === '') |
| 107 | + { |
| 108 | + return ''; |
| 109 | + } |
| 110 | + |
| 111 | + return $this->article_text->display($stored, (string) ($this->config['kb_intro_uid'] ?? ''), $this->is_markdown()); |
| 112 | + } |
| 113 | + |
| 114 | + /** |
| 115 | + * The introduction as the administrator typed it, escaped for a textarea. |
| 116 | + * |
| 117 | + * @return string |
| 118 | + */ |
| 119 | + public function for_edit(): string |
| 120 | + { |
| 121 | + return $this->article_text->for_edit((string) $this->config_text->get('kb_intro_text')); |
| 122 | + } |
| 123 | + |
| 124 | + /** |
| 125 | + * Save the introduction from the ACP form. |
| 126 | + * |
| 127 | + * @param bool $enabled |
| 128 | + * @param string $text Submitted text, escaped by the request layer |
| 129 | + * @param bool $markdown True to parse it as Markdown, false for BBCode |
| 130 | + * @return void |
| 131 | + */ |
| 132 | + public function save(bool $enabled, string $text, bool $markdown): void |
| 133 | + { |
| 134 | + $uid = $bitfield = ''; |
| 135 | + $options = 0; |
| 136 | + if (trim($text) !== '') |
| 137 | + { |
| 138 | + $this->article_text->store($text, $markdown, $uid, $bitfield, $options); |
| 139 | + } |
| 140 | + else |
| 141 | + { |
| 142 | + $text = ''; |
| 143 | + } |
| 144 | + |
| 145 | + $this->config_text->set('kb_intro_text', $text); |
| 146 | + $this->config->set('kb_intro_uid', (string) $uid); |
| 147 | + $this->config->set('kb_intro_markdown', $markdown ? 1 : 0); |
| 148 | + $this->config->set('kb_intro_enabled', $enabled ? 1 : 0); |
| 149 | + } |
| 150 | +} |
0 commit comments