Overview

Namespaces

  • None
  • OpenCloud
    • Autoscale
      • Resource
    • CloudMonitoring
      • Exception
      • Resource
    • Common
      • Exceptions
      • Log
      • Request
        • Response
    • Compute
    • Database
    • DNS
    • LoadBalancer
      • Resources
    • ObjectStore
      • Resource
    • Orchestration
    • Volume
  • PHP

Classes

  • OpenStack
  • Rackspace

Functions

  • __raxsdk_timezone_set
  • define_gettext
  • noslash
  • setDebug
  • Overview
  • Namespace
  • Class
  • Tree
  • Download

Class OpenStack

The OpenStack class represents a relationship (or "connection") between a user and a service.

This is the primary entry point into an OpenStack system, and the only one where the developer is required to know and provide the endpoint URL (in all other cases, the endpoint is derived from the Service Catalog provided by the authentication system).

Since various providers have different mechanisms for authentication, users will often use a subclass of OpenStack. For example, the Rackspace class is provided for users of Rackspace's cloud services, and other cloud providers are welcome to add their own subclasses as well.

General usage example:

$username = 'My Username';
$secret = 'My Secret';
$connection = new OpenCloud\OpenStack($username, $secret);
// having established the connection, we can set some defaults
// this sets the default name and region of the Compute service
$connection->SetDefaults('Compute', 'cloudServersOpenStack', 'ORD');
// access a Compute service
$chicago = $connection->Compute();
// if we want to access a different service, we can:
$dallas = $connection->Compute('cloudServersOpenStack', 'DFW');
OpenCloud\Common\Base
Extended by OpenCloud\OpenStack

Direct known subclasses

OpenCloud\Rackspace
Namespace: OpenCloud
Located at OpenCloud/OpenStack.php
Methods summary
public
# __construct( string $url, array $secret, array $options = array() )

Creates a new OpenStack object

Creates a new OpenStack object

The OpenStack object needs two bits of information: the URL to authenticate against, and a "secret", which is an associative array of name/value pairs. Usually, the secret will be a username and a password, but other values may be required by different authentication systems. For example, OpenStack Keystone requires a username and password, but Rackspace uses a username, tenant ID, and API key. (See OpenCloud\Rackspace for that.)

Parameters

$url
string
$url - the authentication endpoint URL
$secret
array
$secret - an associative array of auth information: * username * password
$options
array
$options - CURL options to pass to the HttpRequest object
public OpenCloud\OpenStack
# setUserAgent( string $useragent )

Set user agent.

Set user agent.

Parameters

$useragent
string
$useragent

Returns

OpenCloud\OpenStack
public OpenCloud\OpenStack
# appendUserAgent( string $useragent )

Allows the user to append a user agent string

Allows the user to append a user agent string

Programs that are using these bindings are encouraged to add their user agent to the one supplied by this SDK. This will permit cloud providers to track users so that they can provide better service.

Parameters

$useragent
string
$agent an arbitrary user-agent string; e.g. "My Cloud App"

Returns

OpenCloud\OpenStack
public string
# getUserAgent( )

Get user agent.

Get user agent.

Returns

string
public OpenCloud\OpenStack
# setUrl( string $url )

Sets the URL which the client will access.

Sets the URL which the client will access.

Parameters

$url
string
$url

Returns

OpenCloud\OpenStack
public string
# getUrl( )

Get the URL.

Get the URL.

Returns

string
public OpenCloud\OpenStack
# setSecret( array $secret = array() )

Set the secret for the client.

Set the secret for the client.

Parameters

$secret
array
$secret

Returns

OpenCloud\OpenStack
public array
# getSecret( )

Get the secret.

Get the secret.

Returns

array
public OpenCloud\OpenStack
# setToken( string $token )

Set the token for this client.

Set the token for this client.

Parameters

$token
string
$token

Returns

OpenCloud\OpenStack
public string
# getToken( )

Get the token for this client.

Get the token for this client.

Returns

string
public OpenCloud\OpenStack
# setExpiration( integer $expiration )

Set the expiration for this token.

Set the expiration for this token.

Parameters

$expiration
integer
$expiration

Returns

OpenCloud\OpenStack
public integer
# getExpiration( )

Get the expiration time.

Get the expiration time.

Returns

integer
public OpenCloud\OpenStack
# setTenant( string $tenant )

Set the tenant for this client.

Set the tenant for this client.

Parameters

$tenant
string
$tenant

Returns

OpenCloud\OpenStack
public string
# getTenant( )

Get the tenant for this client.

Get the tenant for this client.

Returns

string
public OpenCloud\OpenStack
# setCatalog( mixed $catalog )

Set the service catalog.

Set the service catalog.

Parameters

$catalog
mixed
$catalog

Returns

OpenCloud\OpenStack
public array
# getCatalog( )

Get the service catalog.

Get the service catalog.

Returns

array
public OpenCloud\OpenStack
# setCurlOptions( array $options )

Set (all) the cURL options.

Set (all) the cURL options.

Parameters

$options
array
$options

Returns

OpenCloud\OpenStack
public array
# getCurlOptions( )

Get the cURL options.

Get the cURL options.

Returns

array
public OpenCloud\OpenStack
# setFileDescriptor( string $key, resource $value )

Set a specific file descriptor (associated with a URL)

Set a specific file descriptor (associated with a URL)

Parameters

$key
string
$key
$value
resource
$value

Returns

OpenCloud\OpenStack
public resource|false
# getFileDescriptor( string $key )

Get a specific file descriptor (associated with a URL)

Get a specific file descriptor (associated with a URL)

Parameters

$key
string
$key

Returns

resource|false
public array
# getExportItems( )

Get the items to be exported.

Get the items to be exported.

Returns

array
public OpenCloud\OpenStack
# setConnectTimeout( integer $timeout )

Sets the connect timeout.

Sets the connect timeout.

Parameters

$timeout
integer
$timeout

Returns

OpenCloud\OpenStack
public integer
# getConnectTimeout( )

Get the connect timeout.

Get the connect timeout.

Returns

integer
public OpenCloud\OpenStack
# setHttpTimeout( integer $timeout )

Set the HTTP timeout.

Set the HTTP timeout.

Parameters

$timeout
integer
$timeout

Returns

OpenCloud\OpenStack
public integer
# getHttpTimeout( )

Get the HTTP timeout.

Get the HTTP timeout.

Returns

integer
public OpenCloud\OpenStack
# setOverlimitTimeout( integer $timeout )

Set the overlimit timeout.

Set the overlimit timeout.

Parameters

$timeout
integer
$timeout

Returns

OpenCloud\OpenStack
public integer
# getOverlimitTimeout( )

Get the overlimit timeout.

Get the overlimit timeout.

Returns

integer
public OpenCloud\OpenStack
# setDefault( string $service, array $value = array() )

Sets default values (an array) for a service. Each array must contain a "name", "region" and "urltype" key.

Sets default values (an array) for a service. Each array must contain a "name", "region" and "urltype" key.

Parameters

$service
string
$service
$value
array
$value

Returns

OpenCloud\OpenStack
public array|false
# getDefault( string $service )

Get a specific default value for a service. If none exist, return FALSE.

Get a specific default value for a service. If none exist, return FALSE.

Parameters

$service
string
$service

Returns

array|false
public
# setTimeouts( integer $httpTimeout, integer $connectTimeout = null, integer $overlimitTimeout = null )

Sets the timeouts for the current connection

Sets the timeouts for the current connection

Parameters

$httpTimeout
integer
$t_http the HTTP timeout value (the max period that the OpenStack object will wait for any HTTP request to complete). Value is in seconds.
$connectTimeout
integer
$t_conn the Connect timeout value (the max period that the OpenStack object will wait to establish an HTTP connection). Value is in seconds.
$overlimitTimeout
integer
$t_overlimit the overlimit timeout value (the max period that the OpenStack object will wait to retry on an overlimit condition). Value is in seconds.

Api

public string
# url( string $subresource = 'tokens' )

Returns the URL of this object

Returns the URL of this object

Parameters

$subresource
string
$subresource specified subresource

Returns

string

Throws

UrlError

Api

Overrides

OpenCloud\Common\Base::url()
public array
# secret( )

Returns the stored secret

Returns the stored secret

Returns

array
public
# checkExpiration( )

Re-authenticates session if expired.

Re-authenticates session if expired.

public boolean
# hasExpired( )

Checks whether token has expired.

Checks whether token has expired.

Returns

boolean
public string
# token( )

Returns the cached token; if it has expired, then it re-authenticates

Returns the cached token; if it has expired, then it re-authenticates

Returns

string

Api

public string
# expiration( )

Returns the cached expiration time; if it has expired, then it re-authenticates

Returns the cached expiration time; if it has expired, then it re-authenticates

Returns

string

Api

public string
# tenant( )

Returns the tenant ID, re-authenticating if necessary

Returns the tenant ID, re-authenticating if necessary

Returns

string

Api

public stdClass
# serviceCatalog( )

Returns the service catalog object from the auth service

Returns the service catalog object from the auth service

Returns

stdClass
public
# serviceList( )

Returns a Collection of objects with information on services

Returns a Collection of objects with information on services

Note that these are informational (read-only) and are not actually 'Service'-class objects.

public string
# credentials( )

Creates and returns the formatted credentials to POST to the auth service.

Creates and returns the formatted credentials to POST to the auth service.

Returns

string
public
# authenticate( )

Authenticates using the supplied credentials

Authenticates using the supplied credentials

Throws

AuthenticationError

Api

public HttpResponse
# request( string $url, string $method = 'GET', array $headers = array(), string $data = null )

Performs a single HTTP request

Performs a single HTTP request

The request() method is one of the most frequently-used in the entire library. It performs an HTTP request using the specified URL, method, and with the supplied headers and body. It handles error and exceptions for the request.

Parameters

$url
string
url - the URL of the request
$method
string
method - the HTTP method (defaults to GET)
$headers
array
headers - an associative array of headers
$data
string
data - either a string or a resource (file pointer) to use as the request body (for PUT or POST)

Returns

HttpResponse
object

Throws

HttpOverLimitError,
HttpUnauthorizedError, HttpForbiddenError

Api

public
# setDefaults( string $service, string $name = null, string $region = null, string $urltype = null )

Sets default values for name, region, URL type for a service

Sets default values for name, region, URL type for a service

Once these are set (and they can also be set by defining global constants), then you do not need to specify these values when creating new service objects.

Parameters

$service
string
$service the name of a supported service; e.g. 'Compute'
$name
string
$name the service name; e.g., 'cloudServersOpenStack'
$region
string
$region the region name; e.g., 'LON'
$urltype
string
$urltype the type of URL to use; e.g., 'internalURL'

Throws

UnrecognizedServiceError

Api

public
# setUploadProgressCallback( callable $callback )

Allows the user to define a function for tracking uploads

Allows the user to define a function for tracking uploads

This can be used to implement a progress bar or similar function. The callback function is called with a single parameter, the length of the data that is being uploaded on this call.

Parameters

$callback
callable
$callback the name of a global callback function, or an array($object, $functionname)
public
# setDownloadProgressCallback( callable $callback )

Allows the user to define a function for tracking downloads

Allows the user to define a function for tracking downloads

This can be used to implement a progress bar or similar function. The callback function is called with a single parameter, the length of the data that is being downloaded on this call.

Parameters

$callback
callable
$callback the name of a global callback function, or an array($object, $functionname)
public string
# _read_cb( resource $ch, resource $fd, integer $length )

Callback function to handle reads for file uploads

Callback function to handle reads for file uploads

Internal function for handling file uploads. Note that, although this function's visibility is public, this is only because it must be called from the HttpRequest interface. This should NOT be called by users directly.

Parameters

$ch
resource
$ch a CURL handle
$fd
resource
$fd a file descriptor
$length
integer
$length the amount of data to read

Returns

string
the data read

CodeCoverageIgnore

public integer
# _write_cb( resource $ch, string $data )

Callback function to handle writes for file downloads

Callback function to handle writes for file downloads

Internal function for handling file downloads. Note that, although this function's visibility is public, this is only because it must be called via the HttpRequest interface. This should NOT be called by users directly.

Parameters

$ch
resource
$ch a CURL handle
$data
string
$data the data to be written to a file

Returns

integer
the number of bytes written

CodeCoverageIgnore

public array
# exportCredentials( )

exports saved token, expiration, tenant, and service catalog as an array

exports saved token, expiration, tenant, and service catalog as an array

This could be stored in a cache (APC or disk file) and reloaded using ImportCredentials()

Returns

array
public
# importCredentials( array $values )

imports credentials from an array

imports credentials from an array

Takes the same values as ExportCredentials() and reuses them.

public ObjectStore
# objectStore( string $name = null, string $region = null, string $urltype = null )

Creates a new ObjectStore object (Swift/Cloud Files)

Creates a new ObjectStore object (Swift/Cloud Files)

Parameters

$name
string
$name the name of the Object Storage service to attach to
$region
string
$region the name of the region to use
$urltype
string
$urltype the URL type (normally "publicURL")

Returns

ObjectStore

Api

public Compute
# compute( string $name = null, string $region = null, string $urltype = null )

Creates a new Compute object (Nova/Cloud Servers)

Creates a new Compute object (Nova/Cloud Servers)

Parameters

$name
string
$name the name of the Compute service to attach to
$region
string
$region the name of the region to use
$urltype
string
$urltype the URL type (normally "publicURL")

Returns

Compute

Api

public OpenCloud\Orchestration\Service
# orchestration( string $name = null, string $region = null, string $urltype = null )

Creates a new Orchestration (heat) service object

Creates a new Orchestration (heat) service object

Parameters

$name
string
$name the name of the Compute service to attach to
$region
string
$region the name of the region to use
$urltype
string
$urltype the URL type (normally "publicURL")

Returns

OpenCloud\Orchestration\Service

Api

CodeCoverageIgnore

public
# volumeService( string $name = null, string $region = null, string $urltype = null )

Creates a new VolumeService (cinder) service object

Creates a new VolumeService (cinder) service object

This is a factory method that is Rackspace-only (NOT part of OpenStack).

Parameters

$name
string
$name the name of the service (e.g., 'cloudBlockStorage')
$region
string
$region the region (e.g., 'DFW')
$urltype
string
$urltype the type of URL (e.g., 'publicURL');
public Service
# service( string $class, string $name = null, string $region = null, string $urltype = null )

Generic Service factory method

Generic Service factory method

Contains code reused by the other service factory methods.

Parameters

$class
string
$class the name of the Service class to produce
$name
string
$name the name of the Compute service to attach to
$region
string
$region the name of the region to use
$urltype
string
$urltype the URL type (normally "publicURL")

Returns

Service
(or subclass such as Compute, ObjectStore)

Throws

ServiceValueError
public
# serviceCatalogItem( mixed $info = array() )

returns a service catalog item

returns a service catalog item

This is a helper function used to list service catalog items easily

Methods inherited from OpenCloud\Common\Base
__set(), checkJsonError(), getHttpRequestObject(), getLogger(), makeQueryString(), populate(), setLogger(), setProperty()
Properties summary
public string $useragent RAXSDK_USER_AGENT
#

This holds the HTTP User-Agent: used for all requests to the services. It is public so that, if necessary, it can be entirely overridden by the developer. However, it's strongly recomended that you use the appendUserAgent() method to APPEND your own User Agent identifier to the end of this string; the user agent information can be very valuable to service providers to track who is using their service.

This holds the HTTP User-Agent: used for all requests to the services. It is public so that, if necessary, it can be entirely overridden by the developer. However, it's strongly recomended that you use the appendUserAgent() method to APPEND your own User Agent identifier to the end of this string; the user agent information can be very valuable to service providers to track who is using their service.

protected mixed $url
#
protected array $secret array()
#
protected mixed $token
#
protected integer $expiration 0
#
protected mixed $tenant
#
protected mixed $catalog
#
protected mixed $connectTimeout RAXSDK_CONNECTTIMEOUT
#
protected mixed $httpTimeout RAXSDK_TIMEOUT
#
protected mixed $overlimitTimeout RAXSDK_OVERLIMIT_TIMEOUT
#
protected mixed $defaults array( 'Compute' => array( 'name' => RAXSDK_COMPUTE_NAME, 'region' => RAXSDK_COMPUTE_REGION, 'urltype' => RAXSDK_COMPUTE_URLTYPE ), 'ObjectStore' => array( 'name' => RAXSDK_OBJSTORE_NAME, 'region' => RAXSDK_OBJSTORE_REGION, 'urltype' => RAXSDK_OBJSTORE_URLTYPE ), 'Database' => array( 'name' => RAXSDK_DATABASE_NAME, 'region' => RAXSDK_DATABASE_REGION, 'urltype' => RAXSDK_DATABASE_URLTYPE ), 'Volume' => array( 'name' => RAXSDK_VOLUME_NAME, 'region' => RAXSDK_VOLUME_REGION, 'urltype' => RAXSDK_VOLUME_URLTYPE ), 'LoadBalancer' => array( 'name' => RAXSDK_LBSERVICE_NAME, 'region' => RAXSDK_LBSERVICE_REGION, 'urltype' => RAXSDK_LBSERVICE_URLTYPE ), 'DNS' => array( 'name' => RAXSDK_DNS_NAME, 'region' => RAXSDK_DNS_REGION, 'urltype' => RAXSDK_DNS_URLTYPE ), 'Orchestration' => array( 'name' => RAXSDK_ORCHESTRATION_NAME, 'region' => RAXSDK_ORCHESTRATION_REGION, 'urltype' => RAXSDK_ORCHESTRATION_URLTYPE ), 'CloudMonitoring' => array( 'name' => RAXSDK_MONITORING_NAME, 'region' => RAXSDK_MONITORING_REGION, 'urltype' => RAXSDK_MONITORING_URLTYPE ), 'Autoscale' => array( 'name' => RAXSDK_AUTOSCALE_NAME, 'region' => RAXSDK_AUTOSCALE_REGION, 'urltype' => RAXSDK_AUTOSCALE_URLTYPE ) )
#

This associative array holds default values used to identify each service (and to select it from the Service Catalog). Use the Compute::SetDefaults() method to change the default values, or define the global constants (for example, RAXSDK_COMPUTE_NAME) BEFORE loading the OpenCloud library:

This associative array holds default values used to identify each service (and to select it from the Service Catalog). Use the Compute::SetDefaults() method to change the default values, or define the global constants (for example, RAXSDK_COMPUTE_NAME) BEFORE loading the OpenCloud library:

define('RAXSDK_COMPUTE_NAME', 'cloudServersOpenStack');
include('openstack.php');
PHP OpenCloud API API documentation generated by ApiGen 2.8.0