/** * The constructor for the Services_AMEE_DataItem class. * * @param <string> $sPath The path of the AMEE API Data Item. * @param <array> $aOptions An optional array of AMEE API Data Item * name/value pairs that define the AMEE API Data Item's Drill Down * UID, in those cases where the path does not define the UID. * @return <object> The created Services_AMEE_DataItem object; an Exception * object otherwise. */ function __construct($sPath, $aOptions = array()) { try { parent::__construct(); // Helpfully re-format the path, if required if (!preg_match('#^/#', $sPath)) { $sPath = '/' . $sPath; } if (preg_match('#(.*)/$#', $sPath, $aMatches)) { $sPath = $aMatches[1]; } // Store the path and array $this->sPath = $sPath; $this->aOptions = $aOptions; // Prepare the AMEE REST API path $sPath = '/data' . $this->sPath . '/drill'; // Call the AMEE REST API $this->sLastJSON = $this->oAPI->get($sPath, $this->aOptions); // Process the result data $this->aLastJSON = json_decode($this->sLastJSON, true); // Test that a valid Data Item UID has been located if (isset($this->aLastJSON['choices']) && isset($this->aLastJSON['choices']['name']) && $this->aLastJSON['choices']['name'] == 'uid' && isset($this->aLastJSON['choices']['choices']) && count($this->aLastJSON['choices']['choices']) == 1 && isset($this->aLastJSON['choices']['choices'][0]) && isset($this->aLastJSON['choices']['choices'][0]['value'])) { // Set this object's UID $this->sUID = $this->aLastJSON['choices']['choices'][0]['value']; } else { throw new Services_AMEE_Exception('AMEE API Data Item Drill Down for path \'' . $sPath . '\' with the specified options did not return a Data ' . 'Item UID - check that the specified options fully ' . 'define a complete Drill Down to a single Data Item'); } } catch (Exception $oException) { throw $oException; } }
/** * The constructor for the Services_AMEE_ProfileItem class. * * There are three different ways to create a new Services_AMEE_ProfileItem * object. * *************************************************************************** * * 1. Create an object for a new AMEE API Profile Item * * @param <array> $aParams An array of parameters, being: * * $aParams[0] => <Services_AMEE_Profile> The instance of the * Services_AMEE_Profile class representing the AMEE API Profile in * which the new AMEE API Profile Item should be created. * * $aParams[1] => <Services_AMEE_DataItem> The instance of the * Services_AMEE_DataItem class representing the AMEE API Data Item * on which the AMEE API Profile Item should be based. * * $aParams[2] => <array> An array of name/value pairs that represent * the input data for one or more AMEE API Profile Item Values. * * For example, assuming that the AMEE API Data Item that the AMEE * API Profile Item is to be based on is * http://explorer.amee.com/categories/Car_Defra_By_Size, then the * array *must* contain the "distance" key (because this is defined * as a required parameter in the AMEE API Data Item above), with * value specifying the km/year travelled. That is, the absolute * minimum array that this parameter could be for this AMEE API * Data Item would be, for example: * * array( * 'distance' => 100 * ); * * representing that the car usage is/was 100 km/year. * * Optionally, the array in this example could additionally contain * the keys "occupants", "ownFuelConsumption", "totalFuelConsumed" * and "numberOfJourneys", to specify additional information about * the car use, as described on the AMEE API Data Item page above. * * Optionally, the array in this example could addtionally contain * keys specifying "unit" and "perUnit" options for the name/value * pairs. That is, on the * http://explorer.amee.com/categories/Car_Defra_By_Size page, the * required parameter "distance" is, by default, specified in * km/year. However, if you wanted to specify this in another * format, such as miles/week, then you could do so, by setting * the array to be, for example: * * array( * 'distance' => '5' * 'distanceUnit' => 'mi' * 'distancePerUnit' => 'week' * ); * * representing that the car usage is/was 5 miles/week. * * Note that you can only specify "unit" and "perUnit" modifer * options for those name/value pairs that support it -- that is, * for example, it is not possible to specify different "unit" or * "perUnit" options for the "occupants" key in this case. * * You can find details of supported units at * http://my.amee.com/developers/wiki/Units * * $aParams[3] => <array> An optional array of name/value pairs that * represent AMEE API Profile Items options. Valid key values are * "name", "startDate", "endDate", and "duration" as defined at * http://my.amee.com/developers/wiki/ProfileItem#CreateanewProfileItem. * * Use null for this parameter if no AMEE API Profile Item options * need to be set, but you do want to set the fifth option array * below. * * $aParams[4] => <array> An optional array of name/value pairs that * represent the desired "unit" and "per unit" values that should * be used for the AMEE API Profile Item. Must be specified using * the key values "returnUnit" and "returnPerUnit" as defined at * http://my.amee.com/developers/wiki/ProfileCategory#GetCategory. * *************************************************************************** * * 2. Create an object for an existing AMEE API Profile Item by UID * * @param <array> $aParams An array of parameters, being: * * $aParams[0] => <Services_AMEE_Profile> The instance of the * Services_AMEE_Profile class representing the AMEE API Profile in * which the AMEE API Profile Item exists. * * $aParams[1] => <Services_AMEE_DataItem> The instance of the * Services_AMEE_DataItem class representing the AMEE API Data Item * on which the existing AMEE API Profile Item is based. * * $aParams[2] => <string> The AMEE API Profile Item UID for the * existing AMEE API Profile Item. * * $aParams[3] => <array> An optional array of name/value pairs that * represent the desired "unit" and "per unit" values that should * be used for the AMEE API Profile Item. Must be specified using * the key values "returnUnit" and "returnPerUnit" as defined at * http://my.amee.com/developers/wiki/ProfileCategory#GetCategory. * *************************************************************************** * * 3. Create an object for an existing AMEE API Profile Item by AMEE API * Data Item * * @param <array> $aParams An array of parameters, being: * * $aParams[0] => <Services_AMEE_Profile> The instance of the * Services_AMEE_Profile class representing the AMEE API Profile in * which the AMEE API Profile Item exists. * * $aParams[1] => <Services_AMEE_DataItem> The instance of the * Services_AMEE_DataItem class representing the AMEE API Data Item * on which the existing AMEE API Profile Item is based. * * $aParams[2] => <array> An optional array of name/value pairs that * represent the desired "unit" and "per unit" values that should * be used for the AMEE API Profile Item. Must be specified using * the key values "returnUnit" and "returnPerUnit" as defined at * http://my.amee.com/developers/wiki/ProfileCategory#GetCategory. * *************************************************************************** * * In all three cases: * * @return <object> A Services_AMEE_ProfileItem object (either for the * specified existing AMEE API Profile Item, or for the newly created * AMEE API Profile Item), or an Exception object on error. */ function __construct($aParams) { try { parent::__construct(); // Validate the number of parameters passed into the constructor if (!is_array($aParams)) { throw new Services_AMEE_Exception('Services_AMEE_ProfileItem constructor method called ' . 'with a parameter that is not an array'); } if (count($aParams) < 2 || count($aParams) > 5) { throw new Services_AMEE_Exception('Services_AMEE_ProfileItem constructor method called ' . 'with the parameter array containing an invalid number ' . 'of items'); } // Validate parameters one and two, which are always the object // representing the owning AMEE API Profile, and the object // representing the associated AMEE API Data Item, respectively if (!is_a($aParams[0], 'Services_AMEE_Profile')) { throw new Services_AMEE_Exception('Services_AMEE_ProfileItem constructor method called ' . 'with the parameter array\'s first parameter not being ' . 'the required Services_AMEE_Profile object'); } $this->oProfile = $aParams[0]; if (!is_a($aParams[1], 'Services_AMEE_DataItem')) { throw new Services_AMEE_Exception('Services_AMEE_ProfileItem constructor method called ' . 'with the parameter array\'s second parameter not being ' . 'the required Services_AMEE_DataItem object'); } $this->oDataItem = $aParams[1]; // Validate the optional third parameter and set the construction // method type based on the existence (or otherwise) of this // parameter and its type if (array_key_exists(2, $aParams)) { $sConstructType = $this->_validateThirdParam($aParams[2]); } else { $sConstructType = $this->_validateThirdParam(); } // Validate the optional fourth parameter if ($sConstructType == 'search' && array_key_exists(3, $aParams)) { // The fourth parameter is only valid with construction types // 'new' and 'uid' throw new Services_AMEE_Exception('Services_AMEE_ProfileItem constructor method called ' . 'with the parameter array\'s fourth parameter being set, ' . 'but with other parameters such that a fourth parameter ' . 'is not expected to be set'); } if (array_key_exists(3, $aParams)) { $this->_validateFourthParam($sConstructType, $aParams[3]); } // Validate the optional fifth parameter if ($sConstructType != 'new' && array_key_exists(4, $aParams)) { // The fifth parameter is only valid with construction type // 'new' throw new Services_AMEE_Exception('Services_AMEE_ProfileItem constructor method called ' . 'with the parameter array\'s fifth parameter being set, ' . 'but with other parameters such that a fifth parameter ' . 'is not expected to be set'); } if (array_key_exists(4, $aParams)) { $this->_validateReturnUnitParamArray($aParams[4]); } // All validation has passed if ($sConstructType == 'new') { // Create a new AMEE API Profile Item in the AMEE REST API, and // obtain the details of the created AMEE API Profile Item $this->_constructNew($aParams); } else { if ($sConstructType == 'uid') { // Obtain the details of the already existing AMEE API Profile // Item $this->_constructExistingByUID($aParams[2]); } else { if ($sConstructType == 'search') { // Obtain the details of the already existing AMEE API Profile // Item $this->_constructExistingBySearch(); } else { throw new Services_AMEE_Exception('Services_AMEE_ProfileItem constructor method failed ' . 'with an internal error - found construction type of ' . $sConstructType); } } } } catch (Exception $oException) { throw $oException; } }