Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 16 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
### Security
- Nothing yet

## [2.8.0] - 2026-11-08

### Added
- Knowledge base endpoints for FAQ categories and articles. There is no delete; hiding an article means setting it to `internal`.
- `GET /api/kb-categories-list.php`: all categories with parent, visibility and article count.
- `POST /api/kb-categories-create.php`, `PATCH /api/kb-categories-update.php/{id}.json`: name, description, notes, parent, visibility. A category cannot become its own parent or move below one of its subcategories.
- `GET /api/kb-faq-search.php`: text, category, visibility, slug; paging.
- `GET /api/kb-faq-get.php/{id}.json`: article with answer (HTML), notes and help topics.
- `POST /api/kb-faq-create.php`, `PATCH /api/kb-faq-update.php/{id}.json`: title, answer, category, notes, visibility (`internal`, `public`, `featured`). Fields left out keep their value; help topics and attachments stay linked.
- Changes go through osTicket's `FAQ::update()` and `Category::update()`, so the answer is sanitized like in the staff UI and duplicate titles/names are refused. New articles and categories are internal unless `visibility` is set.
- Article responses report `visibleInPortal` (article and category public), and `slug`/`publicUrl` for friendly `/kb/<slug>` URLs. The slugs are read from the `RewriteRule ^kb/<slug>$ kb/faq.php?id=<ID>` lines of the root `.htaccess`; the file is never written.
- Two API key permissions, off by default: `can_read_kb`, `can_write_kb`. Write does not imply read.

### Fixed
- Updating the plugin left the task rewrite rules behind in `api/.htaccess`: removing the old rule block stopped at the subticket unlink rule. The template now ends with an explicit end marker, and leftover plugin rules from earlier updates are removed.

## [2.7.0] - 2026-11-07

### Added
Expand Down
1 change: 1 addition & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,7 @@ Extends osTicket's REST API with powerful endpoints for advanced ticket manageme
- Subticket API for parent-child relationships (requires [Subticket Manager Plugin](https://github.com/studio-prisma/osticket-subticket-manager))
- Ticket Statistics (global, by department, by staff)
- Task API: read, search, create, update (edit, link to a ticket, assign, transfer, due date, close/reopen, notes) and delete osTicket tasks, run as a configurable agent
- Knowledge Base API: list, create and change FAQ categories; search, read, create and change FAQ articles (internal/public/featured), with friendly `/kb/<slug>` URLs read from the root `.htaccess`. No delete
- Granular API Key Permissions per endpoint
- Name-Based Filters (human-readable names instead of IDs)
- No Core Modifications (Signal-based architecture, update-safe)
Expand Down
33 changes: 33 additions & 0 deletions api/kb-categories-create.php
Original file line number Diff line number Diff line change
@@ -0,0 +1,33 @@
<?php
/**
* API File: Knowledge Base Category Create
*
* Creates an FAQ category (internal unless visibility is set).
*
* This file should be deployed to: /api/kb-categories-create.php
* URL pattern: /api/kb-categories-create.php[.json]
*
* Requires the can_write_kb permission. Nothing is ever deleted.
*/

declare(strict_types=1);

// Load osTicket bootstrap FIRST (must be relative to THIS file's location)
require_once '../main.inc.php';

// Then load ApiBootstrap helper
require_once INCLUDE_DIR . 'plugins/api-endpoints/lib/ApiBootstrap.php';

$bootstrap = ApiBootstrap::initialize();

// Parse optional format from path info
$bootstrap->parsePathInfo('#^(?:\.(?P<format>json|xml))?$#');

// Only accept POST: every call creates a new category
$bootstrap->requireMethod('POST');

$data = $bootstrap->parseJsonBody(required: true);

$bootstrap->execute(function() use ($bootstrap, $data) {
return $bootstrap->getController()->createKbCategory($data);
}, 201);
30 changes: 30 additions & 0 deletions api/kb-categories-list.php
Original file line number Diff line number Diff line change
@@ -0,0 +1,30 @@
<?php
/**
* API File: Knowledge Base Category List
*
* Lists all FAQ categories with parent, visibility and article count.
*
* This file should be deployed to: /api/kb-categories-list.php
* URL pattern: /api/kb-categories-list.php[.json]
*
* Requires the can_read_kb permission. Nothing is ever deleted.
*/

declare(strict_types=1);

// Load osTicket bootstrap FIRST (must be relative to THIS file's location)
require_once '../main.inc.php';

// Then load ApiBootstrap helper
require_once INCLUDE_DIR . 'plugins/api-endpoints/lib/ApiBootstrap.php';

$bootstrap = ApiBootstrap::initialize();

// Parse optional format from path info
$bootstrap->parsePathInfo('#^(?:\.(?P<format>json|xml))?$#');

$bootstrap->requireMethod('GET');

$bootstrap->execute(function() use ($bootstrap) {
return $bootstrap->getController()->listKbCategories();
});
35 changes: 35 additions & 0 deletions api/kb-categories-update.php
Original file line number Diff line number Diff line change
@@ -0,0 +1,35 @@
<?php
/**
* API File: Knowledge Base Category Update
*
* Changes name, description, notes, parent or visibility of an FAQ category.
*
* This file should be deployed to: /api/kb-categories-update.php
* URL pattern: /api/kb-categories-update.php/{id}.json
*
* Requires the can_write_kb permission. Nothing is ever deleted.
*/

declare(strict_types=1);

// Load osTicket bootstrap FIRST (must be relative to THIS file's location)
require_once '../main.inc.php';

// Then load ApiBootstrap helper
require_once INCLUDE_DIR . 'plugins/api-endpoints/lib/ApiBootstrap.php';

$bootstrap = ApiBootstrap::initialize();

// Parse id and format from path info
$params = $bootstrap->parsePathInfo(
'#^/(?P<id>[0-9]{1,10})\.(?P<format>json|xml)$#',
'Invalid URL format. Expected: /api/kb-categories-update.php/{id}.json'
);

$bootstrap->requireMethod(['PATCH', 'PUT']);

$data = $bootstrap->parseJsonBody(required: true);

$bootstrap->execute(function() use ($bootstrap, $params, $data) {
return $bootstrap->getController()->updateKbCategory($params['id'], $data);
});
33 changes: 33 additions & 0 deletions api/kb-faq-create.php
Original file line number Diff line number Diff line change
@@ -0,0 +1,33 @@
<?php
/**
* API File: Knowledge Base Article Create
*
* Creates an FAQ article (internal unless visibility is set).
*
* This file should be deployed to: /api/kb-faq-create.php
* URL pattern: /api/kb-faq-create.php[.json]
*
* Requires the can_write_kb permission. Nothing is ever deleted.
*/

declare(strict_types=1);

// Load osTicket bootstrap FIRST (must be relative to THIS file's location)
require_once '../main.inc.php';

// Then load ApiBootstrap helper
require_once INCLUDE_DIR . 'plugins/api-endpoints/lib/ApiBootstrap.php';

$bootstrap = ApiBootstrap::initialize();

// Parse optional format from path info
$bootstrap->parsePathInfo('#^(?:\.(?P<format>json|xml))?$#');

// Only accept POST: every call creates a new article
$bootstrap->requireMethod('POST');

$data = $bootstrap->parseJsonBody(required: true);

$bootstrap->execute(function() use ($bootstrap, $data) {
return $bootstrap->getController()->createKbArticle($data);
}, 201);
33 changes: 33 additions & 0 deletions api/kb-faq-get.php
Original file line number Diff line number Diff line change
@@ -0,0 +1,33 @@
<?php
/**
* API File: Knowledge Base Article Get
*
* Returns one FAQ article with answer (HTML), notes, help topics and slug.
*
* This file should be deployed to: /api/kb-faq-get.php
* URL pattern: /api/kb-faq-get.php/{id}.json
*
* Requires the can_read_kb permission. Nothing is ever deleted.
*/

declare(strict_types=1);

// Load osTicket bootstrap FIRST (must be relative to THIS file's location)
require_once '../main.inc.php';

// Then load ApiBootstrap helper
require_once INCLUDE_DIR . 'plugins/api-endpoints/lib/ApiBootstrap.php';

$bootstrap = ApiBootstrap::initialize();

// Parse id and format from path info
$params = $bootstrap->parsePathInfo(
'#^/(?P<id>[0-9]{1,10})\.(?P<format>json|xml)$#',
'Invalid URL format. Expected: /api/kb-faq-get.php/{id}.json'
);

$bootstrap->requireMethod('GET');

$bootstrap->execute(function() use ($bootstrap, $params) {
return $bootstrap->getController()->getKbArticle($params['id']);
});
39 changes: 39 additions & 0 deletions api/kb-faq-search.php
Original file line number Diff line number Diff line change
@@ -0,0 +1,39 @@
<?php
/**
* API File: Knowledge Base Article Search
*
* Searches FAQ articles by text, category, visibility or slug.
*
* This file should be deployed to: /api/kb-faq-search.php
* URL pattern: /api/kb-faq-search.php[.json]?query=&categoryId=&visibility=&slug=&limit=&offset=
*
* Requires the can_read_kb permission. Nothing is ever deleted.
*/

declare(strict_types=1);

// Load osTicket bootstrap FIRST (must be relative to THIS file's location)
require_once '../main.inc.php';

// Then load ApiBootstrap helper
require_once INCLUDE_DIR . 'plugins/api-endpoints/lib/ApiBootstrap.php';

$bootstrap = ApiBootstrap::initialize();

// Parse optional format from path info
$bootstrap->parsePathInfo('#^(?:\.(?P<format>json|xml))?$#');

$bootstrap->requireMethod('GET');

$params = $bootstrap->parseQueryParams([
'query' => null,
'categoryId' => null,
'visibility' => null,
'slug' => null,
'limit' => null,
'offset' => null,
]);

$bootstrap->execute(function() use ($bootstrap, $params) {
return $bootstrap->getController()->searchKbArticles($params);
});
36 changes: 36 additions & 0 deletions api/kb-faq-update.php
Original file line number Diff line number Diff line change
@@ -0,0 +1,36 @@
<?php
/**
* API File: Knowledge Base Article Update
*
* Changes title, answer, category, notes or visibility of an FAQ article.
* Fields left out keep their value, help topics stay linked.
*
* This file should be deployed to: /api/kb-faq-update.php
* URL pattern: /api/kb-faq-update.php/{id}.json
*
* Requires the can_write_kb permission. Nothing is ever deleted.
*/

declare(strict_types=1);

// Load osTicket bootstrap FIRST (must be relative to THIS file's location)
require_once '../main.inc.php';

// Then load ApiBootstrap helper
require_once INCLUDE_DIR . 'plugins/api-endpoints/lib/ApiBootstrap.php';

$bootstrap = ApiBootstrap::initialize();

// Parse id and format from path info
$params = $bootstrap->parsePathInfo(
'#^/(?P<id>[0-9]{1,10})\.(?P<format>json|xml)$#',
'Invalid URL format. Expected: /api/kb-faq-update.php/{id}.json'
);

$bootstrap->requireMethod(['PATCH', 'PUT']);

$data = $bootstrap->parseJsonBody(required: true);

$bootstrap->execute(function() use ($bootstrap, $params, $data) {
return $bootstrap->getController()->updateKbArticle($params['id'], $data);
});
67 changes: 63 additions & 4 deletions class.ApiEndpointsPlugin.php
Original file line number Diff line number Diff line change
Expand Up @@ -575,6 +575,16 @@ function extendApiKeyTable(&$errors) {
'name' => 'can_delete_tasks',
'definition' => 'TINYINT(1) UNSIGNED NOT NULL DEFAULT 0',
'after' => 'can_search_tasks'
),
array(
'name' => 'can_read_kb',
'definition' => 'TINYINT(1) UNSIGNED NOT NULL DEFAULT 0',
'after' => 'can_delete_tasks'
),
array(
'name' => 'can_write_kb',
'definition' => 'TINYINT(1) UNSIGNED NOT NULL DEFAULT 0',
'after' => 'can_read_kb'
)
);

Expand Down Expand Up @@ -636,6 +646,8 @@ function removeApiKeyTableExtensions() {

// List of columns to remove (in reverse order of adding)
$columnsToRemove = array(
'can_write_kb',
'can_read_kb',
'can_delete_tasks',
'can_search_tasks',
'can_read_tasks',
Expand Down Expand Up @@ -826,12 +838,16 @@ function removeHtaccessRule() {
return true; // Nothing to remove
}

// Find end of template block (next empty line or closing IfModule)
// The template ends with the last RewriteRule line, so we look for the pattern:
// RewriteRule ^tickets-subtickets-unlink\.php/ - [L]
// Find end of template block. Since 2.8.0 the template ends with an
// explicit end marker. Older blocks end with the subticket unlink rule;
// their later rules (tasks) are removed as leftovers below.
$search_start = $start_pos;
$end_marker = 'RewriteRule ^tickets-subtickets-unlink\.php/ - [L]';
$end_marker = '# End of API Endpoints Plugin rules';
$end_pos = strpos($content, $end_marker, $search_start);
if ($end_pos === false) {
$end_marker = 'RewriteRule ^tickets-subtickets-unlink\.php/ - [L]';
$end_pos = strpos($content, $end_marker, $search_start);
}

if ($end_pos === false) {
// Fallback: look for any RewriteRule pattern and find the last one in our block
Expand All @@ -853,6 +869,9 @@ function removeHtaccessRule() {
// Remove the entire block (including leading newline)
$content = substr_replace($content, '', $start_pos, $end_pos - $start_pos);

// Remove leftovers of older blocks whose end was detected too early
$content = self::stripLeftoverRules($content, __DIR__ . '/htaccess.template');

// Write back
$result = file_put_contents($htaccess_file, $content);
if ($result === false) {
Expand All @@ -864,6 +883,46 @@ function removeHtaccessRule() {
return true;
}

/**
* Remove plugin rules left outside the template block
*
* Up to 2.7.0 the block removal stopped at the subticket unlink rule,
* so every update left the rules after it (tasks) behind. This removes
* pass-through rules for the plugin's own endpoint files
* (tickets-*.php, kb-*.php) and comment lines that appear verbatim in
* the template. osTicket's own rules are never touched.
*
* @param string $content .htaccess content without the template block
* @param string $templateFile Path of htaccess.template
* @return string Cleaned content
*/
static function stripLeftoverRules($content, $templateFile) {
$comments = array();
if (is_readable($templateFile)) {
foreach (preg_split('/\R/', (string)file_get_contents($templateFile)) as $line) {
$line = trim($line);
// Only specific comments: skip "#", separator and empty lines
if (strlen($line) > 12 && $line[0] === '#' && strpos($line, '=====') === false) {
$comments[$line] = true;
}
}
}

$kept = array();
foreach (preg_split('/\R/', $content) as $line) {
$trimmed = trim($line);
if (preg_match('#^RewriteRule \^(tickets|kb)-[a-z-]+\\\\\.php(/|\.\*\$) - \[L\]$#', $trimmed)) {
continue;
}
if (isset($comments[$trimmed])) {
continue;
}
$kept[] = $line;
}

return preg_replace("/\n{3,}/", "\n\n", implode("\n", $kept));
}

/**
* Remove deployed API files from /api/ directory (DYNAMIC)
*
Expand Down
Loading
Loading