[Summary view] [Print] [Text view]

   1  <?php
   2  /**
   3   * Zend Framework
   4   *
   5   * LICENSE
   6   *
   7   * This source file is subject to the new BSD license that is bundled
   8   * with this package in the file LICENSE.txt.
   9   * It is also available through the world-wide-web at this URL:
  10   * http://framework.zend.com/license/new-bsd
  11   * If you did not receive a copy of the license and are unable to
  12   * obtain it through the world-wide-web, please send an email
  13   * to [email protected] so we can send you a copy immediately.
  14   *
  15   * @category   Zend
  16   * @package    Zend_Service_Amazon
  17   * @subpackage Ec2
  18   * @copyright  Copyright (c) 2005-2010 Zend Technologies USA Inc. (http://www.zend.com)
  19   * @license    http://framework.zend.com/license/new-bsd     New BSD License
  20   * @version    $Id$
  21   */
  22  
  23  /**
  24   * @see Zend_Service_Amazon_Ec2_Abstract
  25   */
  26  require_once 'Zend/Service/Amazon/Ec2/Abstract.php';
  27  
  28  /**
  29   * An Amazon EC2 interface to register, describe and deregister Amamzon Machine Instances (AMI)
  30   *
  31   * @category   Zend
  32   * @package    Zend_Service_Amazon
  33   * @subpackage Ec2
  34   * @copyright  Copyright (c) 2005-2010 Zend Technologies USA Inc. (http://www.zend.com)
  35   * @license    http://framework.zend.com/license/new-bsd     New BSD License
  36   */
  37  class Zend_Service_Amazon_Ec2_Image extends Zend_Service_Amazon_Ec2_Abstract
  38  {
  39      /**
  40       * Registers an AMI with Amazon EC2. Images must be registered before
  41       * they can be launched.
  42       *
  43       * Each AMI is associated with an unique ID which is provided by the Amazon
  44       * EC2 service through the RegisterImage operation. During registration, Amazon
  45       * EC2 retrieves the specified image manifest from Amazon S3 and verifies that
  46       * the image is owned by the user registering the image.
  47       *
  48       * The image manifest is retrieved once and stored within the Amazon EC2.
  49       * Any modifications to an image in Amazon S3 invalidates this registration.
  50       * If you make changes to an image, deregister the previous image and register
  51       * the new image. For more information, see DeregisterImage.
  52       *
  53       * @param string $imageLocation         Full path to your AMI manifest in Amazon S3 storage.
  54       * @return string                       The ami fro the newly registred image;
  55       */
  56      public function register($imageLocation)
  57      {
  58          $params                 = array();
  59          $params['Action']       = 'RegisterImage';
  60          $params['ImageLocation']= $imageLocation;
  61  
  62          $response = $this->sendRequest($params);
  63          $xpath = $response->getXPath();
  64  
  65          $amiId = $xpath->evaluate('string(//ec2:imageId/text())');
  66  
  67          return $amiId;
  68      }
  69  
  70      /**
  71       * Returns information about AMIs, AKIs, and ARIs available to the user.
  72       * Information returned includes image type, product codes, architecture,
  73       * and kernel and RAM disk IDs. Images available to the user include public
  74       * images available for any user to launch, private images owned by the user
  75       * making the request, and private images owned by other users for which the
  76       * user has explicit launch permissions.
  77       *
  78       * Launch permissions fall into three categories:
  79       *      public: The owner of the AMI granted launch permissions for the AMI
  80       *              to the all group. All users have launch permissions for these AMIs.
  81       *      explicit: The owner of the AMI granted launch permissions to a specific user.
  82       *      implicit: A user has implicit launch permissions for all AMIs he or she owns.
  83       *
  84       * The list of AMIs returned can be modified by specifying AMI IDs, AMI owners,
  85       * or users with launch permissions. If no options are specified, Amazon EC2 returns
  86       * all AMIs for which the user has launch permissions.
  87       *
  88       * If you specify one or more AMI IDs, only AMIs that have the specified IDs are returned.
  89       * If you specify an invalid AMI ID, a fault is returned. If you specify an AMI ID for which
  90       * you do not have access, it will not be included in the returned results.
  91       *
  92       * If you specify one or more AMI owners, only AMIs from the specified owners and for
  93       * which you have access are returned. The results can include the account IDs of the
  94       * specified owners, amazon for AMIs owned by Amazon or self for AMIs that you own.
  95       *
  96       * If you specify a list of executable users, only users that have launch permissions
  97       * for the AMIs are returned. You can specify account IDs (if you own the AMI(s)), self
  98       * for AMIs for which you own or have explicit permissions, or all for public AMIs.
  99       *
 100       * @param string|array $imageId             A list of image descriptions
 101       * @param string|array $owner               Owners of AMIs to describe.
 102       * @param string|array $executableBy        AMIs for which specified users have access.
 103       * @return array
 104       */
 105      public function describe($imageId = null, $owner = null, $executableBy = null)
 106      {
 107          $params = array();
 108          $params['Action'] = 'DescribeImages';
 109  
 110          if(is_array($imageId) && !empty($imageId)) {
 111              foreach($imageId as $k=>$name) {
 112                  $params['ImageId.' . ($k+1)] = $name;
 113              }
 114          } elseif($imageId) {
 115              $params['ImageId.1'] = $imageId;
 116          }
 117  
 118          if(is_array($owner) && !empty($owner)) {
 119              foreach($owner as $k=>$name) {
 120                  $params['Owner.' . ($k+1)] = $name;
 121              }
 122          } elseif($owner) {
 123              $params['Owner.1'] = $owner;
 124          }
 125  
 126          if(is_array($executableBy) && !empty($executableBy)) {
 127              foreach($executableBy as $k=>$name) {
 128                  $params['ExecutableBy.' . ($k+1)] = $name;
 129              }
 130          } elseif($executableBy) {
 131              $params['ExecutableBy.1'] = $executableBy;
 132          }
 133  
 134          $response = $this->sendRequest($params);
 135  
 136          $xpath  = $response->getXPath();
 137          $nodes = $xpath->query('//ec2:imagesSet/ec2:item');
 138  
 139          $return = array();
 140          foreach ($nodes as $node) {
 141              $item = array();
 142  
 143              $item['imageId']        = $xpath->evaluate('string(ec2:imageId/text())', $node);
 144              $item['imageLocation']  = $xpath->evaluate('string(ec2:imageLocation/text())', $node);
 145              $item['imageState']     = $xpath->evaluate('string(ec2:imageState/text())', $node);
 146              $item['imageOwnerId']   = $xpath->evaluate('string(ec2:imageOwnerId/text())', $node);
 147              $item['isPublic']       = $xpath->evaluate('string(ec2:isPublic/text())', $node);
 148              $item['architecture']   = $xpath->evaluate('string(ec2:architecture/text())', $node);
 149              $item['imageType']      = $xpath->evaluate('string(ec2:imageType/text())', $node);
 150              $item['kernelId']       = $xpath->evaluate('string(ec2:kernelId/text())', $node);
 151              $item['ramdiskId']      = $xpath->evaluate('string(ec2:ramdiskId/text())', $node);
 152              $item['platform']       = $xpath->evaluate('string(ec2:platform/text())', $node);
 153  
 154              $return[] = $item;
 155              unset($item, $node);
 156          }
 157  
 158          return $return;
 159      }
 160  
 161      /**
 162       * Deregisters an AMI. Once deregistered, instances of the AMI can no longer be launched.
 163       *
 164       * @param string $imageId                   Unique ID of a machine image, returned by a call
 165       *                                          to RegisterImage or DescribeImages.
 166       * @return boolean
 167       */
 168      public function deregister($imageId)
 169      {
 170          $params                 = array();
 171          $params['Action']       = 'DeregisterImage';
 172          $params['ImageId']      = $imageId;
 173  
 174          $response = $this->sendRequest($params);
 175          $xpath = $response->getXPath();
 176  
 177          $return = $xpath->evaluate('string(//ec2:return/text())');
 178  
 179          return ($return === "true");
 180      }
 181  
 182      /**
 183       * Modifies an attribute of an AMI.
 184       *
 185       * Valid Attributes:
 186       *       launchPermission:  Controls who has permission to launch the AMI. Launch permissions
 187       *                          can be granted to specific users by adding userIds.
 188       *                          To make the AMI public, add the all group.
 189       *       productCodes:      Associates a product code with AMIs. This allows developers to
 190       *                          charge users for using AMIs. The user must be signed up for the
 191       *                          product before they can launch the AMI. This is a write once attribute;
 192       *                          after it is set, it cannot be changed or removed.
 193       *
 194       * @param string $imageId                   AMI ID to modify.
 195       * @param string $attribute                 Specifies the attribute to modify. See the preceding
 196       *                                          attributes table for supported attributes.
 197       * @param string $operationType             Specifies the operation to perform on the attribute.
 198       *                                          See the preceding attributes table for supported operations for attributes.
 199       *                                          Valid Values: add | remove
 200       *                                          Required for launchPermssion Attribute
 201       *
 202       * @param string|array $userId              User IDs to add to or remove from the launchPermission attribute.
 203       *                                          Required for launchPermssion Attribute
 204       * @param string|array $userGroup           User groups to add to or remove from the launchPermission attribute.
 205       *                                          Currently, the all group is available, which will make it a public AMI.
 206       *                                          Required for launchPermssion Attribute
 207       * @param string $productCode               Attaches a product code to the AMI. Currently only one product code
 208       *                                          can be associated with an AMI. Once set, the product code cannot be changed or reset.
 209       *                                          Required for productCodes Attribute
 210       * @return boolean
 211       */
 212      public function modifyAttribute($imageId, $attribute, $operationType = 'add', $userId = null, $userGroup = null, $productCode = null)
 213      {
 214          $params = array();
 215          $params['Action'] = 'ModifyImageAttribute';
 216          $parmas['ImageId'] = $imageId;
 217          $params['Attribute'] = $attribute;
 218  
 219          switch($attribute) {
 220              case 'launchPermission':
 221                  // break left out
 222              case 'launchpermission':
 223                  $params['Attribute'] = 'launchPermission';
 224                  $params['OperationType'] = $operationType;
 225  
 226                  if(is_array($userId) && !empty($userId)) {
 227                      foreach($userId as $k=>$name) {
 228                          $params['UserId.' . ($k+1)] = $name;
 229                      }
 230                  } elseif($userId) {
 231                      $params['UserId.1'] = $userId;
 232                  }
 233  
 234                  if(is_array($userGroup) && !empty($userGroup)) {
 235                      foreach($userGroup as $k=>$name) {
 236                          $params['UserGroup.' . ($k+1)] = $name;
 237                      }
 238                  } elseif($userGroup) {
 239                      $params['UserGroup.1'] = $userGroup;
 240                  }
 241  
 242                  break;
 243              case 'productCodes':
 244                  // break left out
 245              case 'productcodes':
 246                  $params['Attribute'] = 'productCodes';
 247                  $params['ProductCode.1'] = $productCode;
 248                  break;
 249              default:
 250                  require_once 'Zend/Service/Amazon/Ec2/Exception.php';
 251                  throw new Zend_Service_Amazon_Ec2_Exception('Invalid Attribute Passed In.  Valid Image Attributes are launchPermission and productCode.');
 252                  break;
 253          }
 254  
 255          $response = $this->sendRequest($params);
 256          $xpath = $response->getXPath();
 257  
 258          $return = $xpath->evaluate('string(//ec2:return/text())');
 259  
 260          return ($return === "true");
 261      }
 262  
 263      /**
 264       * Returns information about an attribute of an AMI. Only one attribute can be specified per call.
 265       *
 266       * @param string $imageId                   ID of the AMI for which an attribute will be described.
 267       * @param string $attribute                 Specifies the attribute to describe.  Valid Attributes are
 268       *                                          launchPermission, productCodes
 269       */
 270      public function describeAttribute($imageId, $attribute)
 271      {
 272          $params = array();
 273          $params['Action'] = 'DescribeImageAttribute';
 274          $params['ImageId'] = $imageId;
 275          $params['Attribute'] = $attribute;
 276  
 277          $response = $this->sendRequest($params);
 278          $xpath = $response->getXPath();
 279  
 280          $return = array();
 281          $return['imageId'] = $xpath->evaluate('string(//ec2:imageId/text())');
 282  
 283          // check for launchPermission
 284          if($attribute == 'launchPermission') {
 285              $lPnodes = $xpath->query('//ec2:launchPermission/ec2:item');
 286  
 287              if($lPnodes->length > 0) {
 288                  $return['launchPermission'] = array();
 289                  foreach($lPnodes as $node) {
 290                      $return['launchPermission'][] = $xpath->evaluate('string(ec2:userId/text())', $node);
 291                  }
 292              }
 293          }
 294  
 295          // check for product codes
 296          if($attribute == 'productCodes') {
 297              $pCnodes = $xpath->query('//ec2:productCodes/ec2:item');
 298              if($pCnodes->length > 0) {
 299                  $return['productCodes'] = array();
 300                  foreach($pCnodes as $node) {
 301                      $return['productCodes'][] = $xpath->evaluate('string(ec2:productCode/text())', $node);
 302                  }
 303              }
 304          }
 305  
 306          return $return;
 307  
 308      }
 309  
 310      /**
 311       * Resets an attribute of an AMI to its default value.  The productCodes attribute cannot be reset
 312       *
 313       * @param string $imageId                   ID of the AMI for which an attribute will be reset.
 314       * @param String $attribute                 Specifies the attribute to reset. Currently, only launchPermission is supported.
 315       *                                          In the case of launchPermission, all public and explicit launch permissions for
 316       *                                          the AMI are revoked.
 317       * @return boolean
 318       */
 319      public function resetAttribute($imageId, $attribute)
 320      {
 321          $params = array();
 322          $params['Action'] = 'ResetImageAttribute';
 323          $params['ImageId'] = $imageId;
 324          $params['Attribute'] = $attribute;
 325  
 326          $response = $this->sendRequest($params);
 327          $xpath = $response->getXPath();
 328  
 329          $return = $xpath->evaluate('string(//ec2:return/text())');
 330  
 331          return ($return === "true");
 332      }
 333  }