Skip to content

README.en.md

Latest commit

 

History

History
107 lines (73 loc) · 3.26 KB

README.en.md

File metadata and controls

107 lines (73 loc) · 3.26 KB

Logo

🌎 Leia em Português

Ready-to-use application to generate, export, and print math exercise sheets.

✅ About the project

MathX is a math exercise generator built with Laravel. The user selects the operations (addition, subtraction, multiplication, and division), defines a number interval, sets how many exercises will be generated, and the system displays a printable and exportable list.

This project follows a simple structure based on Controller → Services → Models → Views (Blade).

🚀 Features

  • Generation of basic arithmetic exercises: addition, subtraction, multiplication, and division.
  • Control of operand range (min and max values).
  • Define the amount of exercises (5 to 50).
  • Exercises stored temporarily in Laravel Session.
  • Print view for classroom use.
  • Export results as a .txt file.

🛠 Tech stack & conventions

  • PHP (recommended 8.x)
  • Laravel (Blade templates)
  • Bootstrap (static assets included)
  • Composer for dependency management

Main structure of the code:

  • app/Http/Controllers/MainController.php — route logic and service integration.
  • app/Services/ExerciseGeneratorService.php — exercise creation.
  • app/Services/ExerciseExporterService.php — .txt formatting.
  • app/Services/ExerciseSessionService.php — validation and session handling.
  • app/Models/Exercise.php — simple model for exercises.
  • routes/web.php — routes (home, generateExercises, exportExercises, printExercises).
  • resources/views/ — Blade views (layouts, home, operations, etc.)

📥 Installation

  1. Clone the repository:
git clone https://github.com/jprogram-php-projects/MathX.git
cd MathX
  1. Install dependencies:
composer install
  1. Copy and configure the environment file:
cp .env.example .env

Adjust .env if needed (e.g., APP_NAME, APP_URL).

  1. Generate Laravel app key:
php artisan key:generate

  1. Database is not required for current features. If you add DB-related features, update .env and run php artisan migrate.

  2. Start the local server:

php artisan serve

Access the app at http://127.0.0.1:8000.

⚙️ Important notes

  • Rename .env.example to .env before generating the app key.
  • Exercise data is stored in session, default session driver file works great.
  • Static assets are located in public/assets/... and Blade references use asset('assets/...').

🧭 Quick overview of flow

  1. User submits form on / route.

  2. MainController::generateExercises validates and calls ExerciseGeneratorService.

  3. Exercises are stored in session: session(['exercises' => $exercises]).

  4. User can:

    • View exercise list in operations view.
    • Export to .txt using exportExercises.
    • Print exercises with answers using printExercises.

💡 Improvement roadmap

  • Add decimal configuration for division.
  • Filter exercises by operation type on export/visualization.
  • Add PHPUnit tests for ExerciseGeneratorService and MainController.
  • View internationalization (i18n).

🧩 Contributing

  1. Fork the repo.
  2. Create a new branch: git checkout -b feat/feature-name.
  3. Commit small and meaningful changes.
  4. Open a Pull Request with a description of your changes.