Jumlah paparan halaman: {{ number_format($visitorStats['total']) }}
{{ number_format($todayVisits ?? 0) }} lawatan hari ini · {{ number_format($uniqueVisitors ?? 0) }} pelawat unik
``` ### 10.3 Nota: template lama yang menggunakan `Visit` Kod `Visit` telah dibuang sepenuhnya daripada codebase. Jika anda menyalin template lama (atau restore backup) yang masih mengandungi: ```blade @php $todayVisits = \App\Models\Backend\Visit::todayVisits(); $thisWeek = \App\Models\Backend\Visit::thisWeekVisits(); $thisMonth = \App\Models\Backend\Visit::thisMonthVisits(); $thisYear = \App\Models\Backend\Visit::thisYearVisits(); $totalVisits = \App\Models\Backend\Visit::totalVisits(); @endphp ``` ...buang blok tersebut dan gunakan variabel baru seperti dalam §10.2 (`$todayVisits`, `$thisWeekVisits`, `$thisMonthVisits`, `$thisYearVisits`, `$uniqueVisitors`, `$totalVisits`). Kod `Visit` tidak lagi wujud. Contoh gantian: ```blade{{ number_format($onlineNow) }} pelawat aktif (5 minit terakhir)
``` Ini bukan "live session" sebenar — hanya aktiviti page view yang direkod. ### 10.7 Papar bilangan paparan untuk page semasa (optional) ```php $siteKey = $siteId ? 'site:'.$siteId : $siteSlug; // Untuk page biasa: path ternormal tanpa prefix site dan tanpa query $path = '/'.ltrim(request()->path(), '/'); if ($siteSlug && $path === '/'.$siteSlug) { $path = '/'; } elseif ($siteSlug && str_starts_with($path, '/'.$siteSlug.'/')) { $path = substr($path, strlen('/'.$siteSlug)); } // Untuk halaman artikel article-web if (request()->routeIs('frontend-site.page', 'frontend-site.home') && request()->segment(count(request()->segments())) === 'article-web' && request()->filled('id')) { $path = '/article-web/'.rawurlencode((string) request()->query('id')); } $pageViews = \App\Models\Backend\VisitorPageView::query() ->where('site_key', $siteKey) ->where('page_path', $path) ->count(); ``` > Path mesti **sama** dengan normalisasi tracker (lihat §6). Jika tidak, kiraan akan 0. ### 10.8 Guna dalam controller / service / command (PHP) ```php use App\Models\Backend\VisitorDailyCounter; use App\Models\Backend\VisitorPageView; VisitorPageView::todayViews(); VisitorPageView::thisWeekViews(); // mula Isnin VisitorPageView::thisMonthViews(); VisitorPageView::thisYearViews(); VisitorPageView::totalViews(); VisitorPageView::allTimeUniqueVisitors(); VisitorPageView::pageViewsSince(now()->subDays(30)); VisitorPageView::uniqueVisitorsSince(now()->subDays(30)); VisitorDailyCounter::query() ->betweenDates($from, $to) // scope sedia ada ->where('site_key', 'site:1') ->count(); ``` Semua helper ini membuat query agregat (COUNT/DISTINCT) — jangan panggil berulang dalam loop. ### 10.9 Prestasi & caching | Perkara | Cadangan | |---|---| | Query per page render | `PortalHandler` sudah buat 6 query agregat; jika trafik tinggi, cache blok statistik 60 saat | | Cache key | Sertakan `site_key` + tarikh + (jika perlu) jam/minit | | TTL | 30–60 saat untuk counter awam; laporan admin tidak perlu cache | | Index DB | Sudah disediakan; jangan buang index `viewed_at`, `site_key`, `visitor_hash` | | Saiz data | Jalankan `visitor:prune` setiap hari (retensi default 365 hari) | | Trafik tinggi | Pertimbangkan cache/CDN untuk HTML **atau** analytics luaran (GA4/Matomo) | Contoh cache ringkas untuk blok statistik: ```php $stats = \Illuminate\Support\Facades\Cache::remember( 'visitor:summary:'.$siteKey.':'.now()->format('YmdHi'), now()->addMinute(), fn () => [/* query di sini */] ); ``` ### 10.10 Bila tracking OFF atau data kosong | Keadaan | Kesannya | |---|---| | Daily counter OFF | `visitor_daily_counters` tidak bertambah; metrik "Daily visits" kekal pada data lama | | Page-view OFF | `visitor_page_views` tidak bertambah; trend, top pages & laporan paparan halaman kosong | | Kedua-dua OFF | Tiada rekod baru; cookie tidak diset | | Baris `visitor_settings` tiada | Middleware anggap OFF; admin `firstOrFail` gagal | | Selepas "Clear data" | Semua counter kembali 0 | | Template footer legacy | Masih merujuk `Visit`/jadual `visits` yang telah dibuang → error/0 | Guna variabel PortalHandler (§10.2) | Sentiasa gunakan fallback `?? 0` supaya paparan tidak error bila variabel tiada. ## 11. Konfigurasi & operasi ### 11.1 Environment Fail: `config/visitor.php` ```php return [ 'cookie_days' => max(1, (int) env('VISITOR_COOKIE_DAYS', 365)), 'retention_days' => max(1, (int) env('VISITOR_RETENTION_DAYS', 365)), ]; ``` | Env | Default | Maksud | |---|---|---| | `VISITOR_COOKIE_DAYS` | 365 | Umur cookie `cms_visitor_id` | | `VISITOR_RETENTION_DAYS` | 365 | Tempoh simpan page view & daily counter sebelum dipangkas | Selepas ubah `.env`, jalankan: ```bash php artisan config:clear ``` ### 11.2 Pemasangan / deploy ```bash php artisan migrate ``` Yang berlaku: 1. `visitor_settings` dicipta + baris default (`is_active = true`). 2. Migration `2026_10_20_000000_consolidate_visitor_analytics_schema` mencipta schema semasa: - `visitor_page_views` (jika belum wujud); - kolum `is_page_view_active` (jika belum wujud); - `visitor_daily_counters` (jika belum wujud). Semak baris setting: ```bash php artisan tinker --execute="echo App\\Models\\Backend\\VisitorSetting::query()->count();" ``` Jika `0`, cipta baris: ```php \App\Models\Backend\VisitorSetting::query()->firstOrCreate( [], ['is_active' => true, 'is_page_view_active' => true] ); ``` Selepas deploy kod baru: ```bash php artisan optimize:clear # atau config:clear + view:clear ``` ### 11.3 Pembersihan data (retention) Command: ```bash php artisan visitor:prune ``` - Padam `visitor_page_views` dengan `viewed_at < now() - retention_days`. - Padam `visitor_daily_counters` dengan `visited_on < tarikh cutoff`. - Dijadualkan **harian** dalam `routes/console.php`. Produksi: pastikan scheduler Laravel berjalan (cron `php artisan schedule:run` setiap minit). Local (Windows/Laragon): jalankan `php artisan schedule:work` dalam terminal. ### 11.4 Clear data (manual) Admin: butang **Clear data** (SweetAlert confirmation) → `POST /visitor/clear`. Atau melalui command/tinker: ```php DB::transaction(function () { \App\Models\Backend\VisitorPageView::query()->delete(); \App\Models\Backend\VisitorDailyCounter::query()->delete(); }); ``` Tindakan ini tidak boleh diundur. ### 11.5 `APP_KEY` Jangan tukar `APP_KEY` tanpa sebab. Jika ditukar: - Semua `visitor_hash` baru berbeza. - Pelawat sedia ada dikira sebagai pelawat baharu. - Data lama kekal tetapi tidak lagi sepadan dengan cookie semasa. ### 11.6 Backup Sebelum `migrate` yang mengubah schema dan sebelum **Clear data**, buat backup DB. --- ## 12. Testing Jalankan ujian visitor: ```bash php artisan test --filter=Visitor ``` Fail ujian: | Fail | Liputan | |---|---| | `tests/Feature/VisitorAnalyticsTest.php` | Perekodan page view, dedup 30 minit, cookie HttpOnly, article path, site key stabil, toggle berasingan, filter laporan, sanitasi legacy | | `tests/Feature/VisitorMonthlyReportTest.php` | Kiraan KPI laporan bulanan, MoM, series 12 bulan, peak day/hour, site filter, render UI, CSV & PDF | Contoh ujian pantas (manual) selepas tracking ON: ```bash # 1. Lawat page awam dalam incognito curl -I http://127.0.0.1:8000/ # 2. Semak rekod php artisan tinker --execute="echo App\\Models\\Backend\\VisitorPageView::query()->count();" php artisan tinker --execute="echo App\\Models\\Backend\\VisitorDailyCounter::query()->count();" ``` Nota: `curl` tanpa cookie akan dianggap pelawat baharu setiap kali (cookie tidak disimpan) — untuk ujian dedup, gunakan browser atau `curl -c cookies.txt -b cookies.txt`. --- ## 13. Troubleshooting | Masalah | Punca biasa | Penyelesaian | |---|---|---| | Tiada rekod langsung | Kedua-dua toggle OFF | Hidupkan di admin / `visitor_settings` | | Tiada rekod langsung | Route bukan `home` / `frontend-site.home` / `frontend-site.page` | Pastikan page diakses melalui route CMS | | Tiada rekod langsung | Response bukan `200` / bukan `text/html` | Uji URL yang betul; redirect/404 tidak dikira | | Tiada rekod langsung | Baris `visitor_settings` tiada | `firstOrCreate` baris setting (§11.2) | | Tiada rekod langsung | HTML di-cache sepenuhnya oleh CDN/proxy | Laravel tidak menerima request → tiada rekod | | Daily counter bertambah, page view tidak | `is_page_view_active = false` | Hidupkan Page-view analytics | | Page view bertambah, daily counter tidak | `is_active = false` | Hidupkan Daily visitor counter | | Admin page 404/500 | Baris setting tiada (`firstOrFail`) atau tiada permission | Cipta baris setting; semak `visitor.view` | | Admin tunjuk 0 tetapi DB ada data | Filter tarikh/site tidak sepadan | Set semula filter; semak timezone aplikasi | | Laporan bulanan kosong | Bulan/tahun/site salah | Pilih semula Month/Year; kosongkan site | | CSV/PDF 403 | Tiada `visitor.view` | Beri permission kepada role | | PDF gagal dijana | Dompdf tiada/extension PHP | Pastikan `dompdf/dompdf` dipasang & `ext-dom` aktif | | Footer tunjuk angka lama/tak bertambah | Template custom lama masih merujuk `Visit`/jadual `visits` | Guna variabel PortalHandler (§10.2); jadual `visits` telah dibuang | | Footer 0 | Variabel tiada / tracking OFF / cache | Guna `?? 0`, semak toggle, kosongkan cache | | Angka pelawat melonjak selepas deploy | `APP_KEY` ditukar / cookie baru | Dijangka; maklumkan dalam laporan | | `visitor:prune` tidak jalan | Scheduler tidak aktif | Pasang cron `schedule:run` / `schedule:work` | | Page lambat | Query stats setiap render | Cache blok statistik 30–60 saat | --- ## 14. Checklist go-live - [ ] `php artisan migrate` berjaya (2 migration visitor: settings + schema konsolidasi). - [ ] Baris `visitor_settings` wujud. - [ ] Daily counter & page-view dihidupkan mengikut keperluan. - [ ] Notis privasi / dasar cookie dikemas kini. - [ ] Footer/komponen menggunakan variabel **baru** (bukan `Visit::...`). - [ ] Ujian incognito: layari 3 halaman → semak `visitor_page_views` & `visitor_daily_counters`. - [ ] Admin `/visitor` memaparkan angka & laporan. - [ ] Export CSV & PDF berjaya dimuat turun. - [ ] Scheduler `visitor:prune` aktif. - [ ] Permission `visitor.view/update/delete` diberikan kepada role berkaitan. - [ ] Backup DB & polisi retensi disahkan. --- ## 15. Perubahan terkini & dokumen berkaitan ### Ciri terbaru dalam versi ini 1. **Daily visitor counter berasingan** daripada page-view analytics. 2. **Site key stabil `site:{id}`** + migration normalisasi data lama. 3. **UI admin baru**: 3 tab (Daily visitors / Page-view / Monthly report), date picker gaya Content Article, quick ranges, dark mode; 4 kad tempoh (Today / This week / This month / This year) dalam satu baris dengan julat tarikh dinamik. 4. **Bar chart "Visits by day"** yang mengikut filter (hari/minggu/bulan/tahun/custom). 5. **Laporan bulanan gaya kerajaan**: 6 KPI, MoM, peak day/hour, jadual Jan–Dis, top pages, metodologi. 6. **Export CSV & PDF** laporan bulanan (Dompdf). 7. **Ujian regresi**: `VisitorAnalyticsTest` + `VisitorMonthlyReportTest`. 8. **Jadual `visits`, model `Visit` dan trait `HasVisits`/`Visitable` dibuang**; footer & widget dashboard dipindahkan ke `VisitorPageView`/variabel PortalHandler. ### Dokumen berkaitan | Dokumen | Kandungan | |---|---| | [`VISITOR-COUNTER.md`](./VISITOR-COUNTER.md) | Nota ringkas implementasi (English) | | [`module/frontend-site.md`](./module/frontend-site.md) | Render engine, component & variabel frontend | | [`CMS-BUILDER-GUIDE.md`](./CMS-BUILDER-GUIDE.md) | Panduan CMS Builder & component | | [`module/purge-cache.md`](./module/purge-cache.md) | Cache & mirror `storage/app/private` | | [`module/visitor.md`](./module/visitor.md) | Nota lama modul visitor (rujukan sejarah) |