# Installer, Updater, And Tracking Plan

This plan captures the intended release mechanics for PHPLD Next.

## Distribution Model

The source repository can remain private while public users download release packages.

Recommended pieces:

- Private GitHub repo: development source.
- Public update manifest: version metadata, release notes, compatibility, package URL, checksum.
- Public release ZIP: runnable application package with production dependencies and built assets.
- Update service endpoint: receives install/update telemetry and serves version information.

## Release Package Contents

Include:

- Application source needed to run.
- `vendor/` production dependencies.
- Built frontend assets.
- Installer.
- `public/` web entrypoint.
- Version metadata.
- Installation docs.

Exclude:

- `.git/`
- `node_modules/`
- Tests and local tooling unless required.
- Development-only docs.
- `.env`
- Any API keys or secrets.

## Web Installer Flow

1. Welcome and requirement checks.
2. Database credentials.
3. Database connection test.
4. Migration and seed.
5. Admin account creation.
6. Site basics: name, URL, logo, primary color.
7. Optional telemetry disclosure and setting.
8. Installation lock.
9. Redirect to admin login.

## Update Manifest Draft

Example:

```json
{
  "product": "phpld-next",
  "latest": "1.0.1",
  "minimum_php": "8.2.0",
  "released_at": "2026-05-22T00:00:00Z",
  "package_url": "https://www.phplinkdirectory.com/releases/phpld-next-1.0.1.zip",
  "sha256": "example-checksum",
  "release_notes_url": "https://www.phplinkdirectory.com/releases/phpld-next-1.0.1.html",
  "requires_manual_review": false
}
```

## Updater Flow

1. Admin opens Updates.
2. App sends version check with anonymous install ID and current version.
3. App displays available version and release notes.
4. Admin starts update.
5. App creates file/database backup.
6. App downloads package.
7. App verifies checksum.
8. App enters maintenance mode.
9. App swaps files while preserving `.env`, storage, uploads, and install ID.
10. App runs migrations.
11. App clears and rebuilds caches.
12. App exits maintenance mode.
13. App reports success or failure.

## Test Site Release Loop

Use this loop before public releases:

1. Build a release ZIP and manifest from `main`.
2. Install the ZIP on a clean cPanel account or addon domain.
3. Complete `/install` using a fresh database.
4. Confirm admin login, public homepage, category browsing, submissions, media upload, and settings.
5. Publish a newer release ZIP and manifest.
6. On the test site, open Admin > Updates, download the package, and apply it.
7. Confirm version changed, migrations ran, `.env` and uploaded media survived, and the admin can still log in.
8. Repeat on at least three sites with different settings/themes before declaring the release dependable.

For early test beds on the same server, keep each site isolated with its own cPanel user or at least its own database, storage folder, and document root.

## One-Click Update Rules

- Release ZIPs must include `phpld-release.json`.
- Release ZIPs must include production `vendor/` and built `public/build` assets.
- Release ZIPs must not include `.env`, secrets, logs, `node_modules`, or `.git`.
- The manifest must include version, package URL, SHA256 checksum, minimum PHP version, and release notes URL.
- The app version inside `config/phpld.php` must match the release version.
- Normal feature releases should prefer additive migrations: new tables, nullable columns, new indexes, or backward-compatible defaults.
- Destructive migrations require a release note warning and a manual backup recommendation.
- The updater preserves `.env`, storage/uploads, and cache directories.
- The updater backs up overwritten files before copying new files.

## Telemetry Events

Events:

- `install.completed`
- `update.check`
- `update.started`
- `update.completed`
- `update.failed`

Suggested payload:

```json
{
  "event": "install.completed",
  "install_id": "uuid",
  "app_version": "1.0.0",
  "php_version": "8.2.31",
  "database": "mysql",
  "telemetry_level": "basic",
  "domain_hash": "optional"
}
```

## Privacy Rules

- Do not collect passwords, API keys, database credentials, session tokens, or submitted listing content.
- Keep install ID anonymous.
- Make telemetry visible in settings.
- Allow non-essential tracking to be disabled.
- Send only what helps support installs and upgrades.

## Open Decisions

- Should domain reporting default to off, hashed, or explicit opt-in?
- Where should the public update manifest live?
- Should release ZIPs be public URLs, signed temporary URLs, or license-gated downloads?
- How much backup automation is safe on typical shared hosting accounts?
- Should updater support major-version warnings before applying updates?
