From 2689d3e0c86cfe122b40427141015e05e0545040 Mon Sep 17 00:00:00 2001 From: Peter Goodhall Date: Tue, 28 Apr 2026 13:37:19 +0100 Subject: [PATCH 01/48] Bump migration to 267 and add 2.8.13 tag migration Increment migration_version to 267 and add Migration_tag_2_8_13. The new migration updates the 'options' table to set version = '2.8.13' and resets user_options (version_dialog confirmed) to 'false' to trigger the version info dialog; the down() method reverts the version to '2.8.12'. --- application/config/migration.php | 2 +- application/migrations/267_tag_2_8_13.php | 30 +++++++++++++++++++++++ 2 files changed, 31 insertions(+), 1 deletion(-) create mode 100644 application/migrations/267_tag_2_8_13.php diff --git a/application/config/migration.php b/application/config/migration.php index ca0f54dc9..5bb94b1c6 100644 --- a/application/config/migration.php +++ b/application/config/migration.php @@ -22,7 +22,7 @@ | */ -$config['migration_version'] = 266; +$config['migration_version'] = 267; /* |-------------------------------------------------------------------------- diff --git a/application/migrations/267_tag_2_8_13.php b/application/migrations/267_tag_2_8_13.php new file mode 100644 index 000000000..280e57a19 --- /dev/null +++ b/application/migrations/267_tag_2_8_13.php @@ -0,0 +1,30 @@ +db->where('option_name', 'version'); + $this->db->update('options', array('option_value' => '2.8.13')); + + // Trigger Version Info Dialog + $this->db->where('option_type', 'version_dialog'); + $this->db->where('option_name', 'confirmed'); + $this->db->update('user_options', array('option_value' => 'false')); + + } + + public function down() + { + $this->db->where('option_name', 'version'); + $this->db->update('options', array('option_value' => '2.8.12')); + } +} \ No newline at end of file From c3b895fc2e0feb915b3a8f23e80f8d1e43aaceb1 Mon Sep 17 00:00:00 2001 From: phl0 Date: Wed, 29 Apr 2026 08:20:06 +0200 Subject: [PATCH 02/48] Suport bands from 23cm to 3cm --- assets/js/sections/simplefle.js | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/assets/js/sections/simplefle.js b/assets/js/sections/simplefle.js index 42aa7e7a1..c8847e8e7 100644 --- a/assets/js/sections/simplefle.js +++ b/assets/js/sections/simplefle.js @@ -659,6 +659,16 @@ function getBandFromFreq(freq) { return "2m"; } else if (freq > 430 && freq < 460) { return "70cm"; + } else if (freq > 1240 && freq < 1300) { + return "23cm"; + } else if (freq > 2300 && freq < 2450) { + return "13cm"; + } else if (freq > 3300 && freq < 3500) { + return "9cm"; + } else if (freq > 5650 && freq < 5925) { + return "6cm"; + } else if (freq > 10000 && freq < 10500) { + return "3cm"; } return ""; From f137a2ed265e95df66dc45c92ff758bb66c77b73 Mon Sep 17 00:00:00 2001 From: phl0 Date: Wed, 29 Apr 2026 09:27:05 +0200 Subject: [PATCH 03/48] Handle band and prop_mode properly --- assets/js/sections/simplefle.js | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/assets/js/sections/simplefle.js b/assets/js/sections/simplefle.js index c8847e8e7..a0605240e 100644 --- a/assets/js/sections/simplefle.js +++ b/assets/js/sections/simplefle.js @@ -240,9 +240,8 @@ function handleInput() { item.match(/^satellite$/i) || item.match(/^sat$/i) ) { - // Set band to SAT and prop_mode + // Set prop_mode to SAT console.log("SAT keyword detected"); - band = "SAT"; prop_mode = "SAT"; freq = 0; } else if (item.match(/^\d+\.\d+$/)) { @@ -267,7 +266,7 @@ function handleInput() { ) { sotaWwff = item.toUpperCase(); } else if ( - band === "SAT" && + prop_mode === "SAT" && item.match(/^[A-Z0-9]+-\d+[A-Z]*$/i) ) { // Satellite name (e.g., AO-7, ISS, FO-29) @@ -283,7 +282,7 @@ function handleInput() { console.log("Satellite NOT found in database. Available:", Object.keys(satelliteData).length, "satellites"); } } else if ( - band === "SAT" && + prop_mode === "SAT" && item.match(/^(ISS|ARISS)$/i) ) { // Handle satellites without numbers (ISS, ARISS) @@ -292,7 +291,7 @@ function handleInput() { // Update visual feedback updateSatelliteFeedback(sat_name, null); } else if ( - band === "SAT" && + prop_mode === "SAT" && sat_name && item.match(/^[UVLSCX](\/[UVLSCX])?$/i) ) { @@ -301,10 +300,11 @@ function handleInput() { // Update visual feedback with selected mode updateSatelliteFeedback(sat_name, sat_mode); // Now populate frequencies from satellite_data.json - console.log("Looking up satellite:", sat_name, "mode:", sat_mode, "band:", band); + console.log("Looking up satellite:", sat_name, "mode:", sat_mode); if (satelliteData[sat_name] && satelliteData[sat_name].Modes && satelliteData[sat_name].Modes[sat_mode]) { var modeData = satelliteData[sat_name].Modes[sat_mode][0]; freq = modeData.Uplink_Freq / 1000000; + band = getBandFromFreq(freq); freq_rx = modeData.Downlink_Freq / 1000000; band_rx = getBandFromFreq(freq_rx); @@ -315,7 +315,7 @@ function handleInput() { } else { mode = modeData.Uplink_Mode; } - console.log("Satellite data found. Freq:", freq, "Mode:", mode, "Band RX:", band_rx); + console.log("Satellite data found. Freq:", freq, "Mode:", mode, "Band:", band, "Band RX:", band_rx); } else { // Satellite mode not found in database, but still valid // User will need to manually set mode if not in database @@ -353,7 +353,7 @@ function handleInput() { console.log("Processing QSO for callsign:", callsign, "Band:", band, "Mode:", mode, "Freq:", freq, "Sat:", sat_name, sat_mode); // For satellite QSOs, freq should already be set from satellite mode lookup // For regular QSOs, calculate freq if not provided - if (band === "SAT") { + if (prop_mode === "SAT") { // Satellite QSO - freq and mode should be set from satellite mode lookup // If not set (satellite not in database), freq will be 0 or empty if (!freq || freq === 0 || freq === "") { From 96eee63bc860397e6d8a179878dc3200a1eb1146 Mon Sep 17 00:00:00 2001 From: Peter Goodhall Date: Wed, 29 Apr 2026 16:52:14 +0100 Subject: [PATCH 04/48] Update upcoming_dxccs.php --- application/views/components/upcoming_dxccs.php | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/application/views/components/upcoming_dxccs.php b/application/views/components/upcoming_dxccs.php index c672993e2..a153b4446 100644 --- a/application/views/components/upcoming_dxccs.php +++ b/application/views/components/upcoming_dxccs.php @@ -9,6 +9,12 @@ Date: Wed, 29 Apr 2026 22:33:22 +0100 Subject: [PATCH 05/48] Add plugin system and Plugin Manager Introduce a plugin framework and management UI: adds Plugin Manager controller, Plugin_awards controller, Plugin_manager and Cloudlog_hooks libraries, Plugins_model, migration (268) to create the plugins table, and views for plugin manager and award pages. Integrates hooks into Logbook_model (qso.filter.before_save, qso.action.after_save, qso.action.after_edit), updates header to show award plugin entries and a Plugin Manager menu link, and bumps migration_version to 268. Also adds .gitignore rules, plugin index placeholder, docs and example plugin packages. The Plugin Manager supports uploading/installing ZIP packages, safe extraction, manifest validation, enable/disable/delete actions, and CSRF protection. --- .gitignore | 2 + application/config/migration.php | 2 +- application/controllers/Plugin_awards.php | 41 ++ application/controllers/Plugins.php | 161 +++++ application/libraries/Cloudlog_hooks.php | 159 +++++ application/libraries/Plugin_manager.php | 609 ++++++++++++++++++ .../migrations/268_create_plugins_table.php | 69 ++ application/models/Logbook_model.php | 27 + application/models/Plugins_model.php | 101 +++ application/plugins/index.html | 8 + application/views/interface_assets/header.php | 13 + application/views/plugins/award_page.php | 10 + application/views/plugins/index.php | 158 +++++ docs/awards-plugin-guide.md | 389 +++++++++++ docs/examples/plugins/award-73-on-73.zip | Bin 0 -> 4493 bytes .../plugins/award-73-on-73/Plugin.php | 244 +++++++ .../examples/plugins/award-73-on-73/README.md | 31 + .../plugins/award-73-on-73/manifest.json | 15 + .../plugins/club-awards-plus/Plugin.php | 80 +++ .../plugins/club-awards-plus/README.md | 30 + .../plugins/club-awards-plus/manifest.json | 20 + docs/plugin-manager-guide.md | 341 ++++++++++ docs/plugin-system-phase1.md | 192 ++++++ 23 files changed, 2701 insertions(+), 1 deletion(-) create mode 100644 application/controllers/Plugin_awards.php create mode 100644 application/controllers/Plugins.php create mode 100644 application/libraries/Cloudlog_hooks.php create mode 100644 application/libraries/Plugin_manager.php create mode 100644 application/migrations/268_create_plugins_table.php create mode 100644 application/models/Plugins_model.php create mode 100644 application/plugins/index.html create mode 100644 application/views/plugins/award_page.php create mode 100644 application/views/plugins/index.php create mode 100644 docs/awards-plugin-guide.md create mode 100644 docs/examples/plugins/award-73-on-73.zip create mode 100644 docs/examples/plugins/award-73-on-73/Plugin.php create mode 100644 docs/examples/plugins/award-73-on-73/README.md create mode 100644 docs/examples/plugins/award-73-on-73/manifest.json create mode 100644 docs/examples/plugins/club-awards-plus/Plugin.php create mode 100644 docs/examples/plugins/club-awards-plus/README.md create mode 100644 docs/examples/plugins/club-awards-plus/manifest.json create mode 100644 docs/plugin-manager-guide.md create mode 100644 docs/plugin-system-phase1.md diff --git a/.gitignore b/.gitignore index 9c704873a..61e9dafa7 100644 --- a/.gitignore +++ b/.gitignore @@ -6,6 +6,8 @@ !/application/cache/index.html !/application/cache/.htaccess /application/logs/*.php +/application/plugins/* +!/application/plugins/index.html /uploads/*.adi /uploads/*.ADI /uploads/*.tq8 diff --git a/application/config/migration.php b/application/config/migration.php index 5bb94b1c6..2377ca66b 100644 --- a/application/config/migration.php +++ b/application/config/migration.php @@ -22,7 +22,7 @@ | */ -$config['migration_version'] = 267; +$config['migration_version'] = 268; /* |-------------------------------------------------------------------------- diff --git a/application/controllers/Plugin_awards.php b/application/controllers/Plugin_awards.php new file mode 100644 index 000000000..b19bff5a0 --- /dev/null +++ b/application/controllers/Plugin_awards.php @@ -0,0 +1,41 @@ +load->model('user_model'); + if (!$this->user_model->authorize(2)) { + $this->session->set_flashdata('notice', 'You\'re not allowed to do that!'); + redirect('dashboard'); + } + + $this->load->library('plugin_manager'); + } + + public function view($slug = '') + { + $slug = strtolower(trim((string)$slug)); + $result = $this->plugin_manager->render_award_page($slug); + + if (!isset($result['ok']) || $result['ok'] !== true) { + $message = isset($result['message']) ? $result['message'] : 'Unable to load plugin award page.'; + $this->session->set_flashdata('notice', $message); + redirect('awards'); + return; + } + + $data['page_title'] = $result['page_title']; + $data['plugin_award_title'] = $result['page_title']; + $data['plugin_award_content'] = $result['content']; + $data['plugin_award_slug'] = $result['plugin_slug']; + + $this->load->view('interface_assets/header', $data); + $this->load->view('plugins/award_page', $data); + $this->load->view('interface_assets/footer'); + } +} diff --git a/application/controllers/Plugins.php b/application/controllers/Plugins.php new file mode 100644 index 000000000..1c2aa1091 --- /dev/null +++ b/application/controllers/Plugins.php @@ -0,0 +1,161 @@ +load->model('user_model'); + if (!$this->user_model->authorize(99)) { + $this->session->set_flashdata('notice', 'You\'re not allowed to do that!'); + redirect('dashboard'); + } + + $this->load->library('plugin_manager'); + } + + public function index() + { + $data['page_title'] = 'Plugin Manager'; + $data['plugins'] = $this->plugin_manager->list_plugins(); + $data['plugins_csrf_token'] = $this->get_plugins_csrf_token(); + + $this->load->view('interface_assets/header', $data); + $this->load->view('plugins/index', $data); + $this->load->view('interface_assets/footer'); + } + + public function upload() + { + if (strtolower($this->input->method()) !== 'post') { + redirect('plugins'); + return; + } + + if (!$this->validate_plugins_csrf_token((string)$this->input->post('plugins_csrf_token', true))) { + $this->session->set_flashdata('notice', 'Security validation failed. Please retry from the Plugin Manager page.'); + redirect('plugins'); + return; + } + + $upload_dir = FCPATH . 'uploads' . DIRECTORY_SEPARATOR . 'plugins' . DIRECTORY_SEPARATOR; + if (!is_dir($upload_dir) && !@mkdir($upload_dir, 0755, true)) { + $this->session->set_flashdata('notice', 'Unable to create plugin upload directory.'); + redirect('plugins'); + return; + } + + $config = array( + 'upload_path' => $upload_dir, + 'allowed_types' => 'zip|ZIP', + 'max_size' => 20480, + 'encrypt_name' => true, + 'detect_mime' => true, + 'mod_mime_fix' => true, + ); + + $this->load->library('upload'); + $this->upload->initialize($config); + + if (!$this->upload->do_upload('plugin_zip')) { + $this->session->set_flashdata('notice', trim(strip_tags($this->upload->display_errors('', '')))); + redirect('plugins'); + return; + } + + $upload_data = $this->upload->data(); + $result = $this->plugin_manager->install_from_zip($upload_data['full_path']); + @unlink($upload_data['full_path']); + + $this->session->set_flashdata('notice', $result['message']); + redirect('plugins'); + } + + public function enable() + { + if (strtolower($this->input->method()) !== 'post') { + redirect('plugins'); + return; + } + + if (!$this->validate_plugins_csrf_token((string)$this->input->post('plugins_csrf_token', true))) { + $this->session->set_flashdata('notice', 'Security validation failed. Please retry from the Plugin Manager page.'); + redirect('plugins'); + return; + } + + $slug = strtolower(trim((string)$this->input->post('plugin_slug', true))); + $result = $this->plugin_manager->set_enabled($slug, true); + $this->session->set_flashdata('notice', $result['message']); + + redirect('plugins'); + } + + public function disable() + { + if (strtolower($this->input->method()) !== 'post') { + redirect('plugins'); + return; + } + + if (!$this->validate_plugins_csrf_token((string)$this->input->post('plugins_csrf_token', true))) { + $this->session->set_flashdata('notice', 'Security validation failed. Please retry from the Plugin Manager page.'); + redirect('plugins'); + return; + } + + $slug = strtolower(trim((string)$this->input->post('plugin_slug', true))); + $result = $this->plugin_manager->set_enabled($slug, false); + $this->session->set_flashdata('notice', $result['message']); + + redirect('plugins'); + } + + public function delete() + { + if (strtolower($this->input->method()) !== 'post') { + redirect('plugins'); + return; + } + + if (!$this->validate_plugins_csrf_token((string)$this->input->post('plugins_csrf_token', true))) { + $this->session->set_flashdata('notice', 'Security validation failed. Please retry from the Plugin Manager page.'); + redirect('plugins'); + return; + } + + $slug = strtolower(trim((string)$this->input->post('plugin_slug', true))); + $result = $this->plugin_manager->delete_plugin($slug); + $this->session->set_flashdata('notice', $result['message']); + + redirect('plugins'); + } + + private function get_plugins_csrf_token() + { + $token = (string)$this->session->userdata(self::PLUGINS_CSRF_SESSION_KEY); + + if ($token === '') { + $token = bin2hex(random_bytes(32)); + $this->session->set_userdata(self::PLUGINS_CSRF_SESSION_KEY, $token); + } + + return $token; + } + + private function validate_plugins_csrf_token($posted_token) + { + $session_token = (string)$this->session->userdata(self::PLUGINS_CSRF_SESSION_KEY); + + if ($session_token === '' || $posted_token === '') { + return false; + } + + return hash_equals($session_token, $posted_token); + } +} diff --git a/application/libraries/Cloudlog_hooks.php b/application/libraries/Cloudlog_hooks.php new file mode 100644 index 000000000..36a65648d --- /dev/null +++ b/application/libraries/Cloudlog_hooks.php @@ -0,0 +1,159 @@ +CI = &get_instance(); + $this->CI->load->model('plugins_model'); + } + + public function apply_filters($hook_name, $payload, $context = array()) + { + $handlers = $this->get_handlers_for_hook($hook_name); + if (empty($handlers)) { + return $payload; + } + + $current = $payload; + foreach ($handlers as $handler) { + $plugin_instance = $this->load_plugin_instance($handler['plugin'], $handler['manifest']); + if (!$plugin_instance) { + continue; + } + + $method = $handler['method']; + if (!method_exists($plugin_instance, $method)) { + continue; + } + + try { + $returned = $plugin_instance->$method($current, $context); + if ($returned !== null) { + $current = $returned; + } + } catch (Throwable $e) { + log_message('error', 'Plugin filter failed [' . $hook_name . '] plugin=' . $handler['plugin']->plugin_slug . ' error=' . $e->getMessage()); + } + } + + return $current; + } + + public function do_action($hook_name, $payload = array(), $context = array()) + { + $handlers = $this->get_handlers_for_hook($hook_name); + if (empty($handlers)) { + return; + } + + foreach ($handlers as $handler) { + $plugin_instance = $this->load_plugin_instance($handler['plugin'], $handler['manifest']); + if (!$plugin_instance) { + continue; + } + + $method = $handler['method']; + if (!method_exists($plugin_instance, $method)) { + continue; + } + + try { + $plugin_instance->$method($payload, $context); + } catch (Throwable $e) { + log_message('error', 'Plugin action failed [' . $hook_name . '] plugin=' . $handler['plugin']->plugin_slug . ' error=' . $e->getMessage()); + } + } + } + + private function get_handlers_for_hook($hook_name) + { + if (!$this->CI->plugins_model->table_exists()) { + return array(); + } + + $enabled_plugins = $this->CI->plugins_model->get_enabled(); + if (empty($enabled_plugins)) { + return array(); + } + + $handlers = array(); + + foreach ($enabled_plugins as $plugin) { + $manifest = json_decode((string)$plugin->plugin_manifest, true); + if (!is_array($manifest) || !isset($manifest['hooks']) || !is_array($manifest['hooks'])) { + continue; + } + + if (!isset($manifest['hooks'][$hook_name])) { + continue; + } + + $method = $manifest['hooks'][$hook_name]; + if (!is_string($method) || $method === '') { + continue; + } + + $handlers[] = array( + 'plugin' => $plugin, + 'manifest' => $manifest, + 'method' => $method, + ); + } + + return $handlers; + } + + private function load_plugin_instance($plugin, $manifest) + { + $slug = $plugin->plugin_slug; + if (isset($this->plugin_instances[$slug])) { + return $this->plugin_instances[$slug]; + } + + $entry_file = isset($manifest['entry']) ? trim((string)$manifest['entry']) : 'Plugin.php'; + $class_name = isset($manifest['class']) ? trim((string)$manifest['class']) : 'Plugin'; + + if (!preg_match('/^[A-Za-z0-9_\/.-]+$/', $entry_file)) { + log_message('error', 'Plugin entry path invalid for ' . $slug); + return null; + } + + if (!preg_match('/^[A-Za-z_][A-Za-z0-9_]*$/', $class_name)) { + log_message('error', 'Plugin class invalid for ' . $slug); + return null; + } + + $plugin_path = APPPATH . 'plugins' . DIRECTORY_SEPARATOR . $slug . DIRECTORY_SEPARATOR; + $entry_path = realpath($plugin_path . $entry_file); + $plugin_root = realpath($plugin_path); + + if ($plugin_root === false || $entry_path === false || strpos($entry_path, $plugin_root) !== 0) { + log_message('error', 'Plugin entry file missing or outside plugin root for ' . $slug); + return null; + } + + require_once $entry_path; + + if (!class_exists($class_name)) { + log_message('error', 'Plugin class not found: ' . $class_name . ' (' . $slug . ')'); + return null; + } + + try { + $instance = new $class_name($this->CI); + } catch (Throwable $e) { + log_message('error', 'Plugin construction failed (' . $slug . '): ' . $e->getMessage()); + return null; + } + + $this->plugin_instances[$slug] = $instance; + + return $instance; + } +} diff --git a/application/libraries/Plugin_manager.php b/application/libraries/Plugin_manager.php new file mode 100644 index 000000000..f1b8cd0d6 --- /dev/null +++ b/application/libraries/Plugin_manager.php @@ -0,0 +1,609 @@ +CI = &get_instance(); + $this->CI->load->model('plugins_model'); + } + + public function list_plugins() + { + $plugins = $this->CI->plugins_model->get_all(); + $result = array(); + + foreach ($plugins as $plugin) { + $manifest = json_decode((string)$plugin->plugin_manifest, true); + if (!is_array($manifest)) { + $manifest = array(); + } + + $plugin_dir = $this->get_plugin_root() . $plugin->plugin_slug . DIRECTORY_SEPARATOR; + $manifest_path = $plugin_dir . 'manifest.json'; + + if (is_file($manifest_path)) { + $disk_manifest = $this->read_manifest($manifest_path); + if ($disk_manifest) { + $manifest = $disk_manifest; + } + } + + $result[] = (object)array( + 'plugin_slug' => $plugin->plugin_slug, + 'plugin_name' => isset($manifest['name']) ? $manifest['name'] : $plugin->plugin_name, + 'plugin_version' => isset($manifest['version']) ? $manifest['version'] : $plugin->plugin_version, + 'plugin_description' => isset($manifest['description']) ? $manifest['description'] : $plugin->plugin_description, + 'plugin_status' => $plugin->plugin_status, + 'installed_at' => $plugin->installed_at, + 'updated_at' => $plugin->updated_at, + 'path_exists' => is_dir($plugin_dir), + ); + } + + return $result; + } + + public function install_from_zip($zip_file) + { + if (!$this->CI->plugins_model->table_exists()) { + return array('ok' => false, 'message' => 'Plugins table does not exist. Run migrations first.'); + } + + if (!class_exists('ZipArchive')) { + return array('ok' => false, 'message' => 'ZipArchive extension is not available on this server.'); + } + + $this->ensure_plugin_root(); + + $zip = new ZipArchive(); + $open_result = $zip->open($zip_file); + if ($open_result !== true) { + return array('ok' => false, 'message' => 'Could not open plugin zip file.'); + } + + $invalid_path = $this->find_invalid_archive_path($zip); + if ($invalid_path !== null) { + $zip->close(); + return array('ok' => false, 'message' => 'Plugin archive contains an invalid path: ' . $invalid_path); + } + + $temp_base = FCPATH . 'uploads' . DIRECTORY_SEPARATOR . 'plugins_tmp' . DIRECTORY_SEPARATOR; + if (!is_dir($temp_base) && !@mkdir($temp_base, 0755, true)) { + $zip->close(); + return array('ok' => false, 'message' => 'Unable to create plugin temp directory.'); + } + + $extract_dir = $temp_base . uniqid('plugin_', true) . DIRECTORY_SEPARATOR; + if (!@mkdir($extract_dir, 0755, true)) { + $zip->close(); + return array('ok' => false, 'message' => 'Unable to create plugin extraction directory.'); + } + + if (!$zip->extractTo($extract_dir)) { + $zip->close(); + $this->recursive_delete($extract_dir); + return array('ok' => false, 'message' => 'Failed to extract plugin archive.'); + } + $zip->close(); + + $plugin_root = $this->resolve_extracted_plugin_root($extract_dir); + if ($plugin_root === null) { + $this->recursive_delete($extract_dir); + return array('ok' => false, 'message' => 'manifest.json was not found in the uploaded plugin.'); + } + + $manifest_path = $plugin_root . 'manifest.json'; + $manifest = $this->read_manifest($manifest_path); + if (!$manifest) { + $this->recursive_delete($extract_dir); + return array('ok' => false, 'message' => 'manifest.json is invalid JSON.'); + } + + $award_menu_warning = $this->validate_award_menu_definition($plugin_root, $manifest); + + $slug = $this->resolve_slug($manifest); + if ($slug === null) { + $this->recursive_delete($extract_dir); + return array('ok' => false, 'message' => 'manifest.json must include a valid slug (letters, numbers, _ or -).'); + } + + $dest_dir = $this->get_plugin_root() . $slug . DIRECTORY_SEPARATOR; + + $is_upgrade = false; + $previous_version = null; + $backup_dir = null; + + if (is_dir($dest_dir)) { + $is_upgrade = true; + + $existing_manifest_path = $dest_dir . 'manifest.json'; + if (is_file($existing_manifest_path)) { + $existing_manifest = $this->read_manifest($existing_manifest_path); + if (is_array($existing_manifest) && isset($existing_manifest['version'])) { + $previous_version = (string)$existing_manifest['version']; + } + } + + $backup_base = FCPATH . 'uploads' . DIRECTORY_SEPARATOR . 'plugins_backup' . DIRECTORY_SEPARATOR; + if (!is_dir($backup_base) && !@mkdir($backup_base, 0755, true)) { + $this->recursive_delete($extract_dir); + return array('ok' => false, 'message' => 'Unable to create plugin backup directory.'); + } + + $backup_dir = $backup_base . $slug . '_' . date('Ymd_His') . '_' . substr(sha1(uniqid('', true)), 0, 8) . DIRECTORY_SEPARATOR; + if (!@rename($dest_dir, $backup_dir)) { + $this->recursive_delete($extract_dir); + return array('ok' => false, 'message' => 'Unable to backup existing plugin before upgrade.'); + } + } + + if (!$this->recursive_copy($plugin_root, $dest_dir)) { + $this->recursive_delete($extract_dir); + if ($is_upgrade && $backup_dir !== null && is_dir($backup_dir)) { + @rename($backup_dir, $dest_dir); + } + return array('ok' => false, 'message' => 'Failed to copy plugin files into application/plugins.'); + } + + $this->recursive_delete($extract_dir); + + if (!$this->CI->plugins_model->upsert_plugin($slug, $manifest, 'disabled')) { + $this->recursive_delete($dest_dir); + if ($is_upgrade && $backup_dir !== null && is_dir($backup_dir)) { + @rename($backup_dir, $dest_dir); + } + return array('ok' => false, 'message' => 'Failed to persist plugin metadata.'); + } + + if ($is_upgrade && $backup_dir !== null && is_dir($backup_dir)) { + $this->recursive_delete($backup_dir); + } + + $plugin_name = isset($manifest['name']) ? $manifest['name'] : $slug; + $new_version = isset($manifest['version']) ? (string)$manifest['version'] : null; + + if ($is_upgrade) { + if ($previous_version !== null && $new_version !== null) { + $message = 'Plugin upgraded: ' . $plugin_name . ' (' . $previous_version . ' -> ' . $new_version . ')'; + } else { + $message = 'Plugin upgraded: ' . $plugin_name; + } + } else { + $message = 'Plugin installed: ' . $plugin_name; + } + + if ($award_menu_warning !== null) { + $message .= ' Warning: ' . $award_menu_warning; + } + + return array('ok' => true, 'message' => $message); + } + + public function set_enabled($slug, $enabled) + { + if (!preg_match('/^[a-z0-9_-]+$/', $slug)) { + return array('ok' => false, 'message' => 'Invalid plugin slug.'); + } + + $plugin = $this->CI->plugins_model->get_by_slug($slug); + if (!$plugin) { + return array('ok' => false, 'message' => 'Plugin not found.'); + } + + $plugin_dir = $this->get_plugin_root() . $slug . DIRECTORY_SEPARATOR; + if (!is_dir($plugin_dir)) { + return array('ok' => false, 'message' => 'Plugin files are missing on disk.'); + } + + $status = $enabled ? 'enabled' : 'disabled'; + if (!$this->CI->plugins_model->set_status($slug, $status)) { + return array('ok' => false, 'message' => 'Failed to update plugin status.'); + } + + return array('ok' => true, 'message' => 'Plugin ' . $status . ': ' . $slug); + } + + public function delete_plugin($slug) + { + if (!preg_match('/^[a-z0-9_-]+$/', $slug)) { + return array('ok' => false, 'message' => 'Invalid plugin slug.'); + } + + if (!$this->CI->plugins_model->table_exists()) { + return array('ok' => false, 'message' => 'Plugins table does not exist.'); + } + + $plugin = $this->CI->plugins_model->get_by_slug($slug); + if (!$plugin) { + return array('ok' => false, 'message' => 'Plugin not found.'); + } + + $plugin_dir = $this->get_plugin_root() . $slug . DIRECTORY_SEPARATOR; + if (is_dir($plugin_dir)) { + $this->recursive_delete($plugin_dir); + if (is_dir($plugin_dir)) { + return array('ok' => false, 'message' => 'Failed to remove plugin files from disk.'); + } + } + + if (!$this->CI->plugins_model->delete_by_slug($slug)) { + return array('ok' => false, 'message' => 'Failed to remove plugin metadata.'); + } + + return array('ok' => true, 'message' => 'Plugin deleted: ' . $slug); + } + + public function get_award_menu_entries() + { + if (!$this->CI->plugins_model->table_exists()) { + return array(); + } + + $enabled_plugins = $this->CI->plugins_model->get_enabled(); + $entries = array(); + + foreach ($enabled_plugins as $plugin) { + $manifest = $this->get_manifest_for_plugin($plugin); + if (!is_array($manifest) || !isset($manifest['award_menu']) || !is_array($manifest['award_menu'])) { + continue; + } + + $award_menu = $manifest['award_menu']; + $title = isset($award_menu['title']) ? trim((string)$award_menu['title']) : ''; + if ($title === '') { + continue; + } + + $route = isset($award_menu['route']) ? trim((string)$award_menu['route']) : 'plugin_awards/view/' . $plugin->plugin_slug; + $route = ltrim($route, '/'); + if (!preg_match('/^[A-Za-z0-9_\/-]+$/', $route)) { + continue; + } + + $icon = isset($award_menu['icon']) ? trim((string)$award_menu['icon']) : 'fas fa-award'; + if ($icon === '') { + $icon = 'fas fa-award'; + } + + $order = isset($award_menu['order']) ? (int)$award_menu['order'] : 100; + + $entries[] = array( + 'slug' => $plugin->plugin_slug, + 'title' => $title, + 'icon' => $icon, + 'route' => $route, + 'order' => $order, + ); + } + + usort($entries, static function ($a, $b) { + if ($a['order'] === $b['order']) { + return strcmp($a['title'], $b['title']); + } + return $a['order'] <=> $b['order']; + }); + + return $entries; + } + + public function render_award_page($slug) + { + if (!preg_match('/^[a-z0-9_-]+$/', $slug)) { + return array('ok' => false, 'message' => 'Invalid plugin slug.'); + } + + if (!$this->CI->plugins_model->table_exists()) { + return array('ok' => false, 'message' => 'Plugins table does not exist.'); + } + + $plugin = $this->CI->plugins_model->get_by_slug($slug); + if (!$plugin || $plugin->plugin_status !== 'enabled') { + return array('ok' => false, 'message' => 'Award plugin is not enabled.'); + } + + $manifest = $this->get_manifest_for_plugin($plugin); + if (!is_array($manifest) || !isset($manifest['award_menu']) || !is_array($manifest['award_menu'])) { + return array('ok' => false, 'message' => 'Plugin does not declare an award menu entry.'); + } + + $award_menu = $manifest['award_menu']; + $method = isset($award_menu['method']) ? trim((string)$award_menu['method']) : 'renderAwardPage'; + if (!preg_match('/^[A-Za-z_][A-Za-z0-9_]*$/', $method)) { + return array('ok' => false, 'message' => 'Invalid plugin award method.'); + } + + $instance = $this->instantiate_plugin($plugin, $manifest); + if (!$instance) { + return array('ok' => false, 'message' => 'Unable to load plugin class.'); + } + + if (!method_exists($instance, $method)) { + return array('ok' => false, 'message' => 'Plugin award method not found: ' . $method); + } + + try { + $result = $instance->$method(array( + 'slug' => $slug, + 'manifest' => $manifest, + 'user_id' => (int)$this->CI->session->userdata('user_id'), + )); + } catch (Throwable $e) { + log_message('error', 'Plugin award render failed (' . $slug . '): ' . $e->getMessage()); + return array('ok' => false, 'message' => 'Plugin award rendering failed.'); + } + + $page_title = isset($award_menu['title']) ? (string)$award_menu['title'] : $plugin->plugin_name; + $content = ''; + + if (is_string($result)) { + $content = $result; + } elseif (is_array($result)) { + if (isset($result['page_title'])) { + $page_title = (string)$result['page_title']; + } + if (isset($result['content'])) { + $content = (string)$result['content']; + } + } + + if (trim($content) === '') { + return array('ok' => false, 'message' => 'Plugin award page returned empty content.'); + } + + return array( + 'ok' => true, + 'page_title' => $page_title, + 'content' => $content, + 'plugin_slug' => $slug, + ); + } + + public function get_plugin_root() + { + return APPPATH . 'plugins' . DIRECTORY_SEPARATOR; + } + + private function get_manifest_for_plugin($plugin) + { + $manifest = json_decode((string)$plugin->plugin_manifest, true); + if (!is_array($manifest)) { + $manifest = array(); + } + + $plugin_dir = $this->get_plugin_root() . $plugin->plugin_slug . DIRECTORY_SEPARATOR; + $manifest_path = $plugin_dir . 'manifest.json'; + if (is_file($manifest_path)) { + $disk_manifest = $this->read_manifest($manifest_path); + if ($disk_manifest) { + $manifest = $disk_manifest; + } + } + + return $manifest; + } + + private function instantiate_plugin($plugin, $manifest) + { + $entry_file = isset($manifest['entry']) ? trim((string)$manifest['entry']) : 'Plugin.php'; + $class_name = isset($manifest['class']) ? trim((string)$manifest['class']) : 'Plugin'; + + if (!preg_match('/^[A-Za-z0-9_\/.-]+$/', $entry_file)) { + log_message('error', 'Plugin entry path invalid for ' . $plugin->plugin_slug); + return null; + } + + if (!preg_match('/^[A-Za-z_][A-Za-z0-9_]*$/', $class_name)) { + log_message('error', 'Plugin class invalid for ' . $plugin->plugin_slug); + return null; + } + + $plugin_path = $this->get_plugin_root() . $plugin->plugin_slug . DIRECTORY_SEPARATOR; + $entry_path = realpath($plugin_path . $entry_file); + $plugin_root = realpath($plugin_path); + + if ($plugin_root === false || $entry_path === false || strpos($entry_path, $plugin_root) !== 0) { + log_message('error', 'Plugin entry file missing or outside plugin root for ' . $plugin->plugin_slug); + return null; + } + + require_once $entry_path; + + if (!class_exists($class_name)) { + log_message('error', 'Plugin class not found: ' . $class_name . ' (' . $plugin->plugin_slug . ')'); + return null; + } + + try { + return new $class_name($this->CI); + } catch (Throwable $e) { + log_message('error', 'Plugin construction failed (' . $plugin->plugin_slug . '): ' . $e->getMessage()); + return null; + } + } + + private function validate_award_menu_definition($plugin_root, $manifest) + { + if (!isset($manifest['award_menu']) || !is_array($manifest['award_menu'])) { + return null; + } + + $award_menu = $manifest['award_menu']; + $method = isset($award_menu['method']) ? trim((string)$award_menu['method']) : 'renderAwardPage'; + if (!preg_match('/^[A-Za-z_][A-Za-z0-9_]*$/', $method)) { + return 'award_menu.method is invalid and may prevent Awards dropdown rendering.'; + } + + $entry_file = isset($manifest['entry']) ? trim((string)$manifest['entry']) : 'Plugin.php'; + if (!preg_match('/^[A-Za-z0-9_\/.-]+$/', $entry_file)) { + return 'award_menu is declared but entry path is invalid.'; + } + + $entry_path = realpath($plugin_root . $entry_file); + $plugin_root_real = realpath($plugin_root); + if ($entry_path === false || $plugin_root_real === false || strpos($entry_path, $plugin_root_real) !== 0 || !is_file($entry_path)) { + return 'award_menu is declared but plugin entry file was not found.'; + } + + $entry_content = @file_get_contents($entry_path); + if ($entry_content === false) { + return 'award_menu is declared but plugin entry file could not be read.'; + } + + $method_regex = '/function\s+' . preg_quote($method, '/') . '\s*\(/i'; + if (!preg_match($method_regex, $entry_content)) { + return 'award_menu is declared but method ' . $method . ' was not found in ' . $entry_file . '.'; + } + + return null; + } + + private function ensure_plugin_root() + { + $plugin_root = $this->get_plugin_root(); + if (!is_dir($plugin_root)) { + @mkdir($plugin_root, 0755, true); + @file_put_contents($plugin_root . 'index.html', ''); + } + } + + private function find_invalid_archive_path(ZipArchive $zip) + { + for ($i = 0; $i < $zip->numFiles; $i++) { + $name = $zip->getNameIndex($i); + if ($name === false) { + return 'unknown'; + } + + $normalized = str_replace('\\', '/', $name); + if (strpos($normalized, '../') !== false || strpos($normalized, '..\\') !== false) { + return $name; + } + + if (preg_match('/^[a-zA-Z]:\//', $normalized) || strpos($normalized, '/') === 0) { + return $name; + } + } + + return null; + } + + private function resolve_extracted_plugin_root($extract_dir) + { + if (is_file($extract_dir . 'manifest.json')) { + return $extract_dir; + } + + $entries = @scandir($extract_dir); + if (!is_array($entries)) { + return null; + } + + foreach ($entries as $entry) { + if ($entry === '.' || $entry === '..') { + continue; + } + + $path = $extract_dir . $entry; + if (is_dir($path) && is_file($path . DIRECTORY_SEPARATOR . 'manifest.json')) { + return $path . DIRECTORY_SEPARATOR; + } + } + + return null; + } + + private function read_manifest($manifest_path) + { + $content = @file_get_contents($manifest_path); + if ($content === false) { + return null; + } + + $manifest = json_decode($content, true); + if (!is_array($manifest)) { + return null; + } + + return $manifest; + } + + private function resolve_slug($manifest) + { + if (!isset($manifest['slug'])) { + return null; + } + + $slug = strtolower(trim((string)$manifest['slug'])); + if (!preg_match('/^[a-z0-9_-]+$/', $slug)) { + return null; + } + + return $slug; + } + + private function recursive_copy($src, $dst) + { + if (!is_dir($src)) { + return false; + } + + if (!is_dir($dst) && !@mkdir($dst, 0755, true)) { + return false; + } + + $items = @scandir($src); + if (!is_array($items)) { + return false; + } + + foreach ($items as $item) { + if ($item === '.' || $item === '..') { + continue; + } + + $from = $src . DIRECTORY_SEPARATOR . $item; + $to = $dst . DIRECTORY_SEPARATOR . $item; + + if (is_dir($from)) { + if (!$this->recursive_copy($from, $to)) { + return false; + } + } else { + if (!@copy($from, $to)) { + return false; + } + } + } + + return true; + } + + private function recursive_delete($path) + { + if (!file_exists($path)) { + return; + } + + if (is_file($path) || is_link($path)) { + @unlink($path); + return; + } + + $items = @scandir($path); + if (is_array($items)) { + foreach ($items as $item) { + if ($item === '.' || $item === '..') { + continue; + } + $this->recursive_delete($path . DIRECTORY_SEPARATOR . $item); + } + } + + @rmdir($path); + } +} diff --git a/application/migrations/268_create_plugins_table.php b/application/migrations/268_create_plugins_table.php new file mode 100644 index 000000000..51894e467 --- /dev/null +++ b/application/migrations/268_create_plugins_table.php @@ -0,0 +1,69 @@ +db->table_exists('plugins')) { + $this->dbforge->add_field(array( + 'id' => array( + 'type' => 'INT', + 'constraint' => 11, + 'unsigned' => TRUE, + 'auto_increment' => TRUE, + ), + 'plugin_slug' => array( + 'type' => 'VARCHAR', + 'constraint' => 120, + 'null' => FALSE, + ), + 'plugin_name' => array( + 'type' => 'VARCHAR', + 'constraint' => 255, + 'null' => FALSE, + ), + 'plugin_version' => array( + 'type' => 'VARCHAR', + 'constraint' => 60, + 'null' => FALSE, + 'default' => '1.0.0', + ), + 'plugin_description' => array( + 'type' => 'TEXT', + 'null' => TRUE, + ), + 'plugin_status' => array( + 'type' => 'VARCHAR', + 'constraint' => 16, + 'null' => FALSE, + 'default' => 'disabled', + ), + 'plugin_manifest' => array( + 'type' => 'MEDIUMTEXT', + 'null' => TRUE, + ), + 'installed_at' => array( + 'type' => 'DATETIME', + 'null' => FALSE, + ), + 'updated_at' => array( + 'type' => 'DATETIME', + 'null' => FALSE, + ), + )); + + $this->dbforge->add_key('id', TRUE); + $this->dbforge->add_key('plugin_slug', TRUE); + $this->dbforge->create_table('plugins'); + } + } + + public function down() + { + if ($this->db->table_exists('plugins')) { + $this->dbforge->drop_table('plugins'); + } + } +} diff --git a/application/models/Logbook_model.php b/application/models/Logbook_model.php index c3d7db787..ed8118f8a 100755 --- a/application/models/Logbook_model.php +++ b/application/models/Logbook_model.php @@ -443,6 +443,16 @@ function create_qso() $data['COL_LOTW_QSL_RCVD'] = 'N'; } + $this->load->library('cloudlog_hooks'); + $filtered_data = $this->cloudlog_hooks->apply_filters('qso.filter.before_save', $data, array( + 'source' => 'manual', + 'station_id' => $station_id, + )); + + if (is_array($filtered_data)) { + $data = $filtered_data; + } + $this->add_qso($data, $skipexport = false); } @@ -746,6 +756,15 @@ function add_qso($data, $skipexport = false) $this->upload_amsat_status($data); } + $this->load->library('cloudlog_hooks'); + $this->cloudlog_hooks->do_action('qso.action.after_save', array( + 'qso_id' => $last_id, + 'qso' => $data, + ), array( + 'source' => $skipexport ? 'import' : 'manual', + 'station_id' => isset($data['station_id']) ? $data['station_id'] : null, + )); + // No point in fetching hrdlog code or qrz api key and qrzrealtime setting if we're skipping the export if (!$skipexport) { @@ -1529,6 +1548,14 @@ function edit() // Clear dashboard cache for affected station $this->clear_dashboard_cache($stationId); + + $this->load->library('cloudlog_hooks'); + $this->cloudlog_hooks->do_action('qso.action.after_edit', array( + 'qso_id' => (int)$this->input->post('id'), + 'qso' => $data, + ), array( + 'station_id' => $stationId, + )); } /* QSL received */ diff --git a/application/models/Plugins_model.php b/application/models/Plugins_model.php new file mode 100644 index 000000000..fbdf517a5 --- /dev/null +++ b/application/models/Plugins_model.php @@ -0,0 +1,101 @@ +db->table_exists('plugins'); + } + + public function get_all() + { + if (!$this->table_exists()) { + return array(); + } + + $this->db->order_by('plugin_name', 'ASC'); + return $this->db->get('plugins')->result(); + } + + public function get_enabled() + { + if (!$this->table_exists()) { + return array(); + } + + $this->db->where('plugin_status', 'enabled'); + return $this->db->get('plugins')->result(); + } + + public function get_by_slug($slug) + { + if (!$this->table_exists()) { + return null; + } + + $this->db->where('plugin_slug', $slug); + $query = $this->db->get('plugins'); + + return $query->num_rows() > 0 ? $query->row() : null; + } + + public function upsert_plugin($slug, $manifest, $status = 'disabled') + { + if (!$this->table_exists()) { + return false; + } + + $now = date('Y-m-d H:i:s'); + $existing = $this->get_by_slug($slug); + + $data = array( + 'plugin_slug' => $slug, + 'plugin_name' => isset($manifest['name']) ? (string)$manifest['name'] : $slug, + 'plugin_version' => isset($manifest['version']) ? (string)$manifest['version'] : '1.0.0', + 'plugin_description' => isset($manifest['description']) ? (string)$manifest['description'] : null, + 'plugin_manifest' => json_encode($manifest), + 'updated_at' => $now, + ); + + if ($existing) { + if ($existing->plugin_status === 'enabled') { + $data['plugin_status'] = 'enabled'; + } else { + $data['plugin_status'] = $status; + } + + $this->db->where('plugin_slug', $slug); + return $this->db->update('plugins', $data); + } + + $data['plugin_status'] = $status; + $data['installed_at'] = $now; + + return $this->db->insert('plugins', $data); + } + + public function set_status($slug, $status) + { + if (!$this->table_exists()) { + return false; + } + + $this->db->where('plugin_slug', $slug); + return $this->db->update('plugins', array( + 'plugin_status' => $status, + 'updated_at' => date('Y-m-d H:i:s'), + )); + } + + public function delete_by_slug($slug) + { + if (!$this->table_exists()) { + return false; + } + + $this->db->where('plugin_slug', $slug); + return $this->db->delete('plugins'); + } +} diff --git a/application/plugins/index.html b/application/plugins/index.html new file mode 100644 index 000000000..0c44a9d3d --- /dev/null +++ b/application/plugins/index.html @@ -0,0 +1,8 @@ + + + + + + + + diff --git a/application/views/interface_assets/header.php b/application/views/interface_assets/header.php index ffedfec0f..652e1b49e 100644 --- a/application/views/interface_assets/header.php +++ b/application/views/interface_assets/header.php @@ -261,6 +261,15 @@
+ load->library('plugin_manager'); + $plugin_award_entries = $CI->plugin_manager->get_award_menu_entries(); + if (!empty($plugin_award_entries)) { + foreach ($plugin_award_entries as $plugin_award_entry) { ?> + +
+
  • @@ -314,6 +323,10 @@
    + Plugin Manager + +
    + diff --git a/application/views/plugins/award_page.php b/application/views/plugins/award_page.php new file mode 100644 index 000000000..12cf9446d --- /dev/null +++ b/application/views/plugins/award_page.php @@ -0,0 +1,10 @@ +
    +

    +

    Provided by plugin:

    + +
    +
    + +
    +
    +
    diff --git a/application/views/plugins/index.php b/application/views/plugins/index.php new file mode 100644 index 000000000..7e15c1b48 --- /dev/null +++ b/application/views/plugins/index.php @@ -0,0 +1,158 @@ +
    +

    Plugin Manager

    +

    Upload a plugin zip package, install it, and control whether it is enabled.

    + +
    +
    + Upload Plugin +
    +
    +
    + +
    + + +
    Plugin packages must include a manifest.json at the plugin root.
    +
    +
    + +
    +
    +
    +
    + +
    +
    + Installed Plugins +
    +
    +
    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    NameSlugVersionStatusFilesInstalledActions
    + plugin_name); ?> + plugin_description)) { ?> +
    plugin_description); ?>
    + +     		plugin_slug); ?>plugin_version); ?> + plugin_status === 'enabled') { ?> + Enabled + + Disabled + + + path_exists) { ?> + Present + + Missing + + installed_at); ?> + plugin_status === 'enabled') { ?> +
    + + + +
    + +
    + + + +
    + + +
    No plugins installed yet.
    +
    +
    +
    +
    + + + + diff --git a/docs/awards-plugin-guide.md b/docs/awards-plugin-guide.md new file mode 100644 index 000000000..27961e710 --- /dev/null +++ b/docs/awards-plugin-guide.md @@ -0,0 +1,389 @@ +# Cloudlog Awards Plugin Guide (Full) + +This guide explains how to create a full Awards plugin for Cloudlog (CodeIgniter 3), from folder layout to packaging, installation, upgrades, and troubleshooting. + +It is written for the plugin system implemented in Phase 1. + +For Plugin Manager internals and lifecycle details, see: + +- [docs/plugin-manager-guide.md](docs/plugin-manager-guide.md) + +## 1. What an Awards Plugin Can Do + +An awards plugin can: + +- Add a new item to the Awards dropdown menu. +- Render a custom award page at runtime. +- Query Cloudlog logbook data and compute custom award metrics. +- Optionally participate in hook events (before save, after save, after edit). + +The core idea is: + +1. Cloudlog reads your plugin manifest. +2. If `award_menu` exists, your plugin appears in Awards. +3. Cloudlog loads your plugin class and calls your render method. + +## 2. Prerequisites + +- Cloudlog with plugin system migrations applied. +- Access to Admin > Plugin Manager. +- A working development install with sample config already set. +- Basic PHP + SQL understanding. + +## 3. Plugin Folder Layout + +Create a folder for your plugin package: + +```text +my-award-plugin/ + manifest.json + Plugin.php + README.md +``` + +Minimum required files: + +- `manifest.json` +- your entry PHP file (usually `Plugin.php`) + +Useful references in this repository: + +- [docs/examples/plugins/award-73-on-73/manifest.json](docs/examples/plugins/award-73-on-73/manifest.json) +- [docs/examples/plugins/award-73-on-73/Plugin.php](docs/examples/plugins/award-73-on-73/Plugin.php) +- [docs/examples/plugins/club-awards-plus/manifest.json](docs/examples/plugins/club-awards-plus/manifest.json) + +## 4. Manifest: Required and Optional Fields + +Create `manifest.json`: + +```json +{ + "slug": "my-award-plugin", + "name": "My Award Plugin", + "version": "1.0.0", + "description": "Custom award for my club.", + "entry": "Plugin.php", + "class": "MyAwardPlugin", + "award_menu": { + "title": "My Award", + "icon": "fas fa-award", + "route": "plugin_awards/view/my-award-plugin", + "method": "renderAwardPage", + "order": 110 + } +} +``` + +### Required + +- `slug`: lowercase letters, numbers, `_`, `-`. +- `name` +- `version` + +### Strongly recommended + +- `entry` +- `class` +- `description` + +### `award_menu` fields + +- `title`: text shown in Awards dropdown. +- `icon`: Font Awesome class. +- `route`: normally `plugin_awards/view/`. +- `method`: class method used to render the page. +- `order`: lower numbers appear earlier. + +## 5. Plugin Class: Minimal Award Renderer + +Create `Plugin.php`: + +```php +CI = $ci; + } + + public function renderAwardPage($context = array()) + { + $content = ''; + $content .= '
    My Award Plugin is active.
    '; + $content .= '

    Replace this with your custom award stats and tables.

    '; + + return array( + 'page_title' => 'Awards - My Award', + 'content' => $content, + ); + } +} +``` + +Cloudlog loads this class and calls the method defined in `award_menu.method`. + +## 6. Accessing Active Logbook Scope + +Most award plugins should only use station locations attached to the current active logbook. + +Pattern: + +```php +$this->CI->load->model('logbooks_model'); + +$active_logbook = $this->CI->session->userdata('active_station_logbook'); +$station_ids = $this->CI->logbooks_model->list_logbook_relationships($active_logbook); + +if (empty($station_ids) || !is_array($station_ids)) { + return array( + 'page_title' => 'Awards - My Award', + 'content' => '
    No station locations are associated with your active logbook.
    ', + ); +} +``` + +This keeps your award results consistent with the rest of the UI. + +## 7. Querying QSO Data Safely + +Use CI Query Builder. Example: + +```php +$table = $this->CI->config->item('table_name'); + +$this->CI->db->select('COL_CALL, COL_TIME_ON, COL_MODE, COL_GRIDSQUARE, COL_VUCC_GRIDS'); +$this->CI->db->from($table); +$this->CI->db->where_in('station_id', $station_ids); +$this->CI->db->where('UPPER(TRIM(COL_SAT_NAME))', 'AO-73'); +$this->CI->db->group_start(); +$this->CI->db->where('COL_LOTW_QSL_RCVD', 'Y'); +$this->CI->db->or_where('COL_QSL_RCVD', 'Y'); +$this->CI->db->group_end(); +$this->CI->db->order_by('COL_CALL', 'ASC'); +$this->CI->db->order_by('COL_TIME_ON', 'ASC'); + +$query = $this->CI->db->get(); +$rows = $query ? $query->result() : array(); +``` + +Good practices: + +- Filter by active logbook station IDs. +- Normalize fields like callsign and gridsquare (`trim`, `strtoupper`). +- Keep SQL conditions explicit for confirmations. +- Favor deterministic ordering. + +## 8. Date and Time Formatting (User Preference) + +Use user-custom date format if set, fallback to system format: + +```php +$custom_date_format = $this->CI->session->userdata('user_date_format'); +if (!$custom_date_format) { + $custom_date_format = $this->CI->config->item('qso_date_format'); +} + +$ts = strtotime($qso_time); +$display = $ts ? date($custom_date_format, $ts) . ' ' . date('H:i', $ts) : '-'; +``` + +This matches Cloudlog conventions used in core pages. + +## 9. Grid Display Rule (VUCC Preferred) + +If your plugin shows grid information, follow Cloudlog behavior: + +1. Prefer `COL_VUCC_GRIDS` when present. +2. Otherwise use `COL_GRIDSQUARE`. + +Example: + +```php +$vucc = strtoupper(trim((string)($row->COL_VUCC_GRIDS ?? ''))); +$grid = strtoupper(trim((string)($row->COL_GRIDSQUARE ?? ''))); +$grid_to_show = $vucc !== '' ? $vucc : $grid; +``` + +## 10. Building the Award Page UI + +Most plugins generate HTML as a string and return it in `content`. + +Guidelines: + +- Escape dynamic output with `htmlspecialchars(..., ENT_QUOTES, 'UTF-8')`. +- Keep layout Bootstrap-compatible (`card`, `table`, `alert`, etc). +- Return clear empty-state messages. + +Return format: + +```php +return array( + 'page_title' => 'Awards - My Award', + 'content' => $content, +); +``` + +## 11. CSV Export for Table Data + +A common pattern in Cloudlog awards is browser-side CSV export from the visible table. + +Typical approach: + +1. Give your table an ID. +2. Add an Export CSV button. +3. Add a small JS function that reads table header/body and downloads CSV. + +Use your plugin-specific IDs to avoid collisions. + +## 12. Optional: Hook Integration + +Awards plugins may also register hooks to enrich QSO data or trigger side effects. + +Manifest example: + +```json +"hooks": { + "qso.filter.before_save": "beforeSave", + "qso.action.after_save": "afterSave", + "qso.action.after_edit": "afterEdit" +} +``` + +Example methods: + +```php +public function beforeSave($payload, $context = array()) +{ + if (!is_array($payload)) { + return $payload; + } + return $payload; +} + +public function afterSave($payload, $context = array()) +{ + // side effects/logging only +} + +public function afterEdit($payload, $context = array()) +{ + // side effects/logging only +} +``` + +Hook errors are logged; core saves continue. + +## 13. Packaging and Installing + +1. Zip plugin folder contents. +2. In Cloudlog, open Admin > Plugin Manager. +3. Upload zip and install. +4. Enable plugin. +5. Open Awards dropdown and click your plugin. + +Installer notes: + +- If same slug already exists, installer upgrades in place. +- Existing files are backed up and restored automatically on failure. + +## 14. Versioning and Upgrade Strategy + +When releasing changes: + +1. Update `version` in `manifest.json`. +2. Keep `slug` stable. +3. Upload zip via Plugin Manager. +4. Verify plugin still enabled after upgrade. + +Recommended version pattern: + +- Patch: `1.0.0` -> `1.0.1` for fixes. +- Minor: `1.0.x` -> `1.1.0` for non-breaking features. + +## 15. Security Checklist + +- Escape all user/database output in HTML. +- Never trust raw POST/GET without validation. +- Do not execute arbitrary shell commands. +- Keep plugin logic synchronous and predictable. +- Install only trusted plugin packages. + +## 16. Testing Checklist + +Functional checks: + +1. Plugin appears in Plugin Manager after install. +2. Enable/disable works. +3. Awards menu entry appears only when enabled. +4. Award page renders without PHP errors. +5. Empty logbook scope shows safe warning. +6. Counts match expected QSOs. +7. Date/time follows user format preference. +8. CSV export file opens correctly in spreadsheet tools. + +Upgrade checks: + +1. Upload same slug with higher version. +2. Confirm new behavior appears. +3. Confirm no stale files remain. + +## 17. Troubleshooting + +### Plugin does not appear in Awards + +- Check plugin is enabled in Plugin Manager. +- Check `award_menu` exists in manifest. +- Check `award_menu.method` exists in your class. +- Check slug/route consistency. + +### "Unable to load plugin class" + +- Verify `entry` filename and `class` name in manifest. +- Verify class is defined exactly as declared. +- Verify file path is inside plugin root. + +### Empty award page + +- Ensure render method returns non-empty `content`. +- Check active logbook has related station IDs. +- Check SQL filters are not too strict. + +### CSV export button does nothing + +- Confirm table ID matches JS selector. +- Confirm button calls existing function name. +- Confirm browser blocks are not preventing download. + +## 18. Reference Files in Cloudlog + +- Plugin runtime and install logic: + - [application/libraries/Plugin_manager.php](application/libraries/Plugin_manager.php) + - [application/controllers/Plugins.php](application/controllers/Plugins.php) +- Award page routing: + - [application/controllers/Plugin_awards.php](application/controllers/Plugin_awards.php) + - [application/views/plugins/award_page.php](application/views/plugins/award_page.php) +- Hook runtime: + - [application/libraries/Cloudlog_hooks.php](application/libraries/Cloudlog_hooks.php) +- Example plugins: + - [docs/examples/plugins/award-73-on-73/](docs/examples/plugins/award-73-on-73) + - [docs/examples/plugins/club-awards-plus/](docs/examples/plugins/club-awards-plus) + +## 19. Quick Start Template + +Copy this minimal starter and adjust names: + +1. Create folder `my-award-plugin`. +2. Add manifest with `slug`, `name`, `version`, `entry`, `class`, `award_menu`. +3. Add class with `renderAwardPage` method. +4. Zip folder contents. +5. Upload, install, enable. + +If you want a production-ready baseline, start from: + +- [docs/examples/plugins/award-73-on-73/Plugin.php](docs/examples/plugins/award-73-on-73/Plugin.php) diff --git a/docs/examples/plugins/award-73-on-73.zip b/docs/examples/plugins/award-73-on-73.zip new file mode 100644 index 0000000000000000000000000000000000000000..cc53e1e7103cd32c9109e7c1a7009ff2007c5aac GIT binary patch literal 4493 zcmai&cQjmE|HelN6FqthM)XlePZ&XTqK)37_ufSbqQ>YoxLpp;=cE;d+(cj-`_cFea}AYto7M@KWBgccpfb^99&Ak)us6=-}JY^?}Ze=0o*t>0Q?2U_$$oS(#_G% z*4u~Q$=luS-^lI1lUmu^z1Nt7qS$ zv@tybGU-!}>=v#r2<1&62#Z2(KW6Ffc`9H1G;Cxh%mcddoo6B$`%+=Vh{3pWZ8I-_ zgf7KZZZ5Cf^}#bnW%ri*%J8xu+AzWCFN;vcn{yomq>2`hRfIiZo%ucb{E198OCh$ezBN+fghO#uBhT>_tf!sQKK`^ z))}4lwCdlQXQLxgxX0=gXCXUQUyBLtG7Bp?Dx;A++z@%9Kn`E%?S!_m_?&Q%Alf%B=X=}PjYEfdNB6ZfQ+p_QGkY-59JU@}xz3W#nLD!7 z57yr`G?aqRir-hQukXk`9Wj!>cqfZpXjms{07C}{Jc5NFcezq*y!_7HL_i^4KGPC+ z@8-ty^N(=eVi6pzMHS2Km3+z9kXuVJqJNmW8+$u3=N3%UcvK28t{b``a0bo7QbTp` zFh0eS<=C;Lke0nwNbvd%>5n{YO(vB<0m~+EWLv$2iTrd#a$BdAp+{kKCLQ`XeQ&Nu z`!E|5r@{|xFV;|uoUNH*v+y1Jz*KUbsuOHBIP{TX<9WfcNN=M>HmQ(w1-i-!`;a%~ z4x!SRmbw}?HK)G%%gRqKioC6{s{=fP-;=v8IYteU4upEq61H;7N?O@*T*7v~KxsQ7 zeSfwzkf=&1;6llOttZ+7^o2P#Dk9TpKrLlbMnH$ zULrL)C~&vv20J7wh=_HZQ;h?s9$CRM%fcqCeAtMO!uRDHcoa~6bSGiDklPok%&N3w z+b=B4)A6<<$pGaqb6?z8uY=L6#bqdv*T4p5%g`oBWj<`+SrOCPHvtq@4lyBy>rRsS zEDQNij0wyKZT4cRINX-JJEHY|WLnRcCYYbB!h!@|oh4wA*&F6S?ZwXvo+vV~oC004 z%FH;@Ht0()DNSjLw=p=i~iN9OtKsuHEV^0~&g`IS%4 zzFaGs=$MtHqC~S%FMmUT*Gq0p+hPqm{=m1u;6^s^bK8PT)ipv#)`#+G&+R$_Lu4Mv zsWRRaBiHHX5aJi+E$~0h9T&0LlS$>K(Guvla$=^B7={{-Sgvu{tj%7xaG@3AIwo}L z62W^R)%5UyY>yixkp{Gby;}>LmJznL!m=Qic|@QNNLs^5^HE`;u_V`#L5~rdrWi_W z!8?&*@r#;yN#X`+9Vqexwt1;^p$bX10;K5G+_T~-#IIIlh%Gaakv|DaX z;k67~B;^eB$&ZJca~tKicE=tZ9gv=;T36$XvEk8n9?Tbbg}&xwUMh&%FE~r#NFCPq zQ?%2pFohAYGqJMOclW`24lHD1`m0=rB0f`@=`w_+$&9z36&^hPY;v3J6~ijDtXBF3 zE+`p0ffQ)n7^B2K*o24gvBcWG<8kVd2aYB#?NEL-JVt$-4>xh~s3#j$b$SfGXbnKP z5`7Set|9r%>zWQ+w?n#K1Y}eZ1$Is%bbLj@V5zu@!)f@sxzzDvFiuTVWR=<_yAf9qBJq{T3{0jL${Nb*-kl|j zvV&|Fa^kV@dv8gK-*@cE3MtO7yN^e#wiKZK5V?3roRQDagCc08F469_TQDJ3R;zI& z)z5!q8!$y*ldb3B-Tf@7w$D?(Li1d)ZbRY-C>0y`vbxv^Tw2wfrMLaVI6E_)d=m3m z%uMX77Yo5n{W-xqN3TlwRxq~OaL{CEFl8l@If#4y>CnQP#2n$;Oe}sry`b{y&ABrF zkbugAw>;j@77Qs0CzVA#4jS&b^SH9z(Qj@&0s8~$7VSd9jK1|)WY{VuC<20)7iO6# z9vE(1)4HE+$c4l+GFwbEE<&4`TTxd!ASC?M)~3TSq?-JwxG&lm^NjVV9)}>Gs9IbQ zgf?@hz_k8UDFzvhopc-{2Ae8f@AYzU|Dxb%uZI_JW_aM>dp8|EPaQH4)YQk-_(GU@ z)peokeE)L3Yr%n$iCXIPC={`Ra=4xgb~7>}{8*Wq{cLr_>yA3R41P)#Z6I!l_1l5= z7PZ$y&zbr}_^(>P~(`>gK(FI5>g1N#^38>}gd*l%H9dZVU36M6*R zR0!#e-* zXxSIk48dG_(pNBqx(?GHH^3=+t5gd{((sHO4vL<+$wx20zKCiUlsel`2oAk>bd#zf zSzv2Q&{L=1xx+~((MsbfsiYeb#p(Lk+Kmf697P5E=b|dq$5E8Lcogex09*UDX^?PH zt+`n~54!iARRLsZ+ByKB-60VUh)wE;Q=pl174CM#C^G8%@mxD2tvs)xx-jNQpoMoXbqaEfQ$TrlY$RZaJ9nCPt$hIB}R+CiLsn!(F5vE@>H!?-t?_E2|!--tZs$AETFZoG7XTyR3F0vL@M{6jCS~7owa)ND1mwh3k|+?P9>@wpL*bK+ke+)$Ju|SdA?8FsG;HL};n&t%i{3SqC$j;i#z%0)l5N+Es@$>%*kUl(CXB2}>;}$HuZ4w>*yU4DPw} zh=z|sB=H(AnsQKFw#65;!t!zN;*^)7c9^g}RvYNVPz}!&hb8GrVp--=c3Cp#wQa=m z3sa;*r(jghdc0-nwX;<${0wgNXzpsh=W1wSQ{%$qh=PM-ZyO&#@deE6v!FJn3;!!8 z0b4ohg%_T>Z@+n*Ezgen3Ark@;l|p@^G&QwwLsBxocq@fsRybxJO?+5`WxcIT)6Vq z{BUILWeCXQlpZ?cCG7=+Kj`{9tWK!WUk~haSEI+0D|y@=?x)7-CwkbNS9$kB{lt_7l)lV=YB9k=(BGm5(_33wziaZOr$I6UPzf^N0Mctc?PO-Va({p+V( z-_B=N%O?c)D5k8OF%EXw{RNotEJv}>TUy?HBD*u;-o+hm8PTl#wH#fN%zZQ?n4RWk zuC=9%uiro2FxJuc19o)PnR)qn(a^}EjU^kJ1AyNHM_}X1?Mq7y zQ4HqIyPIQ5;bSM_(3+R9X20!GVZ6GwR11|@0ktVv!e*24_TsYlLP9zz;_eVZ3E!9N zVG8=A5G{4|g8xc3Y@nqS9JAOU&yj;H@+BT-p5)s40UPz!9c?R2bRL^6sjzDM@%+%b z?Zbx}7ZU_VrRG>|`S}{}*?Pzmel>^Z#Jas=KyH)CA*9fRCk4%GC0UYOeYhyd{2K>H zX-F)rZKa$Sdr_B(DJx;|U8CD*3~|4y8*u*vu-T7qx3Mj=c}vWjusMA*7&y03zl`wy zzCDc)PFE1a6qj{8WQdx;3Z?O6dLb&h$*Q)`qGPbd8H@QOkB+K`7jHH0`3DE+6<8pA zgAngtUrY2;uJu!H*_*X#iX#4G%qK*mnu+)}_(sZLa_wc`P<8w^gVF1)wiBl(U`+cB z-JFw>SC8|cqk=oEYng$q`a~D!G*>oZ{#`QUEg=9v5B{r7@c%CZNBgTyfGNnzt1Ixk z+WeDCAouyxC78j+o#tf7f=O4H@y@K|_#7r+KoORCC~jWs>xGXFaJu9 zuDd~;GoB}`V~anAMo{rP$9RaI?c3XtX-Bnls@eURDa@4VIeV z5{2qUXz5JSJ)Kc1(gKfCJF6tJhkguLK^;iyQg_!M;4Ce>-KJoQvgCes&hdU!(F6pF zkNnS7*xz_!HU`uKp|Ze@6rVFvFEY{%cdv{cVPvpBw$JW&aPq{1boW wm;X@ZY6DlD^;gAc|Ay}-{ssTCI = $ci; + } + + public function renderAwardPage($context = array()) + { + $this->CI->load->model('logbooks_model'); + + $active_logbook = $this->CI->session->userdata('active_station_logbook'); + $station_ids = $this->CI->logbooks_model->list_logbook_relationships($active_logbook); + + if (empty($station_ids) || !is_array($station_ids)) { + return array( + 'page_title' => 'Awards - 73 on 73', + 'content' => '
    No station locations are associated with your active logbook.
    ', + ); + } + + $unique_call_rows = $this->fetch_unique_call_rows($station_ids, 'any'); + $lotw_unique_call_rows = $this->fetch_unique_call_rows($station_ids, 'lotw'); + $paper_unique_call_rows = $this->fetch_unique_call_rows($station_ids, 'paper'); + + $count = count($unique_call_rows); + $remaining = max(0, self::TARGET - $count); + $progress = min(100, (int)floor(($count / self::TARGET) * 100)); + $lotw_count = count($lotw_unique_call_rows); + $paper_count = count($paper_unique_call_rows); + + $progress_class = 'bg-danger'; + if ($progress >= 100) { + $progress_class = 'bg-success'; + } elseif ($progress >= 75) { + $progress_class = 'bg-info'; + } elseif ($progress >= 40) { + $progress_class = 'bg-primary'; + } + + $status_label = 'Getting Started'; + if ($progress >= 100) { + $status_label = 'Award Complete'; + } elseif ($progress >= 75) { + $status_label = 'Final Stretch'; + } elseif ($progress >= 40) { + $status_label = 'On Track'; + } + + $milestones = array(25, 50, 73); + + $content = ''; + $content .= '
    '; + $content .= ''; + $content .= 'Counts unique callsigns confirmed on ' . htmlspecialchars(self::SATELLITE, ENT_QUOTES, 'UTF-8') . ' via LoTW or paper QSL.'; + $content .= '
    '; + + $content .= '
    '; + $content .= '
    '; + $content .= '
    '; + $content .= '
    '; + $content .= '
    73 on 73
    '; + $content .= '' . htmlspecialchars($status_label, ENT_QUOTES, 'UTF-8') . ''; + $content .= '
    '; + $content .= '

    Work 73 unique stations on ' . htmlspecialchars(self::SATELLITE, ENT_QUOTES, 'UTF-8') . ' with LoTW or paper confirmation.

    '; + $content .= '

    ' . (int)$count . ' / ' . self::TARGET . '

    '; + $content .= '
    '; + $content .= '
    ' . (int)$progress . '%
    '; + $content .= '
    '; + + if ($remaining > 0) { + $content .= '

    ' . (int)$remaining . ' more unique stations needed.

    '; + } else { + $content .= '

    Award complete. 73 unique stations reached.

    '; + } + + $content .= '
    '; + $content .= '
    Milestones
    '; + $content .= '
    '; + foreach ($milestones as $milestone) { + $done = $count >= $milestone; + $badge = $done ? 'bg-success' : 'bg-light text-dark border'; + $icon = $done ? '' : ''; + $content .= '' . $icon . $milestone . ''; + } + $content .= '
    '; + + $content .= '
    '; + + $content .= '
    '; + $content .= '
    Confirmation Mix
    '; + $content .= '
    LoTW confirmed' . (int)$lotw_count . '
    '; + $content .= '
    Paper confirmed' . (int)$paper_count . '
    '; + $content .= '
    '; + + $content .= '
    '; + + $content .= '
    '; + $content .= '
    '; + $content .= '
    '; + $content .= '
    Unique Confirmed Stations on ' . htmlspecialchars(self::SATELLITE, ENT_QUOTES, 'UTF-8') . '
    '; + $content .= '
    '; + if ($count > 0) { + $content .= ''; + } + $content .= '' . (int)$count . ' total'; + $content .= '
    '; + $content .= '
    '; + + if ($count === 0) { + $content .= '

    No qualifying QSOs found yet.

    '; + } else { + $content .= '
    '; + $content .= ''; + $content .= ''; + + $idx = 1; + foreach ($unique_call_rows as $row) { + $content .= ''; + $idx++; + } + + $content .= '
    #QSO Date/TimeCallsignModeGridSquare
    ' . $idx . '' . htmlspecialchars($this->format_qso_datetime($row['qso_time']), ENT_QUOTES, 'UTF-8') . '' . htmlspecialchars($row['call'], ENT_QUOTES, 'UTF-8') . '' . htmlspecialchars($this->format_display_value($row['mode']), ENT_QUOTES, 'UTF-8') . '' . htmlspecialchars($this->format_display_value($row['gridsquare']), ENT_QUOTES, 'UTF-8') . '
    '; + } + + $content .= '
    '; + $content .= '
    '; + + $content .= ''; + + return array( + 'page_title' => 'Awards - 73 on 73', + 'content' => $content, + ); + } + + private function fetch_unique_call_rows($station_ids, $confirmation = 'any') + { + $table = $this->CI->config->item('table_name'); + + $this->CI->db->select('UPPER(TRIM(COL_CALL)) as COL_CALL, COL_TIME_ON, COL_MODE, COL_GRIDSQUARE, COL_VUCC_GRIDS', false); + $this->CI->db->from($table); + $this->CI->db->where_in('station_id', $station_ids); + $this->CI->db->where('UPPER(TRIM(COL_SAT_NAME))', self::SATELLITE); + $this->CI->db->where('UPPER(TRIM(COL_CALL)) !=', ''); + + if ($confirmation === 'lotw') { + $this->CI->db->where('COL_LOTW_QSL_RCVD', 'Y'); + } elseif ($confirmation === 'paper') { + $this->CI->db->where('COL_QSL_RCVD', 'Y'); + } else { + $this->CI->db->group_start(); + $this->CI->db->where('COL_LOTW_QSL_RCVD', 'Y'); + $this->CI->db->or_where('COL_QSL_RCVD', 'Y'); + $this->CI->db->group_end(); + } + + $this->CI->db->order_by('COL_CALL', 'ASC'); + $this->CI->db->order_by('COL_TIME_ON', 'ASC'); + $query = $this->CI->db->get(); + $rows = $query ? $query->result() : array(); + + $result_rows_by_call = array(); + foreach ($rows as $row) { + $call = strtoupper(trim((string)($row->COL_CALL ?? ''))); + if ($call !== '' && !array_key_exists($call, $result_rows_by_call)) { + $vucc_grids = strtoupper(trim((string)($row->COL_VUCC_GRIDS ?? ''))); + $gridsquare = strtoupper(trim((string)($row->COL_GRIDSQUARE ?? ''))); + $result_rows_by_call[$call] = array( + 'call' => $call, + 'qso_time' => (string)($row->COL_TIME_ON ?? ''), + 'mode' => trim((string)($row->COL_MODE ?? '')), + 'gridsquare' => $vucc_grids !== '' ? $vucc_grids : $gridsquare, + ); + } + } + + return array_values($result_rows_by_call); + } + + private function format_qso_datetime($qso_time) + { + $qso_time = trim((string)$qso_time); + if ($qso_time === '') { + return '-'; + } + + $timestamp = strtotime($qso_time); + if ($timestamp === false) { + return '-'; + } + + $custom_date_format = $this->CI->session->userdata('user_date_format'); + if (!$custom_date_format) { + $custom_date_format = $this->CI->config->item('qso_date_format'); + } + + return date($custom_date_format, $timestamp) . ' ' . date('H:i', $timestamp); + } + + private function format_display_value($value) + { + $value = trim((string)$value); + return $value === '' ? '-' : $value; + } +} diff --git a/docs/examples/plugins/award-73-on-73/README.md b/docs/examples/plugins/award-73-on-73/README.md new file mode 100644 index 000000000..f40febad5 --- /dev/null +++ b/docs/examples/plugins/award-73-on-73/README.md @@ -0,0 +1,31 @@ +# 73 on 73 (Award Plugin) + +Live award plugin for Cloudlog. + +Award definition: + +- Work 73 unique stations on satellite AO-73 with LoTW or paper QSL confirmation. + +## What It Adds + +- A new Awards dropdown entry: `73 on 73` +- A live award page with: + - current progress + - remaining stations needed + - list of unique worked callsigns on AO-73 + +## Install + +1. Zip the contents of this folder. +2. In Cloudlog, go to Admin > Plugin Manager. +3. Upload and install the zip. +4. Enable the plugin. +5. Open Awards > 73 on 73. + +## Scope Rules + +- Counts only QSOs in the current active logbook scope (station locations linked to active logbook). +- Counts unique callsigns where `COL_SAT_NAME` matches `AO-73` (case-insensitive). +- Requires confirmation by either: + - `COL_LOTW_QSL_RCVD = Y` (LoTW) + - `COL_QSL_RCVD = Y` (paper QSL) diff --git a/docs/examples/plugins/award-73-on-73/manifest.json b/docs/examples/plugins/award-73-on-73/manifest.json new file mode 100644 index 000000000..5c9c1b94b --- /dev/null +++ b/docs/examples/plugins/award-73-on-73/manifest.json @@ -0,0 +1,15 @@ +{ + "slug": "award-73-on-73", + "name": "73 on 73", + "version": "1.0.0", + "description": "Award for working 73 unique stations on satellite AO-73.", + "entry": "Plugin.php", + "class": "Award73On73Plugin", + "award_menu": { + "title": "73 on 73", + "icon": "fas fa-satellite", + "route": "plugin_awards/view/award-73-on-73", + "method": "renderAwardPage", + "order": 90 + } +} diff --git a/docs/examples/plugins/club-awards-plus/Plugin.php b/docs/examples/plugins/club-awards-plus/Plugin.php new file mode 100644 index 000000000..54cfac73c --- /dev/null +++ b/docs/examples/plugins/club-awards-plus/Plugin.php @@ -0,0 +1,80 @@ +CI = $ci; + } + + /** + * Filter hook: can change QSO data before it is saved. + */ + public function beforeSave($payload, $context = array()) + { + if (!is_array($payload)) { + return $payload; + } + + // Example: normalize SIG and SIG_INFO for club award tracking. + if (!empty($payload['COL_SIG'])) { + $payload['COL_SIG'] = strtoupper(trim((string)$payload['COL_SIG'])); + } + + if (!empty($payload['COL_SIG_INFO'])) { + $payload['COL_SIG_INFO'] = strtoupper(trim((string)$payload['COL_SIG_INFO'])); + } + + // Example: add note marker for this plugin on new QSOs. + $source = isset($context['source']) ? (string)$context['source'] : ''; + if ($source === 'manual') { + $existing_notes = isset($payload['COL_NOTES']) ? trim((string)$payload['COL_NOTES']) : ''; + if (strpos($existing_notes, '[ClubAwardsPlus]') === false) { + $payload['COL_NOTES'] = trim($existing_notes . ' [ClubAwardsPlus]'); + } + } + + return $payload; + } + + /** + * Action hook: runs after a QSO is inserted. + */ + public function afterSave($payload, $context = array()) + { + $qso_id = isset($payload['qso_id']) ? (int)$payload['qso_id'] : 0; + log_message('info', 'ClubAwardsPlus afterSave qso_id=' . $qso_id); + } + + /** + * Action hook: runs after a QSO is edited. + */ + public function afterEdit($payload, $context = array()) + { + $qso_id = isset($payload['qso_id']) ? (int)$payload['qso_id'] : 0; + log_message('info', 'ClubAwardsPlus afterEdit qso_id=' . $qso_id); + } + + /** + * Award page renderer used by plugin_awards/view/. + */ + public function renderAwardPage($context = array()) + { + $user_id = isset($context['user_id']) ? (int)$context['user_id'] : 0; + + $content = ''; + $content .= '
    '; + $content .= 'Club Awards Plus is active for user #' . $user_id . '.'; + $content .= '
    '; + $content .= '

    This is an example plugin award page. Replace this output with your own award statistics and tables.

    '; + + return array( + 'page_title' => 'Club Awards Plus', + 'content' => $content, + ); + } +} diff --git a/docs/examples/plugins/club-awards-plus/README.md b/docs/examples/plugins/club-awards-plus/README.md new file mode 100644 index 000000000..c94f1c4ee --- /dev/null +++ b/docs/examples/plugins/club-awards-plus/README.md @@ -0,0 +1,30 @@ +# Club Awards Plus (Example Plugin) + +This is a minimal example plugin for Cloudlog Phase 1. + +## What It Demonstrates + +- Hook registration in `manifest.json` +- A filter hook (`qso.filter.before_save`) that can modify payload data +- Action hooks (`qso.action.after_save`, `qso.action.after_edit`) for side effects +- Awards dropdown integration via `award_menu` +- Plugin award page rendering via `renderAwardPage` + +## Files + +- `manifest.json` +- `Plugin.php` + +## Quick Test + +1. Zip the contents of this folder. +2. Open Cloudlog Admin > Plugin Manager. +3. Upload the zip. +4. Enable `club-awards-plus`. +5. Add or edit a QSO and check application logs for plugin messages. +6. Open the Awards menu and click `Club Awards Plus` to view the plugin award page. + +## Notes + +- This sample is intentionally simple and uses only safe, synchronous behavior. +- For heavy processing, use queue-based logic in a later phase. diff --git a/docs/examples/plugins/club-awards-plus/manifest.json b/docs/examples/plugins/club-awards-plus/manifest.json new file mode 100644 index 000000000..3edb7e551 --- /dev/null +++ b/docs/examples/plugins/club-awards-plus/manifest.json @@ -0,0 +1,20 @@ +{ + "slug": "club-awards-plus", + "name": "Club Awards Plus", + "version": "1.0.0", + "description": "Example plugin showing Phase 1 hook usage for custom club workflows.", + "entry": "Plugin.php", + "class": "ClubAwardsPlusPlugin", + "award_menu": { + "title": "Club Awards Plus", + "icon": "fas fa-trophy", + "route": "plugin_awards/view/club-awards-plus", + "method": "renderAwardPage", + "order": 120 + }, + "hooks": { + "qso.filter.before_save": "beforeSave", + "qso.action.after_save": "afterSave", + "qso.action.after_edit": "afterEdit" + } +} diff --git a/docs/plugin-manager-guide.md b/docs/plugin-manager-guide.md new file mode 100644 index 000000000..3fb4850fc --- /dev/null +++ b/docs/plugin-manager-guide.md @@ -0,0 +1,341 @@ +# Cloudlog Plugin Manager Guide (Developer Reference) + +This guide is a detailed technical reference for Cloudlog's Plugin Manager. + +It focuses on what developers can do, how the manager works internally, and how to build plugin packages that install and upgrade cleanly. + +## 1. Scope and Audience + +This document is for developers who: + +- Build Cloudlog plugins. +- Maintain plugin zip releases. +- Need predictable install/upgrade behavior. +- Need to troubleshoot plugin install or runtime issues. + +For writing award-specific plugin logic, also see: + +- [docs/awards-plugin-guide.md](docs/awards-plugin-guide.md) + +For system-level architecture overview, see: + +- [docs/plugin-system-phase1.md](docs/plugin-system-phase1.md) + +## 2. Plugin Manager Capabilities + +The Plugin Manager currently supports: + +- Uploading and installing plugin zip packages. +- Metadata registration in the `plugins` database table. +- Enabling/disabling plugins. +- Deleting plugins (files on disk + registry record). +- In-place upgrade when a zip is uploaded with an existing plugin slug. +- Upgrade backup and rollback on failure. +- Validation checks for archive safety and manifest structure. + +Current implementation entry points: + +- Controller: [application/controllers/Plugins.php](application/controllers/Plugins.php) +- Runtime library: [application/libraries/Plugin_manager.php](application/libraries/Plugin_manager.php) +- Data model: [application/models/Plugins_model.php](application/models/Plugins_model.php) +- Admin UI view: [application/views/plugins/index.php](application/views/plugins/index.php) + +## 3. Data Model and Persistence + +Migration: + +- [application/migrations/268_create_plugins_table.php](application/migrations/268_create_plugins_table.php) + +Table: `plugins` + +Key fields: + +- `plugin_slug`: unique plugin identity. +- `plugin_name`, `plugin_version`, `plugin_description`. +- `plugin_status`: `enabled` or `disabled`. +- `plugin_manifest`: stored JSON manifest snapshot. +- `installed_at`, `updated_at`. + +Important behavior: + +- The DB record is the plugin registry. +- On listing, manager attempts to read manifest from disk first, then falls back to DB snapshot. +- `upsert_plugin` preserves enabled status during upgrades. + +## 4. Plugin Package Requirements + +A valid plugin zip must: + +1. Contain `manifest.json` either at zip root or inside a single top-level folder. +2. Include a valid `slug` in manifest matching pattern `^[a-z0-9_-]+$`. +3. Include code files referenced by `entry` and `class` manifest fields (or defaults). + +Minimum recommended package: + +```text +my-plugin/ + manifest.json + Plugin.php + README.md +``` + +Reference examples: + +- [docs/examples/plugins/club-awards-plus/](docs/examples/plugins/club-awards-plus) +- [docs/examples/plugins/award-73-on-73/](docs/examples/plugins/award-73-on-73) + +## 5. Upload and Install Workflow (What Happens) + +When an admin uploads a plugin zip in Plugin Manager: + +1. CSRF token is validated. +2. Zip upload is accepted only for `.zip` extension and configured limits. +3. Archive is inspected for unsafe paths. +4. Archive is extracted to a temp directory. +5. `manifest.json` is located and parsed. +6. Manifest and slug are validated. +7. Plugin files are copied to `application/plugins//`. +8. Plugin metadata is upserted into DB. +9. Plugin remains disabled by default (unless existing plugin was already enabled and upgraded). + +Key code paths: + +- `Plugins::upload()` in [application/controllers/Plugins.php](application/controllers/Plugins.php) +- `Plugin_manager::install_from_zip()` in [application/libraries/Plugin_manager.php](application/libraries/Plugin_manager.php) + +## 6. Upgrade-in-Place Behavior + +If uploaded plugin slug already exists on disk: + +1. Existing plugin directory is moved to backup. +2. New files are copied in. +3. DB metadata is updated. +4. Backup is deleted on success. + +If file copy or DB update fails: + +1. New files are removed. +2. Backup is restored. + +Result: + +- Reduced risk of partial updates. +- Safer iterative plugin release workflow. + +## 7. Security and Safety Checks + +The manager applies multiple protection layers. + +### 7.1 Authorization + +- Plugin Manager UI/actions require admin authorization (`authorize(99)`). + +### 7.2 CSRF on Admin Actions + +Custom session token is required for: + +- Upload +- Enable +- Disable +- Delete + +### 7.3 Archive Path Validation + +Installer rejects zip entries containing: + +- Path traversal (`../`) +- Absolute paths +- Drive-root style paths + +This protects against writing outside plugin directory. + +### 7.4 Manifest Validation + +Installer validates: + +- JSON parseability +- Valid slug pattern +- Award menu method shape (warning if declaration looks invalid/missing) + +### 7.5 Runtime Resilience + +- Hook and award-render exceptions are caught/logged. +- Core QSO workflows continue if plugin execution fails. + +## 8. Enable/Disable Semantics + +Enable/disable toggles update `plugin_status` in DB. + +Effects: + +- Disabled plugins do not run hooks. +- Disabled plugins do not appear in dynamic Awards plugin entries. +- Files remain on disk; only runtime activation changes. + +Methods: + +- `Plugin_manager::set_enabled()` +- `Plugins::enable()` and `Plugins::disable()` + +## 9. Award Menu Integration via Plugin Manager + +Plugin Manager provides menu entry discovery for enabled plugins through: + +- `Plugin_manager::get_award_menu_entries()` + +Manifest `award_menu` fields interpreted: + +- `title`: required for menu inclusion. +- `route`: defaults to `plugin_awards/view/`. +- `icon`: defaults to `fas fa-award`. +- `order`: sort key (then title). + +Rendered from header template: + +- [application/views/interface_assets/header.php](application/views/interface_assets/header.php) + +Award route controller: + +- [application/controllers/Plugin_awards.php](application/controllers/Plugin_awards.php) + +## 10. Delete/Uninstall Behavior + +Delete in Plugin Manager performs two actions: + +1. Removes the plugin directory from `application/plugins//`. +2. Removes the plugin record from the `plugins` table. + +Important notes: + +- Delete is an admin-only action and CSRF protected. +- If file removal fails, metadata is not removed. +- If metadata removal fails, an error is returned and action is reported as failed. + +## 11. Disk Layout and Git Workflow + +Installed plugins live under: + +- `application/plugins//` + +Repository ignore strategy should keep folder scaffold while ignoring installed plugin contents. + +Current `.gitignore` behavior: + +- Ignores all under `application/plugins/*` +- Re-includes `application/plugins/index.html` + +This allows: + +- Folder existence after clone. +- Local plugin installations without git noise during pull/rebase. + +## 12. Developer Packaging Checklist + +Before shipping a plugin zip: + +1. Validate `manifest.json` syntax. +2. Confirm `slug` is stable and lowercase. +3. Confirm `entry` file exists in package. +4. Confirm class name matches manifest `class`. +5. Confirm `award_menu.method` exists if used. +6. Increment version for each release. +7. Test upgrade path by installing old version then uploading new version. + +## 13. Common Errors and Fixes + +### Error: "manifest.json was not found" + +Cause: + +- Incorrect zip structure. + +Fix: + +- Place `manifest.json` at root or within one top-level folder. + +### Error: "manifest.json is invalid JSON" + +Cause: + +- Trailing comma or malformed JSON. + +Fix: + +- Validate with a JSON linter before zipping. + +### Error: "Invalid plugin slug" + +Cause: + +- Slug has spaces/uppercase/special characters. + +Fix: + +- Use lowercase letters, numbers, `_`, `-`. + +### Warning about `award_menu.method` + +Cause: + +- Method declared but missing in entry file. + +Fix: + +- Implement method or correct spelling in manifest. + +### Plugin installs but does not appear in Awards + +Cause: + +- Plugin disabled or missing valid `award_menu` block. + +Fix: + +- Enable plugin and verify `award_menu.title` + method declaration. + +### Upgrade appears not applied + +Cause: + +- Same version uploaded or old package re-zipped accidentally. + +Fix: + +- Bump version, verify zip contents, reinstall. + +## 14. Operational Best Practices + +- Keep plugin slugs permanent. +- Treat manifest as contract/API for manager. +- Keep plugin code self-contained inside plugin folder. +- Avoid side effects in constructors. +- Log meaningful errors with plugin slug context. +- Keep upgrade releases atomic and small. + +## 15. What Plugin Manager Does Not Do (Yet) + +Current known limitations: + +- No plugin signature verification. +- No marketplace/remote catalog. +- No capability/permission prompt model. +- No staged/canary rollout. + +These are potential future-phase enhancements. + +## 16. Useful Source References + +- Plugin Manager controller: + - [application/controllers/Plugins.php](application/controllers/Plugins.php) +- Plugin manager runtime logic: + - [application/libraries/Plugin_manager.php](application/libraries/Plugin_manager.php) +- Plugin data access model: + - [application/models/Plugins_model.php](application/models/Plugins_model.php) +- Plugin awards route: + - [application/controllers/Plugin_awards.php](application/controllers/Plugin_awards.php) +- Hook runtime: + - [application/libraries/Cloudlog_hooks.php](application/libraries/Cloudlog_hooks.php) +- Plugin Manager UI: + - [application/views/plugins/index.php](application/views/plugins/index.php) +- Phase 1 architecture document: + - [docs/plugin-system-phase1.md](docs/plugin-system-phase1.md) diff --git a/docs/plugin-system-phase1.md b/docs/plugin-system-phase1.md new file mode 100644 index 000000000..79dd800ed --- /dev/null +++ b/docs/plugin-system-phase1.md @@ -0,0 +1,192 @@ +# Cloudlog Plugin System Phase 1 + +This document describes the Phase 1 plugin system implemented for Cloudlog. + +Related guides: + +- [docs/plugin-manager-guide.md](docs/plugin-manager-guide.md) +- [docs/awards-plugin-guide.md](docs/awards-plugin-guide.md) + +## Goals + +- Allow admin users to upload plugin zip files in the UI. +- Install plugins without patching core files. +- Enable and disable plugins from an admin page. +- Provide a first set of hook points for QSO workflow integration. + +## What Is Included + +- Admin UI page: Plugin Manager. +- Plugin upload and install flow. +- Plugin metadata persistence in the database. +- Plugin enable or disable controls. +- Hook runtime for filter and action events. +- Initial QSO hooks in add and edit flows. +- Dynamic Award dropdown entries from enabled plugins. + +## Database + +Migration: application/migrations/268_create_plugins_table.php + +Table: plugins + +Columns: + +- id +- plugin_slug (unique) +- plugin_name +- plugin_version +- plugin_description +- plugin_status (enabled or disabled) +- plugin_manifest (json) +- installed_at +- updated_at + +## Admin UI + +Controller: application/controllers/Plugins.php +View: application/views/plugins/index.php + +Menu entry: Admin dropdown in interface header. + +Functions: + +- Upload and install a plugin zip. +- Uploading a zip with an existing plugin slug upgrades that plugin in place. +- See installed plugins and status. +- Enable or disable plugin execution. + +## Plugin Package Format + +A plugin zip must contain a manifest.json in the plugin root (or one level down in a single top folder). + +Reference example plugin: + +- docs/examples/plugins/club-awards-plus/ +- docs/examples/plugins/award-73-on-73/ + +Required manifest fields: + +- slug: lowercase letters, numbers, underscore, dash +- name +- version + +Optional manifest fields: + +- description +- entry (default: Plugin.php) +- class (default: Plugin) +- hooks (map of hook name to method name) +- award_menu (optional object for Awards dropdown integration) + +Award menu object fields: + +- title (required if award_menu is present) +- icon (optional, default: fas fa-award) +- route (optional, default: `plugin_awards/view/{plugin-slug}`) +- method (optional, default: renderAwardPage) +- order (optional integer, default: 100) + +Example manifest: + +```json +{ + "slug": "club-awards-plus", + "name": "Club Awards Plus", + "version": "1.0.0", + "description": "Custom award logic for local club workflows", + "entry": "Plugin.php", + "class": "ClubAwardsPlusPlugin", + "award_menu": { + "title": "Club Awards Plus", + "icon": "fas fa-trophy", + "route": "plugin_awards/view/club-awards-plus", + "method": "renderAwardPage", + "order": 120 + }, + "hooks": { + "qso.filter.before_save": "beforeSave", + "qso.action.after_save": "afterSave", + "qso.action.after_edit": "afterEdit" + } +} +``` + +## Hook Runtime + +Library: application/libraries/Cloudlog_hooks.php + +### Filter Hook + +- qso.filter.before_save +- Called before QSO data is persisted. +- Plugin method receives payload and context and may return modified payload. + +### Action Hooks + +- qso.action.after_save +- qso.action.after_edit +- Called after persistence. +- Plugin method receives payload and context. + +## Award Dropdown Integration + +Controller: application/controllers/Plugin_awards.php +View: application/views/plugins/award_page.php + +Controller route: + +- `plugin_awards/view/{plugin-slug}` + +Behavior: + +- Enabled plugins with an `award_menu` manifest section are shown in the Awards dropdown. +- Clicking the menu entry renders the plugin award page through the plugin method defined by `award_menu.method`. +- If `award_menu.method` is omitted, `renderAwardPage` is used. + +## QSO Integration Points + +File: application/models/Logbook_model.php + +Current Phase 1 dispatch points: + +- create_qso: applies qso.filter.before_save before add_qso. +- add_qso: dispatches qso.action.after_save after insert and cache clear. +- edit: dispatches qso.action.after_edit after update and cache clear. + +## Safety Checks in Upload + +Library: application/libraries/Plugin_manager.php + +Implemented checks: + +- Admin-only access via controller authorization. +- Session-bound CSRF token validation on plugin upload, enable, and disable admin actions. +- ZipArchive availability check. +- Reject path traversal and absolute paths in zip entries. +- Require manifest.json. +- Validate slug format. +- Prevent overwrite when slug already exists. +- Install disabled by default. +- Validate award_menu method declaration and show install warning if missing. +- Backup existing plugin files before upgrade and auto-rollback if upgrade fails. + +## Operational Notes + +- Run migrations before using Plugin Manager. +- Plugins are stored under `application/plugins/`. +- Plugin code runs in-process, so only install trusted plugins. +- Plugin exceptions are caught and logged to avoid breaking QSO saves. + +## Sample Template Packaging Tip + +When creating a zip from the sample template, ensure `manifest.json` is present at the zip root +or in a single top-level folder. The installer supports both patterns. + +## Next Steps (Phase 2 Suggestions) + +- Signed plugin packages and publisher trust list. +- UI uninstall and upgrade flow with rollback. +- Hook instrumentation in ADIF import and award computations. +- Capability declarations and permission prompts. +- Async queue for heavy plugin actions. From 264d6f0b0b6202ad2267cc7698ff606eef98b360 Mon Sep 17 00:00:00 2001 From: Peter Goodhall Date: Wed, 29 Apr 2026 22:40:24 +0100 Subject: [PATCH 06/48] Add plugin award menu and settings Support plugin-provided awards and user-configurable visibility. Controller now loads plugin entries and user options, exposes plugin_award_entries and plugin_award_visibility to views, and adds savePluginAward() to validate input and persist visibility via user_options_model. Views: settings page renders plugin award rows with checkboxes; header only shows plugin awards that are enabled. JS: award_settings.js and awards.js handle plugin award checkbox events, call the new savePluginAward endpoint, and provide saving/feedback UI. Includes input sanitization, slug validation, and preserves existing core award flows. --- application/controllers/Award.php | 45 ++++++++++++++++ application/views/awards/settings.php | 24 +++++++++ application/views/interface_assets/header.php | 18 ++++++- assets/js/sections/award_settings.js | 51 +++++++++++++++++-- assets/js/sections/awards.js | 43 ++++++++++++++++ 5 files changed, 177 insertions(+), 4 deletions(-) diff --git a/application/controllers/Award.php b/application/controllers/Award.php index a10c4aec0..0dcd89af0 100644 --- a/application/controllers/Award.php +++ b/application/controllers/Award.php @@ -18,8 +18,20 @@ function __construct() public function index() { $this->load->model('awards_model'); + $this->load->model('user_options_model'); + $this->load->library('plugin_manager'); $data['user_awards'] = $this->awards_model->get_user_awards(); + $data['plugin_award_entries'] = $this->plugin_manager->get_award_menu_entries(); + + $plugin_award_visibility = array(); + $visibility_query = $this->user_options_model->get_options('plugin_awards_menu'); + foreach ($visibility_query->result() as $option_row) { + if ($option_row->option_key === 'show') { + $plugin_award_visibility[$option_row->option_name] = (string)$option_row->option_value === '1'; + } + } + $data['plugin_award_visibility'] = $plugin_award_visibility; // Render Page $data['page_title'] = "Award Settings"; @@ -58,4 +70,37 @@ public function deactivateall() { echo json_encode(array('message' => 'OK')); return; } + + public function savePluginAward() { + $plugin_slug = strtolower(trim((string)$this->security->xss_clean($this->input->post('plugin_slug')))); + $show_in_menu = trim((string)$this->security->xss_clean($this->input->post('show_in_menu'))); + + if (!preg_match('/^[a-z0-9_-]+$/', $plugin_slug)) { + header('Content-Type: application/json'); + echo json_encode(array('message' => 'Invalid plugin slug')); + return; + } + + $this->load->library('plugin_manager'); + $entries = $this->plugin_manager->get_award_menu_entries(); + $known_slugs = array(); + foreach ($entries as $entry) { + $known_slugs[] = $entry['slug']; + } + + if (!in_array($plugin_slug, $known_slugs, true)) { + header('Content-Type: application/json'); + echo json_encode(array('message' => 'Plugin award entry not found')); + return; + } + + $this->load->model('user_options_model'); + $this->user_options_model->set_option('plugin_awards_menu', $plugin_slug, array( + 'show' => $show_in_menu === '1' ? '1' : '0', + )); + + header('Content-Type: application/json'); + echo json_encode(array('message' => 'OK')); + return; + } } diff --git a/application/views/awards/settings.php b/application/views/awards/settings.php index 832655915..85a2067a0 100644 --- a/application/views/awards/settings.php +++ b/application/views/awards/settings.php @@ -221,6 +221,30 @@ WWFF World Wide Flora and Fauna + + + Plugin Awards + + + + + + > + + + Plugin Award () + + + diff --git a/application/views/interface_assets/header.php b/application/views/interface_assets/header.php index 652e1b49e..6afbc87f0 100644 --- a/application/views/interface_assets/header.php +++ b/application/views/interface_assets/header.php @@ -263,9 +263,25 @@ load->library('plugin_manager'); + $CI->load->model('user_options_model'); $plugin_award_entries = $CI->plugin_manager->get_award_menu_entries(); + $plugin_award_visibility = array(); + $plugin_award_visibility_query = $CI->user_options_model->get_options('plugin_awards_menu'); + foreach ($plugin_award_visibility_query->result() as $plugin_award_visibility_row) { + if ($plugin_award_visibility_row->option_key === 'show') { + $plugin_award_visibility[$plugin_award_visibility_row->option_name] = (string)$plugin_award_visibility_row->option_value === '1'; + } + } if (!empty($plugin_award_entries)) { - foreach ($plugin_award_entries as $plugin_award_entry) { ?> + foreach ($plugin_award_entries as $plugin_award_entry) { + $show_plugin_award = true; + if (isset($plugin_award_visibility[$plugin_award_entry['slug']])) { + $show_plugin_award = (bool)$plugin_award_visibility[$plugin_award_entry['slug']]; + } + if (!$show_plugin_award) { + continue; + } + ?>
    ' + From d2d812375400e79605846e482d302b0b56d25178 Mon Sep 17 00:00:00 2001 From: Peter Goodhall Date: Wed, 29 Apr 2026 22:44:10 +0100 Subject: [PATCH 07/48] Auto-disable plugins on runtime failures Automatically disable plugins when runtime errors or invalid plugin entry/metadata are detected. Adds a disable_plugin_after_failure helper to both Cloudlog_hooks and Plugin_manager that marks the plugin as 'disabled' in plugins_model and logs the reason. Cloudlog_hooks now disables plugins for missing hook methods, exceptions in filters/actions, invalid entry paths/class names, include failures, and construction failures. Plugin_manager disables plugins for invalid award method names, instantiation failures, missing award methods, award render exceptions, and include failures. Documentation updated to mention the new auto-disable behavior. --- application/libraries/Cloudlog_hooks.php | 43 +++++++++++++++++++++++- application/libraries/Plugin_manager.php | 24 ++++++++++++- docs/plugin-manager-guide.md | 1 + 3 files changed, 66 insertions(+), 2 deletions(-) diff --git a/application/libraries/Cloudlog_hooks.php b/application/libraries/Cloudlog_hooks.php index 36a65648d..e8adbafc3 100644 --- a/application/libraries/Cloudlog_hooks.php +++ b/application/libraries/Cloudlog_hooks.php @@ -29,6 +29,10 @@ public function apply_filters($hook_name, $payload, $context = array()) $method = $handler['method']; if (!method_exists($plugin_instance, $method)) { + $this->disable_plugin_after_failure( + $handler['plugin']->plugin_slug, + 'Hook method not found [' . $hook_name . '] method=' . $method + ); continue; } @@ -39,6 +43,10 @@ public function apply_filters($hook_name, $payload, $context = array()) } } catch (Throwable $e) { log_message('error', 'Plugin filter failed [' . $hook_name . '] plugin=' . $handler['plugin']->plugin_slug . ' error=' . $e->getMessage()); + $this->disable_plugin_after_failure( + $handler['plugin']->plugin_slug, + 'Hook filter exception [' . $hook_name . '] ' . $e->getMessage() + ); } } @@ -60,6 +68,10 @@ public function do_action($hook_name, $payload = array(), $context = array()) $method = $handler['method']; if (!method_exists($plugin_instance, $method)) { + $this->disable_plugin_after_failure( + $handler['plugin']->plugin_slug, + 'Hook method not found [' . $hook_name . '] method=' . $method + ); continue; } @@ -67,6 +79,10 @@ public function do_action($hook_name, $payload = array(), $context = array()) $plugin_instance->$method($payload, $context); } catch (Throwable $e) { log_message('error', 'Plugin action failed [' . $hook_name . '] plugin=' . $handler['plugin']->plugin_slug . ' error=' . $e->getMessage()); + $this->disable_plugin_after_failure( + $handler['plugin']->plugin_slug, + 'Hook action exception [' . $hook_name . '] ' . $e->getMessage() + ); } } } @@ -121,11 +137,13 @@ private function load_plugin_instance($plugin, $manifest) if (!preg_match('/^[A-Za-z0-9_\/.-]+$/', $entry_file)) { log_message('error', 'Plugin entry path invalid for ' . $slug); + $this->disable_plugin_after_failure($slug, 'Invalid plugin entry path'); return null; } if (!preg_match('/^[A-Za-z_][A-Za-z0-9_]*$/', $class_name)) { log_message('error', 'Plugin class invalid for ' . $slug); + $this->disable_plugin_after_failure($slug, 'Invalid plugin class name'); return null; } @@ -135,13 +153,21 @@ private function load_plugin_instance($plugin, $manifest) if ($plugin_root === false || $entry_path === false || strpos($entry_path, $plugin_root) !== 0) { log_message('error', 'Plugin entry file missing or outside plugin root for ' . $slug); + $this->disable_plugin_after_failure($slug, 'Plugin entry file missing or outside plugin root'); return null; } - require_once $entry_path; + try { + require_once $entry_path; + } catch (Throwable $e) { + log_message('error', 'Plugin entry include failed (' . $slug . '): ' . $e->getMessage()); + $this->disable_plugin_after_failure($slug, 'Plugin entry include failed: ' . $e->getMessage()); + return null; + } if (!class_exists($class_name)) { log_message('error', 'Plugin class not found: ' . $class_name . ' (' . $slug . ')'); + $this->disable_plugin_after_failure($slug, 'Plugin class not found: ' . $class_name); return null; } @@ -149,6 +175,7 @@ private function load_plugin_instance($plugin, $manifest) $instance = new $class_name($this->CI); } catch (Throwable $e) { log_message('error', 'Plugin construction failed (' . $slug . '): ' . $e->getMessage()); + $this->disable_plugin_after_failure($slug, 'Plugin construction failed: ' . $e->getMessage()); return null; } @@ -156,4 +183,18 @@ private function load_plugin_instance($plugin, $manifest) return $instance; } + + private function disable_plugin_after_failure($slug, $reason) + { + if (!preg_match('/^[a-z0-9_-]+$/', (string)$slug)) { + return; + } + + if ($this->CI->plugins_model->table_exists()) { + $this->CI->plugins_model->set_status($slug, 'disabled'); + } + + unset($this->plugin_instances[$slug]); + log_message('error', 'Plugin auto-disabled: ' . $slug . ' reason=' . $reason); + } } diff --git a/application/libraries/Plugin_manager.php b/application/libraries/Plugin_manager.php index f1b8cd0d6..a0de3bd93 100644 --- a/application/libraries/Plugin_manager.php +++ b/application/libraries/Plugin_manager.php @@ -314,15 +314,18 @@ public function render_award_page($slug) $award_menu = $manifest['award_menu']; $method = isset($award_menu['method']) ? trim((string)$award_menu['method']) : 'renderAwardPage'; if (!preg_match('/^[A-Za-z_][A-Za-z0-9_]*$/', $method)) { + $this->disable_plugin_after_failure($slug, 'Invalid plugin award method name: ' . $method); return array('ok' => false, 'message' => 'Invalid plugin award method.'); } $instance = $this->instantiate_plugin($plugin, $manifest); if (!$instance) { + $this->disable_plugin_after_failure($slug, 'Unable to load plugin class instance'); return array('ok' => false, 'message' => 'Unable to load plugin class.'); } if (!method_exists($instance, $method)) { + $this->disable_plugin_after_failure($slug, 'Plugin award method not found: ' . $method); return array('ok' => false, 'message' => 'Plugin award method not found: ' . $method); } @@ -334,6 +337,7 @@ public function render_award_page($slug) )); } catch (Throwable $e) { log_message('error', 'Plugin award render failed (' . $slug . '): ' . $e->getMessage()); + $this->disable_plugin_after_failure($slug, 'Plugin award render exception: ' . $e->getMessage()); return array('ok' => false, 'message' => 'Plugin award rendering failed.'); } @@ -411,7 +415,12 @@ private function instantiate_plugin($plugin, $manifest) return null; } - require_once $entry_path; + try { + require_once $entry_path; + } catch (Throwable $e) { + log_message('error', 'Plugin entry include failed (' . $plugin->plugin_slug . '): ' . $e->getMessage()); + return null; + } if (!class_exists($class_name)) { log_message('error', 'Plugin class not found: ' . $class_name . ' (' . $plugin->plugin_slug . ')'); @@ -606,4 +615,17 @@ private function recursive_delete($path) @rmdir($path); } + + private function disable_plugin_after_failure($slug, $reason) + { + if (!preg_match('/^[a-z0-9_-]+$/', (string)$slug)) { + return; + } + + if ($this->CI->plugins_model->table_exists()) { + $this->CI->plugins_model->set_status($slug, 'disabled'); + } + + log_message('error', 'Plugin auto-disabled: ' . $slug . ' reason=' . $reason); + } } diff --git a/docs/plugin-manager-guide.md b/docs/plugin-manager-guide.md index 3fb4850fc..4fbe21680 100644 --- a/docs/plugin-manager-guide.md +++ b/docs/plugin-manager-guide.md @@ -161,6 +161,7 @@ Installer validates: - Hook and award-render exceptions are caught/logged. - Core QSO workflows continue if plugin execution fails. +- Failing plugins are automatically disabled when runtime hook or award-render exceptions are detected. ## 8. Enable/Disable Semantics From fd49056a98d77805fc0d940c567f7d04a12034f6 Mon Sep 17 00:00:00 2001 From: Peter Goodhall Date: Thu, 30 Apr 2026 23:03:29 +0100 Subject: [PATCH 08/48] Enforce plugin read-only policy and show alerts Add server-side read-only policy checks for plugins and surface security alerts to admins. Plugin_manager now validates plugin code (collects PHP files and scans for forbidden file/system/exec functions) during install and before enabling; installs are blocked or plugins auto-disabled on violation with a security alert returned. Plugins controller updated to use session validation for login, enforce admin (user_type 99) access, store/display security alerts via a flash session key, and pass a CSRF token to the view. The plugins index view now renders a warning banner for plugin security alerts. Documentation updated to link and include a new QSO Hooks plugin guide for third-party sync plugins. --- application/controllers/Plugins.php | 12 +- application/libraries/Plugin_manager.php | 114 +++++++++++ application/views/plugins/index.php | 12 ++ docs/plugin-system-phase1.md | 1 + docs/qso-hooks-plugin-guide.md | 244 +++++++++++++++++++++++ 5 files changed, 382 insertions(+), 1 deletion(-) create mode 100644 docs/qso-hooks-plugin-guide.md diff --git a/application/controllers/Plugins.php b/application/controllers/Plugins.php index 1c2aa1091..6ceccb8d1 100644 --- a/application/controllers/Plugins.php +++ b/application/controllers/Plugins.php @@ -5,13 +5,18 @@ class Plugins extends CI_Controller { private const PLUGINS_CSRF_SESSION_KEY = 'plugins_csrf_token'; + private const PLUGINS_SECURITY_ALERT_SESSION_KEY = 'plugins_security_alert'; public function __construct() { parent::__construct(); $this->load->model('user_model'); - if (!$this->user_model->authorize(99)) { + if ($this->user_model->validate_session() == 0) { + redirect('user/login'); + } + + if ((int)$this->session->userdata('user_type') !== 99) { $this->session->set_flashdata('notice', 'You\'re not allowed to do that!'); redirect('dashboard'); } @@ -24,6 +29,7 @@ public function index() $data['page_title'] = 'Plugin Manager'; $data['plugins'] = $this->plugin_manager->list_plugins(); $data['plugins_csrf_token'] = $this->get_plugins_csrf_token(); + $data['plugins_security_alert'] = (string)$this->session->flashdata(self::PLUGINS_SECURITY_ALERT_SESSION_KEY); $this->load->view('interface_assets/header', $data); $this->load->view('plugins/index', $data); @@ -72,6 +78,10 @@ public function upload() $result = $this->plugin_manager->install_from_zip($upload_data['full_path']); @unlink($upload_data['full_path']); + if (isset($result['security_alert']) && trim((string)$result['security_alert']) !== '') { + $this->session->set_flashdata(self::PLUGINS_SECURITY_ALERT_SESSION_KEY, (string)$result['security_alert']); + } + $this->session->set_flashdata('notice', $result['message']); redirect('plugins'); } diff --git a/application/libraries/Plugin_manager.php b/application/libraries/Plugin_manager.php index a0de3bd93..321adde1f 100644 --- a/application/libraries/Plugin_manager.php +++ b/application/libraries/Plugin_manager.php @@ -106,6 +106,16 @@ public function install_from_zip($zip_file) $award_menu_warning = $this->validate_award_menu_definition($plugin_root, $manifest); + $read_only_policy_error = $this->validate_plugin_read_only_policy($plugin_root); + if ($read_only_policy_error !== null) { + $this->recursive_delete($extract_dir); + return array( + 'ok' => false, + 'message' => 'Plugin blocked by security policy.', + 'security_alert' => $read_only_policy_error, + ); + } + $slug = $this->resolve_slug($manifest); if ($slug === null) { $this->recursive_delete($extract_dir); @@ -306,6 +316,13 @@ public function render_award_page($slug) return array('ok' => false, 'message' => 'Award plugin is not enabled.'); } + $plugin_root = $this->get_plugin_root() . $slug . DIRECTORY_SEPARATOR; + $read_only_policy_error = $this->validate_plugin_read_only_policy($plugin_root); + if ($read_only_policy_error !== null) { + $this->disable_plugin_after_failure($slug, $read_only_policy_error); + return array('ok' => false, 'message' => 'Plugin disabled due to read-only policy violation.'); + } + $manifest = $this->get_manifest_for_plugin($plugin); if (!is_array($manifest) || !isset($manifest['award_menu']) || !is_array($manifest['award_menu'])) { return array('ok' => false, 'message' => 'Plugin does not declare an award menu entry.'); @@ -628,4 +645,101 @@ private function disable_plugin_after_failure($slug, $reason) log_message('error', 'Plugin auto-disabled: ' . $slug . ' reason=' . $reason); } + + private function validate_plugin_read_only_policy($plugin_root) + { + $plugin_root_real = realpath($plugin_root); + if ($plugin_root_real === false || !is_dir($plugin_root_real)) { + return 'Plugin files are missing on disk.'; + } + + $php_files = $this->collect_php_files($plugin_root_real); + if (empty($php_files)) { + return null; + } + + foreach ($php_files as $php_file) { + $contents = @file_get_contents($php_file); + if ($contents === false) { + return 'Plugin policy check failed: unable to read ' . basename($php_file) . '.'; + } + + $violation = $this->find_forbidden_plugin_operation($contents); + if ($violation !== null) { + $relative_path = ltrim(str_replace($plugin_root_real, '', $php_file), DIRECTORY_SEPARATOR); + return 'Forbidden operation "' . $violation . '" in ' . $relative_path . '. Plugins must be read-only and cannot execute system commands.'; + } + } + + return null; + } + + private function collect_php_files($root) + { + $files = array(); + $items = @scandir($root); + if (!is_array($items)) { + return $files; + } + + foreach ($items as $item) { + if ($item === '.' || $item === '..') { + continue; + } + + $path = $root . DIRECTORY_SEPARATOR . $item; + if (is_dir($path)) { + $files = array_merge($files, $this->collect_php_files($path)); + continue; + } + + if (strtolower(pathinfo($path, PATHINFO_EXTENSION)) === 'php') { + $files[] = $path; + } + } + + return $files; + } + + private function find_forbidden_plugin_operation($php_code) + { + $forbidden_functions = array( + 'file_put_contents', + 'fopen', + 'fwrite', + 'fputs', + 'mkdir', + 'rmdir', + 'rename', + 'unlink', + 'copy', + 'touch', + 'symlink', + 'link', + 'move_uploaded_file', + 'chmod', + 'chown', + 'chgrp', + 'ftruncate', + 'tempnam', + 'tmpfile', + 'system', + 'exec', + 'shell_exec', + 'passthru', + 'proc_open', + 'popen', + 'pcntl_exec', + 'assert', + 'eval', + ); + + foreach ($forbidden_functions as $function_name) { + if (preg_match('/\\b' . preg_quote($function_name, '/') . '\\s*\\(/i', $php_code)) { + return $function_name; + } + } + + return null; + } } diff --git a/application/views/plugins/index.php b/application/views/plugins/index.php index 7e15c1b48..cde3fabac 100644 --- a/application/views/plugins/index.php +++ b/application/views/plugins/index.php @@ -1,7 +1,19 @@ + +

    Plugin Manager

    Upload a plugin zip package, install it, and control whether it is enabled.

    + + + +
    Upload Plugin diff --git a/docs/plugin-system-phase1.md b/docs/plugin-system-phase1.md index 79dd800ed..2de921dcd 100644 --- a/docs/plugin-system-phase1.md +++ b/docs/plugin-system-phase1.md @@ -6,6 +6,7 @@ Related guides: - [docs/plugin-manager-guide.md](docs/plugin-manager-guide.md) - [docs/awards-plugin-guide.md](docs/awards-plugin-guide.md) +- [docs/qso-hooks-plugin-guide.md](docs/qso-hooks-plugin-guide.md) ## Goals diff --git a/docs/qso-hooks-plugin-guide.md b/docs/qso-hooks-plugin-guide.md new file mode 100644 index 000000000..d386a4624 --- /dev/null +++ b/docs/qso-hooks-plugin-guide.md @@ -0,0 +1,244 @@ +# Cloudlog QSO Hooks Plugin Guide + +This guide explains how to build a plugin that uploads or syncs QSOs to third-party systems. + +Primary use case: + +- push newly created QSOs to an external service +- re-sync edited QSOs so external records stay accurate +- normalize outgoing QSO data before sync + +Related docs: + +- [docs/plugin-system-phase1.md](docs/plugin-system-phase1.md) +- [docs/plugin-manager-guide.md](docs/plugin-manager-guide.md) +- [docs/awards-plugin-guide.md](docs/awards-plugin-guide.md) + +## 1. Why Use QSO Hooks For Third-Party Uploads + +QSO hooks let you keep Cloudlog as the source of truth while automatically syncing to external systems. + +Common sync scenarios: + +- Send each new QSO to a club API or internal stats platform. +- Update or overwrite a third-party record when a QSO is edited. +- Trigger webhooks for Discord, Slack, Matrix, or custom automation. +- Bridge Cloudlog to award trackers or event tools that are not built in. + +## 2. Phase 1 Hooks You Will Use + +Current QSO hooks: + +- `qso.filter.before_save` +- `qso.action.after_save` +- `qso.action.after_edit` + +Dispatch points in core: + +- Create flow applies `qso.filter.before_save` before insert. +- Add flow dispatches `qso.action.after_save` after insert and cache clear. +- Edit flow dispatches `qso.action.after_edit` after update and cache clear. + +## 3. Which Hook Does What In Sync Workflows + +### 3.1 `qso.filter.before_save` (optional, pre-sync normalization) + +- Called before QSO data is persisted. +- Receives `payload` and `context`. +- Should return: + - modified payload array to change data + - same payload to keep data unchanged + - `null` to leave current payload as-is + +Typical sync use: + +- trim and uppercase text fields +- set defaults when a value is missing +- normalize contest exchange fields + +### 3.2 `qso.action.after_save` and `qso.action.after_edit` (main sync triggers) + +- Called after database persistence. +- Receive `payload` and `context`. +- Return value is ignored. + +Typical sync use: + +- call external APIs +- send webhooks +- update remote records + +## 4. Payload and Context You Can Send Externally + +These are the shapes currently passed by core dispatch points. + +### 4.1 `qso.filter.before_save` + +Payload: QSO data array before insert. + +Context: + +- `source`: `manual` +- `station_id`: station id used for the QSO + +### 4.2 `qso.action.after_save` + +Payload: + +- `qso_id`: inserted QSO id +- `qso`: inserted QSO data array + +Context: + +- `source`: `manual` or `import` +- `station_id`: station id from QSO payload + +### 4.3 `qso.action.after_edit` + +Payload: + +- `qso_id`: edited QSO id +- `qso`: updated QSO data array + +Context: + +- `station_id`: station id for the edited QSO + +## 5. Minimal Third-Party Sync Plugin Template + +Folder layout: + +```text +my-qso-sync-plugin/ + manifest.json + Plugin.php + README.md +``` + +`manifest.json` example: + +```json +{ + "slug": "my-qso-sync-plugin", + "name": "My QSO Sync Plugin", + "version": "1.0.0", + "description": "Syncs new and edited QSOs to an external system.", + "entry": "Plugin.php", + "class": "MyQsoSyncPlugin", + "hooks": { + "qso.filter.before_save": "beforeSave", + "qso.action.after_save": "afterSave", + "qso.action.after_edit": "afterEdit" + } +} +``` + +`Plugin.php` example: + +```php +CI = $ci; + } + + public function beforeSave($payload, $context = array()) + { + if (!is_array($payload)) { + return $payload; + } + + if (isset($payload['COL_CALL'])) { + $payload['COL_CALL'] = strtoupper(trim((string)$payload['COL_CALL'])); + } + + if (isset($payload['COL_GRIDSQUARE'])) { + $payload['COL_GRIDSQUARE'] = strtoupper(trim((string)$payload['COL_GRIDSQUARE'])); + } + + return $payload; + } + + public function afterSave($payload, $context = array()) + { + $qso_id = isset($payload['qso_id']) ? (int)$payload['qso_id'] : 0; + $qso = isset($payload['qso']) && is_array($payload['qso']) ? $payload['qso'] : array(); + $source = isset($context['source']) ? (string)$context['source'] : 'unknown'; + + // Replace with your real HTTP client call. + $call = isset($qso['COL_CALL']) ? (string)$qso['COL_CALL'] : ''; + log_message('info', 'MyQsoSyncPlugin afterSave qso_id=' . $qso_id . ' source=' . $source . ' call=' . $call); + } + + public function afterEdit($payload, $context = array()) + { + $qso_id = isset($payload['qso_id']) ? (int)$payload['qso_id'] : 0; + $qso = isset($payload['qso']) && is_array($payload['qso']) ? $payload['qso'] : array(); + + // Replace with your real HTTP client call. + $call = isset($qso['COL_CALL']) ? (string)$qso['COL_CALL'] : ''; + log_message('info', 'MyQsoSyncPlugin afterEdit qso_id=' . $qso_id . ' call=' . $call); + } +} +``` + +## 6. Install and Enable + +1. Zip plugin contents. +2. Go to Admin > Plugin Manager. +3. Upload and install zip. +4. Enable the plugin. +5. Create and edit QSOs to verify behavior. + +## 7. Testing Strategy For External Sync + +Use a small test matrix: + +1. Manual create QSO: +Check outbound payload contains expected normalized values. +2. Import create QSO: +Check after-save source context reports `import` and still syncs. +3. Edit QSO: +Check after-edit re-sync sends updated fields. +4. Temporary API outage: +Confirm QSO save still succeeds and plugin logs sync failure. + +Also review logs in application logs for plugin messages and any auto-disable events. + +## 8. Reliability and Security Notes + +- Plugin code runs in-process, so it must be trusted. +- Hook exceptions are caught and plugin may be auto-disabled. +- Plugin Manager enforces read-only and command-execution policy checks. +- Keep hooks fast to avoid slowing down QSO saves. + +Recommended practices: + +- Use timeouts and fail-safe handling for external API calls. +- Keep constructor side-effect free. +- Validate all array keys before use. +- Prefer idempotent remote writes (same QSO sent twice should be safe). + +## 9. Recommended Sync Pattern + +Use this baseline pattern for robust integrations: + +1. Build a stable external key (for example `qso_id` + `station_id`). +2. Send create/update through one upsert-style endpoint where possible. +3. On failure, log details and return without throwing fatal errors. +4. Keep request payload minimal and explicit. +5. Reuse the same mapping logic for both after-save and after-edit. + +## 10. Good First Third-Party Integrations + +- Club leaderboard API sync. +- Team notification webhook on new DXCC. +- Event scoring backend sync. +- Custom analytics pipeline webhook. From e6f6dd22655c3133419b222d7f0bcba9e47bd6d3 Mon Sep 17 00:00:00 2001 From: Peter Goodhall Date: Fri, 1 May 2026 10:22:11 +0100 Subject: [PATCH 09/48] Disable caching for radio JSON; use $.ajax Add no-cache HTTP headers in Radio::json to prevent cached responses. Replace client-side $.getJSON with $.ajax(url, {dataType:'json', cache:false}) and preserve the stale-response checks while updating lastProcessedCatRequest only when a response is applied. Also ensure login errors return early. These changes ensure fresh CAT data and avoid stale or cached responses affecting the UI. --- application/controllers/Radio.php | 4 ++ application/views/interface_assets/footer.php | 43 +++++++++++-------- 2 files changed, 28 insertions(+), 19 deletions(-) diff --git a/application/controllers/Radio.php b/application/controllers/Radio.php index 04df37c69..86abbc6d9 100755 --- a/application/controllers/Radio.php +++ b/application/controllers/Radio.php @@ -79,6 +79,10 @@ function status() { } function json($id) { + $this->output->set_header('Cache-Control: no-store, no-cache, must-revalidate, max-age=0'); + $this->output->set_header('Cache-Control: post-check=0, pre-check=0', false); + $this->output->set_header('Pragma: no-cache'); + $this->output->set_header('Expires: Sat, 01 Jan 2000 00:00:00 GMT'); $this->load->model('user_model'); diff --git a/application/views/interface_assets/footer.php b/application/views/interface_assets/footer.php index 323587f83..640f201d0 100644 --- a/application/views/interface_assets/footer.php +++ b/application/views/interface_assets/footer.php @@ -2119,29 +2119,34 @@ function getUTCDateStamp(el) { const requestId = ++catRequestCounter; const requestContextVersion = catSelectionContextVersion; - $.getJSON(`radio/json/${requestedRadioID}`, (data) => { - const currentSelectedRadioID = String($('select.radios option:selected').val() || '0'); - - // Ignore stale CAT responses when radio selection changed or newer requests have already been applied. - if ( - requestContextVersion !== catSelectionContextVersion || - currentSelectedRadioID !== requestedRadioID || - requestId < lastProcessedCatRequest - ) { - return; - } + $.ajax({ + url: `radio/json/${requestedRadioID}`, + dataType: 'json', + cache: false, + success: (data) => { + const currentSelectedRadioID = String($('select.radios option:selected').val() || '0'); + + // Ignore stale CAT responses when radio selection changed or newer requests have already been applied. + if ( + requestContextVersion !== catSelectionContextVersion || + currentSelectedRadioID !== requestedRadioID || + requestId < lastProcessedCatRequest + ) { + return; + } - lastProcessedCatRequest = requestId; + lastProcessedCatRequest = requestId; - if (data.error) { - if (data.error === 'not_logged_in') { - handleLoginError(); + if (data.error) { + if (data.error === 'not_logged_in') { + handleLoginError(); + } + return; } - return; - } - clearLoginError(); - updateUIWithCATData(data); + clearLoginError(); + updateUIWithCATData(data); + } }); }; From 7e40a0288e6c8154efcabf01e911dcaeda69d2fe Mon Sep 17 00:00:00 2001 From: Peter Goodhall Date: Fri, 1 May 2026 10:23:08 +0100 Subject: [PATCH 10/48] Add resilient CAT polling with backoff and warnings Replace the fixed 3s setInterval CAT updater with a scheduled poller that supports exponential backoff, failure counting, and UI warnings. Introduces consecutiveCatPollFailures, catPollTimer, lastSuccessfulCatUpdateAt, and constants for base/max intervals and warning threshold. Adds helper functions to compute delays, schedule polls, handle success/failure, show/clear warning banners, and only poll the currently selected radio. Clears warnings on login error/reset/selection changes and resets failure counters when selection changes to maintain responsive UI. --- application/views/interface_assets/footer.php | 102 ++++++++++++++++-- 1 file changed, 95 insertions(+), 7 deletions(-) diff --git a/application/views/interface_assets/footer.php b/application/views/interface_assets/footer.php index 640f201d0..293ea36d5 100644 --- a/application/views/interface_assets/footer.php +++ b/application/views/interface_assets/footer.php @@ -2096,6 +2096,13 @@ function getUTCDateStamp(el) { let catRequestCounter = 0; let lastProcessedCatRequest = 0; let catSelectionContextVersion = 0; + let consecutiveCatPollFailures = 0; + let catPollTimer = null; + let lastSuccessfulCatUpdateAt = null; + + const CAT_POLL_BASE_INTERVAL_MS = 3000; + const CAT_POLL_MAX_INTERVAL_MS = 15000; + const CAT_POLL_WARNING_THRESHOLD = 3; // Helper function to update a UI element with CAT data const cat2UI = (ui, cat, allowEmpty = true, allowZero = true, callbackOnUpdate) => { @@ -2141,15 +2148,98 @@ function getUTCDateStamp(el) { if (data.error === 'not_logged_in') { handleLoginError(); } + handleCATPollFailure(requestedRadioID); return; } clearLoginError(); + handleCATPollSuccess(); updateUIWithCATData(data); + }, + error: () => { + handleCATPollFailure(requestedRadioID); } }); }; + const getNextCATPollDelay = () => { + if (consecutiveCatPollFailures <= 0) { + return CAT_POLL_BASE_INTERVAL_MS; + } + + return Math.min( + CAT_POLL_MAX_INTERVAL_MS, + CAT_POLL_BASE_INTERVAL_MS * Math.pow(2, consecutiveCatPollFailures - 1) + ); + }; + + const clearCATPollWarning = () => { + $('.radio_poll_warning').remove(); + }; + + const showCATPollWarning = () => { + const secondsSinceSuccess = lastSuccessfulCatUpdateAt === null + ? null + : Math.max(0, Math.floor((Date.now() - lastSuccessfulCatUpdateAt) / 1000)); + + let warningText = 'Live rig sync is temporarily unstable. Retrying automatically.'; + if (secondsSinceSuccess !== null) { + warningText += ` Last successful update was ${secondsSinceSuccess} seconds ago.`; + } + + if ($('.radio_poll_warning').length === 0) { + $('#radio_status').prepend( + `` + ); + } else { + $('.radio_poll_warning').html(` ${warningText}`); + } + }; + + const handleCATPollSuccess = () => { + consecutiveCatPollFailures = 0; + lastSuccessfulCatUpdateAt = Date.now(); + clearCATPollWarning(); + scheduleNextCATPoll(CAT_POLL_BASE_INTERVAL_MS); + }; + + const handleCATPollFailure = (radioID) => { + const currentSelectedRadioID = String($('select.radios option:selected').val() || '0'); + if (!radioID || currentSelectedRadioID !== String(radioID)) { + return; + } + + consecutiveCatPollFailures += 1; + + if (consecutiveCatPollFailures >= CAT_POLL_WARNING_THRESHOLD) { + showCATPollWarning(); + } + + scheduleNextCATPoll(getNextCATPollDelay()); + }; + + const scheduleNextCATPoll = (delayMs) => { + if (catPollTimer !== null) { + clearTimeout(catPollTimer); + } + + catPollTimer = setTimeout(() => { + pollSelectedRadio(); + }, delayMs); + }; + + const pollSelectedRadio = () => { + const selectedRadioID = String($('select.radios option:selected').val() || '0'); + if (selectedRadioID !== '0') { + updateFromCAT(selectedRadioID); + return; + } + + consecutiveCatPollFailures = 0; + clearCATPollWarning(); + scheduleNextCATPoll(CAT_POLL_BASE_INTERVAL_MS); + }; + // Handle login error display const handleLoginError = () => { $(".radio_cat_state").remove(); @@ -2244,6 +2334,7 @@ function getUTCDateStamp(el) { // Clear CAT value cache so re-selecting a radio with identical values still repopulates fields. $('#frequency, #frequency_rx, #sat_name, #sat_mode, #transmit_power, #selectPropagation, #mode').removeData('catValue'); $(".radio_timeout_error").remove(); + clearCATPollWarning(); }; // Event listeners @@ -2270,20 +2361,17 @@ function getUTCDateStamp(el) { isSubmitting = true; }); - // Update frequency every three seconds for the selected radio - setInterval(() => { - const selectedRadioID = $('select.radios option:selected').val(); - if (selectedRadioID !== '0') { - updateFromCAT(selectedRadioID); - } - }, 3000); + scheduleNextCATPoll(CAT_POLL_BASE_INTERVAL_MS); // Trigger updateFromCAT when any + + + + + +
    +
    +
    From e25714b37a1c444394035c9a62fad5c8025c4a07 Mon Sep 17 00:00:00 2001 From: Peter Goodhall Date: Wed, 6 May 2026 10:33:35 +0100 Subject: [PATCH 13/48] Update GMDX Summer Challenge to 2026 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Advance the GMDX Summer Challenge event to 2026: update controller week end timestamps, and update view copy and table dates/entry link to reflect the new event window (11 May – 5 July 2026). In the model introduce START_DATE (2026-05-11), add validation to ignore empty/null COL_GRIDSQUARE values, and change combined-count logic to normalize gridsquares and group modes into CW / VOICE / DIGITAL so counts are consistent and case-insensitive. --- application/controllers/Awards.php | 66 +++++++++---------- application/models/Gmdxsummer_model.php | 23 +++++-- application/views/awards/gmdxsummer/index.php | 16 ++--- 3 files changed, 59 insertions(+), 46 deletions(-) diff --git a/application/controllers/Awards.php b/application/controllers/Awards.php index 751ed17a3..293790327 100644 --- a/application/controllers/Awards.php +++ b/application/controllers/Awards.php @@ -816,51 +816,51 @@ public function gmdxsummer() $this->load->model('gmdxsummer_model'); // Get Week 1 - $data['week1_6m_cw'] = $this->gmdxsummer_model->get_week('2024-05-26 18:00:00', '6m', 'CW'); - $data['week1_6m_ssb'] = $this->gmdxsummer_model->get_week_voice('2024-05-26 18:00:00', '6m'); - $data['week1_6m_digital'] = $this->gmdxsummer_model->get_week_digital('2024-05-26 18:00:00', '6m'); - $data['week1_6m_combined'] = $this->gmdxsummer_model->get_week_combined('2024-05-26 18:00:00', '6m'); + $data['week1_6m_cw'] = $this->gmdxsummer_model->get_week('2026-05-24 18:00:00', '6m', 'CW'); + $data['week1_6m_ssb'] = $this->gmdxsummer_model->get_week_voice('2026-05-24 18:00:00', '6m'); + $data['week1_6m_digital'] = $this->gmdxsummer_model->get_week_digital('2026-05-24 18:00:00', '6m'); + $data['week1_6m_combined'] = $this->gmdxsummer_model->get_week_combined('2026-05-24 18:00:00', '6m'); - $data['week1_4m_cw'] = $this->gmdxsummer_model->get_week('2024-05-26 18:00:00', '4m', 'CW'); - $data['week1_4m_ssb'] = $this->gmdxsummer_model->get_week_voice('2024-05-26 18:00:00', '4m'); - $data['week1_4m_digital'] = $this->gmdxsummer_model->get_week_digital('2024-05-26 18:00:00', '4m'); - $data['week1_4m_combined'] = $this->gmdxsummer_model->get_week_combined('2024-05-26 18:00:00', '4m'); + $data['week1_4m_cw'] = $this->gmdxsummer_model->get_week('2026-05-24 18:00:00', '4m', 'CW'); + $data['week1_4m_ssb'] = $this->gmdxsummer_model->get_week_voice('2026-05-24 18:00:00', '4m'); + $data['week1_4m_digital'] = $this->gmdxsummer_model->get_week_digital('2026-05-24 18:00:00', '4m'); + $data['week1_4m_combined'] = $this->gmdxsummer_model->get_week_combined('2026-05-24 18:00:00', '4m'); // Get Week 2 - $data['week2_6m_cw'] = $this->gmdxsummer_model->get_week('2024-06-09 18:00:00', '6m', 'CW'); - $data['week2_6m_ssb'] = $this->gmdxsummer_model->get_week_voice('2024-06-09 18:00:00', '6m'); - $data['week2_6m_digital'] = $this->gmdxsummer_model->get_week_digital('2024-06-09 18:00:00', '6m'); - $data['week2_6m_combined'] = $this->gmdxsummer_model->get_week_combined('2024-06-09 18:00:00', '6m'); + $data['week2_6m_cw'] = $this->gmdxsummer_model->get_week('2026-06-07 18:00:00', '6m', 'CW'); + $data['week2_6m_ssb'] = $this->gmdxsummer_model->get_week_voice('2026-06-07 18:00:00', '6m'); + $data['week2_6m_digital'] = $this->gmdxsummer_model->get_week_digital('2026-06-07 18:00:00', '6m'); + $data['week2_6m_combined'] = $this->gmdxsummer_model->get_week_combined('2026-06-07 18:00:00', '6m'); - $data['week2_4m_cw'] = $this->gmdxsummer_model->get_week('2024-06-09 18:00:00', '4m', 'CW'); - $data['week2_4m_ssb'] = $this->gmdxsummer_model->get_week_voice('2024-06-09 18:00:00', '4m'); - $data['week2_4m_digital'] = $this->gmdxsummer_model->get_week_digital('2024-06-09 18:00:00', '4m'); - $data['week2_4m_combined'] = $this->gmdxsummer_model->get_week_combined('2024-06-09 18:00:00', '4m'); + $data['week2_4m_cw'] = $this->gmdxsummer_model->get_week('2026-06-07 18:00:00', '4m', 'CW'); + $data['week2_4m_ssb'] = $this->gmdxsummer_model->get_week_voice('2026-06-07 18:00:00', '4m'); + $data['week2_4m_digital'] = $this->gmdxsummer_model->get_week_digital('2026-06-07 18:00:00', '4m'); + $data['week2_4m_combined'] = $this->gmdxsummer_model->get_week_combined('2026-06-07 18:00:00', '4m'); // Get Week 3 - $data['week3_6m_cw'] = $this->gmdxsummer_model->get_week('2024-06-23 18:00:00', '6m', 'CW'); - $data['week3_6m_ssb'] = $this->gmdxsummer_model->get_week_voice('2024-06-23 18:00:00', '6m'); - $data['week3_6m_digital'] = $this->gmdxsummer_model->get_week_digital('2024-06-23 18:00:00', '6m'); - $data['week3_6m_combined'] = $this->gmdxsummer_model->get_week_combined('2024-06-23 18:00:00', '6m'); + $data['week3_6m_cw'] = $this->gmdxsummer_model->get_week('2026-06-21 18:00:00', '6m', 'CW'); + $data['week3_6m_ssb'] = $this->gmdxsummer_model->get_week_voice('2026-06-21 18:00:00', '6m'); + $data['week3_6m_digital'] = $this->gmdxsummer_model->get_week_digital('2026-06-21 18:00:00', '6m'); + $data['week3_6m_combined'] = $this->gmdxsummer_model->get_week_combined('2026-06-21 18:00:00', '6m'); - $data['week3_4m_cw'] = $this->gmdxsummer_model->get_week('2024-06-23 18:00:00', '4m', 'CW'); - $data['week3_4m_ssb'] = $this->gmdxsummer_model->get_week_voice('2024-06-23 18:00:00', '4m'); - $data['week3_4m_digital'] = $this->gmdxsummer_model->get_week_digital('2024-06-23 18:00:00', '4m'); - $data['week3_4m_combined'] = $this->gmdxsummer_model->get_week_combined('2024-06-23 18:00:00', '4m'); + $data['week3_4m_cw'] = $this->gmdxsummer_model->get_week('2026-06-21 18:00:00', '4m', 'CW'); + $data['week3_4m_ssb'] = $this->gmdxsummer_model->get_week_voice('2026-06-21 18:00:00', '4m'); + $data['week3_4m_digital'] = $this->gmdxsummer_model->get_week_digital('2026-06-21 18:00:00', '4m'); + $data['week3_4m_combined'] = $this->gmdxsummer_model->get_week_combined('2026-06-21 18:00:00', '4m'); // Get Week 4 - $data['week4_6m_cw'] = $this->gmdxsummer_model->get_week('2024-07-01 18:00:00', '6m', 'CW'); - $data['week4_6m_ssb'] = $this->gmdxsummer_model->get_week_voice('2024-07-01 18:00:00', '6m'); - $data['week4_6m_digital'] = $this->gmdxsummer_model->get_week_digital('2024-07-01 18:00:00', '6m'); - $data['week4_6m_combined'] = $this->gmdxsummer_model->get_week_combined('2024-07-01 18:00:00', '6m'); - - $data['week4_4m_cw'] = $this->gmdxsummer_model->get_week('2024-07-01 18:00:00', '4m', 'CW'); - $data['week4_4m_ssb'] = $this->gmdxsummer_model->get_week_voice('2024-07-01 18:00:00', '4m'); - $data['week4_4m_digital'] = $this->gmdxsummer_model->get_week_digital('2024-07-01 18:00:00', '4m'); - $data['week4_4m_combined'] = $this->gmdxsummer_model->get_week_combined('2024-07-01 18:00:00', '4m'); + $data['week4_6m_cw'] = $this->gmdxsummer_model->get_week('2026-07-05 23:59:59', '6m', 'CW'); + $data['week4_6m_ssb'] = $this->gmdxsummer_model->get_week_voice('2026-07-05 23:59:59', '6m'); + $data['week4_6m_digital'] = $this->gmdxsummer_model->get_week_digital('2026-07-05 23:59:59', '6m'); + $data['week4_6m_combined'] = $this->gmdxsummer_model->get_week_combined('2026-07-05 23:59:59', '6m'); + + $data['week4_4m_cw'] = $this->gmdxsummer_model->get_week('2026-07-05 23:59:59', '4m', 'CW'); + $data['week4_4m_ssb'] = $this->gmdxsummer_model->get_week_voice('2026-07-05 23:59:59', '4m'); + $data['week4_4m_digital'] = $this->gmdxsummer_model->get_week_digital('2026-07-05 23:59:59', '4m'); + $data['week4_4m_combined'] = $this->gmdxsummer_model->get_week_combined('2026-07-05 23:59:59', '4m'); // Render page diff --git a/application/models/Gmdxsummer_model.php b/application/models/Gmdxsummer_model.php index 70f6e6427..4d7dfe2ca 100644 --- a/application/models/Gmdxsummer_model.php +++ b/application/models/Gmdxsummer_model.php @@ -2,6 +2,7 @@ class Gmdxsummer_model extends CI_Model { + private const START_DATE = '2026-05-11 00:00:00'; public function get_week($end_date, $band, $mode) { @@ -17,7 +18,8 @@ public function get_week($end_date, $band, $mode) SELECT COUNT(DISTINCT SUBSTRING(COL_GRIDSQUARE, 1, 4)) AS count FROM " . $table_name . " WHERE station_id in (" . $location_list . ") AND COL_MODE = '" . $mode . "' AND COL_BAND = '" . $band . "' - AND (COL_TIME_ON >= '2024-05-13 00:00:00' AND COL_TIME_ON <= '" . $end_date . "') + AND COL_GRIDSQUARE IS NOT NULL AND COL_GRIDSQUARE != '' + AND (COL_TIME_ON >= '" . self::START_DATE . "' AND COL_TIME_ON <= '" . $end_date . "') "); return $query->row()->count; @@ -37,7 +39,8 @@ public function get_week_voice($end_date, $band) SELECT COUNT(DISTINCT SUBSTRING(COL_GRIDSQUARE, 1, 4)) AS count FROM " . $table_name . " WHERE station_id in (".$location_list.") AND COL_MODE IN ('SSB', 'AM', 'FM') AND COL_BAND = '" . $band . "' - AND (COL_TIME_ON >= '2024-05-13 00:00:00' AND COL_TIME_ON <= '" . $end_date . "') + AND COL_GRIDSQUARE IS NOT NULL AND COL_GRIDSQUARE != '' + AND (COL_TIME_ON >= '" . self::START_DATE . "' AND COL_TIME_ON <= '" . $end_date . "') "); @@ -58,7 +61,8 @@ public function get_week_digital($end_date, $band) SELECT COUNT(DISTINCT SUBSTRING(COL_GRIDSQUARE, 1, 4)) AS count FROM " . $table_name . " WHERE station_id in (".$location_list.") AND COL_MODE NOT IN ('CW', 'FM', 'SSB', 'AM') AND COL_BAND = '" . $band . "' - AND (COL_TIME_ON >= '2024-05-13 00:00:00' AND COL_TIME_ON <= '" . $end_date . "') + AND COL_GRIDSQUARE IS NOT NULL AND COL_GRIDSQUARE != '' + AND (COL_TIME_ON >= '" . self::START_DATE . "' AND COL_TIME_ON <= '" . $end_date . "') "); return $query->row()->count; @@ -75,10 +79,19 @@ public function get_week_combined($end_date, $band) $location_list = "'" . implode("','", $logbooks_locations_array) . "'"; $query = $this->db->query(" - SELECT COUNT(DISTINCT SUBSTRING(COL_GRIDSQUARE, 1, 4)) AS count + SELECT COUNT(DISTINCT CONCAT( + UPPER(SUBSTRING(COL_GRIDSQUARE, 1, 4)), + '-', + CASE + WHEN COL_MODE = 'CW' THEN 'CW' + WHEN COL_MODE IN ('SSB', 'AM', 'FM') THEN 'VOICE' + ELSE 'DIGITAL' + END + )) AS count FROM " . $table_name . " WHERE station_id in (".$location_list.") AND COL_BAND = '" . $band . "' - AND (COL_TIME_ON >= '2024-05-13 00:00:00' AND COL_TIME_ON <= '" . $end_date . "') + AND COL_GRIDSQUARE IS NOT NULL AND COL_GRIDSQUARE != '' + AND (COL_TIME_ON >= '" . self::START_DATE . "' AND COL_TIME_ON <= '" . $end_date . "') "); return $query->row()->count; diff --git a/application/views/awards/gmdxsummer/index.php b/application/views/awards/gmdxsummer/index.php index 98d6592d4..eb51503fd 100644 --- a/application/views/awards/gmdxsummer/index.php +++ b/application/views/awards/gmdxsummer/index.php @@ -12,11 +12,11 @@ What is the GMDX Summer Challenge?
    -

    The GMDX Summer Challenge will takes place over 6 weeks beginning 00:00 on Monday 13th May until 2359 on Sunday 30th June.

    -

    The Summer Challenge is a single event using CW, SSB or Digital Modes on both 4m and 6m. GMDX members are expected not to set up FT8 in automated robot mode. You are trusted to operate your station manually.

    -

    The overall winner will have worked the most 4 digit maidenhead locator squares (eg IO75) on 4m and 6m to give the highest combined score. DXCC Countries are not counted, only locator squares. In order to have the leading score, it is expected operators would have to make contacts on both 4m and 6m using all modes.

    +

    The GMDX Summer VHF Challenge 2026 takes place from 00:00 on Monday 11th May until 23:59 on Sunday 5th July.

    +

    The challenge is a single event using CW, Voice, and Digital modes on both 4m and 6m. Acceptable voice modes are SSB, AM, and FM. Entrants are expected not to set up FT8 or other digital modes in automated robot mode, and to operate manually.

    +

    Score is based on 4-digit Maidenhead locator squares (for example IO72), and DXCC countries are not counted. The same locator can be counted once per mode category (CW, Voice, Digital) on each band, so the same locator can count up to 3 times on 4m and again up to 3 times on 6m.

    All GMDX members worldwide are welcome to enter.

    - Submit your entry + Submit your entry
    @@ -39,7 +39,7 @@ - 18:00 on Sunday 26th May + 18:00 on Sunday 24th May @@ -51,7 +51,7 @@ - 18:00 on Sunday 9th June + 18:00 on Sunday 7th June @@ -63,7 +63,7 @@ - 18:00 on Sunday 23th June + 18:00 on Sunday 21st June @@ -75,7 +75,7 @@ - 18:00 on Monday 1st July + 18:00 on Monday 6th July (QSOs counted to 23:59 Sunday 5th July) From 0413d8a6bfed70f7e2f9c443dab647bb8a571d12 Mon Sep 17 00:00:00 2001 From: Peter Goodhall Date: Thu, 7 May 2026 22:12:05 +0100 Subject: [PATCH 14/48] Refactor dashboard helpers and improve UX Move repeated table rendering helpers into a new application/helpers/dashboard_helper.php and load it from the Dashboard controller to remove duplication in views. Improve mobile/responsive dashboard behavior: detect mobile user agent to reduce recent-QSO rows, add mobile-specific quick links, collapse cards for compact display, and adjust HTMX polling intervals and targets. Add htmx loading indicators and last-updated timestamps with a small JS handler, and include minor CSS tweaks. Also add a session validation early-return in radio_display_component and load the user_agent library in the controller. --- application/controllers/Dashboard.php | 12 +- application/helpers/dashboard_helper.php | 167 ++++++++++ .../components/dashboard_logbook_table.php | 158 +-------- application/views/dashboard/index.php | 305 ++++++++---------- 4 files changed, 313 insertions(+), 329 deletions(-) create mode 100644 application/helpers/dashboard_helper.php diff --git a/application/controllers/Dashboard.php b/application/controllers/Dashboard.php index cacf9194f..ea3ac53b4 100644 --- a/application/controllers/Dashboard.php +++ b/application/controllers/Dashboard.php @@ -11,6 +11,7 @@ public function __construct() $this->load->model('user_model'); $this->load->model('logbook_model'); $this->load->model('logbooks_model'); + $this->load->helper('dashboard'); } public function index() @@ -229,16 +230,23 @@ public function logbook_display_component() { return; } + $this->load->library('user_agent'); + // Get Logbook Locations $logbooks_locations_array = $this->logbooks_model->list_logbook_relationships($this->session->userdata('active_station_logbook')); - // Get the last 20 QSOs - $data['last_five_qsos'] = $this->logbook_model->get_last_qsos('20', $logbooks_locations_array); + // Show fewer rows on mobile to reduce dashboard noise. + $recent_qso_limit = $this->agent->is_mobile() ? '10' : '20'; + $data['last_five_qsos'] = $this->logbook_model->get_last_qsos($recent_qso_limit, $logbooks_locations_array); $this->load->view('components/dashboard_logbook_table', $data); } function radio_display_component() { + if ($this->user_model->validate_session() == 0) { + return; + } + $this->load->model('cat'); $data['radio_status'] = $this->cat->recent_status(); diff --git a/application/helpers/dashboard_helper.php b/application/helpers/dashboard_helper.php new file mode 100644 index 000000000..1d6aff6c7 --- /dev/null +++ b/application/helpers/dashboard_helper.php @@ -0,0 +1,167 @@ +' . $ctx->lang->line('gen_hamradio_mode') . ''; + break; + case 'RSTS': + echo '' . $ctx->lang->line('gen_hamradio_rsts') . ''; + break; + case 'RSTR': + echo '' . $ctx->lang->line('gen_hamradio_rstr') . ''; + break; + case 'Country': + echo '' . $ctx->lang->line('general_word_country') . ''; + break; + case 'IOTA': + echo '' . $ctx->lang->line('gen_hamradio_iota') . ''; + break; + case 'SOTA': + echo '' . $ctx->lang->line('gen_hamradio_sota') . ''; + break; + case 'WWFF': + echo '' . $ctx->lang->line('gen_hamradio_wwff') . ''; + break; + case 'POTA': + echo '' . $ctx->lang->line('gen_hamradio_pota') . ''; + break; + case 'State': + echo '' . $ctx->lang->line('gen_hamradio_state') . ''; + break; + case 'Grid': + echo '' . $ctx->lang->line('gen_hamradio_gridsquare') . ''; + break; + case 'Distance': + echo '' . $ctx->lang->line('gen_hamradio_distance') . ''; + break; + case 'Band': + echo '' . $ctx->lang->line('gen_hamradio_band') . ''; + break; + case 'Frequency': + echo '' . $ctx->lang->line('gen_hamradio_frequency') . ''; + break; + case 'Operator': + echo '' . $ctx->lang->line('gen_hamradio_operator') . ''; + break; + case 'Name': + echo '' . $ctx->lang->line('general_word_name') . ''; + break; + case 'Flag': + echo ' '; + break; + } + } +} + +if (!function_exists('echo_table_col')) { + function echo_table_col($row, $name) + { + $ci = &get_instance(); + switch ($name) { + case 'Mode': + echo ''; + echo $row->COL_SUBMODE == null ? $row->COL_MODE : $row->COL_SUBMODE . ''; + break; + case 'RSTS': + echo '' . $row->COL_RST_SENT; + if ($row->COL_STX) { + echo ' COL_CONTEST_ID : "n/a") . '" class="badge text-bg-light">'; + printf("%03d", $row->COL_STX); + echo ''; + } + if ($row->COL_STX_STRING) { + echo ' COL_CONTEST_ID : "n/a") . '" class="badge text-bg-light">' . $row->COL_STX_STRING . ''; + } + echo ''; + break; + case 'RSTR': + echo '' . $row->COL_RST_RCVD; + if ($row->COL_SRX) { + echo ' COL_CONTEST_ID : "n/a") . '" class="badge text-bg-light">'; + printf("%03d", $row->COL_SRX); + echo ''; + } + if ($row->COL_SRX_STRING) { + echo ' COL_CONTEST_ID : "n/a") . '" class="badge text-bg-light">' . $row->COL_SRX_STRING . ''; + } + echo ''; + break; + case 'Country': + echo '' . ucwords(strtolower(($row->COL_COUNTRY))); + if ($row->end != NULL) echo ' ' . $ci->lang->line('gen_hamradio_deleted_dxcc') . '' . ''; + break; + case 'IOTA': + echo '' . ($row->COL_IOTA) . ''; + break; + case 'SOTA': + echo '' . ($row->COL_SOTA_REF) . ''; + break; + case 'WWFF': + echo '' . ($row->COL_WWFF_REF) . ''; + break; + case 'POTA': + echo '' . ($row->COL_POTA_REF) . ''; + break; + case 'Grid': + echo ''; + echoQrbCalcLink($row->station_gridsquare, $row->COL_VUCC_GRIDS, $row->COL_GRIDSQUARE); + echo ''; + break; + case 'Distance': + echo '' . ($row->COL_DISTANCE ? $row->COL_DISTANCE . ' km' : '') . ''; + break; + case 'Band': + echo ''; + if ($row->COL_SAT_NAME != null) { + echo '' . $row->COL_SAT_NAME . ''; + } else { + echo strtolower($row->COL_BAND); + } + echo ''; + break; + case 'Frequency': + echo ''; + if ($row->COL_SAT_NAME != null) { + echo '' . $row->COL_SAT_NAME . ''; + } else { + if ($row->COL_FREQ != null) { + echo $ci->frequency->hz_to_mhz($row->COL_FREQ); + } else { + echo strtolower($row->COL_BAND); + } + } + echo ''; + break; + case 'State': + echo '' . ($row->COL_STATE) . ''; + break; + case 'Operator': + echo '' . ($row->COL_OPERATOR) . ''; + break; + case 'Name': + echo '' . ($row->COL_NAME) . ''; + break; + case 'Flag': + $ci->load->library('DxccFlag'); + $flag = strtolower($ci->dxccflag->getISO($row->COL_DXCC)); + echo 'name))) . '">'; + break; + } + } +} + +if (!function_exists('echoQrbCalcLink')) { + function echoQrbCalcLink($mygrid, $grid, $vucc) + { + if (!empty($grid)) { + echo $grid . ' '; + } else if (!empty($vucc)) { + echo $vucc . ' '; + } + } +} \ No newline at end of file diff --git a/application/views/components/dashboard_logbook_table.php b/application/views/components/dashboard_logbook_table.php index 9dc5bff1a..e0cdbce01 100644 --- a/application/views/components/dashboard_logbook_table.php +++ b/application/views/components/dashboard_logbook_table.php @@ -1,161 +1,5 @@ ' . $ctx->lang->line('gen_hamradio_mode') . ''; - break; - case 'RSTS': - echo '' . $ctx->lang->line('gen_hamradio_rsts') . ''; - break; - case 'RSTR': - echo '' . $ctx->lang->line('gen_hamradio_rstr') . ''; - break; - case 'Country': - echo '' . $ctx->lang->line('general_word_country') . ''; - break; - case 'IOTA': - echo '' . $ctx->lang->line('gen_hamradio_iota') . ''; - break; - case 'SOTA': - echo '' . $ctx->lang->line('gen_hamradio_sota') . ''; - break; - case 'WWFF': - echo '' . $ctx->lang->line('gen_hamradio_wwff') . ''; - break; - case 'POTA': - echo '' . $ctx->lang->line('gen_hamradio_pota') . ''; - break; - case 'State': - echo '' . $ctx->lang->line('gen_hamradio_state') . ''; - break; - case 'Grid': - echo '' . $ctx->lang->line('gen_hamradio_gridsquare') . ''; - break; - case 'Distance': - echo '' . $ctx->lang->line('gen_hamradio_distance') . ''; - break; - case 'Band': - echo '' . $ctx->lang->line('gen_hamradio_band') . ''; - break; - case 'Frequency': - echo '' . $ctx->lang->line('gen_hamradio_frequency') . ''; - break; - case 'Operator': - echo '' . $ctx->lang->line('gen_hamradio_operator') . ''; - break; - case 'Name': - echo '' . $ctx->lang->line('general_word_name') . ''; - break; - case 'Flag': - echo ' '; - break; - } -} - -function echo_table_col($row, $name) -{ - $ci = &get_instance(); - switch ($name) { - case 'Mode': - echo ''; - echo $row->COL_SUBMODE == null ? $row->COL_MODE : $row->COL_SUBMODE . ''; - break; - case 'RSTS': - echo '' . $row->COL_RST_SENT; - if ($row->COL_STX) { - echo ' COL_CONTEST_ID : "n/a") . '" class="badge text-bg-light">'; - printf("%03d", $row->COL_STX); - echo ''; - } - if ($row->COL_STX_STRING) { - echo ' COL_CONTEST_ID : "n/a") . '" class="badge text-bg-light">' . $row->COL_STX_STRING . ''; - } - echo ''; - break; - case 'RSTR': - echo '' . $row->COL_RST_RCVD; - if ($row->COL_SRX) { - echo ' COL_CONTEST_ID : "n/a") . '" class="badge text-bg-light">'; - printf("%03d", $row->COL_SRX); - echo ''; - } - if ($row->COL_SRX_STRING) { - echo ' COL_CONTEST_ID : "n/a") . '" class="badge text-bg-light">' . $row->COL_SRX_STRING . ''; - } - echo ''; - break; - case 'Country': - echo '' . ucwords(strtolower(($row->COL_COUNTRY))); - if ($row->end != NULL) echo ' ' . $ci->lang->line('gen_hamradio_deleted_dxcc') . '' . ''; - break; - case 'IOTA': - echo '' . ($row->COL_IOTA) . ''; - break; - case 'SOTA': - echo '' . ($row->COL_SOTA_REF) . ''; - break; - case 'WWFF': - echo '' . ($row->COL_WWFF_REF) . ''; - break; - case 'POTA': - echo '' . ($row->COL_POTA_REF) . ''; - break; - case 'Grid': - echo ''; - echoQrbCalcLink($row->station_gridsquare, $row->COL_VUCC_GRIDS, $row->COL_GRIDSQUARE); - echo ''; - break; - case 'Distance': - echo '' . ($row->COL_DISTANCE ? $row->COL_DISTANCE . ' km' : '') . ''; - break; - case 'Band': - echo ''; - if ($row->COL_SAT_NAME != null) { - echo '' . $row->COL_SAT_NAME . ''; - } else { - echo strtolower($row->COL_BAND); - } - echo ''; - break; - case 'Frequency': - echo ''; - if ($row->COL_SAT_NAME != null) { - echo '' . $row->COL_SAT_NAME . ''; - } else { - if ($row->COL_FREQ != null) { - echo $ci->frequency->hz_to_mhz($row->COL_FREQ); - } else { - echo strtolower($row->COL_BAND); - } - } - echo ''; - break; - case 'State': - echo '' . ($row->COL_STATE) . ''; - break; - case 'Operator': - echo '' . ($row->COL_OPERATOR) . ''; - break; - case 'Name': - echo '' . ($row->COL_NAME) . ''; - break; - case 'Flag': - $ci->load->library('DxccFlag'); - $flag = strtolower($ci->dxccflag->getISO($row->COL_DXCC)); - echo 'name))) . '">'; - break; - } -} - -function echoQrbCalcLink($mygrid, $grid, $vucc) -{ - if (!empty($grid)) { - echo $grid . ' '; - } else if (!empty($vucc)) { - echo $vucc . ' '; - } -} +if (!defined('BASEPATH')) exit('No direct script access allowed'); ?>
    diff --git a/application/views/dashboard/index.php b/application/views/dashboard/index.php index 6b62c0a6c..d0848035c 100644 --- a/application/views/dashboard/index.php +++ b/application/views/dashboard/index.php @@ -1,162 +1,4 @@ -' . $ctx->lang->line('gen_hamradio_mode') . ''; - break; - case 'RSTS': - echo ''; - break; - case 'RSTR': - echo ''; - break; - case 'Country': - echo ''; - break; - case 'IOTA': - echo ''; - break; - case 'SOTA': - echo ''; - break; - case 'WWFF': - echo ''; - break; - case 'POTA': - echo ''; - break; - case 'State': - echo ''; - break; - case 'Grid': - echo ''; - break; - case 'Distance': - echo ''; - break; - case 'Band': - echo ''; - break; - case 'Frequency': - echo ''; - break; - case 'Operator': - echo ''; - break; - case 'Name': - echo ''; - break; - case 'Flag': - echo ''; - break; - } -} - -function echo_table_col($row, $name) -{ - $ci = &get_instance(); - switch ($name) { - case 'Mode': - echo ''; - break; - case 'RSTS': - echo ''; - break; - case 'RSTR': - echo ''; - break; - case 'Country': - echo ''; - break; - case 'IOTA': - echo ''; - break; - case 'SOTA': - echo ''; - break; - case 'WWFF': - echo ''; - break; - case 'POTA': - echo ''; - break; - case 'Grid': - echo ''; - break; - case 'Distance': - echo ''; - break; - case 'Band': - echo ''; - } else { - echo strtolower($row->COL_BAND); - } - echo ''; - break; - case 'Frequency': - echo ''; - } else { - if ($row->COL_FREQ != null) { - echo $ci->frequency->hz_to_mhz($row->COL_FREQ); - } else { - echo strtolower($row->COL_BAND); - } - } - echo ''; - break; - case 'State': - echo ''; - break; - case 'Operator': - echo ''; - break; - case 'Name': - echo ''; - break; - case 'Flag': - $ci->load->library('DxccFlag'); - $flag = strtolower($ci->dxccflag->getISO($row->COL_DXCC)); - echo ''; - break; - } -} - -function echoQrbCalcLink($mygrid, $grid, $vucc) -{ - if (!empty($grid)) { - echo $grid . ' '; - } else if (!empty($vucc)) { - echo $vucc . ' '; - } -} -?> +
    config->item('use_auth') && ($this->session->userdata('user_type') >= 2)) || $this->config->item('use_auth') === FALSE) { ?> @@ -185,7 +27,7 @@ function echoQrbCalcLink($mygrid, $grid, $vucc) optionslib->get_option('dashboard_banner') != "false") { ?> -
    +
    = 1) { ?>
    ' . $ctx->lang->line('gen_hamradio_rsts') . '' . $ctx->lang->line('gen_hamradio_rstr') . '' . $ctx->lang->line('general_word_country') . '' . $ctx->lang->line('gen_hamradio_iota') . '' . $ctx->lang->line('gen_hamradio_sota') . '' . $ctx->lang->line('gen_hamradio_wwff') . '' . $ctx->lang->line('gen_hamradio_pota') . '' . $ctx->lang->line('gen_hamradio_state') . '' . $ctx->lang->line('gen_hamradio_gridsquare') . '' . $ctx->lang->line('gen_hamradio_distance') . '' . $ctx->lang->line('gen_hamradio_band') . '' . $ctx->lang->line('gen_hamradio_frequency') . '' . $ctx->lang->line('gen_hamradio_operator') . '' . $ctx->lang->line('general_word_name') . ' '; - echo $row->COL_SUBMODE == null ? $row->COL_MODE : $row->COL_SUBMODE . '' . $row->COL_RST_SENT; - if ($row->COL_STX) { - echo ' COL_CONTEST_ID : "n/a") . '" class="badge text-bg-light">'; - printf("%03d", $row->COL_STX); - echo ''; - } - if ($row->COL_STX_STRING) { - echo ' COL_CONTEST_ID : "n/a") . '" class="badge text-bg-light">' . $row->COL_STX_STRING . ''; - } - echo '' . $row->COL_RST_RCVD; - if ($row->COL_SRX) { - echo ' COL_CONTEST_ID : "n/a") . '" class="badge text-bg-light">'; - printf("%03d", $row->COL_SRX); - echo ''; - } - if ($row->COL_SRX_STRING) { - echo ' COL_CONTEST_ID : "n/a") . '" class="badge text-bg-light">' . $row->COL_SRX_STRING . ''; - } - echo '' . ucwords(strtolower(($row->COL_COUNTRY))); - if ($row->end != NULL) echo ' ' . $ci->lang->line('gen_hamradio_deleted_dxcc') . '' . '' . ($row->COL_IOTA) . '' . ($row->COL_SOTA_REF) . '' . ($row->COL_WWFF_REF) . '' . ($row->COL_POTA_REF) . ''; - echoQrbCalcLink($row->station_gridsquare, $row->COL_VUCC_GRIDS, $row->COL_GRIDSQUARE); - echo '' . ($row->COL_DISTANCE ? $row->COL_DISTANCE . ' km' : '') . ''; - if ($row->COL_SAT_NAME != null) { - echo '' . $row->COL_SAT_NAME . ''; - if ($row->COL_SAT_NAME != null) { - echo '' . $row->COL_SAT_NAME . '' . ($row->COL_STATE) . '' . ($row->COL_OPERATOR) . '' . ($row->COL_NAME) . 'name))) . '">
    @@ -281,9 +159,14 @@ function echoQrbCalcLink($mygrid, $grid, $vucc)
    +
    - - +
    + +
    +
    @@ -307,9 +190,16 @@ function echoQrbCalcLink($mygrid, $grid, $vucc)
    +
    config->item('use_auth') && ($this->session->userdata('user_type') >= 2)) || $this->config->item('use_auth') === FALSE) && ($total_qsl_sent != 0 || $total_qsl_rcvd != 0 || $total_qsl_requested != 0)) { ?> +
    + +
    +
    @@ -334,11 +224,18 @@ function echoQrbCalcLink($mygrid, $grid, $vucc)
    +
    config->item('use_auth') && ($this->session->userdata('user_type') >= 2)) || $this->config->item('use_auth') === FALSE) && ($total_eqsl_sent != 0 || $total_eqsl_rcvd != 0)) { ?> +
    + +
    +
    @@ -357,11 +254,18 @@ function echoQrbCalcLink($mygrid, $grid, $vucc)
    +
    config->item('use_auth') && ($this->session->userdata('user_type') >= 2)) || $this->config->item('use_auth') === false) && ($total_lotw_sent != 0 || $total_lotw_rcvd != 0)) { ?> +
    + +
    +
    @@ -380,10 +284,17 @@ function echoQrbCalcLink($mygrid, $grid, $vucc)
    +
    config->item('use_auth') && ($this->session->userdata('user_type') >= 2)) || $this->config->item('use_auth') === false) && ($total_qrz_sent != 0 || $total_qrz_rcvd != 0)) { ?> +
    + +
    +
    @@ -402,10 +313,17 @@ function echoQrbCalcLink($mygrid, $grid, $vucc)
    QRZ.com
    +
    config->item('use_auth') && ($this->session->userdata('user_type') >= 2)) || $this->config->item('use_auth') === FALSE)) { ?> +
    + +
    +
    @@ -425,10 +343,57 @@ function echoQrbCalcLink($mygrid, $grid, $vucc)
    VUCC-Grids
    +
    - \ No newline at end of file + + + + + From 1aff7dcf501fc4c83e4afe8e1498542b3fadc7c8 Mon Sep 17 00:00:00 2001 From: Peter Goodhall Date: Thu, 7 May 2026 22:19:02 +0100 Subject: [PATCH 15/48] Make logbook header and table responsive Add responsive styles and restructure header markup for better mobile layout (flex column on small, row on md+; full-width diary button on small). Update echo_table_header_col() and echo_table_col() to accept an optional CSS class and apply it to th/td elements. Apply Bootstrap responsive utility classes (d-none d-sm-/d-md-/d-lg-table-cell) to hide less-important columns on smaller screens and adjust time column visibility. These changes improve readability on narrow viewports while preserving existing tooltips and badges. --- application/views/view_log/index.php | 22 +++- .../views/view_log/partial/log_ajax.php | 114 +++++++++--------- 2 files changed, 76 insertions(+), 60 deletions(-) diff --git a/application/views/view_log/index.php b/application/views/view_log/index.php index caadb8642..e156a0121 100644 --- a/application/views/view_log/index.php +++ b/application/views/view_log/index.php @@ -104,17 +104,31 @@ color: #0d6efd; text-decoration: underline; } + +@media (max-width: 767.98px) { + .logbook-info-bar .logbook-diary-action .btn { + width: 100%; + } +} + +@media (min-width: 768px) { + .logbook-info-bar .logbook-diary-action { + width: auto !important; + } +}