README

A PHP SDK for interacting with the Eduplus Attendance API — Centralized Attendance Data Collection System. Built with Guzzle HTTP.

Requirements

• PHP 7.4 or higher
• Guzzle HTTP 6.5+ or 7.0+ (automatically installed via Composer)

Installation

composer require eduplus/attendance

Quick Start

<?php

require_once 'vendor/autoload.php';

use Eduplus\EduplusAttendance;

// Get today's attendance
$records = EduplusAttendance::setApiKey('your-api-key')
    ->attendance([
        'start' => date('Y-m-d'),
        'end' => date('Y-m-d'),
    ]);

foreach ($records as $r) {
    echo "{$r['person_identifier']} — {$r['first_checkin']} to {$r['last_checkout']}\n";
}

Configuration

use Eduplus\EduplusAttendance;

// Set API key (required)
EduplusAttendance::setApiKey('your-api-key');

// Override base URL for staging/local (optional)
EduplusAttendance::setBaseUrl('https://staging.attendance.example.com');

Usage

Attendance

$sdk = EduplusAttendance::setApiKey('your-api-key');

// List attendance with filters
$records = $sdk->attendance([
    'start' => '2026-04-01',
    'end' => '2026-04-30',
    'person_identifier' => 'REG001',  // optional
    'machine' => '5th_floor',          // optional: machine identifier or ID
    'tags' => 'students,main_building', // optional: comma-separated
]);

// Attendance for a specific date
$records = $sdk->attendanceForDate('2026-04-30');

// With late/absent status rules
$records = $sdk->attendanceForDate('2026-04-30', [
    'late_time' => '09:30',    // global: checkin after 09:30 = late
    'absent_time' => '10:00',  // global: checkin after 10:00 = absent
    'rules' => [               // per-person overrides
        'REG001' => ['late_time' => '09:00', 'absent_time' => '09:15'],
        'REG002' => ['late_time' => '10:00'],
    ],
]);

// Attendance for a specific person
$records = $sdk->personAttendance('REG001', [
    'start' => '2026-04-01',
    'end' => '2026-04-30',
]);

Punches

$sdk = EduplusAttendance::setApiKey('your-api-key');

// List punches with filters
$punches = $sdk->punches([
    'start' => '2026-04-30',
    'end' => '2026-04-30',
    'person_identifier' => 'REG001',
    'machine' => 'main_gate',
    'tags' => 'teachers',
]);

// Punches for a specific person
$punches = $sdk->personPunches('REG001', [
    'start' => '2026-04-30',
    'end' => '2026-04-30',
]);

Machines

$machines = EduplusAttendance::setApiKey('your-api-key')->machines();

foreach ($machines as $m) {
    echo "[{$m['identifier']}] {$m['label']} — {$m['vendor']} — Tags: " . implode(', ', $m['tags']) . "\n";
}

API Reference

setApiKey(string $apiKey): EduplusAttendance

Set the API key. Returns a new instance for chaining.

setBaseUrl(string $url): void

Override the base URL. Default: https://attendance.eduplus-bd.com

attendance(array $filters = []): array

Get attendance records. Filters: start, end, person_identifier, machine, tags

attendanceForDate(string $date, array $filters = []): array

Get attendance for a date. Extra filters: late_time, absent_time, rules

personAttendance(string $id, array $filters = []): array

Get attendance for a person. Filters: start, end, machine, tags

punches(array $filters = []): array

Get raw punches. Filters: start, end, person_identifier, machine, tags

personPunches(string $id, array $filters = []): array

Get punches for a person. Filters: start, end, machine, tags

machines(): array

Get all machines for the authenticated client.

Response Format

Attendance Record

[
    'person_identifier' => 'REG001',
    'date' => '2026-04-30',
    'first_checkin' => '08:15:00',
    'last_checkout' => '17:02:00',
    'total_minutes_inside' => 480,
    'total_minutes_outside' => 47,
    'punch_count' => 4,
    'status' => 'present',
]

Punch Record

[
    'person_identifier' => 'REG001',
    'person_name' => 'John Doe',
    'punched_at' => '2026-04-30 08:15:23',
    'punch_type' => 'fingerprint',  // fingerprint, card, face, unknown
    'device_identifier' => 'DEV01',
    'location' => null,
]

Machine Record

[
    'identifier' => '5th_floor',
    'label' => '5th Floor Machine',
    'vendor' => 'stellar',
    'timezone' => 'Asia/Dhaka',
    'is_active' => true,
    'sync_status' => 'success',
    'last_synced_at' => '2026-04-30 12:00:00',
    'last_collected_at' => '2026-04-30 12:01:00',
    'tags' => ['students', 'main_building'],
]

Filter Reference

Error Handling

The SDK never throws exceptions. All methods return arrays:

• Success: Returns the data array from the API
• Error/No data: Returns an empty array []

$records = $sdk->attendance(['start' => '2026-04-30', 'end' => '2026-04-30']);

if (empty($records)) {
    echo "No records found or API error\n";
} else {
    echo "Found " . count($records) . " records\n";
}

License

MIT — see LICENSE file.