PHP/Laravel Package Development Rules

You are an expert in Laravel Package Development. This project is an open-source Laravel package for AI-powered translations.

- Always write code and documentation in English. This is a public package for the global Laravel community.
- Write code that is clean, maintainable, and well-documented. Focus on package-specific functionality.
- Follow open-source best practices and Laravel package development guidelines.

## PHP/Laravel Package Development Rules
- Use PHP 8.1 features exclusively:
  - Match expressions for clean control flow
  - Named arguments for better API usability
  - Union types for flexible method signatures
  - Constructor property promotion
  - Attributes for metadata
  - Nullsafe operator for safe chaining
  - Modern string functions (str_contains, str_starts_with, str_ends_with)
  - Readonly properties for immutable data
  - Intersection types where needed
  - Never return type for terminators

## Package Structure and Style
- Follow PSR-12 coding standards strictly
- One class per file
- Use "{$variable}" for string interpolation
- Implement Laravel's ServiceProvider pattern
- Create clear and consistent package configuration
- Follow Laravel package naming conventions
- Provide comprehensive test coverage
- Include proper package documentation

## Documentation
- Write clear PHPDoc comments for all public APIs
- Document all configuration options
- Provide usage examples in README.md
- Include implementation comments for:
  - Complex translation logic
  - AI integration points
  - Performance considerations
  - Error handling strategies
- Don't numbering comments

## Package Features
- Implement robust error handling
- Provide clear logging and debugging
- Support multiple AI providers:
  - OpenAI (GPT-4, GPT-3.5)
  - Anthropic (Claude)
- Support various translation styles
- Handle rate limiting and quotas
- Implement caching where appropriate

## Laravel Debugging
- Use dump() for inspecting variables without stopping execution:
  ```php
  dump($variable);
  dump($translationResult, $aiResponse);
  ```
- Use dd() for critical debugging points:
  ```php
  dd($variable);
  ```
- Strategic debug placement:
  ```php
  dump('Translation Start', $input);
  // Translation logic
  dump('Translation Complete', $result);
  ```
- Use Laravel Debug Bar in development:
  ```bash
  composer require barryvdh/laravel-debugbar --dev
  ```
- API debugging with Log::debug():
  ```php
  Log::debug('AI API Request', ['prompt' => $prompt]);
  ```
- Debug collections with tap():
  ```php
  $strings->map(function ($string) {
      return tap($string->translate(), function ($translated) use ($string) {
          dump("Translating string {$string->key}", $translated);
      });
  });
  ```

## Command-line Debugging
- Interactive debugging with Tinker:
  ```bash
  echo 'App\Models\LocalizedString::first()' | php artisan tinker
  ```
- Monitor Laravel logs:
  ```bash
  tail -f storage/logs/laravel.log
  ```
- Clear caches:
  ```bash
  php artisan cache:clear
  php artisan config:clear
  ```
- Debug tests with verbose output:
  ```bash
  php artisan test --filter=TranslationTest -v
  ```
- Test specific code:
  ```bash
  php artisan tinker
  >>> require app_path('path/to/translation/file.php');
  >>> $result = (new TranslationService())->translate('test');
  >>> dump($result);
  ```
- Analyze database queries:
  ```php
  DB::enableQueryLog();
  // Translation queries
  dd(DB::getQueryLog());
  ```

## Testing
- Write comprehensive unit tests
- Include integration tests for AI providers
- Test error cases and edge conditions
- Provide test coverage reports

## Security
- Secure API key handling
- Input validation and sanitization
- Rate limiting protection
- Error message security

## Performance
- Optimize API calls
- Implement caching strategies
- Handle batch translations efficiently
- Monitor token usage

## Community Guidelines
- Accept contributions via Pull Requests
- Maintain CHANGELOG.md
- Follow Semantic Versioning
- Provide issue templates
- Include contribution guidelines