Students Exams Controller Documentation

File: /controllers/studentsExamsController.php

Purpose: Manages student examination system including exam creation, student participation, and grade recording

Last Updated: December 21, 2024

Total Functions: 5

Lines of Code: ~299

---

📋 Overview

The Students Exams Controller handles the complete examination lifecycle for the student management system. It provides functionality for:

• • Exam creation and configuration
• • Student enrollment in exams
• • Grade recording and management
• • Exam attendance tracking
• • Dynamic student addition to ongoing exams
• • Multi-group exam coordination
• • Exam data visualization and reporting
• • Real-time exam participant management

Primary Functions

• ✅ Create exams for subject assignments
• ✅ Manage student participation in exams
• ✅ Record individual student grades and attendance
• ✅ Handle late exam enrollments
• ✅ Track exam completion status
• ✅ Generate exam reports and listings
• ✅ Support multi-assignment exam coordination
• ✅ Process exam deletion with data preservation

Related Controllers

• • studentSettings.php - System configuration
• • studentSubjectsController.php - Subject management
• • studentsAddSubject.php - Student assignments
• • studentAbsence.php - Attendance tracking

---

🗄️ Database Tables

Primary Tables (Direct Operations)

🔑 Key Functions

1. Default Action - Exam Creation Form

Location: Lines 8-12

Purpose: Display the exam creation interface

Process Flow:

1. Display header template

2. Show exam creation form

3. Set student navigation flag

4. Display footer template

---

2. savedata() - Exam Creation and Management

Location: Lines 101-143

Purpose: Create or update exam records for multiple assignments

Function Signature:

function savedata()

Process Flow:

1. Extract exam parameters from POST

2. Load assignment data to get related assignments

3. Create exam records for all related assignments

4. Set exam configuration (name, max grade)

5. Handle exam updates vs creation

6. Return success/failure status

Multi-Assignment Processing:

$studentaddsubjectsdata = R::load('studentaddsubjects', $studentaddsubjectid); 
$studentaddsubjects = R::findAll('studentaddsubjects', 
    "studentsubjectid = ? and del < 2", [$studentaddsubjectsdata->studentsubjectid]);

if (!$studentsexamid) {
    foreach($studentaddsubjects as $studentaddsubject) {
        $studentsexams = R::dispense('studentsexams');
        // Create exam for each related assignment
    }
}

Exam Configuration:

$studentsexams->studentaddsubjectid = $studentaddsubject->id;
$studentsexams->studentsubjectid = $studentaddsubject->studentsubjectid;
$studentsexams->studentsubjectgroupid = $studentaddsubject->studentsubjectgroupid;
$studentsexams->studentid = $studentaddsubject->studentid;
$studentsexams->examname = $examname;
$studentsexams->greatdegree = $greatdegree;

---

3. edit - Exam Student Management

Location: Lines 21-63

Purpose: Initialize exam with student participants and manage exam sessions

Process Flow:

1. Load exam record and related assignment

2. Auto-enroll all assigned students (first time only)

3. Load existing exam participants

4. Display exam management interface

5. Mark exam as having students enrolled

Student Auto-Enrollment:

if ($studentsexams->examsstudent != 1) {
    $studentaddsubjectdetails = R::findAll('studentaddsubjectdetails', 
        " studentaddsubjectid = ? and studentaddsubjectdetails.del < 2", [$studentsexams->studentaddsubjectid]);
    
    foreach($studentaddsubjectdetails as $studentaddsubjectdetail) {
        $studentsexamsval = R::dispense('studentsexamsval');
        $studentsexamsval->studentid = $studentaddsubjectdetail->studentid;
        $studentsexamsval->examspresence = 1; // Default present
        $studentsexamsval->studentsexamid = $id;
        // Set all reference fields
        R::store($studentsexamsval);
    }
}

Student Data Enhancement:

foreach($studentsexamsval as $studentsexamsva) {
    $students = R::findOne('students', 'id = ? and del < 2', [$studentsexamsva->studentid]);
    $studentsexamsva->student = $students->studentname . ' / ' . $students->studentphone;
}

---

4. showajax() - Exam Listing Data Table

Location: Lines 146-240

Purpose: Provide paginated exam data with filtering and search

Function Signature:

function showajax()

Process Flow:

1. Define column mappings for DataTables

2. Build search query with filters

3. Apply date range and assignment filters

4. Execute complex JOIN query

5. Format results with action buttons

6. Return JSON response

Complex Query Structure:

$rResult = R::getAll('SELECT examname, greatdegree, studentsexams.id as id, 
    studentsexams.addtoday as addtoday, studentsexams.del as del, employeename,
    studentsubjects.del as studentsubjectsdel, studentsubjectgroups.del as studentsubjectgroupsdel,  
    subjectname, subjectgroupname, subjectgroupprice  
    FROM `studentsexams` 
    LEFT JOIN user ON studentsexams.adduserid = user.userid 
    LEFT JOIN studentsubjects ON studentsexams.studentsubjectid = studentsubjects.id 
    LEFT JOIN studentsubjectgroups ON studentsexams.studentsubjectgroupid = studentsubjectgroups.id 
    WHERE studentsubjects.del < 2 and studentsubjectgroups.del < 2 '.$searchQuery);

Action Button Configuration:

if($row["del"] < 2) {    
    $sub_array[] = '<a href="studentsExamsController.php?do=edit&id='. $row["id"] .'" 
                       type="button" class="btn btn-default btn-lg editicon"></a>';
    $sub_array[] = '<a href="javascript:;" data-id="'. $row["id"] .'" data-table="studentsexams"  
                       type="button" class="btn btn-default btn-lg deleteicon removerow"></a>';
}

---

5. examsstudent() - Grade Recording

Location: Lines 243-259

Purpose: Record individual student exam results and attendance

Function Signature:

function examsstudent()

Process Flow:

1. Extract grade and attendance data

2. Load student exam record

3. Update grade and presence status

4. Set audit information

5. Return success status

Grade Update Logic:

$tables = R::load('studentsexamsval', $id);
$tables->del = 1; // Mark as updated
$tables->updatetoday = date("Y-m-d H:i:s");
$tables->updateuserid = $_SESSION['userid']; 
$tables->examsvalue = $examsvalue;  
$tables->examspresence = $examspresence;

---

6. getallstudenttime - Dynamic Student Addition

Location: Lines 64-89

Purpose: Add students to ongoing exams dynamically

Process Flow:

1. Load exam record and student data

2. Add student to exam participant list

3. Create exam value record for new student

4. Return student information for display

Dynamic Addition Process:

$studentsexams = R::load('studentsexams', $studentsexamid);
$studentsexams->studentid = $studentsexams->studentid . ',' . $studentid;
R::store($studentsexams);

$studentsexamsval = R::dispense('studentsexamsval');
$studentsexamsval->studentid = $student->id;
$studentsexamsval->examspresence = 1;
$studentsexamsval->studentsexamid = $studentsexamid;
R::store($studentsexamsval);

---

7. getstudentnotexam() - Available Student Search

Location: Lines 262-292

Purpose: Find students eligible for exam participation

Function Signature:

function getstudentnotexam()

Process Flow:

1. Get assignment and exam details

2. Find students in assignment not yet in exam

3. Build search query with name filtering

4. Return formatted student data for selection

Eligibility Check:

foreach($studentaddsubjectdetails as $studentaddsubjectdetail) {
    $countstudents = R::count('studentsexamsval', 
        "studentid = ? and studentsexamid = ? and del < 2", 
        [$studentaddsubjectdetail->studentid, $studentsexamid]);
    if ($countstudents == 0) {
        $studentid .= ',' . $studentaddsubjectdetail->studentid;
    } 
}

---

🔄 Workflows

Workflow 1: Complete Exam Lifecycle

---

Workflow 2: Dynamic Student Management

---

🌐 URL Routes & Actions

Exam Creation (do=savedata):

• • studentaddsubjectid - Assignment ID
• • examname - Exam name/title
• • greatdegree - Maximum possible grade
• • studentsexamid - Exam ID (for updates)

Exam Management (do=edit):

• • id - Exam ID
• • addstudent - Flag for student addition mode

Grade Recording (do=examsstudent):

• • id - Student exam value record ID
• • examsvalue - Student's grade
• • examspresence - Attendance status (1=present, 0=absent)

Student Addition (do=getallstudenttime):

• • studentid - Student ID to add
• • studentsexamid - Target exam ID

Student Search (do=getstudentnotexam):

• • searchTerms - Search string
• • tablesearch - Search fields
• • studentaddsubjectid - Assignment context
• • studentsexamid - Current exam ID

---

🧮 Calculation Methods

Grade Validation

// Grades typically validated against maximum degree
$greatdegree = filter_input(INPUT_POST, 'greatdegree');
$examsvalue = filter_input(INPUT_POST, 'examsvalue');
// Could add: if ($examsvalue > $greatdegree) { error; }

Attendance Calculation

$examspresence = filter_input(INPUT_POST, 'examspresence');
// 1 = Present, 0 = Absent

Student Eligibility Check

$countstudents = R::count('studentsexamsval', 
    "studentid = ? and studentsexamid = ? and del < 2", 
    [$studentid, $studentsexamid]);
if ($countstudents == 0) {
    // Student eligible for addition
}

---

🔒 Security & Permissions

Authentication Requirements

• • All exam operations require valid session
• • User permissions checked for exam access
• • Student data access controlled

Input Validation

// Grade validation
$examsvalue = filter_input(INPUT_POST, 'examsvalue');
$examspresence = filter_input(INPUT_POST, 'examspresence');

// ID validation
$studentsexamid = filter_input(INPUT_POST, 'studentsexamid');
$studentid = filter_input(INPUT_POST, 'studentid');

Data Integrity

• • Foreign key relationships maintained
• • Soft deletion preserves exam history
• • Audit trail for all grade changes

Audit Trail

// Complete change tracking
$studentsexamsval->addtoday = $today;
$studentsexamsval->adduserid = $_SESSION['userid']; 
$studentsexamsval->updatetoday = $today;
$studentsexamsval->updateuserid = $_SESSION['userid']; 

---

📊 Performance Considerations

Database Optimization

1. Efficient Queries: Uses appropriate indexes for exam lookups

2. Batch Operations: Student enrollment processed in single transaction

3. Minimal Joins: Strategic use of JOINs in data table queries

Potential Bottlenecks

• • Large Exams: Many students in single exam may impact performance
• • Search Operations: Student search across large datasets
• • Grade Recording: Individual AJAX calls for each grade update

Recommended Indexes

CREATE INDEX idx_studentsexams_assignment ON studentsexams(studentaddsubjectid, del);
CREATE INDEX idx_studentsexamsval_exam_student ON studentsexamsval(studentsexamid, studentid, del);
CREATE INDEX idx_studentsexams_subject_group ON studentsexams(studentsubjectid, studentsubjectgroupid, del);

---

🐛 Common Issues & Troubleshooting

1. Students Not Auto-Enrolled

Issue: Exam created but no students appear

Cause: Assignment has no active student details

Debug:

-- Check assignment has students
SELECT COUNT(*) FROM studentaddsubjectdetails 
WHERE studentaddsubjectid = [ASSIGNMENT_ID] AND del < 2;

2. Grades Not Saving

Issue: Grade updates don't persist

Cause: Student exam value record not found

Debug:

$tables = R::load('studentsexamsval', $id);
if (!$tables->id) {
    echo "Exam value record not found: " . $id;
}

3. Duplicate Exams Created

Issue: Multiple exam records for same assignment

Cause: Multi-assignment processing logic error

Fix:

-- Check for duplicate exams
SELECT studentaddsubjectid, examname, COUNT(*) as count
FROM studentsexams 
WHERE del < 2
GROUP BY studentaddsubjectid, examname
HAVING COUNT(*) > 1;

4. Student Search Not Working

Issue: Available students don't appear in search

Cause: Search query or enrollment check logic error

Debug:

// Check student eligibility logic
$studentaddsubjectdetails = R::findAll('studentaddsubjectdetails', 
    "studentaddsubjectdetails.del < 2 and studentaddsubjectdetails.studentaddsubjectid = ?", 
    [$studentaddsubjectid]);
echo "Students in assignment: " . count($studentaddsubjectdetails);

---

🧪 Testing Scenarios

Test Case 1: Complete Exam Creation

1. Create exam for subject assignment
2. Verify all assigned students auto-enrolled
3. Check exam appears in listing
4. Confirm edit interface loads correctly

Test Case 2: Grade Recording

1. Open exam for grade recording
2. Enter grades for multiple students
3. Set attendance status
4. Verify grades save correctly
5. Check grade persistence after reload

Test Case 3: Dynamic Student Addition

1. Start with existing exam
2. Add new student to assignment
3. Add student to ongoing exam
4. Verify student appears in participant list
5. Test grade recording for new student

Test Case 4: Multi-Assignment Exams

1. Create exam for subject with multiple assignments
2. Verify exam created for all assignments
3. Check students from all assignments enrolled
4. Test grade recording across assignments

---

📚 Related Documentation

• • CLAUDE.md - PHP 8.2 migration guide
• • studentSettings.md - System configuration
• • studentSubjectsController.md - Subject management
• • studentsAddSubject.md - Student assignments
• • studentAbsence.md - Attendance tracking
• • Database Schema Documentation - Table relationships

---

Documented By: AI Assistant

Review Status: ✅ Complete

Next Review: When major changes occur