README

Utility classes for vCloud Director PHP SDK

Installation

Installation can be done via Composer. All you need is to add this to your composer.json:

  "repositories": [
    {
      "type": "pear",
      "url": "http://pear.php.net"
    }
  ],
  "require": {
    "purple-dbu/vcloud-sdk-helpers": "1.1.3"
  }

Usage

For full usage instructions, please read the API Documentation.

Right Helper

The Right Helper gives you the ability to manipulate user rights with ease. It helps you determining the current logged user rights.

Determine whether the current user is administrator of his organization, or not

$service = \VMware_VCloud_SDK_Service::getService();
$service->login(...);

\VCloud\Helpers\Right::create($service)->isCurrentUserOrganizationAdmin();

// => true|false depending on currently logged user rights

Query Helper

The Query Helper gives you the ability to manipulate the vCloud SDK Query Service with ease. It provides abstraction for pagination.

Get all results for query 'adminVApp'

$service = \VMware_VCloud_SDK_Service::getService();
$service->login(...);

\VCloud\Helpers\Query::create($service)->queryRecords(\VMware_VCloud_SDK_Query_Types::ADMIN_VAPP);

// => array(
//        \VMware_VCloud_API_QueryResultAdminVAppRecordType,
//        ...
//    )

Get the query result for 'adminVApp' with id 'c47ddf20-05de-44f5-b79e-c463992ffd3f'

$service = \VMware_VCloud_SDK_Service::getService();
$service->login(...);

\VCloud\Helpers\Query::create($service)->queryRecord(
    \VMware_VCloud_SDK_Query_Types::ADMIN_VAPP,
    'id==c47ddf20-05de-44f5-b79e-c463992ffd3f'
);

// => \VMware_VCloud_API_QueryResultAdminVAppRecordType
// OR null if no vApp exist with such id

Exception Helper

The Exception Helper gives you the ability to manipulate vCloud SDK exceptions (VMware_VCloud_SDK_Exception) with ease. It allows extracting the error codes and messages from the original exception message, with is just raw XML of the form:

<Error
    xmlns="http://www.vmware.com/vcloud/v1.5"
    message="xs:string"
    majorErrorCode="xs:int"
    minorErrorCode="xs:string"
    vendorSpecificErrorCode="xs:string"
    stackTrace="xs:string"
/>

Get the error message

...
catch(\VMware_VCloud_SDK_Exception $e) {
    \VCloud\Helpers\Exception::create($e)->getMessage($e);

    // => (string) The message contained in the error XML
}

Get the error code

...
catch(\VMware_VCloud_SDK_Exception $e) {
    \VCloud\Helpers\Exception::create($e)->getMajorErrorCode($e);

    // => (int) The major error code contained in the error XML
}

Metadata helper

The Metadata Helper gives you the ability to manipulate metadata on vCloud objects with ease. It helps finding objects with a particular metadata (to either one particular value, or any value).

Get all vApp Template with a given metadata set (any value)

$service = \VMware_VCloud_SDK_Service::getService();
$service->login(...);

\VCloud\Helpers\Metadata::create($service)->getObjects(
    \VMware_VCloud_SDK_Query_Types::ADMIN_VAPP_TEMPLATE,
    'myMetadata'
);

// => array(
//        \VMware_VCloud_SDK_VAppTemplate,
//        ...
//    )
// The result array contains all the vApp Templates that hold a metadata named
// "myMetadata"

Get the first vApp Template with a given metadata set to a particular value

$service = \VMware_VCloud_SDK_Service::getService();
$service->login(...);

\VCloud\Helpers\Metadata::create($service)->getObject(
    \VMware_VCloud_SDK_Query_Types::ADMIN_VAPP_TEMPLATE,
    'someId',
    '23d6deb1-1778-4325-8289-2f150d122675'
);

// => \VMware_VCloud_SDK_VAppTemplate
// 
// The result vApp Template is the first vApp Template that holds a metadata
// named "someId" with the value "23d6deb1-1778-4325-8289-2f150d122675"

Licensing

This project is released under MIT License license. If this license does not fit your requirement for whatever reason, but you would be interested in using the work (as defined below) under another license, please contact Purple DBU at dbu.purple@gmail.com.

Contributing

Contributions (issues ♥, pull requests ♥♥♥) are more than welcome! Feel free to clone, fork, modify, extend, etc, as long as you respect the license terms.

Requirements

You need to have the following software installed:

git
make
curl
php >= 5.3.2

You need to have a working vCloud Director installation.

Getting started

To start contributing, the best is to follow these steps:

Create a GitHub account
Create your own fork of this project
Clone it to your machine: git clone https://github.com/<you>/vcloud-sdk-php-helpers.git
Go to the project's root directory: cd vcloud-sdk-php-helpers
Create the file tests/config.php: cp tests/config.php.dist tests/config.php
Edit tests/config.php and set values according to your vCloud Director configuration
Install dependencies: make dependencies
Run tests: make test

Common tasks

Update dependencies: make dependencies
Clean dependencies: make clean
Check code quality: make lint
Run integration tests: make integration
Generate stubs for unit tests: make stubs
Run unit tests: make test
Generate API documentation: make doc
Publish API documentation: make publish

Versioning

Using Semver as a base for versioning, this project also follow additional guidelines for version numbering. each version is in the format x.y.z where:

Each modification of x introduces backward compatibility breaks
Each modification of y introduces a new feature
Modifications of y are simply corrections of existing patches

purple-dbu / vcloud-sdk-helpers

Maintainers

Details