alrahma_sunday_school_api/docs/api_parent_controller_plan.md

ParentController plan

Scope

• Controller: app/Http/Controllers/Api/Parents/ParentController.php
• Purpose: parent portal endpoints for attendance, invoices, enrollments, registration, emergency contacts, profile, and event participation.
• Primary dependencies:
  • App\Services\Parents\ParentAttendanceService
  • App\Services\Parents\ParentInvoiceService
  • App\Services\Parents\ParentEnrollmentService
  • App\Services\Parents\ParentRegistrationService
  • App\Services\Parents\ParentEmergencyContactService
  • App\Services\Parents\ParentProfileService
  • App\Services\Parents\ParentEventParticipationService

Routes

All routes are under v1 + parents group:

• Base prefix: GET/POST/PATCH/DELETE /api/v1/parents/...
• Group middleware: parent.access

Endpoints:

• GET /api/v1/parents/attendance → attendance
• GET /api/v1/parents/invoices → invoices
• GET /api/v1/parents/enrollments → enrollments
• POST /api/v1/parents/enrollments → updateEnrollments
• GET /api/v1/parents/registration → registration
• POST /api/v1/parents/registration → storeRegistration
• PATCH /api/v1/parents/students/{studentId} → updateStudent
• DELETE /api/v1/parents/students/{studentId} → deleteStudent
• GET /api/v1/parents/emergency-contacts → emergencyContacts
• POST /api/v1/parents/emergency-contacts → storeEmergencyContact
• PATCH /api/v1/parents/emergency-contacts/{contactId} → updateEmergencyContact
• GET /api/v1/parents/profile → profile
• PATCH /api/v1/parents/profile → updateProfile
• GET /api/v1/parents/events → events
• POST /api/v1/parents/events/participation → updateParticipation

Authentication & authorization

• Uses parent.access middleware which resolves “secondary”/“authorized” users to a primary parent id and stores it in the request attribute primary_parent_id.
• Controller helper parentIdOrUnauthorized():
  • Prefer request()->attributes->get('primary_parent_id')
  • Fallback to auth()->id()
  • On failure returns JSON { ok:false, message:"Unauthorized." } with 401

Requests/validation

Validated via FormRequest classes per endpoint:

• attendance: ParentAttendanceRequest (optional school_year)
• invoices: ParentInvoiceRequest (optional school_year)
• enrollments: ParentEnrollmentRequest (optional school_year)
• updateEnrollments: ParentEnrollmentActionRequest (enroll[], withdraw[])
• storeRegistration: ParentRegistrationRequest (students[], emergency_contacts[])
• updateStudent: ParentStudentUpdateRequest
• store/update emergency contact: ParentEmergencyContactRequest
• updateProfile: ParentProfileUpdateRequest
• updateParticipation: ParentEventParticipationRequest (participation[])

Response shapes (legacy { ok: ... })

This controller largely returns a legacy parent-portal shape rather than the Base API envelope.

• attendance:
  • { ok:true, attendance:[...], schoolYears:[...], selectedYear }
  • attendance uses ParentAttendanceResource::collection(...)
• invoices:
  • { ok:true, invoices:[...] } (InvoiceResource::collection(...))
• enrollments:
  • { ok:true, students:[...], schoolYears:[...], selectedYear, withdrawalDeadline, lastDayOfRegistration, schoolStartDate }
• updateEnrollments:
  • { ok:true, enrolled:[...], withdrawn:[...] }
• registration:
  • { ok:true, parent, existingKids:[...], emergencies:[...], maxChilds, maxEmergency, lastDayOfRegistration, registrationAgeDeadline }
• storeRegistration:
  • { ok:true, created_student_ids:[...], skipped:[...] } with status 201 if created_count>0 else 200
• updateStudent / deleteStudent / updateParticipation:
  • { ok:true }
• emergencyContacts:
  • { ok:true, contacts:[...] }
• store/update emergency contact:
  • { ok:true, contact:{...} } (store returns 201)
• profile / updateProfile:
  • { ok:true, profile:{...} }
• events:
  • { ok:true, activeEvents, charges, yourStudents }

Error handling expectations

• Unauthorized: { ok:false, message:"Unauthorized." } with 401 (from parentIdOrUnauthorized()).
• Service-layer exceptions are generally allowed to bubble unless handled in the service; controller does minimal try/catch.

Test plan (feature)

• Auth/parent.access:
  • Without auth → 401 { ok:false }.
  • With secondary/authorized user → resolved to primary parent id and returns correct data.
• Each endpoint:
  • Valid request returns ok:true and expected keys.
  • Validation errors are returned by FormRequest (422).
• Registration:
  • Returns 201 when at least one student is created, 200 when all entries skipped.