# Website Analytics

Self-hosted PHP/MySQL website analytics for shared hosting and WHM/cPanel environments.

## Stage 1 Status

Stage 1 creates the project structure, configuration, database schema, installer, secure administrator authentication, profile/password changes, and website management.

Later stages will add tracking collection, reporting, live visitors, journey visualisation, exports, cron processing, health checks, and final testing.

## Proposed Project Structure

```text
/
├── admin/
├── api/
├── assets/
│   ├── css/
│   ├── js/
│   └── images/
├── config/
│   └── config.php
├── cron/
├── database/
│   └── install.sql
├── includes/
│   ├── auth.php
│   ├── bootstrap.php
│   ├── csrf.php
│   ├── database.php
│   ├── helpers.php
│   ├── response.php
│   └── validation.php
├── install/
├── logs/
├── storage/
├── templates/
├── index.php
└── .htaccess
```

## Proposed Database Schema

The schema is included in `database/install.sql`. It creates:

- `users`, `password_resets`, `login_attempts`
- `websites`, `website_domains`, `website_settings`, `website_exclusions`
- `visitors`, `sessions`, `pages`, `page_views`, `events`, `page_transitions`
- `campaigns`, `conversion_definitions`, `conversions`
- `live_activity`, `daily_aggregates`, `hourly_aggregates`
- `rate_limits`, `tracking_errors`, `audit_logs`, `system_settings`, `data_deletion_jobs`

All analytics tables include `website_id` so reports and tracking data can remain isolated per website. Public tracking identifiers are random strings, not database IDs. High-volume tables are indexed by website and time.

## Server Requirements

- PHP 8.2 or newer
- MySQL 8 or MariaDB
- PHP extensions: `mysqli`, `json`, `session`, `openssl`
- Apache-compatible `.htaccess` support is recommended

## Installation

1. Upload the files to your hosting account.
2. Create a MySQL database and database user.
3. Edit `config/config.php` with your application URL and database credentials.
4. Visit `/install/`.
5. Create the first administrator account.

The installer creates the database tables and writes `storage/installed.lock`. To run the installer again, remove that lock file manually.

You can also import `database/install.sql` manually through phpMyAdmin or the MySQL command line, then create a super administrator through the installer.

## Website Setup

Open `Websites`, add a website, define its allowed domains, and copy the generated tracking code from the website detail page.

Do not install a tracking snippet that points to `localhost`, `127.0.0.1`, a private LAN IP address, or a `.local` hostname on a public website. On a visitor's browser, `localhost` means the visitor's own device, not your XAMPP machine, and browsers can show local device or network permission prompts. For production tracking, host this analytics app on a public HTTPS domain and set `app_url` in `config/config.php` to that public URL.

Tracking collection is scheduled for Stage 2, so the Stage 1 tracking code is prepared for installation but will not record data until the collector and `tracker.js` are added.

## Stage 2 Tracking

Stage 2 adds the root `tracker.js` file and `api/collect.php` endpoint. The tracker records page views, page exits, custom events, outbound links, downloads, scroll depth, and single-page application history changes.

The collector validates the public site ID, checks the request origin against allowed domains, respects Do Not Track when enabled for a website, filters obvious bots, rate-limits requests by website and IP range, logs rejected or duplicate events, normalises URLs according to website settings, creates sessions and visitors, and updates live activity.

Use the `Test tracking` button on a website detail page to check the local installation. A developer test page is available at `dev/test-tracker.php` only when `debug` is enabled.

## Stage 3 Reports

Stage 3 adds date-range filtering, richer dashboard metrics, page-view trend charts, traffic-channel summaries, referrer reports, device/browser/operating-system reports, and page detail reports.

The main website selector in the header applies to dashboard and report pages. Date range presets include today, yesterday, last 7 days, last 30 days, this month, last month, this year, and custom ranges.

Country reporting is available when the server or CDN provides a country header, such as Cloudflare's `CF-IPCountry`. This stores the two-letter country code on each session without sending visitor IP addresses to an external lookup service.

For local GeoIP lookup, download the MaxMind GeoLite2 Country database in MMDB format from your MaxMind account and upload it to:

```text
storage/geoip/GeoLite2-Country.mmdb
```

The `storage` folder blocks web access with `.htaccess`, so the database is used by PHP but is not publicly downloadable. System Health shows whether the local GeoIP database was found and its build date. GeoLite2 databases should be kept up to date according to MaxMind's licence terms.

The app supports three GeoIP sources, in this order:

- Server/CDN country headers, such as `CF-IPCountry`
- MaxMind GeoLite2 Country MMDB, preferably read through Composer's `geoip2/geoip2` package when `vendor/autoload.php` is present
- MaxMind GeoLite2 Country CSV ranges imported into MySQL

To use the Composer GeoIP2 reader, upload Composer files to the app root:

```text
/vendor/
/composer.json
/composer.lock
```

Do not upload Composer's example `index.php` over the app's root `index.php`; this app already has its own `index.php`.

For manual CSV import, upload the extracted MaxMind GeoLite2 Country CSV files to:

```text
storage/geoip/GeoLite2-Country-Locations-en.csv
storage/geoip/GeoLite2-Country-Blocks-IPv4.csv
storage/geoip/GeoLite2-Country-Blocks-IPv6.csv
```

For city-level reporting, upload the GeoLite2 City CSV files instead. When City CSV files are present, they are preferred over Country CSV files:

```text
storage/geoip/GeoLite2-City-Locations-en.csv
storage/geoip/GeoLite2-City-Blocks-IPv4.csv
storage/geoip/GeoLite2-City-Blocks-IPv6.csv
```

Then run:

```text
/usr/local/bin/php /home/USERNAME/public_html/cron/import_geoip_csv.php
```

You can also run the same import from `System Health` by clicking `Import GeoIP CSV`. The admin import is useful after uploading fresh CSV files manually; the cron script is better for scheduled imports.

Run `database/updates/2026_06_10_geoip_country_ranges.sql` once on existing installations before using CSV import. Run `database/updates/2026_06_10_geoip_city.sql` once before using city-level reporting. New installs already include the required columns.

### Automatic GeoLite2 Updates

MaxMind recommends `geoipupdate` for automatically updating binary GeoIP and GeoLite databases. Download the current release from:

```text
https://github.com/maxmind/geoipupdate/releases
```

Create a private `GeoIP.conf` file from `storage/geoip/GeoIP.conf.example`, fill in your MaxMind account ID and licence key, and set `DatabaseDirectory` to the absolute path of this app's `storage/geoip` folder.

Example `GeoIP.conf` values:

```text
AccountID YOUR_MAXMIND_ACCOUNT_ID
LicenseKey YOUR_MAXMIND_LICENSE_KEY
EditionIDs GeoLite2-Country
DatabaseDirectory /home/USERNAME/public_html/storage/geoip
PreserveFileTimes 1
```

Example cPanel cron command:

```text
/usr/local/bin/geoipupdate -f /home/USERNAME/public_html/storage/geoip/GeoIP.conf -d /home/USERNAME/public_html/storage/geoip
```

Running this once or twice per week is enough for most sites and stays well under MaxMind's download limits. MaxMind notes that `geoipupdate` needs outbound DNS and HTTPS access, including access to the redirected database download host.

## Stage 4 Live Visitors and Journeys

Stage 4 adds an auto-refreshing Live Visitors screen, a JSON live visitor API, individual session journey pages, chronological page/event timelines, a simple visual path view, and aggregate visitor-flow reports.

The Visitor Journeys report calculates common transitions from page-view order for the selected website and date range. It also includes a previous/current/next table for flow analysis.

## Stage 5 Conversions, Exports, and Maintenance

Stage 5 begins with conversion goals, exports, scheduled maintenance, and system visibility. Supported conversion goal detection currently includes page-visited goals and event-name goals such as custom events, outbound links, downloads, and revenue events.

Exports are available in CSV and JSON for sessions, page views, pages, events, conversions, and visitor journeys. Exports use the selected website and chosen date range.

The System Health page shows active websites, live visitors, current-day collection volume, tracking errors, database size, cron status, aggregate rows, and retention settings. Tracking Errors and Audit Log pages provide filtered operational history.

### Cron Jobs

Set these commands in cPanel Cron Jobs or the hosting control panel equivalent. Replace `/home/USERNAME/public_html` with the real path to the analytics app on the server, and use the PHP binary path shown by the host if it differs.

```text
/usr/local/bin/php /home/USERNAME/public_html/cron/close_inactive_sessions.php
/usr/local/bin/php /home/USERNAME/public_html/cron/build_hourly_aggregates.php
/usr/local/bin/php /home/USERNAME/public_html/cron/build_daily_aggregates.php
/usr/local/bin/php /home/USERNAME/public_html/cron/cleanup_old_data.php
/usr/local/bin/php /home/USERNAME/public_html/cron/remove_expired_tokens.php
/usr/local/bin/php /home/USERNAME/public_html/cron/import_geoip_csv.php
```

Suggested schedule:

- Every 5 minutes: `close_inactive_sessions.php`
- Every 15 minutes: `build_hourly_aggregates.php`
- Once per hour: `build_daily_aggregates.php`
- Once per day: `cleanup_old_data.php`
- Once per day: `remove_expired_tokens.php`
- After uploading new MaxMind CSV files: `import_geoip_csv.php`

## Security Notes

- Passwords use `password_hash()`.
- Administrator sessions use HTTP-only cookies and regenerate after login.
- Forms and state-changing requests use CSRF tokens.
- Login attempts are rate-limited by email and IP address.
- Password reset tokens are stored hashed, expire after one hour, and can be used once.
- Config, logs, storage, includes, database, and cron folders include `.htaccess` denial files.

## Privacy Notes

Stage 1 website settings include IP anonymisation, consent-required mode, Do Not Track handling, bot filtering, retention days, excluded IPs, excluded URL patterns, and query-string handling. Consent integration instructions and live tracking privacy details will be expanded as the tracking script is built.

## Stage 1 Test

1. Edit `config/config.php`.
2. Open `/install/`.
3. Confirm all server checks pass.
4. Create the first administrator.
5. Log in.
6. Add a website with at least one allowed domain.
7. Copy the generated tracking code.
8. Edit, disable, activate, archive, and delete a test website.
9. Change the administrator profile name and password.