From 58495a3910ac308fda7f70ff3bfc9c33c4e71d3e Mon Sep 17 00:00:00 2001
From: Tony Murray <murraytony@gmail.com>
Date: Sun, 12 Mar 2017 08:05:31 -0500
Subject: [PATCH] Add php docs for log_event, small cleanups (#6141)

* Add php docs for log_event, clean up eventlog_severity a bit.

* Update functions.php
---
 html/includes/functions.inc.php | 10 ++--------
 includes/functions.php          | 29 ++++++++++++++++++-----------
 2 files changed, 20 insertions(+), 19 deletions(-)

diff --git a/html/includes/functions.inc.php b/html/includes/functions.inc.php
index 65b58a1c6f..d65674af5a 100644
--- a/html/includes/functions.inc.php
+++ b/html/includes/functions.inc.php
@@ -1408,30 +1408,24 @@ function array_to_htmljson($data)
 }
 
 /**
- * @param $eventlog_severity
- * @return $eventlog_severity_icon
+ * @param int $eventlog_severity
+ * @return string $eventlog_severity_icon
  */
 function eventlog_severity($eventlog_severity)
 {
     switch ($eventlog_severity) {
         case 1:
             return "severity-ok"; //OK
-            break;
         case 2:
             return "severity-info"; //Informational
-            break;
         case 3:
             return "severity-notice"; //Notice
-            break;
         case 4:
             return "severity-warning"; //Warning
-            break;
         case 5:
             return "severity-critical"; //Critical
-            break;
         default:
             return "severity-unknown"; //Unknown
-            break;
     }
 } // end eventlog_severity
 
diff --git a/includes/functions.php b/includes/functions.php
index 68666129f5..bbf133d5d0 100644
--- a/includes/functions.php
+++ b/includes/functions.php
@@ -823,23 +823,30 @@ function get_astext($asn)
     }
 }
 
-# Use this function to write to the eventlog table
+/**
+ * Log events to the event table
+ *
+ * @param string $text message describing the event
+ * @param array|int $device device array or device_id
+ * @param string $type brief category for this event. Examples: sensor, state, stp, system, temperature, interface
+ * @param int $severity 1: ok, 2: info, 3: notice, 4: warning, 5: critical, 0: unknown
+ * @param int $reference the id of the referenced entity.  Supported types: interface
+ */
 function log_event($text, $device = null, $type = null, $severity = 2, $reference = null)
 {
     if (!is_array($device)) {
         $device = device_by_id_cache($device);
     }
 
-    $username = $_SESSION['username'] ?: '';
-
-    $insert = array('host' => ($device['device_id'] ? $device['device_id'] : 0),
-        'device_id' => ($device['device_id'] ? $device['device_id'] : 0),
-        'reference' => ($reference ? $reference : "NULL"),
-        'type'      => ($type ? $type : "NULL"),
-        'datetime'  => array("NOW()"),
-        'severity'  => $severity,
-        'message'   => $text,
-        'username'  => $username);
+    $insert = array('host' => ($device['device_id'] ?: 0),
+        'device_id' => ($device['device_id'] ?: 0),
+        'reference' => ($reference ?: "NULL"),
+        'type' => ($type ?: "NULL"),
+        'datetime' => array("NOW()"),
+        'severity' => $severity,
+        'message' => $text,
+        'username'  => $_SESSION['username'] ?: '',
+     );
 
     dbInsert($insert, 'eventlog');
 }