Writing service data; Improved docs and DocBlocks

CONTRIBUTION.md

@@ -1,4 +1,4 @@
 # Contribution
 
-To contribute to this application, you can make pull requests or fill bugs in Github. As this php application is developed
-internally and only mirrored in Github, your changes will be manually added to the application.
+To contribute to this application, you can make pull requests or fill bugs in GitHub. As this PHP application is developed
+internally and only mirrored in GitHub, your changes will be manually added to the application.

README.md

@@ -1,12 +1,11 @@
 # Icinga2 Api Client for PHP
 
-This is a simple api client for Icinga2 written in PHP. At the moment it has only
-read functions. In the future it will be capable of writing to Icinga2
-too.
+This is a simple api client for Icinga2 written in PHP. At the moment it has mostly
+read functions. The only writing function is Service::processCheckResult().
 
 ## Installation
 
-To use this client simply add it to your package requirements with composer:
+To use this client simply add it to your package requirements with Composer:
 
 ```lang=bash
 composer require rzuw/icinga2
@@ -19,13 +18,13 @@ The following settings should be set to make this client work.
 ```lang=php
 $config = array
 (
-    "host" => ""
-    "port" => ""
+    "host" => "",
+    "port" => "",
     // should be set when you decide for username and password login
-    "user" => ""
-    "password" => ""
+    "user" => "",
+    "password" => "",
     // should be used when you decide for certificate login
-    "cert" => ""
+    "cert" => "",
     "key" => ""
 );
 ```
@@ -129,23 +128,26 @@ curl --cert your-client-cn.crt --key your-client-cn.key --cacert ca.crt 'https:/
 
 ## Usage
 
-To use this client simply create an instance of Icinga2Api class and
+To use this client simply create an instance of Icinga2 class and
 load the configuration inside.
 
 ```lang=php
 $config = array
 (
-    "host" => ""
-    "port" => ""
+    "host" => "",
+    "port" => "",
     // should be set when you decide for username and password login
-    "user" => ""
-    "password" => ""
+    "user" => "",
+    "password" => "",
     // should be used when you decide for certificate login
-    "cert" => ""
+    "cert" => "",
     "key" => ""
 );
 $icinga2 = new Icinga2($config);
-$matchedHosts = $icinga2->getHosts(array("match(\"" . $this->hostData["hostname"] . "*\",host.name)"
+$matchedHosts = $icinga2->getHosts(array('match("' . $config["host"] . '", host.name)'));
+
+// "Host runs Linux."
+echo $matchedHosts[0]->getName() . ' runs ' . $matchedHosts[0]->getAttributes()['vars']['os'] .".\n";
 ```
 
 See the test cases for more examples.

src/De/Uniwue/RZ/Api/Icinga2/Icinga2.php

@@ -1,8 +1,7 @@
 <?php
 
 /**
- * Icinga2 Class is the main API interface for the icinga library. At the moment only reads from the server is
- * possible.
+ * Icinga2 Class is the main API interface for this library.
  *
  * Created by PhpStorm.
  * User: poa32kc
@@ -19,6 +18,7 @@
 use De\Uniwue\RZ\Api\Icinga2\Auth\PasswordAuth;
 use De\Uniwue\RZ\Api\Icinga2\Icinga2Object\Comment;
 use De\Uniwue\RZ\Api\Icinga2\Icinga2Object\Host;
+use De\Uniwue\RZ\Api\Icinga2\Icinga2Object\Icinga2ObjectInterface;
 use De\Uniwue\RZ\Api\Icinga2\Icinga2Object\Service;
 use De\Uniwue\RZ\Api\Icinga2\Query\Query;
 
@@ -176,7 +176,7 @@ public function getPermissions($withHttps = true)
      *
      * @param bool $withHttps
      *
-     * @return array
+     * @return Host[]
      *
      * @throws \Httpful\Exception\ConnectionErrorException
      */
@@ -197,7 +197,7 @@ public function getAllHosts($withHttps = true)
      *
      * @param bool $withHttps
      *
-     * @return array
+     * @return Service[]
      *
      * @throws \Httpful\Exception\ConnectionErrorException
      */
@@ -218,7 +218,7 @@ public function getAllServices($withHttps = true)
      *
      * @param bool $withHttps
      *
-     * @return array
+     * @return Comment[]
      *
      * @throws \Httpful\Exception\ConnectionErrorException
      */
@@ -242,21 +242,16 @@ public function getAllComments($withHttps = true)
      * @param array $filter
      * @param array $attrs
      * @param array $joins
-     * @param bool $withHttps
      *
-     * @return array
+     * @return Comment[]
      *
      * @throws \Httpful\Exception\ConnectionErrorException
      */
-    public function getComments($filter = [], $attrs = [], $joins = [], $withHttps = true)
+    public function getComments($filter = [], $attrs = [], $joins = [])
     {
         $result = [];
-        $query = new Query($this->config["host"], $this->config["port"], "v1/objects/comments", $withHttps, "POST");
-        $query->setFilters($filter);
-        $query->setAttributes($attrs);
-        $query->setJoins($joins);
-        $request = $this->authenticate($query->getRequest());
-        $request->addHeaders(array("Accept" => "application/json", "X-HTTP-Method-Override" => "GET"));
+        $request = $this->buildRequest("v1/objects/comments", $filter, $attrs, $joins);
+        $request->addHeader('X-HTTP-Method-Override', 'GET');
         $response = $request->send();
         if ($response->code === 200) {
             $result = $this->decodeResult($response, "comment");
@@ -278,21 +273,21 @@ public function getHostAcknowledgement($hostName = false, $withHttps = true)
     {
 
         $joins = [
-            "host.name", 
-            "host.acknowledgement", 
+            "host.name",
+            "host.acknowledgement",
             "host.acknowledgement_expiry",
         ];
-        
+
         $filterString = 'comment.entry_type==4 && comment.service_name==""';
-        
-        if($hostName !== false) {
-            $filterString .= ' && host.name=="'.$hostName.'"';
+
+        if ($hostName !== false) {
+            $filterString .= ' && host.name=="' . $hostName . '"';
         }
-        
+
         $filter = [
             $filterString
         ];
-        
+
         return $this->getComments($filter, [], $joins, $withHttps);
     }
 
@@ -333,22 +328,19 @@ public function getServiceAcknowledgement($serviceName = false, $withHttps = tru
      * Returns the list of hosts that match the given filter and attributes and joins
      *
      * @param array $filter
+     *   As documented at https://icinga.com/docs/icinga2/latest/doc/12-icinga2-api/#filters
      * @param array $attrs
      * @param array $joins
      *
-     * @return array
+     * @return Host[]
      *
      * @throws \Httpful\Exception\ConnectionErrorException
      */
     public function getHosts($filter = array(), $attrs = array(), $joins = array())
     {
         $result = array();
-        $query = new Query($this->config["host"], $this->config["port"], "v1/objects/hosts", true, "POST");
-        $query->setFilters($filter);
-        $query->setAttributes($attrs);
-        $query->setJoins($joins);
-        $request = $this->authenticate($query->getRequest());
-        $request->addHeaders(array("Accept" => "application/json", "X-HTTP-Method-Override" => "GET"));
+        $request = $this->buildRequest("v1/objects/hosts", $filter, $attrs, $joins);
+        $request->addHeader('X-HTTP-Method-Override', 'GET');
         $response = $request->send();
         if ($response->code === 200) {
             $result = $this->decodeResult($response, "host");
@@ -364,22 +356,18 @@ public function getHosts($filter = array(), $attrs = array(), $joins = array())
      * @param array $attrs
      * @param array $joins
      *
-     * @return array
+     * @return Service[]
      *
      * @throws \Httpful\Exception\ConnectionErrorException
      */
     public function getServices($filter = array(), $attrs = array(), $joins = array())
     {
         $result = array();
-        $query = new Query($this->config["host"], $this->config["port"], "v1/objects/services", true, "POST");
-        $query->setFilters($filter);
-        $query->setAttributes($attrs);
-        $query->setJoins($joins);
-        $request = $this->authenticate($query->getRequest());
-        $request->addHeaders(array("Accept" => "application/json", "X-HTTP-Method-Override" => "GET"));
+        $request = $this->buildRequest("v1/objects/services", $filter, $attrs, $joins);
+        $request->addHeader('X-HTTP-Method-Override', 'GET');
         $response = $request->send();
         if ($response->code === 200) {
-            $result = $this->decodeResult($response, "host");
+            $result = $this->decodeResult($response, "service");
         }
 
         return $result;
@@ -391,41 +379,31 @@ public function getServices($filter = array(), $attrs = array(), $joins = array(
      * @param Response $response
      * @param $type
      *
-     * @return array
+     * @return Icinga2ObjectInterface[]
      */
     public function decodeResult(Response $response, $type)
     {
         $result = array();
         $decodedResponse = json_decode($response, true);
         if (isset($decodedResponse["results"]) & sizeof($decodedResponse["results"]) > 0) {
             foreach ($decodedResponse["results"] as $icingaRow) {
+                $params = array(
+                    $icingaRow["name"],
+                    $icingaRow["type"],
+                    $this,
+                    $icingaRow["attrs"],
+                    $icingaRow["meta"],
+                    $icingaRow["joins"]
+                );
                 switch ($type) {
                     case "host":
-                        $icingaObject = new Host(
-                            $icingaRow["name"],
-                            $icingaRow["type"],
-                            $icingaRow["attrs"],
-                            $icingaRow["meta"],
-                            $icingaRow["joins"]
-                        );
+                        $icingaObject = new Host(...$params);
                         break;
                     case "service":
-                        $icingaObject = new Service(
-                            $icingaRow["name"],
-                            $icingaRow["type"],
-                            $icingaRow["attrs"],
-                            $icingaRow["meta"],
-                            $icingaRow["joins"]
-                        );
+                        $icingaObject = new Service(...$params);
                         break;
                     case "comment":
-                        $icingaObject = new Comment(
-                            $icingaRow["name"],
-                            $icingaRow["type"],
-                            $icingaRow["attrs"],
-                            $icingaRow["meta"],
-                            $icingaRow["joins"]
-                        );
+                        $icingaObject = new Comment(...$params);
                         break;
                     default:
                         $icingaObject = null;
@@ -438,4 +416,24 @@ public function decodeResult(Response $response, $type)
         }
         return $result;
     }
+
+    /**
+     * @param string $url
+     * @param array $filter
+     * @param array $attrs
+     * @param array $joins
+     *
+     * @return \Httpful\Request
+     */
+    public function buildRequest(string $url, $filter = [], $attrs = [], $joins = []): Request
+    {
+        $query = new Query($this->config["host"], $this->config["port"], $url, true, "POST");
+        $query->setFilters($filter);
+        $query->setAttributes($attrs);
+        $query->setJoins($joins);
+        $request = $this->authenticate($query->getRequest());
+        $request->addHeader("Accept", "application/json");
+        return $request;
+    }
+
 }

src/De/Uniwue/RZ/Api/Icinga2/Icinga2Object/Icinga2Object.php

@@ -9,6 +9,8 @@
 namespace De\Uniwue\RZ\Api\Icinga2\Icinga2Object;
 
 
+use De\Uniwue\RZ\Api\Icinga2\Icinga2;
+
 class Icinga2Object
 {
     /**
@@ -36,18 +38,26 @@ class Icinga2Object
      */
     private $type;
 
+    /**
+     * @var \De\Uniwue\RZ\Api\Icinga2\Icinga2 
+     */
+    protected $icinga2;
+
     /**
      * Icinga2Object constructor.
+     *
      * @param string $name The name of the given Icinga2Object
      * @param string $type The type of the given Icinga2Object
+     * @param \De\Uniwue\RZ\Api\Icinga2\Icinga2 $icinga2
      * @param array $attributes The attributes for the given Icinga2Object
      * @param array $meta The meta information for the given Icinga2Object
      * @param array $joins The joins for the given query result
      */
-    public function __construct($name, $type, $attributes = array(), $meta = array(), $joins = array())
+    public function __construct($name, $type, Icinga2 $icinga2, $attributes = array(), $meta = array(), $joins = array())
     {
         $this->name = $name;
         $this->type = $type;
+        $this->icinga2 = $icinga2;
         $this->attributes = $attributes;
         $this->meta = $meta;
         $this->joins = $joins;