Zkteco_app

A PHP and MySQL web application for receiving and managing attendance data from ZKTeco biometric devices (e.g., uFace800). Provides a REST-style API, data persistence, and a modern, searchable/loggable front end.

---

Features

• Receives attendance logs from ZKTeco devices via HTTP PUSH (POST)
• Securely stores logs in a MySQL attendance_db
• Web interface: filter, search, paginate, and export logs (CSV/Excel)
• Modern UI with Bootstrap 5 styling
• Easy local and production deployment

FOLDER STRUCTURE

Zkteco_app/
├── api.php                # Attendance log POST endpoint for device push
├── index.php              # Web UI for viewing/filtering/searching logs
├── includes/
│   └── database.php       # PDO connection to MySQL (edit for production)
├── assets/
│   ├── css/
│   │   └── style.css      # Custom CSS (layout/table/etc)
│   └── js/
│       └── script.js      # Basic UI scripts
├── templates/             # (optional, for extra PHP/HTML templates)
├── attendance_db_setup.sql# SQL to init/fix the DB
└── README.md              # This file

REQUIREMENTS

• PHP 7.4 or newer (PHP 8.x recommended)
• MySQL or MariaDB server
• Apache/Nginx (tested on Apache, port 80)
• ZKTeco device (e.g. uFace800) supporting ADMS PUSH (with HTTP POST)
• (For local development: Laragon/XAMPP/WAMP etc.)

DATABASE SETUP

1. Open phpMyAdmin (or MySQL Workbench/CLI).
2. Run (from attendance_db_setup.sql):

   CREATE DATABASE IF NOT EXISTS attendance_db;
   USE attendance_db;
   CREATE TABLE IF NOT EXISTS attendance_log (
       id INT AUTO_INCREMENT PRIMARY KEY,
       user_id INT NOT NULL,
       timestamp DATETIME NOT NULL,
       status VARCHAR(50) NOT NULL
   );

CONFIGURING CREDENTIALS

• Edit includes/database.php:
  • DB host, name, username, password must match your local or server SQL settings.
  • Example for Laragon: localhost, DB attendance_db, user root, blank password.
• In production, set a secure/non-root DB user and strong password!

API USAGE (DEVICE PUSH)

• Devices PUSH records via POST to http://<SERVER>/Zkteco_app/api.php
• Payload: one or more lines of tab-separated fields (user_id, timestamp, ..., status)
• Only POST is accepted (GET returns error)
• Example request (from device):

  1024\t2025-10-13 13:54:28\t0\tIN
  1024\t2025-10-13 17:16:45\t0\tOUT
  

• All valid entries (user_id, timestamp, status) are saved; status typically 'IN'/'OUT'.
• Prepared PDO statements are always used for inserts (prevents SQL injection).

FRONT END: LOG VIEWER (index.php)

• Bootstrap 5 table (with sorting, searching, paging)
• Search/filter by user/status/date
• Export to CSV/Excel
• Responsive UI for mobile/desktop
• Optionally extend columns in both DB and UI as needed

LOCAL DEVELOPMENT & TESTING

1. Place Zkteco_app in your local server's root (e.g., C:/laragon/www/)
2. Start Apache/MySQL.
3. Visit http://localhost/Zkteco_app/api.php (GET returns "Invalid request method.")
4. Configure your ZKTeco device's ADMS (Cloud/ADMS Settings):
   • Server URL: http://<your_ip>/Zkteco_app/api.php
   • Port: 80
5. Make a scan/event on the device. Check DB/table to confirm record(s).
6. Visit index.php to search/filter logs.

DEPLOYMENT

1. Upload the whole Zkteco_app folder to your public web root.
2. Create/import the MySQL DB as above, and update includes/database.php for production credentials.
3. Point your device to your real/public-domain URL (e.g., https://yourdomain.com/Zkteco_app/api.php)
4. (Highly recommended) Enable HTTPS (SSL) with Let's Encrypt/ZeroSSL, update device config to use https://....

BASIC TROUBLESHOOTING

• If device POST fails: verify server URL, port, and that PHP works (view api.php in browser)
• Check DB user/pw in includes/database.php
• Look for error messages in Apache/PHP logs
• Use MySQL GUI (phpMyAdmin/Workbench) to check if records are saved
• If records appear in DB but not in UI, check index.php filters and column names

SECURITY & BEST PRACTICES

• Only allow trusted IPs to POST to api.php (e.g., via firewall or code)
• Never commit production database.php with real credentials to public repositories
• Hide detailed DB errors from users in production
• Enable HTTPS in production
• Regularly backup your attendance_log table
• (Optional) Add authentication or IP filtering for the API

---

AUTHOR & LICENSE

Developed by Umar FarooQ

Feel free to modify and extend for your organization! Contribute fixes via pull requests if using version control.