# RepoRev API - Slim Framework 4 with Eloquent ORM

A modern, scalable RESTful API built with Slim Framework 4, featuring Eloquent ORM, advanced OOP patterns, and a robust RBAC (Role-Based Access Control) system.

## 🚀 Features

- **Modern Architecture**: Built with Slim 4 and advanced OOP patterns
- **Eloquent ORM**: Complete integration with Laravel's Eloquent ORM
- **RBAC System**: Comprehensive role-based access control with user-role-module permissions
- **Dependency Injection**: PHP-DI container for service management
- **Normalized Database**: Clean, normalized MySQL schema with proper relationships
- **Repository Pattern**: Interface-based repositories for data abstraction
- **Service Layer**: Business logic separation with validation and error handling
- **JWT Authentication**: Secure token-based authentication with refresh tokens
- **Advanced Controllers**: Standardized controller base with response helpers
- **Comprehensive API**: Full CRUD operations for users, companies, and reports

## 📋 Requirements

- PHP 8.0 or higher
- MySQL 5.7+ or 8.0+
- Composer
- Web server (Apache/Nginx)

## 🛠 Installation

### 1. Clone the Repository

```bash
git clone <repository-url> project-slim
cd project-slim
```

### 2. Install Dependencies

```bash
composer install
```

### 3. Environment Configuration

```bash
cp .env.example .env
```

Edit `.env` file with your configuration:

```env
# Database Configuration
DB_HOST=localhost
DB_NAME=reporev
DB_USER=root
DB_PASS=your_password

# JWT Configuration
JWT_SECRET=your-super-secret-jwt-key-change-this-in-production

# App Configuration
APP_DEBUG=true
APP_NAME="RepoRev API"
```

### 4. Database Setup

Create the database:
```sql
CREATE DATABASE reporev CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
```

Run the schema migration:
```bash
mysql -u root -p reporev < database/schema.sql
```

### 5. Web Server Configuration

#### Apache Configuration
Create a virtual host pointing to the `/public` directory:

```apache
<VirtualHost *:80>
    DocumentRoot /path/to/project-slim/public
    ServerName reporev-api.local
    
    <Directory /path/to/project-slim/public>
        AllowOverride All
        Require all granted
    </Directory>
</VirtualHost>
```

#### Nginx Configuration
```nginx
server {
    listen 80;
    server_name reporev-api.local;
    root /path/to/project-slim/public;
    index index.php;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location ~ \.php$ {
        fastcgi_pass unix:/var/run/php/php8.0-fpm.sock;
        fastcgi_index index.php;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        include fastcgi_params;
    }
}
```

### 6. Directory Permissions

```bash
chmod -R 755 storage/
chmod -R 755 logs/
```

## 🏗 Architecture Overview

### Database Schema

The application uses a normalized database schema with the following main tables:

- **repo_user**: User accounts with profile information
- **repo_company**: Company profiles and information
- **repo_role**: System roles (admin, user, moderator, etc.)
- **repo_module**: System modules/features
- **repo_user_role**: User-role assignments
- **repo_role_module**: Role-module permissions
- **repo_user_flags**: Additional user boolean attributes
- **repo_user_security**: Authentication and security data
- **repo_company_social**: Company social media links
- **repo_company_product_link**: Company product/service links
- **repo_report**: Report generation and management

### Directory Structure

```
project-slim/
├── app/
│   ├── Bootstrap/           # Application bootstrapping
│   │   ├── EloquentBootstrap.php
│   │   └── ServiceContainer.php
│   ├── Controllers/         # Request handlers
│   │   ├── BaseController.php
│   │   ├── AuthController.php
│   │   ├── UserController.php
│   │   ├── CompanyController.php
│   │   ├── ReportsController.php
│   │   └── AdminController.php
│   ├── Models/             # Eloquent models
│   │   ├── BaseModel.php
│   │   ├── UserEloquent.php
│   │   ├── CompanyEloquent.php
│   │   ├── Role.php
│   │   └── Module.php
│   ├── Repositories/       # Data access layer
│   │   ├── Interfaces/
│   │   └── Eloquent/
│   ├── Services/           # Business logic layer
│   │   ├── UserService.php
│   │   ├── CompanyService.php
│   │   ├── AuthService.php
│   │   └── ReportService.php
│   ├── Middleware/         # Request middleware
│   ├── Validators/         # Input validation
│   └── Routes/            # Route definitions
├── public/                # Web server document root
│   └── index.php         # Application entry point
├── database/             # Database files
│   └── schema.sql       # Database schema
├── storage/             # File storage
├── vendor/              # Composer dependencies
└── .env                # Environment configuration
```

## 🔧 Key Components

### Models (Eloquent)

All models extend `BaseModel` which provides:
- Automatic timestamps
- Common scopes (active, recent)
- Date formatting
- Standardized JSON serialization

Example usage:
```php
use App\Models\UserEloquent;

// Get active users with their company
$users = UserEloquent::active()
    ->with('company')
    ->paginate(20);

// Check user permissions
$user = UserEloquent::find(1);
if ($user->hasRole('admin')) {
    // User has admin role
}

if ($user->hasModulePermission('users', 'create')) {
    // User can create users
}
```

### Repositories

Repository pattern with interfaces for clean abstraction:

```php
use App\Repositories\Interfaces\UserRepositoryInterface;

class UserService
{
    public function __construct(
        private UserRepositoryInterface $userRepository
    ) {}
    
    public function getUsers($page = 1, $limit = 20, $filters = [])
    {
        return $this->userRepository->getAll($page, $limit, $filters);
    }
}
```

### Services

Business logic layer with validation and error handling:

```php
use App\Services\UserService;

$userService = $container->get(UserService::class);

// Create user with validation
$user = $userService->createUser([
    'username' => 'john_doe',
    'email' => 'john@example.com',
    'password' => 'secure_password'
]);

// Bulk operations
$count = $userService->bulkActivate([1, 2, 3, 4]);
```

### Controllers

Standardized controllers extending `BaseController`:

```php
class UserController extends BaseController
{
    public function index(Request $request, Response $response): Response
    {
        try {
            $pagination = $this->getPaginationParams($request);
            $filters = $this->getFilterParams($request, ['company_id', 'is_active']);
            
            $users = $this->userService->getUsers(
                $pagination['page'],
                $pagination['limit'],
                $filters
            );

            return $this->successResponse($response, $this->transformPaginatedResults($users));
        } catch (\Exception $e) {
            return $this->handleException($response, $e);
        }
    }
}
```

## 🔐 Authentication & Authorization

### JWT Authentication

The API uses JWT tokens for authentication:

```bash
# Login
POST /auth/login
{
    "email": "user@example.com",
    "password": "password"
}

# Response
{
    "status": "success",
    "data": {
        "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
        "refresh_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
        "expires_in": 3600,
        "user": { ... }
    }
}
```

### RBAC System

The application implements a comprehensive Role-Based Access Control system:

- **Roles**: super_admin, admin, moderator, company_admin, user, viewer
- **Modules**: dashboard, users, companies, reports, analytics, settings, admin
- **Permissions**: can_view, can_create, can_edit, can_delete, can_manage

## 📚 API Endpoints

### Authentication
```
POST   /auth/login              # User login
POST   /auth/register           # User registration  
POST   /auth/logout             # User logout
POST   /auth/refresh            # Refresh token
POST   /auth/forgot-password    # Forgot password
POST   /auth/reset-password     # Reset password
GET    /auth/me                 # Get current user
```

### Users
```
GET    /users                   # Get all users
POST   /users                   # Create user
GET    /users/{id}              # Get user by ID
PUT    /users/{id}              # Update user
DELETE /users/{id}              # Delete user
GET    /users/search            # Search users
POST   /users/bulk-activate     # Bulk activate users
POST   /users/bulk-deactivate   # Bulk deactivate users
GET    /users/profile           # Get current user profile
PUT    /users/profile           # Update current user profile
```

### Companies
```
GET    /companies               # Get all companies
POST   /companies               # Create company
GET    /companies/{id}          # Get company by ID
PUT    /companies/{id}          # Update company
DELETE /companies/{id}          # Delete company
GET    /companies/search        # Search companies
GET    /companies/filter        # Filter companies
POST   /companies/{id}/social   # Add social link
DELETE /companies/{id}/social/{link_id}  # Remove social link
```

### Reports
```
GET    /reports                 # Get all reports
POST   /reports                 # Create report
GET    /reports/{id}            # Get report by ID
PUT    /reports/{id}            # Update report
DELETE /reports/{id}            # Delete report
POST   /reports/generate        # Generate report
GET    /reports/{id}/export     # Export report
POST   /reports/schedule        # Schedule report
```

### Admin
```
GET    /admin/dashboard         # Admin dashboard
GET    /admin/users             # Admin user management
GET    /admin/companies         # Admin company management
POST   /admin/bulk-user-action  # Bulk user actions
POST   /admin/bulk-company-action # Bulk company actions
GET    /admin/health            # System health check
GET    /admin/logs              # Application logs
POST   /admin/clear-cache       # Clear cache
```

## 🧪 Testing

### Manual Testing

You can test the API using tools like Postman or curl:

```bash
# Test user creation
curl -X POST http://localhost/users \
  -H "Content-Type: application/json" \
  -d '{"username":"testuser","email":"test@example.com","password":"password123"}'

# Test authentication
curl -X POST http://localhost/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"test@example.com","password":"password123"}'
```

## 🔧 Development

### Adding New Features

1. **Create Model**: Extend `BaseModel` for new entities
2. **Create Repository**: Implement repository interface
3. **Create Service**: Add business logic and validation
4. **Create Controller**: Extend `BaseController`
5. **Add Routes**: Define API endpoints
6. **Update Permissions**: Add module/role permissions if needed

### Database Migrations

For schema changes, update `database/schema.sql` and run:

```bash
mysql -u root -p reporev < database/schema.sql
```

## 🚀 Deployment

### Production Checklist

1. **Environment**: Set `APP_DEBUG=false` in production
2. **Security**: Use strong JWT secrets and database passwords
3. **HTTPS**: Always use HTTPS in production
4. **Database**: Regular backups and monitoring
5. **Logs**: Configure proper log rotation
6. **Cache**: Enable OPcache for PHP
7. **Monitoring**: Set up application monitoring

### Performance Optimization

- Enable database query caching
- Use Redis for session storage
- Implement API rate limiting
- Optimize database indexes
- Enable gzip compression
- Use CDN for static assets

## 📝 Contributing

1. Fork the repository
2. Create a feature branch
3. Follow PSR-12 coding standards
4. Add tests for new features
5. Submit a pull request

## 📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

## 🤝 Support

For support and questions:
- Create an issue in the repository
- Email: support@reporev.com
- Documentation: [API Documentation](https://docs.reporev.com)

---

**Built with ❤️ using Slim Framework 4 and Eloquent ORM**