Adding type safety to any other class

Author: Ente

README.md

@@ -128,6 +128,8 @@ DDNS(new API(__DIR__ . "/configurations", ".env-custom"), file_get_contents("/my
 ### v1.1.4: Type safety
 
 - Added type safety to the `DDNS.Helper.API.dnsserver.ente.php` class
+- Added type safety to all other classes
+- Fixed incorrect/Added API docs
 
 ### v1.1.3: Shell safe
 

src/API.dnsserver.ente.php

@@ -18,7 +18,7 @@
 
 class API {
 
-    private $protocol;
+    private string $protocol;
     private $admin;
     private $allowed;
     private $apps;
@@ -32,20 +32,20 @@ class API {
     private $zones;
     private $ddns;
     private $log;
-    private $conf;
-    private $path;
-    private $fullPath;
-    private $env = [];
+    private string $conf;
+    private string $path;
+    private string $fullPath;
+    private array $env = [];
     const PREFIX_GET = "&token=";
     const PREFIX_POST = "?token=";
 
-    public function __construct($confPath, $name = null){
+    public function __construct(string $confPath, ?string $name = null){
         $this->loader();
         $this->loadConf($confPath, $name);
         $this->setProtocol();
     }
 
-    private function setProtocol(){
+    private function setProtocol(): void{
         if($this->env["USE_HTTPS"] == "true"){
             $this->protocol = "https";
         } else {
@@ -59,7 +59,7 @@ private function setProtocol(){
      * @param mixed $name The name of the .env file. (optional)
      * @return void
      */
-    private function loadConf($path, $name = null){
+    private function loadConf(string $path, ?string $name = null): void{
         $this->conf = $name ?? ".env";
         if(!isset($_SERVER)){
             $path = __DIR__;
@@ -90,7 +90,7 @@ private function loadConf($path, $name = null){
 
     }
 
-    public function loader(){
+    public function loader(): void{
         require_once __DIR__ . "/endpoints/admin/Admin.php";
         require_once __DIR__ . "/endpoints/allowed/Allowed.php";
         require_once __DIR__ . "/endpoints/apps/Apps.php";
@@ -111,12 +111,12 @@ public function loader(){
      * `sendCall()` - Send a request to the Technitium API.
      * @param array $data The data to send to the API
      * @param string $endpoint The endpoint to send the data to, e.g. "admin/users/list"
-     * @param mixed $method The HTTP method to use. Default is "POST".
-     * @param mixed $skip Set to `true` to skip the authentication URI append.
-     * @param mixed $bypass Set to `true` to bypass the endpoint check allowing to access not (yet) implemented methods.
+     * @param string $method The HTTP method to use. Default is "POST".
+     * @param bool $skip Set to `true` to skip the authentication URI append.
+     * @param bool $bypass Set to `true` to bypass the endpoint check allowing to access not (yet) implemented methods.
      * @return array Returns the response from the API or an error (["status" => "error"]) as an array.
      */
-    public function sendCall($data, $endpoint, $method = "POST", $skip = false, $bypass = false){
+    public function sendCall(array $data, string $endpoint, string $method = "POST", bool $skip = false, bool $bypass = false): array{
         $c = curl_init();
         $endpoint = $this->prepareEndpoint($endpoint, $bypass);
         if($this->env["USE_POST"]){
@@ -161,11 +161,11 @@ public function sendCall($data, $endpoint, $method = "POST", $skip = false, $byp
 
     /**
      * `appendAuth()` - Append the authentication token to the URI.
-     * @param mixed $m The HTTP method to use. Default is "POST".
-     * @param mixed $skip Set to `true` to skip the authentication URI append, allowing the use of `API::getPermanentToken()`.
+     * @param string $m The HTTP method to use. Default is "POST".
+     * @param bool $skip Set to `true` to skip the authentication URI append, allowing the use of `API::getPermanentToken()`.
      * @return string Returns the authentication token URI string or an empty string.
      */
-    private function appendAuth($m = "POST", $skip = false){
+    private function appendAuth(string $m = "POST", bool $skip = false): string{
         $this->loadConf($this->path, $this->conf);
         $authAppend = null;
         if($skip){
@@ -206,7 +206,7 @@ private function appendAuth($m = "POST", $skip = false){
      * This function is called when the token is not found in the .env file.
      * @return bool Returns `true` if the token was successfully written to the .env file.
      */
-    private function getPermanentToken(){
+    private function getPermanentToken(): bool{
         Log::error_rep("Getting permanent token... | .env: " . $this->fullPath);
         $response = $this->sendCall([
             "user" => $this->env["USERNAME"],
@@ -234,10 +234,10 @@ private function getPermanentToken(){
     /**
      * `checkResponse()` - Check if the Technitium API response is valid.
      * If the response status contains either "error" or "invalid-token" it is considered invalid.
-     * @param mixed $response The response returned by `API::sendCall()` function.
+     * @param string $response The response returned by `API::sendCall()` function.
      * @return bool Returns `true` if the response is valid, otherwise `false`.
      */
-    private function checkResponse(string $response){
+    private function checkResponse(string $response): bool{
         if(is_null($response)){
             return false;
         } else {
@@ -248,11 +248,11 @@ private function checkResponse(string $response){
 
     /**
      * `prepareEndpoint()` - Generates the API URI for the endpoint in question.
-     * @param mixed $endpoint The endpoint to generate the URI for.
-     * @param mixed $bypass Set to `true` to bypass the endpoint check allowing to access not (yet) implemented methods.
+     * @param string $endpoint The endpoint to generate the URI for.
+     * @param bool $bypass Set to `true` to bypass the endpoint check allowing to access not (yet) implemented methods.
      * @return bool|string Returns the URI as string or `false` if the endpoint is not implemented.
      */
-    private function prepareEndpoint($endpoint, $bypass = false){
+    private function prepareEndpoint(string $endpoint, bool $bypass = false): bool|string{
         if($bypass){
             return $this->protocol . "://" . $this->env["API_URL"] . "/api/" . $endpoint;
         }

src/endpoints/admin/Admin.php

@@ -20,12 +20,12 @@ class admin {
 
     private $groups;
 
-    public function __construct($api){
+    public function __construct(\Technitium\DNSServer\API\API $api){
         $this->API = $api;
         $this->eloader();
     }
 
-    private function eloader(){
+    private function eloader(): void{
         require_once __DIR__ . "/Groups.admin.php";
         require_once __DIR__ . "/Logs.admin.php";
         require_once __DIR__ . "/Permissions.admin.php";

src/endpoints/admin/Groups.admin.php

@@ -9,7 +9,7 @@
 class groups {
     public $API;
 
-    public function __construct($api){
+    public function __construct(\Technitium\DNSServer\API\API $api){
         $this->API = $api;
     }
 
@@ -18,7 +18,7 @@ public function __construct($api){
      * - `PERMISSIONS`: `Administration:View`
      * @return array|bool Returns the result array or an error array
      */
-    public function list(){
+    public function list(): array|bool{
         $response = $this->API->sendCall([], "admin/groups/list");
         if($response["status"] == "ok"){
             return $response["response"];
@@ -34,7 +34,7 @@ public function list(){
      * @param bool $includeUsers Set to `true` to include the list of users in the group.
      * @return array|bool Returns the result array or false if the group was not found.
      */
-    public function get(string $name, bool $includeUsers = true){
+    public function get(string $name, bool $includeUsers = true): array|bool{
         $includeUsers = $includeUsers ? "true" : "false";
         $response = $this->API->sendCall(["group" => $name, "includeUsers" => "true"], "admin/groups/get");
         if($response["response"]["name"] == $name){
@@ -50,7 +50,7 @@ public function get(string $name, bool $includeUsers = true){
      * @param string $description The description text for the group (optional).
      * @return bool Returns `true` if the group was created successfully, otherwise `false`.
      */
-    public function create(string $name, string $description = null){
+    public function create(string $name, string $description = null): bool{
         $response = $this->API->sendCall(["group" => $name, "description" => $description], "admin/groups/create");
         return $response["response"]["name"] == $name;
     }
@@ -64,7 +64,7 @@ public function create(string $name, string $description = null){
      * @param array $members An array of users to add to the group (optional).
      * @return array|bool Returns the result array or `false` if the group was not found.
      */
-    public function set(string $name, string $newName = null, string $description = null, array $members = []){
+    public function set(string $name, string $newName = null, string $description = null, array $members = []): array|bool{
         $response = $this->API->sendCall(["group" => $name, "newGroup" => $newName, "description" => $description, "members" => implode(",", $members)], "admin/groups/set");
         if($response["response"]["name"] == $name){
             return $response["response"];
@@ -78,7 +78,7 @@ public function set(string $name, string $newName = null, string $description =
      * @param string $name The name of the group to delete.
      * @return bool Returns the result array or an error array.
      */
-    public function delete(string $name){
+    public function delete(string $name): bool{
         $response = $this->API->sendCall(["group" => $name], "admin/groups/delete");
         return $response["status"] == "ok";
     }

src/endpoints/admin/Logs.admin.php

@@ -4,15 +4,15 @@
 class logs {
     public $API;
 
-    public function __construct($api){
+    public function __construct(\Technitium\DNSServer\API\API $api){
         $this->API = $api;
     }
 
     /**
      * `list()` - Returns a list of all log files.
      * @return array|bool Returns the result array or `false` if the group was not found.
      */
-    public function list(){
+    public function list(): array|bool{
         $response = $this->API->sendCall([], "admin/logs/list");
         if($response["status"] == "ok"){
             return $response["response"];
@@ -39,7 +39,7 @@ public function list(){
      * - `qclass` (optional): The DNS class (QCLASS) in the request question section to filter the logs.
      * @return array Returns the result array or `false` if the group was not found.
      */
-    public function query($data){
+    public function query($data): array{
         return $this->API->sendCall($data, "admin/logs/query");
     }
 
@@ -49,7 +49,7 @@ public function query($data){
      * @param int $limit The number of mb to limit the download to.
      * @return array|bool Returns the result array or `false` if the group was not found.
      */
-    public function download(string $fileName, int $limit = 0){
+    public function download(string $fileName, int $limit = 0): array|bool{
         $response = $this->API->sendCall(["fileName" => $fileName, "limit" => $limit], "admin/logs/download");
         if($response["status"] == "ok"){
             return $response["response"];
@@ -63,7 +63,7 @@ public function download(string $fileName, int $limit = 0){
      * @param string $log The name of the file to delete.
      * @return bool Returns `true` if the file was deleted or `false` if the file was not found.
      */
-    public function delete(string $log){
+    public function delete(string $log): bool{
         $response = $this->API->sendCall(["log" => $log], "admin/logs/delete");
         return $response["status"] == "ok";
     }
@@ -72,7 +72,7 @@ public function delete(string $log){
      * `deleteAll()` - Deletes all log files.
      * @return bool Returns `true` if the files were deleted or `false` if the files were not found.
      */
-    public function deleteAll(){
+    public function deleteAll(): bool{
         $response = $this->API->sendCall([], "admin/logs/deleteAll");
         return $response["status"] == "ok";
     }

src/endpoints/admin/Permissions.admin.php

@@ -8,7 +8,7 @@
 class permissions {
     public $API;
 
-    public function __construct($api){
+    public function __construct(\Technitium\DNSServer\API\API $api){
         $this->API = $api;
     }
 
@@ -17,7 +17,7 @@ public function __construct($api){
      * - `PERMISSIONS`: `Administration:View`
      * @return array|bool Returns the result array or `false` if the group was not found.
      */
-    public function list(){
+    public function list(): array|bool{
         $response = $this->API->sendCall([], "admin/permissions/list");
         if($response["status"] == "ok"){
             return $response["response"];
@@ -32,7 +32,7 @@ public function list(){
      * @param bool $includeUsersAndGroups Set to `true` to include the list of users and groups with permissions. (optional)
      * @return array|bool Returns the result array or `false` if the group was not found.
      */
-    public function get(string $section, bool $includeUsersAndGroups = false){
+    public function get(string $section, bool $includeUsersAndGroups = false): array|bool{
         if($includeUsersAndGroups){ $includeUsersAndGroups = "true"; } else { $includeUsersAndGroups = "false"; }
         $response = $this->API->sendCall(["section" => $section, "includeUsersAndGroups" => $includeUsersAndGroups], "admin/permissions/get");
         if($response["status"] == "ok"){
@@ -49,7 +49,7 @@ public function get(string $section, bool $includeUsersAndGroups = false){
      * @param string $groupPermissions The permissions to set for groups (pipe seperated table data with each row containing group names and bools for view, modify and delete permission, e.g. `Administrators|true|true|false|Example Group|true|false|false`). (optional)
      * @return array|bool Returns the result array or `false` if the group was not found.
      */
-    public function set(string $section, string $userPermissions = null, string $groupPermissions = null){
+    public function set(string $section, string $userPermissions = null, string $groupPermissions = null): array|bool{
         $response = $this->API->sendCall(["section" => $section, "userPermissions" => $userPermissions, "groupPermissions" => $groupPermissions], "admin/permissions/set");
         if($response["response"]["section"] == $section){
             return $response["response"];

src/endpoints/admin/Sessions.admin.php

@@ -5,7 +5,7 @@ class sessions {
 
     public $API;
 
-    public function __construct($api){
+    public function __construct(\Technitium\DNSServer\API\API $api){
         $this->API = $api;
     }
 
@@ -16,7 +16,7 @@ public function __construct($api){
      * @param string $tokenName The name of the token to create.
      * @return array|bool Returns the result array or `false` if the request failed.
      */
-    public function createToken(string $username, string $tokenName){
+    public function createToken(string $username, string $tokenName): array|bool{
         $response = $this->API->sendCall(["user" => $username, "tokenName" => $tokenName], "admin/sessions/create", "POST");
         if($response["status"] == "ok"){
             return $response["response"];
@@ -31,7 +31,7 @@ public function createToken(string $username, string $tokenName){
      * @param string $partialToken The partial token to delete (Can be obtained from `list()`).
      * @return bool Returns `true` if the request was successful, `false` otherwise.
      */
-    public function delete(string $partialToken){
+    public function delete(string $partialToken): bool{
         $response = $this->API->sendCall(["partialToken" => $partialToken], "admin/sessions/delete", "POST");
         return $response["status"] == "ok";
     }
@@ -41,7 +41,7 @@ public function delete(string $partialToken){
      * - `PERMISSIONS`: `Administration:View`
      * @return array|bool Returns the list of session tokens or `false` if the request failed.
      */
-    public function list(){
+    public function list(): array|bool{
         $response = $this->API->sendCall([], "admin/sessions/list", "GET");
         if($response["status"] == "ok"){
             return $response["response"];

src/endpoints/admin/Users.admin.php

@@ -4,7 +4,7 @@
 class users {
     public $API;
 
-    public function __construct($api){
+    public function __construct(\Technitium\DNSServer\API\API $api){
         $this->API = $api;
     }
 
@@ -13,7 +13,7 @@ public function __construct($api){
      * - `PERMISSIONS`: `Administration:View`
      * @return array|bool Returns the list of users or `false` if the request failed.
      */
-    public function list(){
+    public function list(): array|bool{
         $response = $this->API->sendCall([], "admin/users/list", "GET");
         if($response["status"] == "ok"){
             return $response["response"];
@@ -30,7 +30,7 @@ public function list(){
      * @param string $displayName The display name of the user to create.
      * @return bool Returns `true` if the request was successful, `false` otherwise.
      */
-    public function create(string $username, string $password, string $displayName = ""){
+    public function create(string $username, string $password, string $displayName = ""): bool{
         $response = $this->API->sendCall(["user" => $username, "pass" => $password, "displayName" => $displayName], "admin/users/create", "POST");
         return $response["status"] == "ok";
     }
@@ -48,7 +48,7 @@ public function create(string $username, string $password, string $displayName =
      * @param array $memberOfGroups The groups the user should be a member of.
      * @return bool Returns `true` if the request was successful, `false` otherwise.
      */
-    public function set(string $username, string $displayName = "", string $newUser = "", bool $disabled = false, int $sessionTimeoutSeconds = 0, string $newPassword = "", int $iterations = 5, array $memberOfGroups = []){
+    public function set(string $username, string $displayName = "", string $newUser = "", bool $disabled = false, int $sessionTimeoutSeconds = 0, string $newPassword = "", int $iterations = 5, array $memberOfGroups = []): bool{
         if($disabled){$disabled = "true";}else{$disabled = "false";}
         $response = $this->API->sendCall(["user" => $username, "displayName" => $displayName, "newUser" => $newUser, "disabled" => $disabled, "sessionTimeoutSeconds" => $sessionTimeoutSeconds, "newPass" => $newPassword, "iterations" => $iterations, "memberOfGroups" => implode(",", $memberOfGroups)], "admin/users/set", "POST");
         return $response["status"] == "ok";
@@ -60,7 +60,7 @@ public function set(string $username, string $displayName = "", string $newUser
      * @param string $username The username of the user to delete.
      * @return bool Returns `true` if the request was successful, `false` otherwise.
      */
-    public function delete(string $username){
+    public function delete(string $username): bool{
         $response = $this->API->sendCall(["user" => $username], "admin/users/delete", "POST");
         return $response["status"] == "ok";
     }
@@ -72,7 +72,7 @@ public function delete(string $username){
      * @param bool $includeGroups Whether to include the groups the user is a member of.
      * @return array|bool Returns the user details or `false` if the request failed.
      */
-    public function get(string $username, bool $includeGroups = false){
+    public function get(string $username, bool $includeGroups = false): array|bool{
         if($includeGroups){$includeGroups = "true";} else {$includeGroups = "false";}
         $response = $this->API->sendCall(["user" => $username, "includeGroups" => $includeGroups], "admin/users/get", "GET");
         if($response["status"] == "ok"){