¶ Plugin Update Checker
¶ Overview
The Plugin Update Checker automatically checks GitHub for available updates of all installed osTicket plugins and shows update badges directly in the plugin list (Admin Panel > Manage > Plugins). No more manually visiting GitHub repositories to check for new versions.
Installed Plugins
Plugin Name (instances) Version Status Date Installed
----------------------------------------------------------------------
Markdown Support (2) 1.0.0 [1.2.0] Enabled 2025-01-10
^^^^^^^ clickable badge
API Endpoints (3) 1.1.0 [1.1.2] Enabled 2025-01-05
Priority Icons (1) 1.0.3 Enabled 2025-01-08
(no badge = up to date)
¶ Key Features
- Automatic update checks - Queries GitHub Releases API for all plugins with a GitHub URL
- Clickable badges - Orange update badge with version number, links to GitHub release page
- File-based caching - Configurable cache TTL (default: 6 hours) prevents excessive API calls
- Optional GitHub Token - Support for Personal Access Token for higher rate limits (5,000 vs 60 requests/hour)
- Zero performance impact - Only active on the plugins page, early return on all other pages
- PJAX support - Badges re-applied after dynamic navigation
- XSS-safe - URL validation, JSON encoding with
JSON_HEX_TAG - No core modifications - Output buffer-based asset injection
¶ Table of Contents
- Requirements
- Installation
- Configuration
- How It Works
- Plugin Prerequisites
- Troubleshooting
- Technical Details
- FAQ
¶ Requirements
| Component | Version | Note |
|---|---|---|
| osTicket | 1.18.x | Tested with 1.18.x |
| PHP | 8.1+ | Required |
| PHP cURL | any | Required for GitHub API calls |
| Modern Browser | ES6+ | Chrome, Firefox, Edge, Safari |
¶ Installation
¶ Step 1: Download Plugin
¶ Method 1: ZIP Download (Recommended)
- Visit GitHub Releases
- Download the latest release ZIP
- Extract and upload the
update-checkfolder to/include/plugins/on your osTicket server - Run
composer install --no-devin the plugin directory
Final path: /path/to/osticket/include/plugins/update-check/
¶ Method 2: Git Clone
cd /path/to/osticket/include/plugins
git clone https://github.com/markus-michalski/osticket-plugin-update-check.git update-check
cd update-check
composer install --no-dev
¶ Step 2: Enable Plugin
- Login to osTicket Admin Panel
- Navigate to: Admin Panel -> Manage -> Plugins
- Find "Plugin Update Checker" in the plugin list
- Click "Enable"
The plugin automatically creates a singleton instance and starts checking for updates.
¶ Step 3: Configure (Optional)
- Click "Instances" next to "Plugin Update Checker"
- Click the instance, then "Config"
- Adjust settings as needed (see Configuration)
¶ Directory Structure
include/plugins/update-check/
+-- plugin.php # Plugin metadata
+-- class.UpdateCheckPlugin.php # Main plugin class
+-- config.php # Configuration form
+-- src/
| +-- AssetInjector.php # Output buffer injection
| +-- FileCache.php # File-based cache
| +-- GitHubReleaseChecker.php # GitHub API client
| +-- PluginUpdateCollector.php # Update data collector
+-- assets/
| +-- update-badges.css # Badge styling
| +-- update-badges.js # DOM manipulation
+-- vendor/ # Composer autoload
+-- README.md
+-- CHANGELOG.md
¶ Configuration
¶ Available Settings
| Setting | Default | Description |
|---|---|---|
| Cache Duration | 6 hours | How long GitHub API responses are cached |
| GitHub Token | (empty) | Optional Personal Access Token for higher rate limits |
¶ GitHub Rate Limits
| Mode | Limit | Recommendation |
|---|---|---|
| Without token | 60 requests/hour | Fine for fewer than 10 plugins |
| With token | 5,000 requests/hour | Recommended for many plugins |
¶ Setting Up a GitHub Token
If you have many plugins or see rate limit errors:
- Go to GitHub Settings > Developer Settings > Personal Access Tokens
- Click "Generate new token (classic)"
- Give it a name (e.g., "osTicket Update Checker")
- No scopes needed - public repository access is sufficient
- Copy the token and paste it into the plugin configuration
¶ How It Works
¶ Update Check Flow
- Plugin's
bootstrap()detects if user is on/scp/plugins.php - On other pages: returns immediately (zero performance impact)
- On plugins page: collects update data for all plugins with GitHub URLs
- GitHub API responses are cached in temp directory (configurable TTL)
- Output buffer injects CSS and JavaScript before page closes
- JavaScript reads update data and adds badges to plugin table rows
¶ Version Comparison
The plugin uses PHP's version_compare() with v prefix stripping:
v1.2.0and1.2.0are treated identically- Only newer versions trigger a badge (not equal or older)
- Pre-release tags are not specifically handled
¶ Caching Strategy
- Success cache: Stores latest release info for the configured TTL (default: 6 hours)
- Error cache: Stores "no result" for 1 hour (prevents hammering on errors/rate limits)
- Cache location:
sys_get_temp_dir() . '/osticket-update-check/' - Cache format: JSON files with
expires_atanddatafields
¶ Plugin Prerequisites
For a plugin to receive update checks, its plugin.php must contain a GitHub URL in the url field:
<?php return [
'id' => 'vendor:plugin-name',
'version' => '1.0.0',
'name' => 'My Plugin',
'url' => 'https://github.com/user/repo', // Required!
'plugin' => 'class.MyPlugin.php:MyPlugin',
];
Supported URL formats:
https://github.com/user/repohttps://github.com/user/repo.githttp://github.com/user/repo
Additionally required:
- The plugin developer must create GitHub Releases (tagged versions) for updates to be detected
- The release tag should follow semantic versioning (e.g.,
v1.0.0or1.0.0)
¶ Troubleshooting
¶ No Badges Appearing
Check:
-
Plugin enabled?
- Admin Panel -> Plugins -> Plugin Update Checker must show "Enabled"
- An instance must exist and be active
-
Plugins have GitHub URL?
- Open the
plugin.phpof the target plugin - Verify it has a
'url' => 'https://github.com/...'entry
- Open the
-
GitHub Releases exist?
- Visit the plugin's GitHub repository
- Check that published Releases exist (not just tags)
-
Check PHP error log:
grep "UpdateCheck" /path/to/osticket/include/ost-errors.log -
Clear cache:
rm -rf /tmp/osticket-update-check/
¶ Rate Limit Issues
Symptoms: Badges stop appearing after many checks.
Fix:
- Wait 1 hour (error cache TTL)
- Or configure a GitHub Personal Access Token in plugin settings (see Configuration)
¶ Badge Shows Wrong Version
Possible causes:
- Cached data is stale - clear cache and reload
- GitHub Release uses an unexpected tag format
- The
versionfield inplugin.phpdoesn't match the actual installed version
¶ Technical Details
¶ Architecture
The plugin follows a clean separation of concerns:
| Class | Responsibility |
|---|---|
UpdateCheckPlugin |
Bootstrap, page detection, orchestration |
UpdateCheckConfig |
Admin configuration form |
FileCache |
File-based caching with TTL |
GitHubReleaseChecker |
GitHub API client, URL parsing, version comparison |
PluginUpdateCollector |
Iterates plugins, collects update data |
AssetInjector |
Output buffer injection of CSS/JS |
¶ Asset Injection
The plugin uses output buffer injection (ob_start() callback) - the same proven pattern as the Priority Icons plugin:
ob_start(function (string $buffer) use ($injector, $updateData): string {
try {
return $injector->inject($buffer, $updateData);
} catch (\Throwable $e) {
error_log('[UpdateCheck] Asset injection failed: ' . $e->getMessage());
return $buffer;
}
});
Why ob_start()?
| Method | Problem |
|---|---|
Signal::connect('apps.scp') |
Only fires on Apps tab, not on plugin list |
$ost->addExtraHeader() |
global $ost is NULL during bootstrap() |
| External CSS/JS files | include/.htaccess blocks HTTP access |
ob_start() callback |
Reliable, crash-protected with try-catch |
¶ Security
-
XSS Prevention:
- JSON encoding with
JSON_HEX_TAG | JSON_HEX_APOSprevents script injection - JavaScript URL validation (
isValidHttpUrl()) only allowshttp:andhttps:protocols - No
innerHTMLfor user-controlled data
- JSON encoding with
-
SSL Verification:
CURLOPT_SSL_VERIFYPEER = trueandCURLOPT_SSL_VERIFYHOST = 2on all API calls
-
Double-Injection Protection:
- Checks for
data-plugin="update-check"before injecting
- Checks for
-
Crash Protection:
- try-catch in
ob_start()callback prevents white screen on errors
- try-catch in
-
No Database Modifications:
- Plugin only reads plugin metadata and caches to temp files
¶ Performance
| Scenario | Impact |
|---|---|
| Non-plugin pages | Zero (early return in bootstrap()) |
| Plugin page, warm cache | < 10ms additional load time |
| Plugin page, cold cache | ~5s per plugin (cURL timeout), cached afterward |
| cURL timeout | 5 seconds per request |
¶ FAQ
¶ General Questions
Q: Does the plugin check for its own updates?
A: Yes! Since the plugin itself has a GitHub URL in its plugin.php, it will also check for its own updates.
Q: What happens if GitHub is unreachable?
A: The plugin caches errors for 1 hour and returns gracefully. No badge is shown and no errors are displayed to the user. Errors are logged to the PHP error log.
Q: Does it work with private GitHub repositories?
A: Only if you configure a GitHub Personal Access Token that has access to the private repository. Without a token, only public repositories are accessible.
Q: What happens when I disable the plugin?
A: The badges disappear immediately. No data is modified - the plugin only injects CSS/JS into the page output.
¶ Technical Questions
Q: Why are assets loaded inline instead of as external files?
A: osTicket's include/.htaccess contains Deny from all, which blocks HTTP access to all files in the include/ directory. Inline injection bypasses this without modifying core files.
Q: Why file-based cache instead of database?
A: osTicket doesn't provide a general-purpose cache API. File-based caching using sys_get_temp_dir() is simple, requires no database modifications, and works on all systems.
Q: Does it work with NGINX?
A: Yes. Since all assets are injected inline, there are no external file requests that could be blocked by web server configurations.
Q: How does the plugin find which plugins to check?
A: It uses PluginManager::allInstalled() to iterate all installed plugins, then reads each plugin's plugin.php metadata via PluginManager::getInfoForPath() to find the url field. Only URLs matching github.com are checked.
¶ License
This plugin is released under the GNU General Public License v2, compatible with osTicket core.
See LICENSE for details.
¶ Support
For questions or issues, please create an issue on GitHub:
Issue Tracker: https://github.com/markus-michalski/osticket-plugin-update-check/issues
When reporting issues, please include:
- osTicket version (Admin Panel -> Settings -> About)
- PHP version (
php -v) - Plugin version
- Browser console errors (F12 -> Console)
- PHP error log entries containing
[UpdateCheck]
¶ Contributing
Developed by Markus Michalski
Contributions welcome!
- Fork the repository
- Create a feature branch
- Submit a pull request
¶ Changelog
See CHANGELOG.md for version history.