Pitcher Laravel Package

Getting Started

Minimal Setup

1. Install the Package

   composer require braune-digital/pitcher "^1.0"
   

   Note: Due to the package's age (last release in 2016), ensure your PHP version (7.4+) and dependencies (e.g., GuzzleHTTP) are compatible.

2. Register with Pitcher App

   • Sign up at pitcher-app.com to create a project.
   • Retrieve your satellite name and secret key from the dashboard.

3. First Pitch Initialize the client in a service or bootstrap file:

   use BrauneDigital\Pitcher\Client\BaseClient;
   
   $client = new BaseClient('YOUR_SATELLITE_NAME', 'YOUR_SECRET_KEY');
   $client->pitch(BaseClient::LEVEL_CRITICAL, 'Initial test message');
   

4. Verify Notifications Check your Pitcher App dashboard or configured channels (email, iOS push, etc.) for the test message.

First Use Case: Exception Logging

Wrap try-catch blocks to log unhandled exceptions:

try {
    // Risky operation (e.g., API call, DB query)
} catch (\Exception $e) {
    $client->pitch(
        BaseClient::LEVEL_ERROR,
        "Exception in [Module]: " . $e->getMessage() . "\nTrace: " . $e->getTraceAsString()
    );
    // Optionally rethrow or handle locally
}

Implementation Patterns

1. Integration with Laravel’s Exception Handler

Extend Laravel’s App\Exceptions\Handler to auto-pitch exceptions:

use BrauneDigital\Pitcher\Client\BaseClient;
use Illuminate\Foundation\Exceptions\Handler as ExceptionHandler;

class Handler extends ExceptionHandler
{
    protected $pitcher;

    public function __construct()
    {
        $this->pitcher = new BaseClient(config('pitcher.satellite'), config('pitcher.secret'));
    }

    public function report(\Throwable $exception)
    {
        $this->pitcher->pitch(
            $this->getLevel($exception),
            $exception->getMessage() . "\n" . $exception->getTraceAsString()
        );
        parent::report($exception);
    }

    protected function getLevel(\Throwable $exception): string
    {
        return $exception instanceof \ErrorException
            ? BaseClient::LEVEL_ERROR
            : BaseClient::LEVEL_CRITICAL;
    }
}

2. Configuration Management

Store credentials in .env:

PITCHER_SATELLITE=your_satellite_name
PITCHER_SECRET=your_secret_key

Access via Laravel’s config:

config('pitcher.satellite'); // 'your_satellite_name'

3. Logging Integration

Use Pitcher as a fallback logger for critical messages:

use Psr\Log\LoggerInterface;

class PitcherLogger implements LoggerInterface
{
    protected $client;

    public function __construct(BaseClient $client)
    {
        $this->client = $client;
    }

    public function emergency($message, array $context = [])
    {
        $this->client->pitch(BaseClient::LEVEL_CRITICAL, $message);
    }

    // Implement other PSR-3 methods (warning, error, etc.)
}

Register in config/logging.php:

'pitcher' => [
    'driver' => 'custom',
    'via' => PitcherLogger::class,
    'satellite' => env('PITCHER_SATELLITE'),
    'secret' => env('PITCHER_SECRET'),
],

4. Middleware for API Requests

Log failed API requests in middleware:

public function handle($request, Closure $next)
{
    try {
        return $next($request);
    } catch (\GuzzleHttp\Exception\RequestException $e) {
        $client->pitch(
            BaseClient::LEVEL_WARNING,
            "API Failure: " . $e->getMessage() . "\nURL: " . $e->getRequest()->getUri()
        );
        throw $e;
    }
}

Gotchas and Tips

1. Deprecation Risks

• No Active Maintenance: The package is archived (last release in 2016). Test thoroughly in staging before production.
• Dependency Conflicts: GuzzleHTTP v6 is outdated. Pin versions in composer.json:

  "require": {
      "guzzlehttp/guzzle": "^6.3",
      "braune-digital/pitcher": "^1.0"
  }
  

2. Debugging

• Response Validation: Always check the JSON response for success: false:

  $response = $client->pitch(BaseClient::LEVEL_ERROR, "Test");
  if (!$response['success']) {
      Log::error("Pitcher failed: " . json_encode($response['errors']));
  }
  

• Rate Limiting: Pitcher may throttle requests. Implement exponential backoff for retries.

3. Configuration Quirks

• Secret Exposure: Avoid hardcoding secrets. Use Laravel’s .env or a secrets manager.
• Satellite Naming: Use descriptive names (e.g., laravel-prod-api) for easier filtering in the Pitcher dashboard.

4. Extension Points

• Custom Payloads: Extend BaseClient to include additional metadata (e.g., user ID, request ID):

  $client->pitch(
      BaseClient::LEVEL_INFO,
      "User login failed",
      ['user_id' => auth()->id(), 'ip' => request()->ip()]
  );
  

  Note: Verify if Pitcher’s API supports custom payloads (check their docs or test with var_dump).

5. Fallback Strategies

• Local Logging: Combine Pitcher with Laravel’s default logger to ensure no data loss if Pitcher is unavailable:

  try {
      $client->pitch(BaseClient::LEVEL_ERROR, $message);
  } catch (\Exception $e) {
      Log::error("Pitcher failed: " . $e->getMessage() . "\nMessage: " . $message);
  }
  

6. Performance Considerations

• Async Pitching: For high-traffic apps, use queues to avoid blocking requests:

  dispatch(new PitchExceptionJob($message, $level));
  

  Implement PitchExceptionJob to extend BaseClient and use Laravel’s queue system.