Prowlphp Laravel Package

Getting Started

This is a single-purpose, thin wrapper around Prowl’s public HTTP API: you give it an API key and a payload (application, event, description, priority, optional url), and it pushes a notification to registered iOS devices. The package is archived (last release 2016), so treat it as a small vendored utility rather than a living dependency.

1. Get a Prowl API key. Install the Prowl iOS app, create an account, and generate an API key. Verify the key works before writing any integration code:

   curl https://api.prowlapp.com/publicapi/verify?apikey=YOUR_KEY
   

2. Install or vendor the package. Try Composer first; if the package no longer resolves from Packagist, copy the class into your project (e.g. app/Support/Prowl/) and autoload it manually.

   composer require xenji/prowlphp
   

3. Read the source before coding. Because the repository metadata is unavailable, confirm the actual class name, constructor signature, and send method in composer.json, the class file, and any README/examples. Most wrappers of this era expose either push(array $payload) or a positional send($application, $event, $description, $priority); do not assume.
4. Send a first test notification from a tinker session or an Artisan command:

   // Adapt class/method names to the package source.
   $prowl = new Prowl(config('services.prowl.api_key'));
   
   $prowl->push([
       'application' => 'Billing',
       'event'       => 'Payment failed',
       'description' => 'Invoice #1234 failed after 3 retries',
       'priority'    => 1,
       'url'         => 'https://ops.example.com/invoices/1234',
   ]);
   

5. First real use case: a scheduled health check or a queued job that alerts the on-call developer when a background process fails. This is the lowest-risk integration and validates credentials, network access, and delivery end-to-end.

Implementation Patterns

• Wrap it behind your own notifier interface. Do not scatter new Prowl(...) calls through the codebase. Define an AlertNotifier contract, implement a ProwlNotifier, and bind it in the container. This makes it trivial to swap in Pushover, ntfy, Slack, or a direct HTTP call when Prowl or this package becomes untenable.
• Centralize configuration. Keep the API key in config/services.php sourced from PROWL_API_KEY, and expose defaults for application name (per service/environment) and priority mapping.
• Map severity to Prowl priorities consistently. Use constants: -2 very low, -1 low, 0 normal, 1 high, 2 emergency. Reserve 2 for actual pages because it bypasses the device’s quiet hours.
• Use the payload fields as an alert schema. application = system or service name, event = short alert title, description = context including correlation/request IDs, url = dashboard or runbook link. This makes notifications actionable from the lock screen.
• Dispatch asynchronously. Send from a queued job (ShouldQueue) rather than inline in a web request. The upstream API is external and can be slow or down; you do not want a failing notification provider to fail a user request.
• Fan out deliberately. For multiple recipients, either loop over API keys or use the API’s comma-separated apikey support if the wrapper exposes it. Normalize/validate keys and be aware each send consumes rate-limit budget.
• Integrate with logging. A small Monolog handler or a Laravel logging channel that forwards only ERROR/CRITICAL records is a common pattern. Add throttling and deduplication so a retry storm does not produce hundreds of pushes.
• Protect the dependency with a circuit breaker. After N consecutive transport failures, stop calling Prowl for a cooldown period and log the fallback. This package predates modern retry/backoff abstractions.
• Make it testable. Extract a Sender/transport interface or subclass the package’s send method so tests can assert payloads without network calls. Keep at least one integration smoke test that runs manually or nightly.
• Provide a migration path from day one. The interface boundary is the important design decision; the package itself is not.

Gotchas and Tips

• Archived since 2016. Expect no PHP 8 compatibility work. Look for old-style constructors, each(), create_function(), PEAR-style require_once paths, and unguarded file_get_contents. Run it on your target PHP version before committing.
• The Prowl service itself is legacy. Confirm the API and your device registration still work before building around it. If verify succeeds but adds fail, the problem is likely the account/device, not your code.
• HTTP 200 does not always mean success. Prowl can return an error payload with a non-error-looking response; the wrapper may return a boolean or raw body. Log the raw response and check for known codes/messages: invalid key, not approved, not registered, server error.
• Respect field limits. Description ≈10,000 chars, event ≈1,024, application ≈256, URL ≈512. Truncate long exception traces at your layer.
• Rate limits are per IP by default (roughly 1,000 calls/hour). Provider keys raise limits for high-volume use. Cache a counter or use a lock if you fan out heavily.
• Priority 2 ignores quiet hours. Do not use it for routine deploys or informational messages; users will revoke the key.
• No idempotency key exists. Retries can duplicate notifications. Deduplicate on an event/correlation ID in your own layer.
• Check transport settings. If the package uses cURL or stream wrappers, ensure timeouts are set and TLS verification is not disabled. The defaults may be unsuitable for production.
• Never log the API key. Pass it via config/env only, and scrub request URLs from logs.
• Debug at the HTTP layer first. Reproduce with curl https://api.prowlapp.com/publicapi/add using the same parameters to separate library bugs from API/account issues.
• Do not edit vendor code. If you must fix PHP compatibility, fork the package, use a VCS Composer repository, and pin the fork. That also gives you an extension point for custom transport behavior.
• Quiet hours and device-level settings belong to Prowl. Do not attempt to reimplement scheduling or per-user time windows in your application.