Crayfish Commons Laravel Package

## Getting Started

### **Minimal Setup**
1. **Installation**
   Update to the latest version via Composer in your Laravel project:
   ```bash
   composer require islandora/crayfish-commons:^4.1.0

Publish the config (if available) with:

php artisan vendor:publish --provider="Islandora\CrayfishCommons\CrayfishCommonsServiceProvider"

2. First Use Case: Enhanced Input Escaping Leverage improved escaping utilities for security-sensitive data:

   use Islandora\CrayfishCommons\Facades\CrayfishSanitizer;
   
   $safeInput = CrayfishSanitizer::escapeHtml($userInput);
   $safeJson = CrayfishSanitizer::escapeJson($apiPayload);
   

3. Key Entry Points

   • CrayfishLogger: Centralized logging facade (unchanged).
   • CrayfishResponse: Standardized API response formatting (unchanged).
   • CrayfishValidator: Shared validation rules (unchanged).
   • CrayfishSanitizer: New utility for robust input escaping (4.1.0+).

Implementation Patterns

1. Logging Workflow (Unchanged)

• Structured Logging: Maintain existing patterns with added context:

  CrayfishLogger::debug('Processing request', [
      'service' => 'user-service',
      'request_id' => $request->header('X-Request-ID'),
  ]);
  

2. API Response Standardization (Unchanged)

• Consistent Format: Continue using CrayfishResponse:

  return CrayfishResponse::success($data, 'Resource fetched');
  

3. Input Sanitization (New in 4.1.0)

• HTML Escaping: Protect against XSS in user-generated content:

  $safeTitle = CrayfishSanitizer::escapeHtml($request->input('title'));
  

• JSON Payload Escaping: Secure API payloads before processing:

  $decoded = json_decode(CrayfishSanitizer::escapeJson($request->getContent()), true);
  

• Context-Aware Escaping: Use with validation for defense-in-depth:

  $validator = Validator::make($request->all(), [
      'description' => 'required|string|max:255',
  ]);
  $safeDescription = CrayfishSanitizer::escapeHtml($validator->validated('description'));
  

4. Service Communication (Unchanged)

• Event Dispatching: Continue using shared events:

  event(new \Islandora\CrayfishCommons\Events\ServiceEvent('user.created', $userData));
  

Gotchas and Tips

Pitfalls

1. Logger Configuration (Unchanged)

   • Verify config('logging.default') is set correctly (e.g., 'single').

2. Response Overrides (Unchanged)

   • Explicitly use CrayfishResponse facade to avoid conflicts.

3. Validation Rules (Unchanged)

   • Register custom rules in AppServiceProvider if not auto-discovered.

4. Escaping Pitfalls (New in 4.1.0)

   • Double Escaping: Avoid chaining escapeHtml() multiple times on the same data.

     // ❌ Avoid
     $doubleEscaped = CrayfishSanitizer::escapeHtml(
         CrayfishSanitizer::escapeHtml($input)
     );
     

   • Context Mismatch: Use escapeHtml() for browser output and escapeJson() for API payloads.
   • Performance: Escaping is lightweight, but batch operations (e.g., bulk API imports) may benefit from lazy escaping.

Debugging Tips (Updated)

• Log Levels: Use CrayfishLogger::setLevel('debug') temporarily.
• Request Tracing: Add X-Trace-ID for cross-service correlation:

  CrayfishLogger::setContext(['trace_id' => $request->header('X-Trace-ID')]);
  

• Sanitizer Validation: Verify escaping with:

  if (strpos($escaped, '&') !== false) {
      CrayfishLogger::debug('HTML escaping applied', ['input_sample' => substr($input, 0, 50)]);
  }
  

Extension Points (Updated)

1. Custom Log Handlers (Unchanged) Extend via config/logging.php:

   'channels' => [
       'crayfish' => [
           'driver' => 'single',
           'path' => storage_path('logs/crayfish.log'),
           'level' => 'debug',
       ],
   ],
   

2. Sanitizer Decorators (New in 4.1.0) Override escaping behavior globally:

   $this->app->singleton(\Islandora\CrayfishCommons\CrayfishSanitizer::class, function () {
       return new \App\Services\CustomCrayfishSanitizer();
   });
   

3. PHP Version Compatibility (4.1.0 Note)

   • The package now supports PHP 8.0+. If using older versions (e.g., 7.4), pin to ^4.0.0:

     composer require islandora/crayfish-commons:^4.0.0
     

Performance Notes (Updated)

• Avoid Over-Logging: Prefer info()/warning() in production.
• Escaping Optimization: For large datasets, escape in bulk:

  $safeTitles = array_map([CrayfishSanitizer::class, 'escapeHtml'], $titles);
  

• Build Matrix: The new build matrix (PR #66) ensures compatibility across PHP versions and Laravel 9/10.

Security Notes (New in 4.1.0)

• Always Escape: Treat escapeHtml()/escapeJson() as mandatory for:
  • User-generated content (e.g., comments, descriptions).
  • API inputs before processing (e.g., webhook payloads).
• Deprecated Functions: If using older code, replace manual htmlspecialchars() with CrayfishSanitizer::escapeHtml().
• Testing: Validate escaping with tools like OWASP ZAP to catch edge cases.

NO_UPDATE_NEEDED would **not** apply here due to the new `CrayfishSanitizer` feature and PHP version updates.