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
and certificate_transparency
.
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 ofYmdHis
that determines the start of the range you want to get uptime for -
end
: a date in the form ofYmdHis
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
andmonth
.
$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 acrontab
-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
.
Feel free to reach out via [email protected] or on Twitter via @OhDearApp if you have any other questions. We'd love to help!