clqms-be/.serena/memories/suggested_commands.md

# CLQMS Suggested Commands

## Database Commands

### Migrations
```bash
# Run all pending migrations
php spark migrate

# Run specific migration
php spark migrate [migration_file]

# Rollback last batch of migrations
php spark migrate:rollback

# Rollback and re-run migrations
php spark migrate:refresh

# Refresh and seed database
php spark migrate:refresh --seed

# Check migration status
php spark migrate:status
```

### Database Seeding
```bash
# Run all seeders
php spark db:seed

# Run specific seeder
php spark db:seed DBSeeder

# Create new database
php spark db:create
```

### Database Query
```bash
# Get table information
php spark db:table [table_name]
```

## Testing Commands

### PHPUnit Tests
```bash
# Run all tests
vendor/bin/phpunit

# Run specific test file (IMPORTANT for debugging)
vendor/bin/phpunit tests/feature/UniformShowTest.php
vendor/bin/phpunit tests/feature/Patient/PatientCreateTest.php

# Run tests in specific directory
vendor/bin/phpunit tests/feature/Patient/

# Run tests with coverage (text output)
vendor/bin/phpunit --coverage-text=tests/coverage.txt -d memory_limit=1024m

# Run tests with coverage (HTML report)
vendor/bin/phpunit --coverage-text=tests/coverage.txt --coverage-html=tests/coverage/ -d memory_limit=1024m

# Run with verbose output
vendor/bin/phpunit --verbose

# Run specific test method
vendor/bin/phpunit --filter testCanCreatePatient
```

## Code Generation Commands

### Generate Code Files
```bash
# Generate new model
php spark make:model ModelName

# Generate new controller
php spark make:controller ControllerName

# Generate new migration
php spark make:migration MigrationName

# Generate new seeder
php spark make:seeder SeederName

# Generate new test
php spark make:test TestName

# Generate scaffold (complete set)
php spark make:scaffold ModelName
```

## Development Server

### Start Development Server
```bash
# Start CodeIgniter dev server (default port 8080)
php spark serve

# Start on specific port
php spark serve --port=8080

# Start with specific host
php spark serve --host=0.0.0.0
```

## Cache Management

### Clear Caches
```bash
# Clear application cache
php spark cache:clear

# Show cache information
php spark cache:info

# Clear debug bar JSON files
php spark debugbar:clear

# Clear log files
php spark logs:clear
```

## System Utilities

### Configuration & Environment
```bash
# Get current environment
php spark env

# Set environment
php spark env development

# Check configuration values
php spark config:check

# Check php.ini values (for production)
php spark phpini:check

# Verify namespaces
php spark namespaces
```

### Routes
```bash
# Display all routes
php spark routes

# Check filters for a route
php spark filter:check
```

### Optimization
```bash
# Optimize for production
php spark optimize
```

## Utility Commands

### Encryption
```bash
# Generate new encryption key (writes to .env)
php spark key:generate
```

### Publish
```bash
# Publish predefined resources
php spark publish
```

## General Utility Commands (Windows)

### File & Directory Operations
```bash
# List files in current directory
dir

# List files with details
dir /a

# Change directory
cd path\to\directory

# Go to parent directory
cd ..

# Create directory
mkdir directory_name

# Remove directory (empty)
rmdir directory_name

# Remove directory with contents
rmdir /s /q directory_name

# Copy file
copy source_file destination

# Move/Rename file
move source destination

# Delete file
del filename

# Search for file
dir /s filename
```

### File Content Operations
```bash
# Display file content
type filename

# Display file content page by page
more filename

# Search for text in file
findstr "pattern" filename

# Search recursively
findstr /s /i "pattern" *.php
```

### Git Commands
```bash
# Check git status
git status

# View changes
git diff

# View staged changes
git diff --staged

# Add files to staging
git add .

# Add specific file
git add path/to/file

# Commit changes
git commit -m "commit message"

# Push to remote
git push

# Pull from remote
git pull

# View commit history
git log

# View commit history with graph
git log --graph --oneline

# Create new branch
git checkout -b branch_name

# Switch branch
git checkout branch_name

# Merge branch
git merge branch_name

# View branches
git branch
```

### Process Management
```bash
# List running processes
tasklist

# Kill process by PID
taskkill /PID pid_number

# Kill process by name
taskkill /IM process_name.exe

# Kill process forcefully
taskkill /F /PID pid_number
```

### Network Operations
```bash
# Check port usage
netstat -an | findstr :port

# Test network connectivity
ping hostname

# View active connections
netstat -an
```

## After Task Completion Checklist

When completing a task, run the following commands to ensure code quality:

### 1. Run Tests
```bash
# Run all tests
vendor/bin/phpunit

# If tests fail, run specific test file for debugging
vendor/bin/phpunit tests/feature/[SpecificTestFile].php
```

### 2. Check for Linting Issues (if configured)
```bash
# Check for PHP syntax errors
php -l app/Controllers/YourController.php
php -l app/Models/YourModel.php

# Run any custom linting tools if configured in composer.json
composer test  # if 'test' script includes linting
```

### 3. Type Checking (if configured)
```bash
# Run static analysis tools if configured
vendor/bin/phpstan analyse  # if phpstan is installed
vendor/bin/psalm  # if psalm is installed
```

### 4. Database Verification
```bash
# Check migration status
php spark migrate:status

# If you created a migration, run it
php spark migrate
```

### 5. API Documentation Update (CRITICAL)
```bash
# After modifying ANY controller, MUST update api-docs.yaml
# This is a manual process - edit public/api-docs.yaml

# Verify YAML syntax (optional, if yamllint is available)
yamllint public/api-docs.yaml
```

### 6. Code Review Checklist
- [ ] All tests passing
- [ ] No PHP syntax errors
- [ ] Database migrations applied (if any)
- [ ] API documentation updated (`public/api-docs.yaml`)
- [ ] Code follows style conventions (see `code_style_conventions.md`)
- [ ] Proper error handling in place
- [ ] Input validation implemented
- [ ] JWT authentication required where needed
- [ ] UTC date handling via BaseModel
- [ ] Soft delete using `DelDate` where applicable
- [ ] ValueSet lookups properly used and cached cleared if modified

### 7. Verify API Endpoints (if applicable)
```bash
# If you have curl or a REST client, test the endpoints
# Example using curl:
curl -X GET http://localhost:8080/api/patient -H "Cookie: token=your_jwt_token"
```

## Common Workflows

### Creating a New API Endpoint
1. Create controller: `php spark make:controller ControllerName`
2. Create model: `php spark make:model ModelName`
3. Create migration (if new table): `php spark make:migration MigrationName`
4. Run migration: `php spark migrate`
5. Add routes in `app/Config/Routes.php`
6. Implement controller methods following pattern
7. Create tests: `php spark make:test Feature/EndpointNameTest`
8. Run tests: `vendor/bin/phpunit tests/feature/EndpointNameTest.php`
9. Update `public/api-docs.yaml`
10. Verify with test client

### Debugging a Failing Test
1. Run specific test file: `vendor/bin/phpunit tests/feature/SpecificTest.php`
2. Add debug output: `var_dump($result); die();` temporarily
3. Check database state: View with database client
4. Check logs: `writable/logs/` directory
5. Run with verbose: `vendor/bin/phpunit --verbose`
6. Isolate specific test: `vendor/bin/phpunit --filter testMethodName`

### Working with ValueSets
1. Create/edit JSON file: `app/Libraries/Data/valuesets/{name}.json`
2. Clear cache: `ValueSet::clearCache();` (in code) or via code
3. Verify via API: GET `/api/valueset/{name}`
4. Test lookup: `ValueSet::get('name')` in controller/model