/**
* 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;
}
}
