# Cory's IT Helpdesk — PHP rewrite v1.0

This is a PHP-native rewrite of the uploaded Perl/CGI helpdesk package. It retains the ticket workflow and directory concepts while replacing executable Perl `.pm` data files with JSON flat files. No SQL database or Composer packages are required.

## Included

- Ticket dashboard with active, urgent, closed, and total counts
- Searchable ticket queue and status filter
- Create, view, edit, close, and reopen tickets
- Ticket replies / technician notes with time-spent tracking
- Attachments (10 MB maximum, allow-listed file extensions, random stored names, controlled download)
- Client, agent, and client-type directory screens
- JSON flat-file records with locked writes
- CSRF tokens on state-changing forms
- HTML escaping for user-supplied values
- Dark NOC-style interface
- Legacy query compatibility for common URLs such as `?listing+all` and `?read+10001`
- One-time legacy `.pm` assignment importer
- Original uploaded CSS/images/templates retained under `assets/` as references

## Install on Debian / Apache

1. Unzip the package into your web root, for example `/var/www/html/helpdesk`.
2. Make PHP's data directory writable:

   ```sh
   sudo chown -R www-data:www-data /var/www/html/helpdesk/data
   sudo find /var/www/html/helpdesk/data -type d -exec chmod 750 {} \;
   sudo find /var/www/html/helpdesk/data -type f -exec chmod 640 {} \;
   ```

3. Ensure PHP 8.1+ is installed with `fileinfo` not required and `mbstring` recommended. Apache's PHP-FPM/mod_php setup must be enabled.
4. Open `/helpdesk/index.php`.

The package defaults to its local `data/` folder. To keep the old storage location, configure the PHP-FPM pool or Apache environment with `CORYSIT_DATA_PATH=/var/www/data`, then make sure the PHP worker can write there. Do not point the PHP version at production data until you have a full backup and have reviewed the migration.

## Import legacy Perl data

The uploaded ZIP contains the Perl code and UI assets, but not `/var/www/data` itself. If your old Perl data directory exists on the server, first make a backup, then run the importer from the extracted package directory:

```sh
sudo -u www-data php legacy-import.php /var/www/data
```

Set `CORYSIT_DATA_PATH` for this CLI invocation if you want the imported JSON files written somewhere other than this package's `data/` directory. For example:

```sh
sudo -u www-data env CORYSIT_DATA_PATH=/var/www/html/helpdesk/data php legacy-import.php /var/www/data
```

The importer reads Perl scalar assignment files using a constrained parser; it does not `eval` or execute legacy `.pm` files. Back up first and verify imported tickets before switching production traffic.

## Storage format

- `data/tickets/<ticket-id>.json` — ticket record
- `data/tickets/<ticket-id>-replies.json` — replies and work notes
- `data/clients/<id>.json` — clients
- `data/agents/<id>.json` — agents
- `data/client_types/<id>.json` — client types
- `data/uploads/<ticket-id>/` — attachment files

## Security notes

- Put the helpdesk behind HTTPS.
- Restrict agent-only screens to a VPN, management network, or Apache authentication. This first PHP rewrite does not implement a full user/password/role login system; it uses `REMOTE_USER` if Apache authentication is configured and otherwise labels activity as `web-guest`.
- Ensure the `data/` directory is outside the web document root or denied by Apache. If it must remain below the document root, use this Apache rule in that directory:

  ```apache
  Require all denied
  ```

- Review PHP `upload_max_filesize` and `post_max_size` if attachments are enabled.
- The original Perl files are not run by this PHP application.