Docs/Integrations

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 sites via the SDK (get data, add new site, remove an existing site).

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 sites 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\Resources\User.

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

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

$teams = $user->teams;

The $teams variable is an array of OhDear\PhpSdk\Resources\Team.

$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.

Sites

Retrieve all sites

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

$sites = $ohDear->sites();

This will return an array of OhDear\PhpSdk\Resources\Site instances.

You can get a few properties of a site.

$site->id;
$site->url;
...

You can also get a single site:

$ohDear->site($siteId);

Add a site through the SDK

A new site can be created with createSite().

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

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

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

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

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

Valid values to pass to checks are uptime, broken_links, certificate_health, mixed_content.

Deleting a site

A site can easily be deleted. This assumes the $site is an instance of OhDear\PhpSdk\Resources\Site, which you can get with the sites() method.

$site->delete(); // This particular site is deleted

See the retrieving all sites section above to get all available sites.

Managing maintenance periods

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

$ohDear->site($siteId)->startMaintenance();

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

$ohDear->site($siteId)->startMaintenance($durationOfMaintenancePeriodInSeconds);

To manually stop maintenance mode, use this code:

$ohDear->site($siteId)->stopMaintenance();

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

Checks

Get all checks per site

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

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

$checks = $site->checks;

This will return an array with instances of OhDear\PhpSdk\Resources\Check.

$check->id; // returns the id
$check->type; // returns the check type eg. 'uptime' or 'mixed-content'

Each OhDear\PhpSdk\Resources\Check instance has several methods you can call.

Disabling a check

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

$check->disable(); // OhDear will not run the check anymore

Enabling a check

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

$check->enable(); // back in business

Requesting a new run

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

$check->requestRun(); // 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 snooze($minutes) method to snooze.

$check->snooze(10); // Silence all notifications for 10 minutes

Unsnoozing a check

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

$check->unsnooze(); // 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 a site. The method expects three parameters:

start: a date in the form of YmdHis that determines the start of the range you want to get uptime for
end: a date in the form of YmdHis that determines the end of the range you want to get uptime for
split: a string that determines how fine grained the answer periods should be. Valid values are hour, day and month.

$ohDear->site($siteId)->uptime($start, $end, $split);

//alternatively you could do this
$ohDear->uptime($siteId, $start, $end, $split);

Both methods above will return an array of OhDear\PhpSdk\Resources\Uptime instances. A Uptime instance.

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

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

Downtime

Getting downtime data

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

$ohDear->site($siteId)->downtime();

//alternatively you could do this
$ohDear->downtime($siteId);

Both methods above will return an array of OhDear\PhpSdk\Resources\Downtime instances. A Downtime instance.

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

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

Broken Links

Getting broken links

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

$ohDear->site($siteId)->brokenLinks();

//alternatively you could do this
$ohDear->brokenLinks($siteId);

Both methods above will return an array of OhDear\PhpSdk\Resources\BrokenLink instances.

You can get a few properties of a broken link.

// The status code the site 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 site.

$ohDear->site($siteId)->mixedContent();

//alternatively you could do this
$ohDear->mixedContent($siteId);

Both methods above will return an array of OhDear\PhpSdk\Resources\MixedContentItem 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 site has its certificate health check enabled, you can get some information regarding the found certificate.

$certificate = $ohDear->site($siteId)->certificateHealth();

//alternatively you could do this
$certificate = $ohDear->certificateHealth($siteId);

Both methods above will return an OhDear\PhpSdk\Resources\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 array of OhDear\PhpSdk\Resources\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. Below, we'll retrieve the status page with the ID of 1.

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

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

You can get a few properties of a Status Page.

$statusPage->id;
$statusPage->title;
$statusPage->attributes->sites; /* Array of sites */
$statusPage->attributes->updates; /* Array of update message */
$statusPage->summarized_status;
...

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

Performance records

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

$records = $ohDear->performanceRecords(1, '2020-06-07', '2020-06-08');

The above example will retrieve the performance metrics between 2020-06-07 and 2020-06-08. You can also be more specific with your request, by including the hour/minute/seconds:

$records = $ohDear->performanceRecords(1, '2020-06-07 09:00:00', '2020-06-08 17:00:00');

The SDK will convert any date format to the correct notation our API expects.

This will return an array of OhDear\PhpSdk\Resources\PerformanceRecord instances.

You can get a few properties of a performance record.

$record->id;
$record->siteId;
$record->timeRemoteserver;
$record->timeTotal;

Cron job monitoring

Cron job monitors are attached to a site. In order to get a list of defined monitors, you'll need a site ID.

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

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

This will return an array of OhDear\PhpSdk\Resources\CronCheck instances.

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

$check->id;
$check->name;
$check->uuid;
$check->type;
$check->checkId;
$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 one of two methods:

createSimpleCronCheck(): lets you define a frequency and a grace time
createCronCheck(): lets you provide a crontab-style syntax for defining the frequency

For example, to use the simple cron monitor definition:

$check = $ohDear->createSimpleCronCheck(
    1,                  // Site ID
    'your-cron-name',   // Name
    5,                  // Frequency (minutes)
    10,                 // Grace time (minutes)
    'your description', // A description of this cron monitor
);

Or the crontab-style one:

$check = $ohDear->createSimpleCronCheck(
    1,                  // Site ID
    'your-cron-name',   // Name
    '* * * * *',        // Crontab expression
    10,                 // Grace time
    'your description', // A description
    'UTC',              // Your server timezone
);

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

Deleting a cron job monitor

A cron job monitor can easily be deleted. If you have the cron object, you can call the delete() method on it:

$cronCheck->delete(); // This particular cron job monitor is deleted

Alternatively, you can use the SDK to delete a particular ID:

$ohdear->deleteCronCheck(1); // This will delete cron job ID 1

Syncing a large list of cron job monitors

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

$ohdear->syncCronChecks(1, [
    $cronCheck1,
    $cronCheck2,
    $cronCheck3,
]);

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

Status pages

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

$ohDear->statusPage(1)->updates();

// Alternatively you could do this
$statusPages = $ohDear->statusPageUpdates(1);

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

The individual attributes will be explained in the next section.

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', // A UTC date field for this update in the Y-m-d H:i format
]);

This will return an instance of OhDear\PhpSdk\Resources\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 site can easily be deleted. This assumes the $statusPageUpdate is an instance of OhDear\PhpSdk\Resources\StatusPageUpdate, which you can get with the statusPageUpdates() method.

$statusPageUpdate->delete();

// Alternatively you could do this
$ohDear->deleteStatusPageUpdate(1);

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 website. Here, we'll get the maintenance periods for a site with ID 1.

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

This will return an array of OhDear\PhpSdk\Resources\MaintenancePeriod instances.

You can get a few properties of a maintenance window.

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

Add a maintenance period through the SDK

We have a convenient method for adding a maintenance window now to any site. 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 startSiteMaintenance() method.

$ohDear->startSiteMaintenance(
   1,       // Site ID
   120      // Amount of seconds
);

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

$ohDear->createSiteMaintenance(
    1,                   // Site ID
    '2020-05-19 13:00',  // Start date
    '2020-05-19 13:02'   // End date
)

The createSiteMaintenance() method allows a $startDate and $endDate to be specified. You can pass the date as any string, it will be formatted by the SDK into the correct format.

Stopping any ongoing maintenance

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

$ohDear->stopSiteMaintenance(1);

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->startSiteMaintenance(1, 600);

// Your deployment code here
// ...

// Stop the maintenance period
$ohDear->stopSiteMaintenance(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->deleteSiteMaintenance(1);

The above will delete maintenance period with ID 1.

Was this page helpful?

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

Api

Webhooks