Goralys

Goralys is a lightweight web app to manage "Grand Oral" topics for students and teachers at a high school.

Features

• Student/teacher/admin roles with automatic role detection at registration (AuthController::register).
• Two-topic student workflow: draft, submit, and read-only once submitted (useSubjects, SubjectsController).
• Session-backed user data caching for fast frontend rendering (AuthController::login manages session data).
• CSRF protection using a short-lived session token: CSRFService + fetchCsrfClient.
• Toast notification system used by both PHP and Next.js (ToastController::showToast and toast-provider.tsx).

Quick start (development)

Prerequisites:

• PHP 8.1+ with mysqli
• Composer (for PHPMailer)
• pnpm package manager

To simulate a local PHP server with mysql on Windows, you can use XAMPP (also available on Linux and macOS)

(Optional):

• PHP_CodeSniffer
• PHP ruleset for PSR-12 convention

Steps:

1. Run setup script:

   .\setup.bat

   Or if you use Linux:

   ./setup.sh

2. Configure environment:
   • For development, modify the values inside .env (created using setup.bat)
3. Database:
   • Create the database and tables using the schema at backend/data_structure.sql.
4. Run dev server:
   • Run Next and PHP's built-in server for the API, by default the next rewrite port for the API is 80:

     pnpm run dev
     php -S localhost:80

5. Access the app:
   • Visit http://localhost/goralys/ (or http://localhost:8000 if using built-in server).

Testing

You can use phpunit to run the unit tests for the backend in backend/tests. To run the tests, use the following command after installing the projects dependencies with composer:

.\backend\vendor\bin\phpunit --configuration backend\phpunit.xml

Security notes

• CSRF:
  • Token validated by CSRFService::validate.
• Passwords:
  • Passwords are hashed using PHP's password_hash (RegisterService::register) and verified with password_verify (LoginService::login).
• Sensitive config:
  • You must use .env to configure your project.

Note: the develop branch serves as a pre-production playground, so some commits may include experimental or buggy code — I try to minimize this as much as possible.

Key code pointers

• Main Kernel (Initialization & Routing): GoralysKernel
• Authentication & Sessions: AuthController
• Subjects Management: SubjectsController
• Database schema: backend/data_structure.sql
• Frontend Subject logic: useSubjects hook
• Toast notification: ToastController and toast-provider.tsx
• CSRF Service: CSRFService

Project structure

Frontend (Next.js)

• app/: Contains the application pages and logic.
• app/subject/: Student, Teacher, and Admin dashboards.
• app/hooks/: React hooks for data fetching and state management.
• app/ui/: Reusable UI components.

Backend (PHP)

• backend/API/: API endpoints, acting as entry points for the kernel.
• backend/src/Kernel/: The core of the backend, handles initialization and request management.
• backend/src/App/: Controllers and application-level services.
• backend/src/Core/: Business logic and core domain services.
• backend/src/Platform/: Low-level platform services (DB, Logger, Loader).
• backend/tests/: Unit and integration tests.

License and contributing information

This project is under an MIT license (see: LICENSE). All contributions are welcome as long as they respect the terms inside Contributing.

Notes

Any pull request containing sensitive information inside .env will have no chance to be merged.