Merge pull request #14 from Ente/v1.2

v1.2
Ente · Nov 18, 2024 · 2e864f0 · 2e864f0
2 parents d5408ef + 823b2d0
commit 2e864f0
Show file tree

Hide file tree

Showing 22 changed files with 400 additions and 126 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,15 @@
 # Changelog
 
+## v1.2
+
+* All API classes can now directly be used from the Cryptolens base class
+
+* Analytics class no longer extends Cryptolens base class
+* removed php closing tag within classes and excess empty lines
+* added documentation for internal functions
+* quality improvements
+* added php class headers
+
 ## v1.1
 
 * added support to User authentication endpoints `login`, `register`, `associate`, `dissociate`, `getUsers`, `changePassword`, `resetPasswordToken`, `removeUser` <!-- I simply forgot this endpoint group exists aswell or it has been added newly. -->

diff --git a/Cryptolens.php b/Cryptolens.php
@@ -1,10 +1,32 @@
 <?php
+/**
+ * Cryptolens_PHP_Client
+ * 
+ * Namespace for all classes implementing API endpoints
+ */
 namespace Cryptolens_PHP_Client {
+    use Cryptolens_PHP_Client\Analytics;
+    use Cryptolens_PHP_Client\Auth;
+    use Cryptolens_PHP_Client\Customer;
+    use Cryptolens_PHP_Client\Data;
+    use Cryptolens_PHP_Client\Endpoints;
+    use Cryptolens_PHP_Client\Key;
+    use Cryptolens_PHP_Client\License;
+    use Cryptolens_PHP_Client\Message;
+    use Cryptolens_PHP_Client\PaymentForm;
+    use Cryptolens_PHP_Client\Reseller;
+    use Cryptolens_PHP_Client\Results;
+    use Cryptolens_PHP_Client\Subscription;
+    use Cryptolens_PHP_Client\User;
     /**
      * Cryptolens main class
-     * 
      * This is the cryptolens main class containing an auto loader. It is also holding the sensitive login information needed for the API.
      * You can define the output to either JSON or Arrays (PHP)
+     * 
+     * @author Bryan Böhnke-Avan <bryan@openducks.org>
+     * @license MIT
+     * @since v0.1
+     * @link https://app.cryptolens.io/docs/api/v3
      */
     class Cryptolens {
 
@@ -43,11 +65,30 @@ class Cryptolens {
 
         public static int $output;
 
+        private $analytics;
+        private $auth;
+        private $customer;
+        private $data;
+        private $endpoints;
+        private $key;
+        private $license;
+        private $message;
+        private $paymentForm;
+        private $product;
+        private $reseller;
+        private $subscription;
+        private $user;      
+
 
-        private function set_token(string $token): void{
+        /**
+         * `setToken()` - Setter for API token
+         * @param string $token The API token to set
+         * @return void
+         */
+        private function setToken(string $token): void{
             $this->token = $token;
         }
-        private function set_product_id($product_id){
+        private function setProductId($product_id){
             $this->productId = $product_id;
         }
 
@@ -56,23 +97,40 @@ private function set_product_id($product_id){
          */
         public function __construct($token, $productid, $output = self::CRYPTOLENS_OUTPUT_PHP){
             self::$output = $output;
-            $this->set_token($token);
-            $this->set_product_id($productid);
+            $this->setToken($token);
+            $this->setProductId($productid);
         }
 
 
-        public function get_token(){
+        /**
+         * `getToken()` - Getter for API token
+         * @return string Returns the API Authentication token
+         */
+        public function getToken(){
             return $this->token;
         }
 
-      public function get_product_id(){
+      /**
+       * `getProductId()` - Getter for product ID
+       * @return int Returns the product ID
+       */
+      public function getProductId(){
             return $this->productId;
         }
 
-        public function set_output($output){
+        /**
+         * `setOutput()` - Setter for output mode, either `Cryptolens::CRYPTOLENS_OUTPUT_PHP` (1) or `Cryptolens::CRYPTOLENS_OUTPUT_JSON` (2)
+         * @param mixed $output
+         * @return void
+         */
+        public function setOutput($output){
             $this->output = $output;
         }
 
+        /**
+         * `loader()` - Loads all required sub classes
+         * @return void `require_once`s the API classes
+         */
         public static function loader(){
             require_once dirname(__FILE__) . "/classes/Helper.cryptolens.php";
             require_once dirname(__FILE__) . "/classes/Errors.cryptolens.php";
@@ -89,11 +147,17 @@ public static function loader(){
             require_once dirname(__FILE__) . "/classes/Customer.cryptolens.php";
             require_once dirname(__FILE__) . "/classes/Analytics.cryptolens.php";
             require_once dirname(__FILE__) . "/classes/User.cryptolens.php";
-            @require_once dirname(__FILE__) . "/classes/License.cryptolens.php";
+            require_once dirname(__FILE__) . "/classes/License.cryptolens.php";
 
 
         }
 
+        /**
+         * `outputHelper` - Returns the corresponding data type, either JSON or an PHP array
+         * @param mixed $data The data returned checked by `Helper::connection(...)`
+         * @param int $error
+         * @return array|bool|string
+         */
         public static function outputHelper($data, int $error = 0){
             if(self::$output == self::CRYPTOLENS_OUTPUT_PHP){
                 if($error == 1){
@@ -113,11 +177,73 @@ public static function outputHelper($data, int $error = 0){
                 }
                 return json_encode($data);
             }
+            return (array) $data;
         }
 
-    }
-}
+        public function analytics(): Analytics {
+            if(!$this->analytics) $this->analytics = new Analytics($this);
+            return $this->analytics;
+        }
+
+        public function auth(): Auth {
+            if(!$this->auth) $this->auth = new Auth($this);
+            return $this->auth;
+        }
+
+        public function customer(): Customer {
+            if(!$this->customer || $this->customer === null) $this->customer = new Customer($this);
+            return $this->customer;
+        }
 
+        public function data(): Data{
+            if(!$this->data) $this->data = new Data($this);
+            return $this->data;
+        }
+
+        public function endpoints(): Endpoints {
+            if(!$this->endpoints) $this->endpoints = new Endpoints;
+            return $this->endpoints;
+        }
+
+        public function key(): Key {
+            if(!$this->key) $this->key = new Key($this);
+            return $this->key;
+        }
+
+        public function license(bool $publicKeyIsXMLFormat = false, ?string $publicKeyFile = null): License {
+            if(!$this->license) $this->license = new License($publicKeyIsXMLFormat, $publicKeyFile);
+            return $this->license;
+        }
+
+        public function message(?string $channel = null): Message {
+            if(!$this->message) $this->message = new Message($this, $channel);
+            return $this->message;
+        }
+
+        public function paymentForm(): PaymentForm {
+            if(!$this->paymentForm) $this->paymentForm = new PaymentForm($this);
+            return $this->paymentForm;
+        }
+
+        public function product(): Product {
+            if(!$this->product) $this->product = new Product($this);
+            return $this->product;
+        }
+
+        public function reseller(): Reseller {
+            if(!$this->reseller) $this->reseller = new Reseller($this);
+            return $this->reseller;
+        }
 
+        public function subscription(): Subscription {
+            if(!$this->subscription) $this->subscription = new Subscription($this);
+            return $this->subscription;
+        }
+
+        public function user(): User {
+            if(!$this->user) $this->user = new User($this);
+            return $this->user;
+        }
 
-?>
+    }
+}
diff --git a/Cryptolens_old.php b/Cryptolens_old.php
@@ -1,6 +1,18 @@
 <?php
 
-function cryptolens_activate($token, $product_id, $key, $machine_code)
+/**
+ * `cryptolens_activate` - Standalone function to activate a key
+ * @param mixed $token The token to authenticate against the API
+ * @param mixed $product_id Your product ID
+ * @param mixed $key The key to activate
+ * @param mixed $machine_code optional machine code to bind the key to
+ * @return bool Either true on success or false on failure
+ * 
+ * @author Cryptolens AB
+ * @link https://github.com/cryptolens/cryptolens-php
+ * @deprecated You should use the library. This functions exits only for backwards compatibility.
+ */
+function cryptolens_activate(string $token, string $product_id, string $key, ?string $machine_code)
 {
   $params = 
     array(

diff --git a/README.md b/README.md
@@ -1,9 +1,9 @@
 # Cryptolens PHP
 
-This repository contains functions for interacting with the Cryptolens
-Web API from PHP. Currently most endpoints are supported and more are following.
+This repository contains functions for interacting with the Cryptolens Web API from PHP.
+All endpoints are supported. This API client uses Cryptolens Web API 3.
 
-For more information about the API and possible values and types, visit https://app.cryptolens.io/docs/api/v3, the official API documentation
+For more information about the API and possible values and types, visit https://app.cryptolens.io/docs/api/v3, the official API documentation.
 
 To use the library, you can `require_once` the `loader.php` which loads all other classes automatically or use composer where you just have to `require` the composer `autoload.php`. Currently, this library is not safe to use for CLI.
 Inside your script you need to `use` the classes, here is an example:
@@ -24,6 +24,11 @@ $k = new Key($c);
 $key = "XXXXX-XXXXX-XXXXX-XXXXX";
 $machine_id = $k->getMachineId();
 print_r("Key 'activate':" . var_dump($k->activate($key, $machine_id)));
+
+// OR
+
+$c->key()->activate($key, $c->key()->getMachineId());
+
 ?>
 ```
 

diff --git a/classes/Analytics.cryptolens.php b/classes/Analytics.cryptolens.php
@@ -1,7 +1,16 @@
 <?php
-
 namespace Cryptolens_PHP_Client {
-    class Analytics extends Cryptolens {
+    /**
+     * Analytics
+     * 
+     * Allows the use of all Analytics endpoints
+     * 
+     * @author Bryan Böhnke-Avan <bryan@openducks.org>
+     * @license MIT
+     * @since v0.9
+     * @link https://app.cryptolens.io/docs/api/v3/AI
+     */
+    class Analytics {
         private Cryptolens $cryptolens;
 
         private string $group;
@@ -38,7 +47,7 @@ public function register_event(string $key, string $machineid, string $featurena
                 "Currency" => $currency,
                 "Metadata" => $metadata
             );
-            $parms = Helper::build_params($this->cryptolens->get_token(), $this->cryptolens->get_product_id(), $key, $machineid, $additional_flags);
+            $parms = Helper::build_params($this->cryptolens->getToken(), $this->cryptolens->getProductId(), $key, $machineid, $additional_flags);
             $c = Helper::connection($parms, "registerEvent", $this->group);
             if($c == true){
                 if(Helper::check_rm($c)){
@@ -71,7 +80,7 @@ public function register_events(string $key = null, string $machineid = null, ar
                 "MachineCode" => $machineid,
                 "Events" => $events
             );
-            $parms = Helper::build_params($this->cryptolens->get_token(), $this->cryptolens->get_product_id(), $key, $machineid, $additional_flags);
+            $parms = Helper::build_params($this->cryptolens->getToken(), $this->cryptolens->getProductId(), $key, $machineid, $additional_flags);
             $c = Helper::connection($parms, "registerEvents", $this->group);
             if($c == true){
                 if(Helper::check_rm($c)){
@@ -102,7 +111,7 @@ public function get_events(int $limit = 10, int $startingafter = null, int $endi
             if(isset($key) && !isset($product_id)){
                 return false;
             }
-            $parms = Helper::build_params($this->cryptolens->get_token(), $product_id ?? $this->cryptolens->get_product_id(), $key, null, array("Limit" => $limit, "StartingAfter" => $startingafter, "EndingBefore" => $endingbefore, "Time" => $time, "Metadata" => $metadata));
+            $parms = Helper::build_params($this->cryptolens->getToken(), $product_id ?? $this->cryptolens->getProductId(), $key, null, array("Limit" => $limit, "StartingAfter" => $startingafter, "EndingBefore" => $endingbefore, "Time" => $time, "Metadata" => $metadata));
             $c = Helper::connection($parms, "getEvents", $this->group);
             if($c == true){
                 if(Helper::check_rm($c)){
@@ -128,7 +137,7 @@ public function get_object_log(int $limit = 10, int $startingafter = null){
             if($limit > 100){
                 return false;
             }
-            $parms = Helper::build_params($this->cryptolens->get_token(), $this->cryptolens->get_product_id(), null, null, array("Limit" => $limit, "StartingAfter" => $startingafter));
+            $parms = Helper::build_params($this->cryptolens->getToken(), $this->cryptolens->getProductId(), null, null, array("Limit" => $limit, "StartingAfter" => $startingafter));
             $c = Helper::connection($parms, "getObjectLog", $this->group);
             if($c == true){
                 if(Helper::check_rm($c)){
@@ -163,7 +172,7 @@ public function get_web_api_log(int $product_id = null, string $key = null, $lim
                 return false;
             }
 
-            $parms = Helper::build_params($this->cryptolens->get_token(), $this->cryptolens->get_product_id(), null, null, array("ProductId" => $product_id, "Key" => $key, "Limit" => $limit, "StartingAfter" => $startingafter, "EndingBefore" => $endingbefore, "AnomalyClassification" => $anomalyClassification));
+            $parms = Helper::build_params($this->cryptolens->getToken(), $this->cryptolens->getProductId(), null, null, array("ProductId" => $product_id, "Key" => $key, "Limit" => $limit, "StartingAfter" => $startingafter, "EndingBefore" => $endingbefore, "AnomalyClassification" => $anomalyClassification));
             $c = Helper::connection($parms, "getWebAPILog", $this->group);
             if($c == true){
                 if(Helper::check_rm($c)){
@@ -177,6 +186,3 @@ public function get_web_api_log(int $product_id = null, string $key = null, $lim
         }
     }
 }
-
-
-?>
diff --git a/classes/Auth.cryptolens.php b/classes/Auth.cryptolens.php
@@ -1,5 +1,15 @@
 <?php
 namespace Cryptolens_PHP_Client {
+    /**
+     * Auth
+     * 
+     * Allows the use of all Auth endpoints
+     * 
+     * @author Bryan Böhnke-Avan <bryan@openducks.org
+     * @license MIT
+     * @since v0.4
+     * @link https://app.cryptolens.io/docs/api/v3/AuthMethods
+     */
     class Auth {
 
         private Cryptolens $cryptolens;
@@ -18,7 +28,7 @@ public function __construct($cryptolens){
          * @return array|bool Returns an array on success, false on failure
          */
         public function key_lock($key){
-            $parms = Helper::build_params($this->cryptolens->get_token(), $this->cryptolens->get_product_id(), $key);
+            $parms = Helper::build_params($this->cryptolens->getToken(), $this->cryptolens->getProductId(), $key);
             $c = Helper::connection($parms, "keyLock", $this->group);
             if($c == true){
                 if(Helper::check_rm($c)){
@@ -33,6 +43,3 @@ public function key_lock($key){
         }
     }
 }
-
-
-?>