HR Management

Overview

This project is a Laravel-based backend API for HR management. It implements employee and position management, authentication, notifications, hierarchical queries, logging, data import/export, rate limiting, and more, strictly following the assignment requirements.

Features

• Employee and position CRUD
• Authentication (Sanctum)
• Notifications (email, broadcast)
• Hierarchical queries
• Logging (DB and file)
• Data import/export (CSV, JSON, SQL)
• Rate limiting (10 requests/min per user)
• Custom Artisan commands

Project Structure

app/
├── Http/
│   └── Controllers/         # Controllers: Handle HTTP requests and responses for API endpoints
├── Actions/                 # Actions: Business logic for CRUD/search, called by controllers
├── Repositories/            # Repositories: Data access, Eloquent queries
├── Services/                # Services: Reusable business logic/orchestration (where used)
├── Observers/               # Observers: Listen for model events, trigger logging/notifications/history
├── Notifications/           # Notifications: Email/broadcast for salary changes, new employee
├── Console/
│   └── Commands/            # Commands: Custom Artisan CLI commands (export, cleanup, bulk ops)
├── Traits/                  # Traits: Shared code, e.g., ApiResponse.php for standardized responses

---

Requirements

• PHP: ^8.2
• Composer: Latest version recommended
• Database: MariaDB/MySQL (recommended), other Laravel-supported DBs possible
• Node.js & npm: For broadcasting/queues (if needed)
• Required Composer Packages:
  • laravel/framework ^12.0
  • laravel/sanctum ^4.0
  • laravel/tinker
  • ifsnop/mysqldump-php
  • See composer.json for full list

---

Installation & Setup

1. Clone the Repository

   git clone https://github.com/Muhamad-jamal/Assignment.git
   cd Assignment

2. Install Dependencies

   composer install

3. Environment Setup
   • Copy the example environment file and configure your DB credentials:

     cp .env.example .env

   • Edit .env for your database settings:

     DB_CONNECTION=mysql
     DB_HOST=127.0.0.1
     DB_PORT=3306
     DB_DATABASE=assignment
     DB_USERNAME=root
     DB_PASSWORD=your_password
     

   • Email Setup: Configure the following mail settings in your .env file to enable email notifications (salary change, manager notification, etc.):

     MAIL_MAILER=smtp
     MAIL_HOST=smtp.mailtrap.io
     MAIL_PORT=2525
     MAIL_USERNAME=your_mailtrap_username
     MAIL_PASSWORD=your_mailtrap_password
     MAIL_ENCRYPTION=null
     MAIL_FROM_ADDRESS=hr@example.com
     MAIL_FROM_NAME="HR Management"
     

     (You may use Mailtrap or any SMTP provider for testing.)
4. Generate Application Key

   php artisan key:generate

5. Run Migrations and Seeders

   php artisan migrate --seed

   This will automatically:
   • Create an admin user:
     • Email: admin@example.com
     • Password: password
   • Use factories to create:
     • 5 positions
     • 5 employees You can customize the seed data in database/seeders and factories in database/factories.
6. Start the Development Server

   php artisan serve

7. Run the Queue Worker To process email and broadcast notifications, start the queue worker in a separate terminal:

   php artisan queue:work

   (This is required for notifications to be sent and broadcasted.)

---

API Reference

Authentication

• POST /api/v1/auth/register – Register new user
• POST /api/v1/auth/login – Login, receive token
• POST /api/v1/auth/logout – Logout, invalidate token

Employees

• GET /api/v1/employees – List all employees
• GET /api/v1/employees/search?name=alice&salary=5000 – Search employees
• GET /api/v1/employees/without-recent-salary-change?months=12 – Employees without salary change
• POST /api/v1/employees – Create new employee
• GET /api/v1/employees/{id} – Show employee details
• PATCH /api/v1/employees/{id} – Update employee info/salary
• DELETE /api/v1/employees/{id} – Delete employee
• GET /api/v1/employees/{id}/hierarchy/names – Get hierarchy names
• GET /api/v1/employees/{id}/hierarchy/names-salaries – Get hierarchy names and salaries
• GET /api/v1/employees/export/csv – Export employees as CSV
• POST /api/v1/employees/import/csv – Import employees from CSV

Positions

• GET /api/v1/positions – List all positions
• GET /api/v1/positions/{id} – Show position details
• POST /api/v1/positions – Create position
• PATCH /api/v1/positions/{id} – Update position
• DELETE /api/v1/positions/{id} – Delete position

Utility & Artisan Commands

• php artisan employee-logs:cleanup – Delete employee logs older than one month from the logs table
• php artisan logs:remove-all – Remove all log files from storage/logs directory
• php artisan employees:insert {count} – Insert a given number of employees with a progress bar
• php artisan db:export – Export the entire database to a SQL file in storage/backups
• php artisan employees:export-json – Export all employee data to a JSON file in storage/backups

---

Postman Collection

A Postman collection is provided in the project root as Assignment.postman_collection.json.

Instructions for Reviewers:

• Import Assignment.postman_collection.json into Postman.
• Update environment variables in Postman as needed (e.g., base URL).
• Refer to the API Reference above for details on each endpoint.

---

License

MIT