Added one more test, improved docs and CONTRIBUTING.md

Author: zzantares

CHANGELOG.md

@@ -1,8 +1,10 @@
-v2.0.0
+v2.1.0
 ------
 
 - Now it is possible to specify the desired return type when creating Proxmox object, setters and getters for return type were added.
-- Added docs about getters & setters of the Proxmox client object.
+- Added docs about getters & setters and other tricks of the Proxmox client object.
+- Now you can create a Proxmox API client object with a custom credentials object.
+
 
 v2.0.0
 ------

CONTRIBUTING.md

@@ -0,0 +1,25 @@
+Welcome developers!
+==================
+
+Before making any contribution you should now:
+
+- All code contribution should follow PSR-1 and PSR-2 coding style standards. (Thanks to [Alexey Ashurok](https://github.com/aotd1))
+- You should code the tests for any function you add, some times is not possible but try doing it.
+- All functions need to be properly documented, all comments, variable names, function names only on english language.
+- Variables and functions names should be self descriptive.
+
+
+Installation
+------------
+
+Of course you should [fork the repo](https://github.com/ZzAntares/ProxmoxVE/fork), then after cloning your forked repo:
+
+```sh
+$ composer install --dev  # run cmd inside the project folder
+```
+
+What needs to be done?
+----------------------
+
+What ever you think will improve this library and also let's wait the people to open issues and then we'll see.
+

doc/core_concepts.md

@@ -182,6 +182,51 @@ echo 'Hostname: ' . $credentialsB->getHostname();  // Hostname: hostB
 ```
 
 
+Using custom credentials object
+-------------------------------
+
+You can pass your own custom credentials object when creating the API client object, for now this library internally will create a valid credentials object. The only thing you custom credentials object needs, is to have the required accesible properties:
+
+- `hostname`
+- `username`
+- `password`
+- `realm` (optional defaults to `pam`)
+- `port` (optional defaults to `8006`)
+
+If you feel using getters is better, the Proxmox API client object will search for the next getters if properties are not accesible:
+
+- `getHostname()`
+- `getUsername()`
+- `getPassword()`
+- `getRealm()` (optional defaults to `pam`)
+- `getPort()` (optional defaults to `8006`)
+
+```php
+<?
+require_once 'vendor/autoload.php';
+
+// Example of custom credentials class
+class CustomCredentials
+{
+    public function __construct($host, $user, $pass)
+    {
+        $this->hostname = $host;
+        $this->username = $user;
+        $this->password = $pass;
+    }
+}
+
+// Create an object of your custom credentials object
+$customCredentials = new CustomCredentials('my.proxmox.tld', 'user', 'secret');
+
+// Pass your custom credentials when creating the API client
+$proxmox = new ProxmoxVE\Proxmox($customCredentials);
+
+// At this point you can use the $proxmox normally
+```
+
+> **Why is this useful?** Personally when dealing with Eloquent models I already have a Credentials object, so I want to use that object to login to a proxmox server.
+
 Set and get response type
 -------------------------
 

src/Proxmox.php

@@ -172,10 +172,20 @@ public function getCredentials()
     /**
      * Assign the passed Credentials object to the ProxmoxVE.
      *
-     * @param \ProxmoxVE\Credentials $credentials to assign.
+     * @param object $credentials A custom object holding credentials or a
+     *                            Credentials object to assign.
      */
-    public function setCredentials(Credentials $credentials)
+    public function setCredentials($credentials)
     {
+        if (!$credentials instanceof Credentials) {
+            if (!$this->validCredentialsObject($credentials)) {
+                $errorMessage = 'setCredentials needs a valid object.';
+                throw new \InvalidArgumentException($errorMessage);
+            }
+
+            $credentials = $this->loginUsingCredentials($credentials);
+        }
+
         $this->credentials = $credentials;
         $token = $credentials->login();
 
@@ -403,16 +413,16 @@ public function validCredentialsObject($credentials)
      *
      * @param object $credentials A custom object holding proxmox login data.
      */
-    public function loginUsingCredentials($credentials)
+    protected function loginUsingCredentials($credentials)
     {
 
         if ($this->accessibleBy == 'properties') {
             return new Credentials(
                 $credentials->hostname,
                 $credentials->username,
                 $credentials->password,
-                isset($credentials->realm) ? $credentials->realm : 'pam',  // Make it optional?
-                isset($credentials->port) ? $credentials->port : '8006'  // Make it optional?
+                isset($credentials->realm) ? $credentials->realm : 'pam',
+                isset($credentials->port) ? $credentials->port : '8006'
             );
         }
 

tests/CustomCredentials/BadCredentials.php

@@ -0,0 +1,18 @@
+<?php
+
+namespace ProxmoxVE\CustomCredentials;
+
+class BadCredentials
+{
+    private $hostname;
+    private $username;
+    private $password;
+
+
+    public function __construct($host, $user, $pass)
+    {
+        $this->hostname = $host;
+        $this->username = $user;
+        $this->password = $pass;
+    }
+}

tests/ProxmoxTest.php

@@ -212,23 +212,23 @@ public function testValidCredentialsObject()
         $credentials = $this->getMockCredentials(array('host', 'user', 'pass'));
         $proxmox = new Proxmox($credentials);
 
-        $propertiesCredentials = new CustomCredentials\PropertiesCredentials('host', 'user', 'pass', 'realm', 'port');
-        $methodsCredentials = new CustomCredentials\MethodsCredentials('host', 'user', 'pass', 'realm', 'port');
-
         $this->assertFalse($proxmox->validCredentialsObject('not an object'));
+
+        $propertiesCredentials = new CustomCredentials\PropertiesCredentials('host', 'user', 'pass', 'realm', 'port');
         $this->assertTrue($proxmox->validCredentialsObject($propertiesCredentials));
+
+        $methodsCredentials = new CustomCredentials\MethodsCredentials('host', 'user', 'pass', 'realm', 'port');
         $this->assertTrue($proxmox->validCredentialsObject($methodsCredentials));
 
         $propertiesOptCredentials = new CustomCredentials\PropertiesOptCredentials('host', 'user', 'pass');
-        $methodsOptCredentials = new CustomCredentials\MethodsOptCredentials('host', 'user', 'pass');
-
         $this->assertTrue($proxmox->validCredentialsObject($propertiesOptCredentials));
+
+        $methodsOptCredentials = new CustomCredentials\MethodsOptCredentials('host', 'user', 'pass');
         $this->assertTrue($proxmox->validCredentialsObject($methodsOptCredentials));
-    }
 
+        $badCredentials = new CustomCredentials\BadCredentials('bad', 'user', 'passwd');
+        $this->assertFalse($proxmox->validCredentialsObject($badCredentials));
+    }
 
-    /**
-     * Probar que se pueda usar CustomCredentials con campos realm y port optativos
-     */
 }