README

CloudStack API v4.8+的PHP客户端库 (参考)

此项目最初是从以下项目分叉的

此项目将这两个工具合并为一个项目。代码生成不再通过抓取HTML文档来完成。我们现在使用CloudStack API提供的listApis调用来生成库。

生成的代码已标记为phpdoc。

安装

只需从发布页面下载最新的php-cloudstack-generator.phar并将其放在您希望的位置。phar的位置将主要取决于您的实现。

代码生成

1. 定义配置文件

请参阅files/config_prototype.yml以获取示例配置文件

2. 生成客户端

php-cloudstack-generator cs-gen:generate-client --config="your_config_file.yml" --env="environment in config you wish to generate from"

此生成器的输出具有以下基本结构

# as Composer package
/ - {configured output root}
  | - src/
    | - CloudStackRequest/
      | - # Every API will have a corresponding CloudStack**Request class present in here.  If you have Swagger documentation, add this directory to your project's scan path
    | - CloudStackResponse/
      | - # Every API will have a corresponding CloudStack**Response class present in here.  If you have Swagger documentation, add this directory to your project's scan path
    | - CloudStackClient.php                # This is the actual client
    | - CloudStackConfiguration.php   # This is the configuration object that must be provided when constructing a client
    | - CloudStackGenerationMeta.php        # This file contains metadata about the most recent generation, including date, api source, and environment configuration (sans api keys and secrets)
    | - # several exception and helper classes that you will rarely directly construct
  | - composer.json
  | - LICENSE
  
  
# as raw code
/ - {configured output root}
  | - CloudStackRequest/
    | - # Every API will have a corresponding CloudStack**Request class present in here.  If you have Swagger documentation, add this directory to your project's scan path
  | - CloudStackResponse/
    | - # Every API will have a corresponding CloudStack**Response class present in here.  If you have Swagger documentation, add this directory to your project's scan path
  | - CloudStackClient.php                # This is the actual client
  | - CloudStackConfiguration.php   # This is the configuration object that must be provided when constructing a client
  | - CloudStackGenerationMeta.php        # This file contains metadata about the most recent generation, including date, api source, and environment configuration (sans api keys and secrets)
  | - # several exception and helper classes that you will rarely directly construct

3. 包含在项目中

如何包含生成的代码取决于您如何生成代码，是作为Composer库还是作为独立的类。

如果您已将客户端生成为一个已推送到Composer可以访问的某处的Composer包，则只需将其添加到项目的composer.json文件中

如果您仅生成了代码，建议您将代码放在包含项目的include或autoload路径中。

PHP库使用

初始化

    $configuration = new CloudStackConfiguration([
        'api_key'      => '',               // YOUR_API_KEY (required)
        'secret_key'   => '',               // YOUR_SECRET_KEY (required)
        'host'         => 'localhost',      // Your CloudStack host (required)
        'scheme'       => 'http',           // http or https (defaults to http)
        'port'         => 8080,             // api port (defaults to 8080)
        'api_path'     => 'client/api',     // admin api path (defaults to 'client/api')
        'console_path' => 'client/console', // console api path (defaults to 'client/console')
        'http_client'  => null,             // GuzzleHttp\ClientInterface compatible client
    ]);
    
    $client = new CloudStackClient($config);

列表

    $vms = $client->listVirtualMachines();
    foreach ($vms as $vm) {
        printf("%s : %s %s", $vm->id, $vm->name, $vm->state);
    }

异步任务

    $job = $client->deployVirtualMachine(1, 259, 1);
    printf("VM being deployed. Job id = %s", $job->jobid);

    print "All jobs";

    foreach ($client->listAsyncJobs() as $job) {
        printf("%s : %s, status = %s", $job->jobid, $job->cmd, $job->jobstatus);
    }

您还可以选择等待作业完成

    $result = $client->waitForAsync($job);

高级主题

API缓存

此库生成的代码能够利用实现Doctrine Cache 接口的任何缓存库。

任何/所有“读取”请求（get*、list*等）都可以缓存其响应。

工作流程如下所示

# The below is pseudo-code

// First, determine if this command is cacheable, caching has been configured, and we have a cache provider defined
$cacheable = $cacheableCommand && $cacheConfigured && $cacheProviderProvided;

// determine if above == true
if ($cacheable) {
    // build cache key for this specific request
    // Each key contains the following to prevent any collisions:
    //  1. CloudStack Host from client config
    //  2. API Key from client config
    //  3. API Secret from client config
    //  4. Name of command being executed (listTemplates, for example)
    //  5. The parameters specified for this request are serialized and appended in "{$k}{$v}" fashion
    // The above is prepended with your configure cache prefix after being run through sha1()
    $key = '{configured-prefix}-'.sha1("{cloudStackHost}{apiKey}{secretKey}{commandName}{requestParameterKVPairs}";
    
    // test to see if the key exists in the cache and can be fetched successfully
    if ($cacheProvider->contains($key) && ($fetched = $cacheProvider->fetch($key)) && (false !== $fetched)) {
        // if we got got a cache key, return the cached response
        return $fetched;
    }
}
    
// if we make it here, we're either dealing with a write request, a command for which caching has been disabled, 
// caching has not been configured at all, or a cached response was not found

// ... perform typical API request against cloudstack ...

// once again test cacheability
if ($cacheable) {
    // attempt to store cached response with configured TTL using $key generated above
}

// return response from CloudStack

响应对象重载

在代码生成过程中，可以指定一个自定义类，该类扩展了由本库生成的响应类。

例如，可以使用tags概念来存储与虚拟机、模板、iso、区域（以resourcedetails的形式）等各种实现相关的特定业务逻辑。每次需要引用这些值时，从标签数组中提取值可能相当繁琐，因此我们利用类重载的一种方式是定义自己的ListVirtualMachinesResponse类，其中包含一些辅助方法来解析和从tags数组中提取特定的标签。

唯一真正的要求是重载类必须保留与它重载的类相同的__construct参数。当然，它必须可以被您的应用程序加载。

生成器不会对提供的重载列表进行任何类型的验证！如果您指定了一个不存在的类，那么该查询将不会工作。

myena/cloudstack-client-generator

维护者

详细信息