Safe Laravel Package

Getting Started

1. Install: Run composer require thecodingmachine/safe — the package is lightweight (≈1MB) with no external dependencies beyond PHP ≥7.4.
2. First Use: Replace vulnerable native functions with Safe\ equivalents. For example:

   // Before (prone to silent failure)
   $data = file_get_contents('config.json');
   if ($data === false) { /* handle error */ }
   
   // After (explicit exception)
   try {
       $data = Safe\file_get_contents('config.json');
   } catch (Safe\Exception $e) {
       logger()->error('Failed to load config', ['exception' => $e]);
       throw new ConfigLoadException($e->getMessage(), 0, $e);
   }
   

3. Start here: Focus on filesystem (Safe\file_get_contents, Safe\fopen), JSON (Safe\json_decode), and string functions (Safe\sprintf) — these show the biggest ergonomics improvement.

Implementation Patterns

• Batch migration: Use IDEFind (Safe\ prefix) to identify candidates — functions that return false or emit warnings are ideal. Prioritize critical paths (e.g., config loading, auth token validation).
• Wrapper pattern: For domain-specific operations, create typed Safe wrappers:

  use Safe;
  
  class ConfigService
  {
      public function load(string $file): array
      {
          return Safe\json_decode(
              Safe\file_get_contents($file),
              true
          );
      }
  }
  

• Error context injection: Use Safe\ErrorException (implements \Safe\Exception) to attach extra context:

  try {
      return Safe\json_decode($raw, true);
  } catch (Safe\Exception $e) {
      throw new JsonDecodingException($e->getMessage(), $e->getCode(), $e, ['file' => $file]);
  }
  

• Test strategy: Combine with PHPUnit’s expectThrows or custom assertions to validate exception triggers in integrations.

Gotchas and Tips

• Exception hierarchy: All Safe exceptions extend \Safe\Exception (strictly typed), not Error. Use instanceof Safe\Exception for catching, not generic Throwable.
• Autoload quirks: Safe uses class aliasing. Ensure Composer’s autoloader includes it — Safe\ is PSR-4 autoloaded, but verify vendor/composer/installed.php has it.
• Type inference: Static analyzers (PHPStan/Psalm) may misinfer return types. Add /** @return non-empty-string */ or use @phpstan-assert annotations for wrapped calls.
• Override warning suppressions: Avoid @-operator with Safe functions — suppressing exceptions defeats the purpose. If unavoidable, use try { ... } catch { ... } inside @ to preserve context.
• Extend safely: Create your own Safe wrappers using Safe\functions\functions.php as a reference — implement in Safe\MyApp\MyFunc() to avoid conflicts.
• CI tip: Enable phpstan with safe extension (via extension=safe.so if compiled, or via auto-prepend) to detect false returns in Safe function callers.