Adds readme and docstrings

README.md

@@ -0,0 +1,29 @@
+# Introduction
+A heartbeat can be used to monitor background processes that should regularly
+trigger. The heartbeat can be linked to an external URL. This URL is pinged
+when the heartbeat is triggered.
+
+In WordPress an overview of triggered heartbeats, timestamps and environment
+are shown in the `Tools`/`Heartbeat status` menu.
+
+# Examples
+
+## To trigger a heartbeat
+```
+use LL\Heartbeat\Heart;
+Heart::beat('START_UPDATE_ALL', 'Updates all objects.');
+```
+
+## To trigger a URL ping
+Add a define to `wp-config.php` which links the heartbeat context to a URL. The
+context is prefixed with `LL_HB_` by default.
+
+As an example:
+
+In *envoyer.io* you can set a heartbeat under Project/Heartbeats/Add heartbeat.
+Here you configure a name and the timing interval you expect the heartbeat to
+trigger. The resulting URL is added to `wp-config.php`.
+
+```
+define('LL_HB_START_UPDATE_ALL', 'http://beats.envoyer.io/heartbeat/#####');
+```

src/Heart.php

@@ -2,9 +2,24 @@
 
 namespace LL\Heartbeat;
 
+/**
+ * Manages the heartbeats. Heartbeats are used to monitor regularly occuring background
+ * processes, such as cronjobs.
+ */
 class Heart{
+  /**
+   * Namespace for the constant referring to a heartbeat
+   * @var string
+   */
   const HB_PREFIX = 'LL_HB_';
 
+  /**
+   * Triggers a heartbeat. If configured makes a call to external URL
+   * @method beat
+   * @param  string  $context     Name of the heartbeat. Used in the constant to retrieve the URL.
+   * @param  string  $description Allows for more detailed description and debugging information.
+   * @param  boolean $skip_beat   Allows to skip a second level beat.
+   */
   public static function beat($context, $description = '', $skip_beat = false){
     if(!$skip_beat){
       self::beat('TRIGGERED_HEARTBEAT', "A heartbeat with context '{$context}' was triggered.", true);
@@ -18,6 +33,12 @@ public static function beat($context, $description = '', $skip_beat = false){
     self::log_internal($name, $description);
   }
 
+  /**
+   * Logs the heartbeat occurrance to an option, for later display
+   * @method log_internal
+   * @param  string       $name        Constant name of the heartbeat
+   * @param  string       $description Extended info about the heartbeats purpose
+   */
   protected static function log_internal($name, $description){
     $ll_heartbeat_log = get_option('ll_heartbeat_log');
     if(!is_array($ll_heartbeat_log)){
@@ -37,6 +58,12 @@ protected static function log_internal($name, $description){
     update_option('ll_heartbeat_log', $ll_heartbeat_log);
   }
 
+  /**
+   * Provides the constant that allows retrieval of the heartbeat URL
+   * @method get_hb_name
+   * @param  string      $context The context in which the heartbeat is triggered
+   * @return string               The constant name
+   */
   public static function get_hb_name($context){
     return self::HB_PREFIX . strtoupper($context);
   }