Docs/Tools & SDKs

The Oh Dear PHP SDK

We've created an easy-to-use open source PHP package that allows you to communicate with the Oh Dear API. It provides some convenient models and methods to quickly get started.

The API itself is a REST API. If you're unfamiliar with it, we suggest you read through the API documentation first, it'll make things a lot clearer.

If you want to dive straight in, here's what we suggest;

Read the getting started guide guide for the SDK. This will get the package installed and configure your API keys.
Start managing your monitors via the SDK (get data, add a new monitor, remove an existing monitor).

Once you've got that going, you're all set.

Getting started #

We offer a PHP SDK package that is ready for use. It's open source and we happily accept contributions to it.

First, grab the latest stable version via composer.

composer require ohdearapp/ohdear-php-sdk

Next, create an instance of the SDK. This takes your API key as a single, mandatory, parameter. If you don't have an API key yet, read up on the API authentication first first.

$apiKey = "iK4YfZe2i1RAe22tKP4xejGKDZP .... ";
$ohDear = new OhDear\PhpSdk\OhDear($apiKey);

Once the SDK has been initiated, you can continue adding monitors or checks to your account.

User Info #

You can get your user info with the convenient me() method. Behind the scenes, it queries the user info API endpoint.

$user = $ohDear->me();

The me() method will return an instance of OhDear\PhpSdk\Dto\User.

$user->name; // returns your name
$user->email; // returns your email

You can get the teams you belong to through the teams property.

$teams = $user->teams;

$team['id']; // returns the id of the team
$team['name']; // returns the name of the team

A user can belong to multiple teams. The API key you used to authenticate with belongs to a single user.

Monitors #

Retrieve all monitors #

The simplest example is one where we list all your monitors on your Oh Dear accounts.

$monitors = $ohDear->monitors();

This will return an iterable of OhDear\PhpSdk\Dto\Monitor instances.

You can get a few properties of a monitor.

$monitor->id;
$monitor->url;
...

You can also get a single monitor:

$ohDear->monitor($monitorId);

Add a monitor through the SDK #

A new monitor can be created with createMonitor().

$ohDear->createMonitor([
   'url' => 'https://yourbrandnewsite.tld',
   'type' => 'http',
   'team_id' => $yourTeamId,
]);

Take a look at the User section to learn how to get your team id.

When an https monitor is created, all checks will automatically be enabled. When an http monitor is created only the uptime and broken links checks will be enabled.

If you only want to enable specific checks when creating a monitor you can just pass them like this:

$ohDear->createMonitor([
   'url' => 'https://yourbrandnewsite.tld',
   'type' => 'http',
   'team_id' => $yourTeamId,
   'checks' => ['uptime', 'mixed_content'],
]);

Valid values to pass to checks are uptime, broken_links, certificate_health, mixed_content, dns, lighthouse, sitemap, cron, application_health, domain, ai.

Deleting a monitor #

$ohDear->deleteMonitor($monitorId);

Managing maintenance periods #

You can use the SDK to put a monitor in maintenance mode. This means that Oh Dear will continue running checks, but will not send any notifications while the monitor is in maintenance mode.

$ohDear->startMaintenancePeriod($monitorId);

A maintenance period will stop after an hour by default. To shorten or extend that period, you can pass an amount of seconds.

$ohDear->startMaintenancePeriod($monitorId, $durationOfMaintenancePeriodInSeconds);

To manually stop maintenance mode, use this code:

$ohDear->stopMaintenancePeriod($monitorId);

When integrated into your deployment or maintenance flow, this will allow you to create and stop a maintenance period for just the right amount of time.

Checks #

Get all checks per monitor #

The simplest example is one where we list all your checks for a particular monitor. First, make sure you retrieve the monitors via the SDK.

You can get all checks of a monitor with the checks property.

$checks = $monitor->checks;

$check['id']; // returns the id
$check['type']; // returns the check type eg. 'uptime' or 'mixed_content'

Disabling a check #

If you want to disable a check just call disable on it.

$ohDear->disableCheck($checkId); // OhDear will not run the check anymore

Enabling a check #

If you want to enable the check just call enable on it.

$ohDear->enableCheck($checkId); // back in business

Requesting a new run #

If you want Oh Dear to perform a specific check now, call the requestCheckRun() method.

$ohDear->requestCheckRun($checkId); // OhDear will perform the check in a bit

It'll be added to the queue and checked instantly.

Snoozing a check #

We can temporarily stop sending notifications for checks, by snoozing them. You can call the snoozeCheck() method to snooze.

$ohDear->snoozeCheck($checkId, 10); // Silence all notifications for 10 minutes

Unsnoozing a check #

To remove an existing snooze, you can call the unsnoozeCheck() method.

$ohDear->unsnoozeCheck($checkId); // Any existing snooze will now be removed

From then on, all new notifications will be sent again.

Uptime #

Getting uptime data #

You can get uptime with the uptime() method on the OhDear client. The method expects four parameters:

monitorId: the ID of the monitor
start: a date in the form of Y-m-d H:i:s that determines the start of the range you want to get uptime for
end: a date in the form of Y-m-d H:i:s that determines the end of the range you want to get uptime for
split: a UptimeSplit enum that determines how fine grained the answer periods should be. Valid values are UptimeSplit::Hour, UptimeSplit::Day and UptimeSplit::Month.

use OhDear\PhpSdk\Enums\UptimeSplit;

$ohDear->uptime($monitorId, $start, $end, UptimeSplit::Hour);

This will return an array of OhDear\PhpSdk\Dto\Uptime instances. From an instance you can get the following properties:

// The start of the period
$uptime->datetime;

// A float representing the percentage of time the monitor was up
$uptime->uptimePercentage;

Downtime #

Getting downtime data #

Here's how to get the downtime for a given monitor.

$ohDear->downtime($monitorId, $start, $end);

The start and end values must be strings in Y-m-d H:i:s format.

This will return an array of OhDear\PhpSdk\Dto\DowntimePeriod instances. From an instance you can get the following properties:

// The date time when we started detecting downtime
$downtime->startedAt;

// The date time when we detected the monitor was back up
$downtime->endedAt;

Broken Links #

Getting broken links #

Here's how to get the broken links for a given monitor.

$ohDear->brokenLinks($monitorId);

This will return an iterable of OhDear\PhpSdk\Dto\BrokenLink instances.

You can get a few properties of a broken link.

// The status code the monitor responded with
$brokenLink->statusCode;

// The url that is broken.
$brokenLink->crawledUrl;

// The url where the broken url was found.
$brokenLink->foundOnUrl;

Mixed Content #

Here's how to get the mixed content for a given monitor.

$ohDear->mixedContent($monitorId);

This will return an array of OhDear\PhpSdk\Dto\MixedContent instances.

You can get a few properties of a mixed content item.

// The name of the element that was detected as mixed content.
$mixedContentItem->elementName;

// The url of the detected mixed content.
$mixedContentItem->mixedContentUrl;

// The url where the mixed content was found.
$mixedContentItem->foundOnUrl;

Certificate health #

If your monitor has its certificate health check enabled, you can get some information regarding the found certificate.

$certificate = $ohDear->certificateHealth($monitorId);

This will return an OhDear\PhpSdk\Dto\CertificateHealth instance.

You can get the properties of a certificate

// An array containing some details about the certificate itself
$certificate->certificateDetails;

// An array containing all the checks we performed on the certificate
$certificate->certificateChecks;

// An array containing the names of all the issuers in the certificate chain.
$certificate->certificateChainIssuers;

The specific return values are described in the certificate health API endpoint.

Status pages #

The simplest example is one where we list all your status pages that have been configured.

$statusPages = $ohDear->statusPages();

This will return an iterable of OhDear\PhpSdk\Dto\StatusPage instances.

The individual attributes will be explained in the next section.

Retrieve the status of a single status page #

The simplest example is one where we get the details of a single status page that has been configured.

$statusPage = $ohDear->statusPage($statusPageId);

This will return an instance of OhDear\PhpSdk\Dto\StatusPage.

You can get a few properties of a Status Page.

$statusPage->id;
$statusPage->title;
$statusPage->monitors; /* Array of monitors */
$statusPage->updates; /* Array of update messages */
$statusPage->summarizedStatus;
...

For a more extensive understanding of the return values, please have a look at our status page API documentation.

Uptime Metrics #

The simplest example is one where we retrieve the HTTP uptime metrics for a monitor in a particular time window. Here, we'll get metrics for the monitor with ID 1.

use OhDear\PhpSdk\Enums\UptimeMetricsSplit;

$metrics = $ohDear->httpUptimeMetrics(1, '2020-06-07 00:00:00', '2020-06-08 00:00:00', UptimeMetricsSplit::Hour);

The above example will retrieve the metrics between 2020-06-07 00:00:00 and 2020-06-08 00:00:00, grouped by hour. You can also choose a different time range:

use OhDear\PhpSdk\Enums\UptimeMetricsSplit;

$metrics = $ohDear->httpUptimeMetrics(1, '2020-06-07 09:00:00', '2020-06-08 17:00:00', UptimeMetricsSplit::Minute);

The optional splitBy argument controls the grouping and defaults to UptimeMetricsSplit::Minute. Available values: Minute, Hour, Day, Week, Month.
Timestamps must be strings in Y-m-d H:i:s format.

This will return an array of OhDear\PhpSdk\Dto\UptimeMetric\HttpUptimeMetric instances.

You can get a few properties of an HTTP uptime metric:

$metric->date;                                  // e.g. '2020-06-07 09:00:00'
$metric->dnsTimeInSeconds;                      // float
$metric->tcpTimeInSeconds;                      // float
$metric->sslHandshakeTimeInSeconds;             // float
$metric->remoteServerProcessingTimeInSeconds;   // float
$metric->downloadTimeInSeconds;                 // float
$metric->totalTimeInSeconds;                    // float
$metric->curl;                                  // array with raw cURL timing details

If you're working with other monitor types, use the corresponding methods:

// Ping monitor metrics
$pingMetrics = $ohDear->pingUptimeMetrics(1, '2020-06-07 09:00:00', '2020-06-08 17:00:00', UptimeMetricsSplit::Hour);

// TCP monitor metrics
$tcpMetrics = $ohDear->tcpUptimeMetrics(1, '2020-06-07 09:00:00', '2020-06-08 17:00:00', UptimeMetricsSplit::Hour);

Cron job monitoring #

Cron job monitors are attached to a monitor. To get a list of defined cron job monitors, you'll need a monitor ID.

In this example, let's use monitor ID 1 and retrieve all cron job monitors for it.

$cronChecks = $ohDear->cronCheckDefinitions(1);

This will return an iterable of OhDear\PhpSdk\Dto\CronCheckDefinition instances.

You can get a few properties of a cron job monitor:

$check->id;
$check->name;
$check->uuid;
$check->type;
$check->frequencyInMinutes;
$check->pingUrl;
$check->graceTimeInMinutes;
$check->cronExpression;
$check->description;
...

Add a cron job monitor through the SDK #

You can create a new cron job monitor using createCronCheckDefinition(). The method accepts a monitor ID and an array of options including a type field that determines whether to use frequency-based or crontab-style scheduling.

For a frequency-based cron monitor (ping every X minutes):

use OhDear\PhpSdk\Enums\CronType;

$check = $ohDear->createCronCheckDefinition($monitorId, [
    'name' => 'Daily Backup',
    'type' => CronType::Simple,
    'frequency_in_minutes' => 1440, // 24 hours
    'grace_time_in_minutes' => 5,
    'description' => 'Runs once per day',
]);

Or the crontab-style one:

use OhDear\PhpSdk\Enums\CronType;

$check = $ohDear->createCronCheckDefinition($monitorId, [
    'name' => 'Nightly Reports',
    'type' => CronType::Cron,
    'cron_expression' => '0 2 * * *', // Run at 2:00 AM daily
    'grace_time_in_minutes' => 10,
    'server_timezone' => 'UTC',
    'description' => 'Generate nightly reports',
]);

The return value is an instance of OhDear\PhpSdk\Dto\CronCheckDefinition, with all the properties available as defined above.

Deleting a cron job monitor #

A cron job monitor can be deleted using deleteCronCheckDefinition().

$ohDear->deleteCronCheckDefinition($cronCheckDefinitionId);

Syncing a large list of cron job monitors #

There's a special function available called syncCronCheckDefinitions() that allows you to bulk-update a list of cron job monitors for a monitor.

Each item in the list should be an array with cron check attributes.

$ohDear->syncCronCheckDefinitions(1, [
    ['name' => 'Backup', 'type' => 'simple', 'frequency_in_minutes' => 60],
    ['name' => 'Cleanup', 'type' => 'simple', 'frequency_in_minutes' => 1440],
]);

Please note: this will delete all cron jobs that are not present in the new syncCronCheckDefinitions() call!

Status page updates #

The simplest example is one where we list all the updates for a status page.

$updates = $ohDear->statusPageUpdates($statusPageId);

This will return an array of OhDear\PhpSdk\Dto\StatusPageUpdate instances.

Add a status page update through the SDK #

A new status page update can be created with createStatusPageUpdate().

$statusPageUpdate = $ohDear->createStatusPageUpdate([
    'status_page_id' => 1,
    'title' => 'Our site is down',
    'text' => 'We are working on it!',
    'pinned' => true,
    'severity' => 'high', // One of: info, warning, high, resolved, scheduled
    'time' => '2021-02-09 12:25:00', // A UTC date field for this update in the Y-m-d H:i:s format
]);

This will return an instance of OhDear\PhpSdk\Dto\StatusPageUpdate

You can get a few properties of a Status Page Update.

$statusPageUpdate->id;
$statusPageUpdate->title;
$statusPageUpdate->text;
$statusPageUpdate->pinned;
$statusPageUpdate->severity;
$statusPageUpdate->time;
$statusPageUpdate->statusPageUrl;

Deleting a status page update #

A status page update can be deleted using deleteStatusPageUpdate().

$ohDear->deleteStatusPageUpdate($statusPageUpdateId);

For more extensive understanding of the return values, please have a look at our status page updates API documentation.

Maintenance windows #

The simplest example is one where we list the maintenance windows for a particular monitor. Here, we'll get the maintenance periods for the monitor with ID 1.

$maintenanceWindows = $ohDear->maintenancePeriods(1);

This will return an iterable of OhDear\PhpSdk\Dto\MaintenancePeriod instances.

You can get a few properties of a maintenance window.

$window->id;
$window->monitorId;
$window->startsAt;
$window->endsAt;

Add a maintenance period through the SDK #

We have a convenient method for adding a maintenance window now to any monitor. This can be useful in deploy-scripts, to create a maintenance period that lasts for X amount of minutes.

This can be done using the startMaintenancePeriod() method.

$ohDear->startMaintenancePeriod(
   1,       // Monitor ID
   120,     // Amount of seconds
);

This creates a new maintenance period for monitor ID 1 that lasts for 120 seconds, or 2 minutes. It's a shorthand for this, longer version, of the maintenance period creation:

$ohDear->createMaintenancePeriod([
    'monitor_id' => 1,
    'name' => 'Scheduled Server Maintenance',
    'starts_at' => '2020-05-19 13:00:00',
    'ends_at' => '2020-05-19 13:02:00',
]);

The createMaintenancePeriod() method allows a starts_at and ends_at to be specified. Pass dates in Y-m-d H:i:s format.

Stopping any ongoing maintenance #

If you used the startMaintenancePeriod() shorthand for creating a new maintenance window, you can also use the stopMaintenancePeriod() method.

$ohDear->stopMaintenancePeriod($monitorId);

This will stop any currently ongoing maintenance window.

The ideal use case is in deployment scripts, where you can call the following methods:

// Create a 10-minute maintenance period
$ohDear->startMaintenancePeriod(1, 600);

// Your deployment code here
// ...

// Stop the maintenance period
$ohDear->stopMaintenancePeriod(1);

This will create a perfectly timed, on-demand maintenance window.

Deleting a particular maintenance window #

If you have the maintenance period ID, you can also delete it.

$ohDear->deleteMaintenancePeriod(1);

The above will delete a maintenance period with ID 1.

Reseller / Managed Teams #

If you're an Oh Dear reseller, you can manage your clients' teams through the SDK. All reseller methods require your reseller team ID as the first parameter.

Retrieve all managed teams #

$teams = $ohDear->managedTeams($resellerTeamId);

This will return an array of OhDear\PhpSdk\Dto\ManagedTeam instances.

You can get a few properties of a managed team.

$team->id;
$team->name;
$team->timezone;
$team->monitorsCount;
$team->createdAt;

You can also get a single managed team:

$team = $ohDear->managedTeam($resellerTeamId, $managedTeamId);

Create a managed team #

A new managed team can be created with createManagedTeam().

$team = $ohDear->createManagedTeam($resellerTeamId, [
    'name' => 'Client Company',
    'timezone' => 'Europe/Brussels',
    'default_uptime_check_location' => 'eu-west',
]);

The timezone and default_uptime_check_location fields are optional. See the reseller API documentation for all available options.

Update a managed team #

You can update the name, timezone, and default uptime check location of a managed team.

$team = $ohDear->updateManagedTeam($resellerTeamId, $managedTeamId, [
    'name' => 'Updated Company Name',
    'timezone' => 'Europe/London',
    'default_uptime_check_location' => 'us-east',
]);

All fields are optional — only pass the ones you want to change.

You can generate a temporary login link that gives access to a managed team's Oh Dear dashboard.

$loginLink = $ohDear->managedTeamLoginLink($resellerTeamId, $managedTeamId);

$loginLink['login_url']; // The temporary login URL
$loginLink['valid_until']; // When the link expires

Decoupling a managed team #

Decoupling removes the reseller relationship. The team becomes independent and retains all its monitors and data.

$ohDear->decoupleManagedTeam($resellerTeamId, $managedTeamId);

Deleting a managed team #

This will permanently delete the team and all associated data.

$ohDear->deleteManagedTeam($resellerTeamId, $managedTeamId);

Was this page helpful?

Feel free to reach out via [email protected] or on X via @OhDearApp if you have any other questions. We'd love to help!

Oh dear mcp server

Our laravel nova tool

All of this from €15/mo

Latest update

We are for everyone

We sweat the details

Latest update

All of this from €15/mo

Latest update

We are for everyone

We sweat the details

Latest update

The Oh Dear PHP SDK

Getting started #

User Info #

Monitors #

Retrieve all monitors #

Add a monitor through the SDK #

Deleting a monitor #

Managing maintenance periods #

Checks #

Get all checks per monitor #

Disabling a check #

Enabling a check #

Requesting a new run #

Snoozing a check #

Unsnoozing a check #

Uptime #

Getting uptime data #

Downtime #

Getting downtime data #

Broken Links #

Getting broken links #

Mixed Content #

Certificate health #

Status pages #

Retrieve the status of a single status page #

Uptime Metrics #

Cron job monitoring #

Add a cron job monitor through the SDK #

Deleting a cron job monitor #

Syncing a large list of cron job monitors #

Status page updates #

Add a status page update through the SDK #

Deleting a status page update #

Maintenance windows #

Add a maintenance period through the SDK #

Stopping any ongoing maintenance #

Deleting a particular maintenance window #

Reseller / Managed Teams #

Retrieve all managed teams #

Create a managed team #

Update a managed team #

Getting a login link #

Decoupling a managed team #

Deleting a managed team #