Update documentation for release of version 1.0.0 (#14)

* Baremetal documentation

* Add billing documentation

* Block storage documentation

* Add DNS documentation

* Add firewall documentation

* ISO documentation

* Add instance documentation

* Add ModelOptions usage example to readme

* Add kubernetes documentation

* Update changelog

* Ignore comment at the top of model

* Load balancer documentation

* Add object storage documentation

* Add operating system documentation

* Add plan documentation

* Regions documentation

* More documentation on models

* More documentation

* Add missing getAvailableVersions test for kubernetes service

* Add exception test to getAvailableUpgrades for baremetal service handler

* add missing json file

* Add more documentation and grammar

CHANGELOG.md

@@ -1,5 +1,8 @@
 # Changelog
 
+## Release [1.0.0]
+* Initial Release of the Client
+
 ## Beta Release [0.5]
 * Initial Beta Release of the client
 * Ongoing test before the release of version 1

README.md

@@ -16,7 +16,7 @@
 
 Must have a PSR7, PSR17, and PSR18 Compatible HTTP Client. 
 [View all PSR's](https://www.php-fig.org/psr/)
-This client will act on those interfaces above interfaces which allow for dependancy injection. See Usage for more info.
+This client will act on those interfaces which allow for dependancy injection. See Usage for more info.
 https://packagist.org/providers/psr/http-client-implementation
 
 ### Installation
@@ -63,7 +63,7 @@ The client uses a linked list to paginate between your cursors. Each list call r
 
 declare(strict_types=1);
 
-require (__DIR__.'/../vendor/autoload.php');
+require(__DIR__.'/../vendor/autoload.php');
 
 $client = Vultr\VultrPhp\VultrClient::create('Your Lovely Vultr API Key');
 
@@ -92,6 +92,37 @@ while (true)
 
 ```
 
+#### ModelOptions Usage
+ModelOptions are objects that allow the user to pass in many arguments that don't neccessarily belong to a Model object. These are attributes that are specific to creation and update functions throughout the client library. Usage of these objects are quite simple. The idea was to reduce code complexity but also give the flexibility to deprecate certain methods when/if attributes are removed from responses.
+
+Lets take InstanceCreate for example. This object has many properties in it, that are all underscore_cased. These property names are than used to generate a request to the api.
+
+To keep the uniformity between the camelCased functions in this client library. ModelOptions makes use of php's `__call` magic method. In order to set these protected properties you can use variation of with functions example: withYourLovelyPropName('hello_world') or set functions example: setYourLovelyPropName('hello_world').
+
+These functions will set your attributes that will be used to generate the request of our underscored_props that will be sent to the api.
+
+With the addition of with and set type functions. There are also get functions that can be used as well. They follow the same camcelCased layout as the with and set functions.
+
+Example usage of these object functions.
+
+```php
+
+declare(strict_types=1);
+
+require(__DIR__.'/../vendor/autoload.php');
+
+use Vultr\VultrPhp\Services\Instances\InstanceCreate;
+
+$create = new InstanceCreate('ewr', 'vc2-6c-16gb');
+
+$create->setOsId(6969);
+
+$create = $create->withHostname('my-amazing-hostname');
+
+var_dump($create->getOsId(), $create->getHostname());
+
+```
+
 #### Exception Usage
 
 All exceptions are children of VultrException. 

examples/instances.php

@@ -51,6 +51,7 @@
 
 echo PHP_EOL;
 echo "Removing the instance\n";
+sleep(1);
 $client->instances->deleteInstance($instance->getId());
 
 var_dump($client->instances->getInstances());

src/Services/Account/Account.php

@@ -7,7 +7,7 @@
 use Vultr\VultrPhp\Util\Model;
 
 /**
- * Contains information about, the account, permission, and billing information
+ * Contains information about, the account, permission, and billing information.
  */
 class Account extends Model
 {

src/Services/Account/AccountService.php

@@ -6,10 +6,16 @@
 
 use Vultr\VultrPhp\Services\VultrService;
 
+/**
+ * Account service handler, for account endpoints.
+ *
+ * @see https://www.vultr.com/api/#tag/account
+ */
 class AccountService extends VultrService
 {
 	/**
 	 * Get the Account Model with information for the logged in API Key.
+	 *
 	 * @throws AccountException
 	 * @throws VultrException
 	 * @return Account

src/Services/Applications/Application.php

@@ -7,7 +7,7 @@
 use Vultr\VultrPhp\Util\Model;
 
 /**
- * Holds deployable application image info that can be used on virtualmachine's and baremetal's
+ * Holds deployable application image info that can be used on virtualmachine's and baremetal's.
  */
 class Application extends Model
 {

src/Services/Applications/ApplicationService.php

@@ -7,6 +7,11 @@
 use Vultr\VultrPhp\Services\VultrService;
 use Vultr\VultrPhp\Util\ListOptions;
 
+/**
+ * Application service handler, for applications endpoints.
+ *
+ * @see https://www.vultr.com/api/#tag/application
+ */
 class ApplicationService extends VultrService
 {
 	public const FILTER_ALL = 'all';
@@ -17,6 +22,7 @@ class ApplicationService extends VultrService
 
 	/**
 	 * Get a list of all available application images.
+	 *
 	 * @param $filter - ENUM('all', 'marketplace', 'one-click')
 	 * @param $options - ListOptions|null - Interact via reference.
 	 * @throws ApplicationException
@@ -33,6 +39,7 @@ public function getApplications(string $filter = self::FILTER_ALL, ?ListOptions
 
 	/**
 	 * Get a specific application object based on the app_id.
+	 *
 	 * @param $id - int - Application id, whether one click or marketplace app.
 	 * @throws ApplicationException
 	 * @return Application|null
@@ -44,6 +51,8 @@ public function getApplication(int $id) : ?Application
 	}
 
 	/**
+	 * Cache all available applications from the vultr api.
+	 *
 	 * @param $override - bool - Depending on whether to requery the applications.
 	 * @throws ApplicationException
 	 * @return void

src/Services/Backups/BackupService.php

@@ -7,6 +7,11 @@
 use Vultr\VultrPhp\Services\VultrService;
 use Vultr\VultrPhp\Util\ListOptions;
 
+/**
+ * Backup service handler, for backup endpoints.
+ *
+ * @see https://www.vultr.com/api/#tag/backup
+ */
 class BackupService extends VultrService
 {
 	/**

src/Services/BareMetal/BareMetal.php

@@ -6,6 +6,9 @@
 
 use Vultr\VultrPhp\Util\Model;
 
+/**
+ * Holds baremetal information from the response of the api.
+ */
 class BareMetal extends Model
 {
 	protected string $id;

src/Services/BareMetal/BareMetalCreate.php

@@ -6,12 +6,13 @@
 
 use Vultr\VultrPhp\Util\ModelOptions;
 
+/**
+ * Options to create a baremetal machine.
+ *
+ * @see https://www.vultr.com/api/#operation/create-baremetal
+ */
 class BareMetalCreate extends ModelOptions
 {
-	/**
-	 * @see https://www.vultr.com/api/#operation/create-baremetal
-	 */
-
 	// Required Parameters.
 	protected string $region;
 	protected string $plan;

src/Services/BareMetal/BareMetalIPv4Info.php

@@ -6,6 +6,9 @@
 
 use Vultr\VultrPhp\Util\Model;
 
+/**
+ * Holds ipv4 address information on the ip address attached to the baremetal machine.
+ */
 class BareMetalIPv4Info extends Model
 {
 	// The response data.

src/Services/BareMetal/BareMetalIPv6Info.php

@@ -6,6 +6,9 @@
 
 use Vultr\VultrPhp\Util\Model;
 
+/**
+ * Holds ipv6 address information on the ip address attached to the baremetal machine.
+ */
 class BareMetalIPv6Info extends Model
 {
 	// The response data.

src/Services/BareMetal/BareMetalService.php

@@ -12,9 +12,15 @@
 use Vultr\VultrPhp\Util\VultrUtil;
 use Vultr\VultrPhp\VultrClientException;
 
+/**
+ * Baremetal service handler, for bare-metals endpoints.
+ *
+ * @see https://www.vultr.com/api/#tag/baremetal
+ */
 class BareMetalService extends VultrService
 {
 	/**
+	 * List all Bare Metal instances in your account.
 	 * @see https://www.vultr.com/api/#operation/list-baremetals
 	 * @param $options - ListOptions|null - Interact via reference.
 	 * @throws BareMetalException
@@ -26,6 +32,7 @@ public function getBareMetals(?ListOptions &$options = null) : array
 	}
 
 	/**
+	 * Get information for a Bare Metal instance.
 	 * @see https://www.vultr.com/api/#operation/get-baremetal
 	 * @param $id - string - Example: cb676a46-66fd-4dfb-b839-443f2e6c0b60
 	 * @throws BareMetalException
@@ -37,6 +44,7 @@ public function getBareMetal(string $id) : BareMetal
 	}
 
 	/**
+	 * Delete a Bare Metal instance.
 	 * @see https://www.vultr.com/api/#operation/delete-baremetal
 	 * @throws BareMetalException
 	 * @return void
@@ -47,6 +55,8 @@ public function deleteBareMetal(string $id) : void
 	}
 
 	/**
+	 * Create a new Bare Metal instance based on BareMetalCreate
+	 * @see BareMetalCreate
 	 * @see https://www.vultr.com/api/#operation/create-baremetal
 	 * @param $payload - BareMetalCreate
 	 * @throws BareMetalException
@@ -58,6 +68,7 @@ public function createBareMetal(BareMetalCreate $payload) : BareMetal
 	}
 
 	/**
+	 * Update a Bare Metal instance. All attributes are optional in BareMetalUpdate. If not set the attributes will not be sent to the API.
 	 * @see https://www.vultr.com/api/#operation/update-baremetal
 	 * @param $id - string - Example: cb676a46-66fd-4dfb-b839-443f2e6c0b60
 	 * @param $payload - BareMetalUpdate
@@ -83,6 +94,7 @@ public function updateBareMetal(string $id, BareMetalUpdate $payload) : BareMeta
 	}
 
 	/**
+	 * Get all IPv4 information for the Bare Metal instance.
 	 * @see https://www.vultr.com/api/#operation/get-ipv4-baremetal
 	 * @param $id - string - Example: cb676a46-66fd-4dfb-b839-443f2e6c0b60
 	 * @throws BareMetalException
@@ -95,6 +107,7 @@ public function getIPv4Addresses(string $id) : array
 	}
 
 	/**
+	 * Get all IPv6 information for the Bare Metal instance.
 	 * @see https://www.vultr.com/api/#operation/get-ipv6-baremetal
 	 * @param $id - string - Example: cb676a46-66fd-4dfb-b839-443f2e6c0b60
 	 * @throws BareMetalException
@@ -142,6 +155,7 @@ public function startBareMetal(string $id) : void
 	}
 
 	/**
+	 * Start the Bare Metal instance.
 	 * @see https://www.vultr.com/api/#operation/start-bare-metals
 	 * @param $ids - array - Example: [cb676a46-66fd-4dfb-b839-443f2e6c0b60, cb676a46-66fd-4dfb-b839-443f2e6c0b65]
 	 * @throws BareMetalException
@@ -153,6 +167,7 @@ public function startBareMetals(array $ids) : void
 	}
 
 	/**
+	 * Reboot the Bare Metal instance.
 	 * @see https://www.vultr.com/api/#operation/reboot-baremetal
 	 * @param $id - string - Example: cb676a46-66fd-4dfb-b839-443f2e6c0b60
 	 * @throws BareMetalException
@@ -164,6 +179,7 @@ public function rebootBareMetal(string $id) : void
 	}
 
 	/**
+	 * Reboot multiple Bare Metal instances with 1 api call.
 	 * @see https://www.vultr.com/api/#operation/reboot-bare-metals
 	 * @param $ids - array - Example: [cb676a46-66fd-4dfb-b839-443f2e6c0b60, cb676a46-66fd-4dfb-b839-443f2e6c0b65]
 	 * @throws BareMetalException
@@ -175,6 +191,7 @@ public function rebootBareMetals(array $ids) : void
 	}
 
 	/**
+	 * Reinstall the Bare Metal instance. This action usually takes a few seconds to complete.
 	 * @see https://www.vultr.com/api/#operation/reinstall-baremetal
 	 * @param $id - string - Example: cb676a46-66fd-4dfb-b839-443f2e6c0b60
 	 * @throws BareMetalException
@@ -186,6 +203,7 @@ public function reinstallBareMetal(string $id) : BareMetal
 	}
 
 	/**
+	 * Halt the Bare Metal instance. The machine will remain off till started again.
 	 * @see https://www.vultr.com/api/#operation/halt-baremetal
 	 * @param $id - string - Example: cb676a46-66fd-4dfb-b839-443f2e6c0b60
 	 * @throws BareMetalException
@@ -197,6 +215,7 @@ public function haltBareMetal(string $id) : void
 	}
 
 	/**
+	 * Halt multiple Bare Metal instances. The machines will remain off till started again.
 	 * @see https://www.vultr.com/api/#operation/halt-baremetals
 	 * @param $ids - array - Example: [cb676a46-66fd-4dfb-b839-443f2e6c0b60, cb676a46-66fd-4dfb-b839-443f2e6c0b65]
 	 * @throws BareMetalException
@@ -232,6 +251,11 @@ private function multipleServersAction(string $action, array $ids) : void
 	}
 
 	/**
+	 * Get bandwidth information for the Bare Metal instance
+	 *
+	 * The structure of the array will follow this format.
+	 * ['2022-11-05' => ['incoming_bytes' => 234523452352, 'outgoing_bytes' => 132432423]]
+	 *
 	 * @see https://www.vultr.com/api/#operation/get-bandwidth-baremetal
 	 * @param $id - string - Example: cb676a46-66fd-4dfb-b839-443f2e6c0b60
 	 * @throws BareMetalException
@@ -266,6 +290,8 @@ public function getBandwidth(string $id) : array
 	}
 
 	/**
+	 * Get the user-supplied, which is decoded for you from base64 that the api returns.
+	 *
 	 * @see https://www.vultr.com/api/#operation/get-bare-metal-userdata
 	 * @param $id - string - Example: cb676a46-66fd-4dfb-b839-443f2e6c0b60
 	 * @throws BareMetalException
@@ -287,6 +313,8 @@ public function getUserData(string $id) : string
 	}
 
 	/**
+	 * Get available upgrades for a Bare Metal instance.
+	 *
 	 * @see https://www.vultr.com/api/#operation/get-bare-metals-upgrades
 	 * @param $id - string - Example: cb676a46-66fd-4dfb-b839-443f2e6c0b60
 	 * @param $type - string - filter based on upgrade types.
@@ -319,6 +347,8 @@ public function getAvailableUpgrades(string $id, string $type = 'all') : array
 	}
 
 	/**
+	 * Get the VNC URL for a Bare Metal instance. Which can be used to access the console of the machine.
+	 *
 	 * @see https://www.vultr.com/api/#operation/get-bare-metal-vnc
 	 * @param $id - string - Example: cb676a46-66fd-4dfb-b839-443f2e6c0b60
 	 * @throws BareMetalException

src/Services/BareMetal/BareMetalUpdate.php

@@ -6,11 +6,13 @@
 
 use Vultr\VultrPhp\Util\ModelOptions;
 
+/**
+ * Options to update a baremetal machine.
+ *
+ * @see https://www.vultr.com/api/#operation/update-baremetal
+ */
 class BareMetalUpdate extends ModelOptions
 {
-	/**
-	 * @see https://www.vultr.com/api/#operation/update-baremetal
-	 */
 	protected ?string $user_data = null;
 	protected ?string $label = null;
 	protected ?int $os_id = null;

src/Services/Billing/Bill.php

@@ -6,6 +6,9 @@
 
 use Vultr\VultrPhp\Util\Model;
 
+/**
+ * Holds billing history information.
+ */
 class Bill extends Model
 {
 	protected int $id;