# MobileAttend cPanel Installation

## Requirements

- PHP 8.0 or newer
- MySQL 8.0 or MariaDB 10.5 or newer
- PHP extensions: `pdo_mysql`, `json`
- Apache with `.htaccess`, `mod_rewrite`, and HTTPS

No webcam, camera permission, Composer, cron job, or external QR service is required.

## Recommended file layout

```text
/home/CPANEL_USERNAME/mobile-attendance/
|-- config.php
|-- config.local.php
|-- database.sql
|-- scripts/
|-- src/
|-- templates/
`-- public/
    |-- .htaccess
    |-- index.php
    `-- assets/
```

Set the domain or subdomain document root to:

```text
/home/CPANEL_USERNAME/mobile-attendance/public
```

Only `public` should be web-accessible.

## 1. Create and import the database

1. Open **cPanel > MySQL Databases**.
2. Create a database, for example `username_attendance`.
3. Create a database user and strong password.
4. Add the user to the database with **All Privileges**.
5. Open **phpMyAdmin**.
6. Select the new database.
7. Import `database.sql`.

The SQL file contains tables, indexes, foreign keys, defaults, and attendance settings. It does not create or select a database.

## 2. Upload the application

1. Upload `mobile-qr-attendance-cpanel.zip`.
2. Extract it to `/home/CPANEL_USERNAME/mobile-attendance/`.
3. Set the domain or subdomain document root to its `public` directory.
4. If the host only permits `public_html`, extract to `/home/CPANEL_USERNAME/public_html/mobile-attendance/` and point the domain to `public`.

## 3. Configure database and URL

1. Copy `config.local.php.example` to `config.local.php`.
2. Edit `config.local.php`.
3. Enter the exact cPanel database name, user, and password.
4. Set `app.url` to the public HTTPS URL without a trailing slash.
5. Set the PHP timezone.
6. Replace `setup_key` with at least 32 random characters.

Example:

```php
<?php
return [
    'app' => [
        'url' => 'https://attendance.example.com',
        'timezone' => 'Asia/Dhaka',
        'debug' => false,
        'session_secure' => true,
        'setup_key' => 'replace-with-a-long-random-secret-key',
    ],
    'db' => [
        'host' => 'localhost',
        'port' => 3306,
        'name' => 'username_attendance',
        'user' => 'username_attendance',
        'pass' => 'database-password',
    ],
];
```

Permissions:

- Directories: `0755`
- PHP, CSS, JavaScript, and SQL files: `0644`
- `config.local.php`: `0600` or `0640`

Never use `0777`.

## 4. Create the administrator

Open:

```text
https://attendance.example.com/index.php?page=install
```

Enter the setup key from `config.local.php`, administrator details, and a password of at least 12 characters. After the first administrator is created, the installation page returns 404.

Alternatively, use cPanel Terminal:

```sh
cd /home/CPANEL_USERNAME/mobile-attendance
php scripts/create_admin.php admin@example.com "System Admin" "StrongPassword12!"
```

## 5. Configure attendance

1. Sign in at `/index.php?page=admin_login`.
2. Open **Settings**.
3. Set work start time.
4. Set late grace minutes.
5. Set the employee ID prefix.

Employee IDs are generated automatically:

```text
EMP001
EMP002
EMP003
```

Changing the prefix affects only new employees.

## 6. Add employees

1. Open **Employees**.
2. Enter employee name and initial password.
3. Optionally enter email, phone, department, and designation.
4. Give the employee their generated ID and password privately.

Passwords are stored using PHP password hashing and cannot be viewed. Use **Reset password** when necessary.

Deleting an employee archives the account and prevents login while preserving historical attendance.

## 7. Generate and print QR codes

1. Open **QR codes**.
2. The system generates:

```text
https://attendance.example.com/checkin
https://attendance.example.com/checkout
```

3. Select **Download PNG** beneath either QR code.
4. Select **Print both posters** to print the office signs.
5. Place Check In and Check Out posters at the appropriate office locations.

QR codes contain only attendance page URLs. They do not contain employee IDs or passwords.

## 8. Employee workflow

Check In:

1. Employee scans the Check In poster using their phone camera.
2. The phone opens `/checkin`.
3. Employee enters ID and password.
4. The server saves the local attendance date and UTC check-in timestamp.

Check Out:

1. Employee scans the Check Out poster.
2. The phone opens `/checkout`.
3. Employee enters ID and password.
4. The server saves checkout and calculates total working hours.

The system prevents:

- Duplicate check-in
- Duplicate check-out
- Check-out before check-in
- Attendance by inactive or deleted employees
- Repeated password guessing through 15-minute database-backed rate limiting

## 9. Reports and exports

- **Daily Report** shows present and absent employees with check-in, check-out, working hours, and late status.
- **Monthly Report** shows present days, late days, and total hours.
- **Excel** downloads SpreadsheetML, which opens directly in Microsoft Excel.
- **PDF** downloads a real PDF generated by PHP without external libraries.

## 10. Production verification

1. Add a test employee.
2. Confirm the generated ID is correct.
3. Download both QR PNG files.
4. Scan Check In with a phone.
5. Confirm duplicate Check In is rejected.
6. Scan Check Out and confirm total working time.
7. Confirm duplicate Check Out is rejected.
8. Test Daily Excel and PDF downloads.
9. Test Monthly Excel and PDF downloads.
10. Reset the test employee password.
11. Delete the employee and confirm attendance history remains.

## Security notes

- Use HTTPS. Employee passwords must never travel over plain HTTP.
- Keep `config.local.php` outside the public document root.
- Leave debug mode disabled in production.
- Back up MySQL daily.
- Protect cPanel and phpMyAdmin with multi-factor authentication.
- The system authenticates identity, but it does not prove physical location. Add office-network restrictions or geofencing only if your policy requires it.