Directory
The Directory module is the central place for managing people (students, guardians, staff) and organizational structures (classes, enrollments). It handles creating, updating, and retrieving directory-related information.
Quick Reference
Updates existing student information
Creates parent-child relationship link
Constructor
Creates a new Directory module instance with database, events, and storage path dependencies.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
$db | DB | Yes | Database instance for data operations |
$events | Events | Yes | Events system for triggering notifications |
$storagePath | string | Yes | File system path for storing exports and files |
Example
<?php
$config = [
'db' => [
'dsn' => 'mysql:host=localhost;dbname=schoolkit;charset=utf8mb4',
'user' => 'your_username',
'pass' => 'your_password'
],
'storage_path' => __DIR__ . '/storage'
];
$schoolKit = SchoolKit::start($config);
$directory = $schoolKit->directory();
?>Student Management
Creates a new student record.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
$data |
array |
Yes | Associative array of student data (e.g., first_name, last_name, grade_level). |
Returns
The ID of the newly created student.
Example
<?php
$studentId = $schoolKit->directory()->createStudent([
'first_name' => 'Sally',
'last_name' => 'Ride',
'grade_level' => '11',
'email' => 'sally.ride@school.edu',
'status' => 'active'
]);
echo "Created student with ID: {$studentId}";
?>Updates an existing student's record.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
$studentId | int | Yes | The ID of the student to update. |
$data | array | Yes | An associative array of fields to update. |
Returns
true if the record was updated, false otherwise.
Example
<?php
$wasUpdated = $schoolKit->directory()->updateStudent(123, ['email' => 's.ride@school.edu']);
if ($wasUpdated) {
echo "Student email updated.";
}
?>Deletes a student record permanently from the database.
Example
<?php
$deleted = $schoolKit->directory()->deleteStudent(123);
if ($deleted) {
echo "Student record deleted successfully";
}
?>Parameters
int $studentId- The ID of the student to delete
Returns
bool - True if deleted successfully, false otherwise
Retrieves a single student record by their ID.
Returns
An associative array of the student's data, or null if not found.
Example
<?php
$student = $schoolKit->directory()->getStudent(123);
if ($student) {
print_r($student);
}
?>Finds students based on various filter criteria.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
$filters | array | No | Filter by grade_level, status, ext_id, or a search query q. |
$opts | array | No | Options for order, limit, and columns. |
Returns
An array of student records matching the criteria.
Example
<?php
// Find all active students in Grade 11 whose name contains 'Ri'
$students = $schoolKit->directory()->findStudents([
'grade_level' => '11',
'status' => 'active',
'q' => 'Ri'
]);
print_r($students);
?>Imports student records from a CSV file with customizable field mapping.
Example
<?php
$result = $schoolKit->directory()->importStudentsCSV('/path/to/students.csv', [
'first_name' => 'First Name',
'last_name' => 'Last Name',
'grade_level' => 'Grade',
'email' => 'Email Address'
]);
echo "Imported {$result['inserted']} students, updated {$result['updated']} students";
if (!empty($result['errors'])) {
print_r($result['errors']);
}
?>Parameters
string $csvPath- Path to the CSV filearray $map- Field mapping (database field => CSV column name)
Returns
array - Import results with counts and any errors
Exports student records to a CSV file based on optional filters.
Example
<?php
// Export all Grade 11 students
$csvPath = $schoolKit->directory()->exportStudentsCSV([
'grade_level' => '11',
'status' => 'active'
]);
echo "Students exported to: {$csvPath}";
// Download the file
header('Content-Type: text/csv');
header('Content-Disposition: attachment; filename="students.csv"');
readfile($csvPath);
?>Parameters
array $filters- Optional filters to limit export (grade_level, status, etc.)
Returns
string - Path to the generated CSV file
Moves all active students from one grade level to another.
Example
<?php
// At the end of the school year, promote all 10th graders to 11th grade
$result = $schoolKit->directory()->promoteGrade('10', '11');
echo "Promoted {$result['count']} students from Grade 10 to Grade 11";
?>Parameters
string $from- Current grade level to promote fromstring $to- Target grade level to promote to
Returns
array - Result array with count of promoted students: ['count' => int]
Archives all active students in a specific grade level (typically used for graduating students).
Example
<?php
// Archive all Grade 12 students at graduation
$result = $schoolKit->directory()->archiveStudentsByGrade('12');
echo "Archived {$result['count']} graduating students";
?>Parameters
string $graduatingGrade- Grade level to archive (e.g., '12' for seniors)
Returns
array - Result array with count of archived students: ['count' => int]
Guardian Management
Creates a new guardian record.
Returns
The ID of the newly created guardian.
Example
<?php
$guardianId = $schoolKit->directory()->createGuardian([
'first_name' => 'Alan',
'last_name' => 'Shepard',
'email' => 'alan.shepard@example.com'
]);
?>Updates an existing guardian's record with new information.
Example
<?php
$updated = $schoolKit->directory()->updateGuardian(456, [
'phone' => '555-0123',
'email' => 'newemail@example.com'
]);
if ($updated) {
echo "Guardian contact information updated";
}
?>Parameters
int $guardianId- ID of the guardian to updatearray $data- Fields to update (first_name, last_name, email, phone, etc.)
Returns
bool - True if updated successfully, false otherwise
Links a guardian to a student.
Returns
true on success, false if the link already exists.
Example
<?php
$studentId = 123;
$guardianId = 456;
$schoolKit->directory()->linkGuardian($studentId, $guardianId, 'Father');
?>Removes the link between a guardian and a student (does not delete the guardian record).
Example
<?php
$unlinked = $schoolKit->directory()->unlinkGuardian(123, 456);
if ($unlinked) {
echo "Guardian unlinked from student";
}
?>Parameters
int $studentId- ID of the studentint $guardianId- ID of the guardian to unlink
Returns
bool - True if unlinked successfully, false if link didn't exist
Retrieves a list of all guardians linked to a specific student with their contact information and relationships.
Example
<?php
$contacts = $schoolKit->directory()->guardianContacts(123);
foreach ($contacts as $contact) {
echo "{$contact['first_name']} {$contact['last_name']} ({$contact['relationship']})\n";
echo "Email: {$contact['email']}\n";
echo "Phone: {$contact['phone']}\n\n";
}
?>Parameters
int $studentId- ID of the student
Returns
array - Array of guardian records with contact details and relationship information
Finds guardians based on various filter criteria.
Example
<?php
// Find guardians by email domain
$guardians = $schoolKit->directory()->getGuardians([
'q' => '@gmail.com'
]);
// Find all guardians
$allGuardians = $schoolKit->directory()->getGuardians();
print_r($guardians);
?>Parameters
array $filters- Optional filters (q for search query, email, etc.)
Returns
array - Array of guardian records matching the criteria
Staff Management
Creates a new staff member record with the provided information.
Example
<?php
$staffId = $schoolKit->directory()->createStaff([
'first_name' => 'Chris',
'last_name' => 'Hadfield',
'email' => 'chris.hadfield@school.edu',
'role' => 'Science Teacher'
]);
echo "Created staff member with ID: {$staffId}";
?>Parameters
array $data- Staff information (first_name, last_name, email, role - required fields)
Returns
int - The ID of the newly created staff member
Updates an existing staff member's record with new information.
Example
<?php
$updated = $schoolKit->directory()->updateStaff(789, [
'role' => 'Head of Science Department',
'email' => 'c.hadfield@school.edu'
]);
if ($updated) {
echo "Staff member information updated successfully";
}
?>Parameters
int $staffId- ID of the staff member to updatearray $data- Fields to update (first_name, last_name, email, role)
Returns
bool - True if updated successfully, false otherwise
Finds a staff member by their email address.
Example
<?php
$staff = $schoolKit->directory()->findStaffByEmail('chris.hadfield@school.edu');
if ($staff) {
echo "Found: {$staff['first_name']} {$staff['last_name']}";
echo "Role: {$staff['role']}";
} else {
echo "Staff member not found";
}
?>Parameters
string $email- Email address to search for
Returns
array|null - Staff member record if found, null otherwise
Finds staff members based on various filter criteria and options.
Example
<?php
// Find all staff members with 'Teacher' in their role
$teachers = $schoolKit->directory()->listStaff(['q' => 'Teacher']);
// Find staff in Science role, ordered by last name
$scienceStaff = $schoolKit->directory()->listStaff(
['role' => 'Science Teacher'],
['order' => ['last_name' => 'ASC'], 'limit' => 10]
);
print_r($teachers);
?>Parameters
array $filters- Filter criteria (q for search query, role, etc.)array $opts- Options for ordering, limiting, and column selection
Returns
array - Array of staff records matching the criteria
Class & Enrollment Management
Creates a new class with the specified information.
Example
<?php
$classId = $schoolKit->directory()->createClass([
'code' => 'SCI-101',
'name' => 'Introduction to Physics',
'grade' => '11',
'homeroom_teacher_id' => 789,
'room' => 'Room 201'
]);
echo "Created class with ID: {$classId}";
?>Parameters
array $data- Class information (code, name, grade - required; homeroom_teacher_id, room - optional)
Returns
int - The ID of the newly created class
Updates an existing class record with new information.
Example
<?php
$updated = $schoolKit->directory()->updateClass(50, [
'room' => 'Room 301',
'name' => 'Advanced Physics'
]);
if ($updated) {
echo "Class information updated successfully";
}
?>Parameters
int $classId- ID of the class to updatearray $data- Fields to update (code, name, grade, homeroom_teacher_id, room)
Returns
bool - True if updated successfully, false otherwise
Deletes a class record. Operation fails if students are still enrolled in the class.
Example
<?php
$deleted = $schoolKit->directory()->deleteClass(50);
if ($deleted) {
echo "Class deleted successfully";
} else {
echo "Cannot delete class - students may still be enrolled";
}
?>Parameters
int $classId- ID of the class to delete
Returns
bool - True if deleted successfully, false if enrollments exist or deletion failed
Retrieves a single class record by its ID.
Example
<?php
$class = $schoolKit->directory()->getClass(50);
if ($class) {
echo "Class: {$class['name']} ({$class['code']})";
echo "Room: {$class['room']}";
echo "Grade: {$class['grade']}";
} else {
echo "Class not found";
}
?>Parameters
int $classId- ID of the class to retrieve
Returns
array|null - Class record if found, null otherwise
Assigns a student to a class, creating an enrollment record.
Example
<?php
$enrolled = $schoolKit->directory()->assignStudentToClass(50, 123);
if ($enrolled) {
echo "Student successfully enrolled in class";
} else {
echo "Student is already enrolled or enrollment failed";
}
?>Parameters
int $classId- ID of the classint $studentId- ID of the student to enroll
Returns
bool - True on successful enrollment, false if already enrolled or operation failed
Removes a student from a class by deleting the enrollment record.
Example
<?php
$removed = $schoolKit->directory()->removeStudentFromClass(50, 123);
if ($removed) {
echo "Student successfully removed from class";
} else {
echo "Student was not enrolled in this class";
}
?>Parameters
int $classId- ID of the classint $studentId- ID of the student to remove
Returns
bool - True if removed successfully, false if not enrolled or operation failed
Gets a list of all students enrolled in a specific class.
Example
<?php
$roster = $schoolKit->directory()->classRoster(50);
echo "Class Roster (" . count($roster) . " students):";
foreach ($roster as $student) {
echo "- {$student['first_name']} {$student['last_name']} (Grade {$student['grade_level']})";
}
?>Parameters
int $classId- ID of the class
Returns
array - Array of student records enrolled in the class
Gets all classes for a specific grade level.
Example
<?php
$classes = $schoolKit->directory()->classesByGrade('11');
echo "Grade 11 Classes:";
foreach ($classes as $class) {
echo "- {$class['name']} ({$class['code']}) in {$class['room']}";
}
?>Parameters
string $grade- Grade level to search for (e.g., '11', '12')
Returns
array - Array of class records for the specified grade
Gets all classes assigned to a specific teacher (staff member).
Example
<?php
$classes = $schoolKit->directory()->teacherClasses(789);
echo "Teacher's Classes:";
foreach ($classes as $class) {
echo "- {$class['name']} ({$class['code']}) - Grade {$class['grade']}";
}
?>Parameters
int $staffId- ID of the teacher/staff member
Returns
array - Array of class records assigned to the teacher