UnknownSec Bypass 403

: /mnt/lmsestudio-instance-vol002/lms_8167adff8173/ [ drwxr-xr-x ]
name : AGENTS.md # AGENTS.md This file provides context and instructions to help AI coding agents work effectively on the EstudioLMS project (main LMS platform). ## Project Overview **EstudioLMS** is the main Learning Management System (LMS) platform built with Laravel 5.1. This is the **original single-tenant version** of the LMS, serving as the foundation for the multi-tenant version. It provides comprehensive e-learning capabilities including course management, user authentication, payment processing, gamification, and content delivery. ### Key Differences from Multi-Tenant Version - **Single-tenant architecture** - Each instance serves one organization - **Laravel 5.1** - Older, more stable version - **No tenancy package** - Simpler database structure - **Direct deployment** - No tenant provisioning needed ### Key Technologies - **Backend**: Laravel 5.1 (PHP Framework) - **Database**: MySQL with Doctrine ORM 2.5.6 - **Frontend**: Blade templates, jQuery, Bootstrap - **Payment Gateways**: PagarMe, PagSeguro, PayPal (via Omnipay) - **Testing**: PHPUnit ~4.0, PHPSpec ~2.1 - **PDF Generation**: Snappy (wkhtmltopdf wrapper) - **Media Processing**: Intervention Image - **Authentication**: Laravel Socialite (Facebook, Google, etc.) - **Authorization**: Zizaco Entrust (Role-Based Access Control) - **Cache/Queue**: Redis (Predis) - **Rich Text Editor**: CKEditor with elFinder file manager - **Backup**: Spatie Laravel Backup ^3.0 ### Project Structure ``` app/ ├── Http/Controllers/ # Application controllers (Admin, Site, Environment) ├── Services/ # Business logic layer │ ├── Admin/ # Admin-specific services │ ├── Hires/ # Payment and hiring services │ ├── Environment/ # Student environment services │ └── Site/ # Public site services ├── Models/ # Eloquent models ├── Repositories/ # Data access layer (prettus/l5-repository) └── Entities/ # Doctrine entities (if used) resources/ ├── views/ # Blade templates │ ├── admin/ # Admin panel views │ ├── site/ # Public site views │ └── environment/ # Student environment views └── lang/ # Translations (PT-BR, EN, ES) database/ ├── migrations/ # Database migrations └── seeds/ # Database seeders tests/ # PHPUnit and PHPSpec tests public/ # Public assets routes/ # Application routes config/ # Configuration files ``` ### Architecture Patterns - **Repository Pattern**: Data access abstraction using `prettus/l5-repository` v2.6.32 - **Service Layer**: Business logic separated from controllers - **Role-Based Access Control**: Entrust for permissions and roles - **Translation**: Dimsav Laravel Translatable for multi-language models - **Doctrine ORM**: Used alongside Eloquent for complex queries ## Setup and Installation ### Prerequisites - PHP >= 5.6.4 (ideally PHP 5.6 or 7.1) - Composer - Node.js and NPM - MySQL 5.6+ - Redis (for caching and queues) - wkhtmltopdf (for PDF generation) ### Initial Setup ```bash # Clone the repository git clone <repository-url> cd estudiolms # Install PHP dependencies composer install # Copy environment file cp .env.example .env # Configure database in .env file # DB_CONNECTION=mysql # DB_HOST=127.0.0.1 # DB_PORT=3306 # DB_DATABASE=estudiolms # DB_USERNAME=root # DB_PASSWORD= # Generate application key php artisan key:generate # Run migrations php artisan migrate # Run seeders (if available) php artisan db:seed # Optimize application php artisan optimize ``` ### Additional Configuration #### Storage Setup ```bash # Create symbolic link for storage php artisan storage:link # Set proper permissions chmod -R 775 storage bootstrap/cache ``` #### Cache Configuration ```bash # Clear and cache configuration php artisan config:cache php artisan route:cache ``` ### Development Server ```bash # Start development server php artisan serve # Or use Docker docker-compose up -d ``` ## Testing ### PHPUnit Tests ```bash # Run all tests vendor/bin/phpunit # Run specific test file vendor/bin/phpunit tests/ExampleTest.php # Run with coverage vendor/bin/phpunit --coverage-html coverage/ ``` ### PHPSpec Tests ```bash # Run all specs vendor/bin/phpspec run # Run specific spec vendor/bin/phpspec run spec/PathToSpec.php # Create new spec vendor/bin/phpspec describe ClassName ``` ## Code Style Guidelines ### PHP Code Style - Follow **PSR-2** coding standards (Laravel 5.1 era) - Keep controllers **thin** - move business logic to Services - Use **Repository Pattern** for data access - Prefer **dependency injection** over facades where possible - Use **type hinting** where available (limited in PHP 5.6) ### Naming Conventions - **Controllers**: Singular noun + "Controller" (e.g., `UserController`) - **Models**: Singular noun (e.g., `User`, `Course`) - **Services**: Descriptive name + "Service" or "Services" (e.g., `BillingServices`) - **Repositories**: Model name + "Repository" (e.g., `UserRepository`) - **Methods**: camelCase for methods (e.g., `getUserData()`) - **Variables**: camelCase (e.g., `$userData`) - **Constants**: SCREAMING_SNAKE_CASE (e.g., `MAX_ATTEMPTS`) ### Blade Templates - Use **@extends** and **@section** for layouts - Prefer **@include** for partials - Escape output with **{{ $variable }}** (default) - Use **{!! $html !!}** only for trusted HTML content - Keep business logic out of views ### Database - **Migrations**: Use descriptive names with timestamps - Always include **up()** and **down()** methods - Use **Schema::table()** for modifications - Add **foreign key constraints** where appropriate - Use **indexes** for frequently queried columns ### JavaScript - Use **jQuery** for DOM manipulation - Prefer **const** and **let** over **var** (if using ES6 transpiler) - Comment complex logic clearly - Keep inline scripts minimal - prefer external files ## Role-Based Access Control (Entrust) ### Using Roles and Permissions ```php // Check if user has role if ($user->hasRole('admin')) { // User is admin } // Check if user has permission if ($user->can('create-posts')) { // User can create posts } // In Blade templates @role('admin') <!-- Content for admins --> @endrole @permission('edit-posts') <!-- Content for users with edit-posts permission --> @endpermission ``` ### Creating Roles and Permissions ```php // Create role $admin = new Role(); $admin->name = 'admin'; $admin->display_name = 'Administrator'; $admin->save(); // Create permission $permission = new Permission(); $permission->name = 'create-courses'; $permission->display_name = 'Create Courses'; $permission->save(); // Attach permission to role $admin->attachPermission($permission); // Attach role to user $user->attachRole($admin); ``` ## Payment Integration The system integrates multiple payment gateways: ### PagarMe - Service: `app/Services/PagarMeService.php` - API Service: `app/Services/PagarMeServiceApi.php` - Version: 3.8.1a - Supports: Credit card, Boleto - Brazilian payment gateway ### PagSeguro - Integration via `phpsc/pagseguro` - Service: Check `app/Services/Hires/BoletoService.php` - Brazilian payment platform ### PayPal - Integration via Omnipay v4.0.1 - Service: Check controllers in `app/Http/Controllers/` **Important**: Never commit payment credentials. Use environment variables. ## Security Considerations ### Critical Security Rules 1. **Never commit** `.env` files or credentials 2. **Always validate** user input on the server side 3. **Use prepared statements** (Eloquent ORM handles this) 4. **Sanitize output** in Blade templates (use `{{ }}` not `{!! !!}`) 5. **Implement CSRF protection** (Laravel includes this by default) 6. **Rate limit** authentication endpoints 7. **Validate file uploads** (type, size, content) 8. **Use HTTPS** in production 9. **Keep dependencies updated** (considering compatibility) ### Authentication & Authorization - Laravel 5.1's built-in authentication system - Social login: Laravel Socialite (Facebook, Google) - Role-based permissions: Zizaco Entrust - Check `config/auth.php` for configuration ### Important Security Notes - Laravel 5.1 is an **older version** - be aware of security advisories - Ensure all packages are at their latest compatible versions - Implement additional security layers for production ## Database ### Connection Configuration - Single database for all application data - Configure in `.env` and `config/database.php` - Supports MySQL, PostgreSQL, SQLite ### Important Tables - `users` - System users - `roles` - User roles (Entrust) - `permissions` - User permissions (Entrust) - `courses` - Course management - `lessons` - Course lessons - `enrollments` - Student enrollments - Check migrations in `database/migrations/` for complete schema ### Running Migrations ```bash # Run all pending migrations php artisan migrate # Rollback last migration php artisan migrate:rollback # Reset all migrations php artisan migrate:reset # Fresh migration with seed php artisan migrate:fresh --seed # Check migration status php artisan migrate:status ``` ## Gamification System The platform includes a gamification system: ### Services - `app/Services/Environment/GamificationService.php` - `app/Services/Admin/BadgeService.php` - `app/Services/Admin/BadgeRuleService.php` ### Features - Badges for student achievements - Points system - Leaderboards - Achievement rules ## Translation System ### Using Translations ```php // In PHP __('messages.welcome') trans('messages.welcome') // In Blade {{ __('messages.welcome') }} {{ trans('messages.welcome') }} ``` ### Translation Files Located in `resources/lang/{locale}/` ### Translation Manager - Access via `/translations` route - Uses `barryvdh/laravel-translation-manager` - Manage translations via web interface ### Translatable Models ```php // Using dimsav/laravel-translatable class Course extends Model { use \Dimsav\Translatable\Translatable; public $translatedAttributes = ['title', 'description']; } ``` ## File Management ### elFinder Integration - File manager available via `barryvdh/laravel-elfinder` - Version: 0.3.11 - Configuration: `config/elfinder.php` - Integrated with CKEditor for content management ### Image Processing - Uses Intervention Image - Resize, crop, and optimize images - Support for multiple formats ## Backup System ### Spatie Laravel Backup ```bash # Run backup php artisan backup:run # Backup only database php artisan backup:run --only-db # Backup only files php artisan backup:run --only-files # List backups php artisan backup:list # Clean old backups php artisan backup:clean ``` ### Configuration - Config file: `config/laravel-backup.php` - Supports local and S3 storage (AWS S3 via league/flysystem-aws-s3-v3) ## Common Tasks ### Creating a New Feature 1. Create migration: `php artisan make:migration create_feature_table` 2. Create model: `php artisan make:model Feature` 3. Create repository: Follow `prettus/l5-repository` pattern 4. Create service in `app/Services/` 5. Create controller: `php artisan make:controller FeatureController` 6. Define routes in `routes/web.php` 7. Create views in `resources/views/` 8. Write tests (PHPUnit/PHPSpec) ### Adding a New Role/Permission ```bash # Create migration for new permissions php artisan make:migration add_new_permissions # In migration, seed the permissions Permission::create([ 'name' => 'manage-feature', 'display_name' => 'Manage Feature' ]); ``` ### Working with Repositories ```php // Create repository php artisan make:repository FeatureRepository // Use in controller public function __construct(FeatureRepository $repository) { $this->repository = $repository; } // Repository methods $this->repository->all(); $this->repository->find($id); $this->repository->create($data); $this->repository->update($data, $id); ``` ## Git Workflow ### Branch Naming - `feature/description` - New features - `bugfix/description` - Bug fixes - `hotfix/description` - Critical production fixes - `refactor/description` - Code refactoring ### Commit Messages Follow conventional commits format: ``` type(scope): brief description Longer description if needed - Bullet points for details ``` **Types**: feat, fix, docs, style, refactor, test, chore ### Before Committing ```bash # Run tests vendor/bin/phpunit vendor/bin/phpspec run # Clear caches php artisan config:clear php artisan cache:clear php artisan route:clear ``` ## Development Environment Tips ### IDE Configuration - Laravel IDE Helper is included (`barryvdh/laravel-ide-helper`) - Generate helper files: ```bash php artisan ide-helper:generate php artisan ide-helper:models php artisan ide-helper:meta ``` ### Debug Tools - **Laravel Debugbar** is available (`barryvdh/laravel-debugbar`) - Check `.env` - set `APP_DEBUG=true` for development - Use `dd()` and `dump()` for debugging - Check `storage/logs/laravel.log` for errors ### Cache Management ```bash # Clear all caches php artisan cache:clear php artisan config:clear php artisan route:clear php artisan view:clear # Rebuild caches (production) php artisan config:cache php artisan route:cache php artisan optimize ``` ### Queue Workers ```bash # Run queue worker php artisan queue:work # For development (restarts on code changes) php artisan queue:work --tries=3 # Run specific queue php artisan queue:work --queue=high,default ``` ## API Reference Check available routes: ```bash php artisan route:list ``` Routes are defined in: - `app/Http/routes.php` (Laravel 5.1 uses single routes file) ## Troubleshooting ### Common Issues **Issue**: Class not found errors ```bash # Regenerate autoload files composer dump-autoload # Clear compiled files php artisan clear-compiled php artisan optimize ``` **Issue**: Migrations fail ```bash # Check database connection php artisan migrate:status # Reset and re-run php artisan migrate:refresh ``` **Issue**: Assets not loading ```bash # Clear views cache php artisan view:clear # Check public/storage symlink ls -la public/storage ``` **Issue**: Permission denied errors ```bash # Fix storage permissions chmod -R 775 storage bootstrap/cache chown -R www-data:www-data storage bootstrap/cache ``` **Issue**: Composer dependencies conflict ```bash # This is Laravel 5.1 - old PHP version required # Ensure PHP 5.6 or 7.0 is being used php -v # Update dependencies carefully composer update --with-dependencies ``` ## Laravel 5.1 Specific Notes ### Important Differences from Modern Laravel - **Routes file**: `app/Http/routes.php` (not `routes/web.php`) - **Middleware**: Defined differently in Kernel - **Form requests**: Different namespace and structure - **Validation**: Some rules work differently - **Eloquent**: Fewer features than modern versions - **No Laravel Mix**: Uses Elixir (Gulp-based) ### Running Elixir ```bash # Install Node dependencies npm install # Run Gulp gulp # Watch for changes gulp watch ``` ## Additional Resources - **Laravel 5.1 Documentation**: https://laravel.com/docs/5.1 - **Repository Pattern**: https://github.com/andersao/l5-repository - **Entrust Documentation**: https://github.com/Zizaco/entrust - **Laravel Socialite**: https://laravel.com/docs/5.1/authentication#social-authentication ## Contributing ### Pull Request Guidelines 1. Create a feature branch from `main`/`master` 2. Write clear, descriptive commit messages 3. Include tests for new functionality 4. Update documentation as needed 5. Ensure all tests pass 6. Request code review ### Code Review Checklist - [ ] Code follows PSR-2 standards - [ ] Tests are included and passing - [ ] No sensitive data in commits - [ ] Documentation updated - [ ] No breaking changes without discussion - [ ] Security implications reviewed - [ ] Compatible with PHP 5.6/7.0 ## Project Rules and Best Practices ### Code Documentation - **Always comment your code**: Every new function, class, or complex logic must include clear comments explaining its purpose and behavior - Use PHPDoc blocks for all methods with proper `@param`, `@return`, and `@throws` annotations - Add inline comments for non-obvious logic or business rules ### Testing Guidelines - **Avoid creating test scripts** unless explicitly requested by the user - **Remove test scripts after use**: Any test scripts created during development must be deleted once testing is complete - Keep the codebase clean and free of temporary testing code - Prefer using existing test suites (PHPUnit, PHPSpec) when validation is needed ### Documentation Management - **DOCUMENTATION.md**: Create and update documentation for relevant features and routines in this file - Document new features, complex workflows, and important business logic - Keep documentation up-to-date when making changes to existing features - Include usage examples, configuration details, and integration notes ### Bug Tracking - **BUGTRACK.md**: Register pending bugs and issues for later treatment - Document the date, description, affected files, and reproduction steps - **After fixing a bug**: Update BUGTRACK.md with execution date, solution implemented, and files modified - Maintain a complete audit trail of all bug fixes ### Communication - **Always respond in Portuguese (PT-BR)**: All communication with users must be in Portuguese - Code comments and documentation can be in English for technical clarity - Commit messages should follow conventional commits in English ## Notes for AI Agents - This is a **legacy Laravel 5.1 codebase** - use appropriate syntax and patterns - **Single-tenant architecture** - simpler than the multi-tenant version - **PHP 5.6/7.0 compatibility** - avoid modern PHP features - Uses **both Eloquent and Doctrine** - check which is used where - **Entrust for RBAC** - always consider role/permission checks - **Payment processing** is critical - never mock or skip validation - The project uses **Portuguese (PT-BR)** as primary language - Uses **Gulp/Elixir** for asset compilation (not Laravel Mix) - **jQuery and Bootstrap** are standard - don't suggest modern alternatives - Some packages are pinned to specific versions for compatibility - Always test with PHPUnit AND PHPSpec when available - The `optimize` command is important for production performance - **Follow the project rules** outlined in "Project Rules and Best Practices" section above