Download the PHP package viewmend/sdk without Composer

ViewMend PHP SDK

The ViewMend PHP SDK is the official framework-agnostic PHP client for ViewMend APIs. It provides shared authentication and configuration, a production-ready HTTP transport, safe retries, typed errors, and isolated product modules for integrating PHP applications with the ViewMend website monitoring platform.

Available modules

Site Tracker

PHP applications can send deployment events, content updates, cache clears, and maintenance activity to ViewMend, which connects that change context with subsequent checks of tracked pages in the Events and Timeline workflow.

Applications can also read integration dashboards and paginated check resources using the same Site Tracker token.

Learn more about ViewMend Site Tracker for website change monitoring.

Cron

Applications can register one scheduled HTTPS callback for the domain connected in ViewMend. The client chooses the schedule and callback path; ViewMend fixes the method to POST, verifies the endpoint, and runs it on a dedicated queue. The client never submits an arbitrary callback host.

Installation

Install the SDK with Composer:

Guzzle is included as the SDK's default HTTP transport; application code does not need to install, configure, or import it.

Quick Start

This example uses Site Tracker Events:

The default versioned API base URL is https://viewmend.com/api/v1. Creating and enriching an event performs no network request; the side effect occurs only when send() is called.

Add change context

Fluent methods add validated context while keeping the event immutable:

site() identifies the affected site, while each page() adds a specific tracked-page URL. Supported semantic event methods are deployment(), contentUpdate(), pluginUpdate(), themeUpdate(), cacheCleared(), trackingScriptChange(), maintenance(), and custom().

For optional integration-declared changed_fields and metadata, see Site Tracker event context.

Use an event ID that is unique and stable for the originating change. Safe retries send the identical serialized payload and the same event ID. If the server already accepted that ID, it returns a duplicate delivery instead of creating a second event.

Read the Site Tracker dashboard

dashboard() and resources() perform GET requests and return immutable typed responses. See Site Tracker dashboards and resources for page selection, pagination, missing data, and error handling.

Register Cron

First create a connection for the site's domain in ViewMend and copy the one-time connection token into the application settings. The application then registers its callback path and schedule:

The registration request sends only an endpoint path. ViewMend combines that path with the connected domain and always calls it using HTTPS POST. The returned RegistrationResult contains the saved settings and current server state, so the application can update its form immediately. Registering a new or changed path starts endpoint verification before normal runs begin.

Load saved Cron settings

When the application settings screen opens, use the saved token to load the authoritative settings from ViewMend:

current() calls GET /api/v1/cron/registration and returns null only when no registration exists. ViewMend is the source of truth. A client may keep the last successful response for temporary offline display, but it must not let that cache overwrite a later server response, and it must never cache or log the connection token as part of the settings snapshot. Catch TokenScopeException before AuthenticationException because it is the more specific authentication failure.

disable() pauses the saved schedule. See the complete settings synchronization contract.

The callback must verify the signature against the exact raw request body before processing it:

Cron delivery is at least once: a transient failure can cause the same runId to be delivered again with a higher attempt. Store completed run IDs before repeating side effects. See the complete Cron integration contract.

Handle the result

send() returns a typed DeliveryResult:

QueueStatus preserves unknown future values. Use isKnown() for display decisions, but retain its raw value rather than treating a new server status as a malformed response.

All SDK failures extend ViewMend\Exception\ViewMendException. Significant API statuses have dedicated exception types:

• TokenScopeException when a Site Tracker token is passed to the Cron API
• AuthenticationException for other 401 responses
• EndpointDisabledException for 410
• PayloadTooLargeException for 413
• UnprocessableEventException for 422
• ResourceNotFoundException for dashboard/resource 404 responses, including an out-of-scope page or run
• UnprocessableQueryException for dashboard/resource 422 responses
• UnprocessableRegistrationException for invalid Cron registration
• CallbackVerificationException for an invalid or stale Cron callback
• RateLimitException for exhausted 429 responses
• ServerException for exhausted 5xx responses
• NetworkException for exhausted PSR-18 network failures
• TransportException for other non-retryable transport failures
• UnexpectedResponseException for unexpected status codes or malformed successful JSON

Exception messages and SDK log context do not include authorization headers, API tokens, or raw response bodies.

Advanced configuration

The SDK uses Guzzle by default. Applications that manage their own HTTP infrastructure can inject a PSR-18 client and PSR-17 factories. See Advanced configuration.

License

The ViewMend PHP SDK is available under the MIT License.

Development

Tests use mock PSR-18 clients and never send real network traffic or perform real sleeps. Architectural decisions and public boundaries are recorded in docs/architecture.md.