feat: add automatic cache-busting for all static assets

Implement SystemURLs::assetVersioned() method to append file modification
timestamps to asset URLs, forcing browser cache refresh after deployments
without requiring manual hard refreshes.

Changes:
- Add assetVersioned() static method to SystemURLs DTO class
- Uses PHP filemtime() to generate ?v=<timestamp> query parameters
- Update all 70+ asset references across templates to use new method
- Covers CSS, JavaScript, and external library references

Files Modified (38 total):
- Core includes: Header/Footer scripts and utilities
- Admin dashboard and system views
- User-facing pages: Person, Family, Event, Calendar views
- External templates: Registration, Verification, Calendar
- Finance and Sunday school modules
- Kiosk and checkout workflows

Result: All static asset URLs now include automatic cache-busting
Parameters. When files are updated (CSS/JS changes), the timestamp
changes automatically, creating unique URLs that force browser cache
refresh. When files are unchanged, the same URL is served from cache.

Author: DawoudIO

src/CSVImport.php

@@ -957,7 +957,7 @@ function GetAge(int $Month, int $Day, ?int $Year): int
     });
   });
 </script>
-<script src="<?= SystemURLs::getRootPath() ?>/skin/js/DropdownManager.js"></script>
-<script src="<?= SystemURLs::getRootPath() ?>/skin/js/MemberView.js" ></script>
+<script src="<?= SystemURLs::assetVersioned('/skin/js/DropdownManager.js') ?>"></script>
+<script src="<?= SystemURLs::assetVersioned('/skin/js/MemberView.js') ?>"></script>
 <?php
 require_once 'Include/Footer.php';

src/CartToEvent.php

@@ -171,7 +171,7 @@
     <?php
 }
 
-<script src="<?= SystemURLs::getRootPath() ?>/skin/js/cart-photo-viewer.js"></script>
+<script src="<?= SystemURLs::assetVersioned('/skin/js/cart-photo-viewer.js') ?>"></script>
 
 <?php
 require_once 'Include/Footer.php';

src/CartToFamily.php

@@ -314,9 +314,9 @@
 ?>
 </div>
 
-<script src="<?= SystemURLs::getRootPath() ?>/skin/js/DropdownManager.js"></script>
-<script src="<?= SystemURLs::getRootPath() ?>/skin/js/CartToFamily.js"></script>
-<script src="<?= SystemURLs::getRootPath() ?>/skin/js/cart-photo-viewer.js"></script>
+<script src="<?= SystemURLs::assetVersioned('/skin/js/DropdownManager.js') ?>"></script>
+<script src="<?= SystemURLs::assetVersioned('/skin/js/CartToFamily.js') ?>"></script>
+<script src="<?= SystemURLs::assetVersioned('/skin/js/cart-photo-viewer.js') ?>"></script>
 
 <?php
 require_once 'Include/Footer.php';

src/Checkin.php

@@ -477,8 +477,8 @@ function filterByType(typeId) {
     window.location.href = 'Checkin.php?EventTypeID=' + typeId;
 }
 </script>
-<script src="<?= SystemURLs::getRootPath() ?>/skin/js/cart-photo-viewer.js"></script>
-<script nonce="<?= SystemURLs::getCSPNonce() ?>" src="<?= SystemURLs::getRootPath() ?>/skin/js/checkin.js"></script>
+<script src="<?= SystemURLs::assetVersioned('/skin/js/cart-photo-viewer.js') ?>"></script>
+<script nonce="<?= SystemURLs::getCSPNonce() ?>" src="<?= SystemURLs::assetVersioned('/skin/js/checkin.js') ?>"></script>
 
 <?php require_once 'Include/Footer.php';
 

src/ChurchCRM/dto/SystemURLs.php

@@ -123,4 +123,22 @@ public static function getCSPNonce(): ?string
     {
         return self::$CSPNonce;
     }
+
+    /**
+     * Get versioned asset URL with file modification time for cache-busting.
+     * Appends ?v=<filemtime> to asset URLs to force browser cache refresh after deploys.
+     *
+     * @param string $webPath Asset path relative to document root (e.g., '/skin/v2/churchcrm.min.css')
+     * @return string Versioned URL with modification time, or original URL if file doesn't exist
+     */
+    public static function assetVersioned(string $webPath): string
+    {
+        $rootUrl = self::getRootPath();
+        $docRoot = self::getDocumentRoot();
+        $fullPath = rtrim($docRoot, DIRECTORY_SEPARATOR) . $webPath;
+        if (file_exists($fullPath)) {
+            return $rootUrl . $webPath . '?v=' . filemtime($fullPath);
+        }
+        return $rootUrl . $webPath;
+    }
 }

src/DepositSlipEditor.php

@@ -279,7 +279,7 @@ class="btn btn-outline-primary <?= $nextDeposit ? '' : 'disabled'; ?>"
   </div>
 </div>
 
-<script src="<?= SystemURLs::getRootPath() ?>/skin/js/DepositSlipEditor.js"></script>
+<script src="<?= SystemURLs::assetVersioned('/skin/js/DepositSlipEditor.js') ?>"></script>
 <style>
 .card {
     margin-bottom: 1.5rem;

src/FamilyEditor.php

@@ -1035,7 +1035,7 @@
     };
 </script>
 <?php } ?>
-<script src="<?= SystemURLs::getRootPath() ?>/skin/js/DropdownManager.js"></script>
-<script src="<?= SystemURLs::getRootPath() ?>/skin/js/FamilyEditor.js"></script>
+<script src="<?= SystemURLs::assetVersioned('/skin/js/DropdownManager.js') ?>"></script>
+<script src="<?= SystemURLs::assetVersioned('/skin/js/FamilyEditor.js') ?>"></script>
 <?php
 require_once 'Include/Footer.php';

src/FindDepositSlip.php

@@ -75,6 +75,6 @@
   </div>
 </div>
 
-<script src="<?= SystemURLs::getRootPath() ?>/skin/js/FindDepositSlip.js"></script>
+<script src="<?= SystemURLs::assetVersioned('/skin/js/FindDepositSlip.js') ?>"></script>
 <?php
 require_once 'Include/Footer.php';

src/GeoPage.php

@@ -413,6 +413,6 @@ class="control-label col-xs-12 col-sm-3 col-md-3 col-lg-3"><?= gettext('Coordina
 <script nonce="<?= SystemURLs::getCSPNonce() ?>">
     var listPeople = <?= json_encode($aPersonIDs) ?>;
 </script>
-<script src="<?= SystemURLs::getRootPath() ?>/skin/js/GeoPage.js"></script>
+<script src="<?= SystemURLs::assetVersioned('/skin/js/GeoPage.js') ?>"></script>
 <?php
 require_once 'Include/Footer.php';

src/GetText.php

@@ -24,7 +24,7 @@
 <head>
   <meta charset="UTF-8">
   <title><?= InputUtils::escapeHTML($aEventTitle) ?></title>
-  <link rel="stylesheet" href="<?= SystemURLs::getRootPath() ?>/skin/v2/churchcrm.min.css">
+  <link rel="stylesheet" href="<?= SystemURLs::assetVersioned('/skin/v2/churchcrm.min.css') ?>">
 </head>
 <body>
 <div class="container-fluid p-4">