Merge branch 'release-1.3.0'

CHANGELOG.md

@@ -1,5 +1,13 @@
 # CHANGELOG
 
+## 1.3.0
+
+* Added ability to create `Memo` to assigned recipients ([#5](https://github.com/communityds/deputy-api-wrapper/pull/5)).
+* Added `Roster` helper method `isTimesheetCreated` ([#7](https://github.com/communityds/deputy-api-wrapper/pull/7)).
+* Added ability to change `Company` settings ([#8](https://github.com/communityds/deputy-api-wrapper/pull/8)).
+* Added support for `CustomField` and `CustomFieldData` ([#9](https://github.com/communityds/deputy-api-wrapper/pull/9)).
+* Fixed issue when updating `Roster` instances caused by missing payload information ([#6](https://github.com/communityds/deputy-api-wrapper/pull/6)).
+
 ## 1.2.0
 
 * Added PHP 7 support.

src/Model/Company.php

@@ -40,8 +40,10 @@
  * @property string $operationalUnitNames
  * @property string $timeZone
  */
-class Company extends Record
+class Company extends Record implements CompanySettingsInterface
 {
+
+    use CompanySettingsTrait;
 
     /**
      * Names of operational units to create for new companies.

src/Model/CompanySettingsInterface.php

@@ -0,0 +1,53 @@
+<?php
+
+namespace CommunityDS\Deputy\Api\Model;
+
+interface CompanySettingsInterface
+{
+    /**
+     * Scheduling settings
+     */
+    const SETTING_WEEK_START = 'WEEK_START';
+    const SETTING_ACTIVE_HOURS_START = 'ACTIVE_HOURS_START';
+    const SETTING_ACTIVE_HOURS_END = 'ACTIVE_HOURS_END';
+    const SETTING_ROSTER_DEFAULT_SHIFT_LEN = 'ROSTER_DEFAULT_SHIFT_LEN';
+    const SETTING_DEFAULT_MEALBREAK_DURATION = 'DEFAULT_MEALBREAK_DURATION';
+    const SETTING_SHIFT_COST_ADDITIONAL = 'SHIFT_COST_ADDITIONAL';
+    const SETTING_ROSTER_PREVENT_CHANGE_HOURS = 'ROSTER_PREVENT_CHANGE_HOURS';
+    const SETTING_ROSTER_NOTIFICATION_MANAGER = 'ROSTER_NOTIFICATION_MANAGER';
+    const SETTING_ROSTER_REQUIRE_CONFIRM_HOURS = 'ROSTER_REQUIRE_CONFIRM_HOURS';
+    const SETTING_ROSTER_RECOMMENDATION_SORTING = 'ROSTER_RECOMMENDATION_SORTING';
+    const SETTING_ROSTER_ALLOW_PEER_VIEW = 'ROSTER_ALLOW_PEER_VIEW';
+    const SETTING_ROSTER_ALLOW_SWAP_SHIFT = 'ROSTER_ALLOW_SWAP_SHIFT';
+    const SETTING_ROSTER_SWAP_REQUIRE_APPROVAL = 'ROSTER_SWAP_REQUIRE_APPROVAL';
+    const SETTING_ROSTER_ALLOW_OFFER_SHIFT = 'ROSTER_ALLOW_OFFER_SHIFT';
+    const SETTING_ROSTER_ALLOW_SMS_WITH_FULL_NAME = 'ROSTER_ALLOW_SMS_WITH_FULL_NAME';
+
+    /**
+     * Timesheet settings
+     */
+    const SETTING_CAN_BUMP_SHIFT_VIA_DESK = 'CAN_BUMP_SHIFT_VIA_DESK';
+    const SETTING_CAN_MOBILE_BUMP_SHIFT = 'CAN_MOBILE_BUMP_SHIFT';
+    const SETTING_CAN_SMS_BUMP_SHIFT = 'CAN_SMS_BUMP_SHIFT';
+    const SETTING_REQUIRE_KIOSK_PHOTO_BUMP_SHIFT = 'REQUIRE_KIOSK_PHOTO_BUMP_SHIFT';
+    const SETTING_CAN_SUBMIT_SHIFT_VIA_DESK = 'CAN_SUBMIT_SHIFT_VIA_DESK';
+    const SETTING_CAN_MODIFY_TIMESHEET_ON_END = 'CAN_MODIFY_TIMESHEET_ON_END';
+    const SETTING_TIMESHEET_MATURITY = 'TIMESHEET_MATURITY';
+    const SETTING_TIMESHEET_CLOSEST_BLOCK = 'TIMESHEET_CLOSEST_BLOCK';
+    const SETTING_MEALBREAK_IS_PAID = 'MEALBREAK_IS_PAID';
+    const SETTING_TIMESHEET_AUTO_ROUND = 'TIMESHEET_AUTO_ROUND';
+    const SETTING_TIMESHEET_ROUND_START_TIME = 'TIMESHEET_ROUND_START_TIME';
+    const SETTING_TIMESHEET_ROUND_END_TIME = 'TIMESHEET_ROUND_END_TIME';
+    const SETTING_TIMESHEET_ROUND_MEALBREAK = 'TIMESHEET_ROUND_MEALBREAK';
+    const SETTING_TIMESHEET_ROUND_START_TIME_RS = 'TIMESHEET_ROUND_START_TIME_RS';
+    const SETTING_TIMESHEET_ROUND_END_TIME_RS = 'TIMESHEET_ROUND_END_TIME_RS';
+    const SETTING_TIMESHEET_ROUND_MEALBREAK_RS = 'TIMESHEET_ROUND_MEALBREAK_RS';
+    const SETTING_TIMESHEET_AUTO_TIME_APPROVE = 'TIMESHEET_AUTO_TIME_APPROVE';
+    const SETTING_CAN_CLOCKIN_SHIFT_EARLIER = 'CAN_CLOCKIN_SHIFT_EARLIER';
+    const SETTING_TIMESHEET_MATCH_ROSTER = 'TIMESHEET_MATCH_ROSTER';
+    const SETTING_TIMESHEET_MATCH_ROSTER_TIME = 'TIMESHEET_MATCH_ROSTER_TIME';
+    const SETTING_CAN_CLOCKIN_SHIFT_EARLIER_MINS = 'CAN_CLOCKIN_SHIFT_EARLIER_MINS';
+    const SETTING_CAN_END_BREAK_EARLIER = 'CAN_END_BREAK_EARLIER';
+    const SETTING_AUTO_SUGGEST_BREAK = 'AUTO_SUGGEST_BREAK';
+    const SETTING_CAN_DISPLAY_BREAK_WARNING = 'CAN_DISPLAY_BREAK_WARNING';
+}

src/Model/CompanySettingsTrait.php

@@ -0,0 +1,121 @@
+<?php
+
+namespace CommunityDS\Deputy\Api\Model;
+
+trait CompanySettingsTrait
+{
+
+    /**
+     * Get All settings for this Company
+     *
+     * @return array
+     */
+    public function getSettings()
+    {
+        try {
+            $settings = $this->getSuperviseCompanySettings();
+        } catch (\Exception $e) {
+            return [];
+        }
+
+        return is_array($settings) ? $settings : [];
+    }
+
+    /**
+     * Set All settings for given key/value pairs
+     *
+     * @param mixed[] $settingsKeyValues Key => Value pairs
+     *
+     * @return boolean
+     *
+     * @throws \Exception When issue
+     */
+    public function setSettings($settingsKeyValues)
+    {
+        $settingsPayLoad = $settingsKeyValues;
+        return $this->postSuperviseCompanySettings($settingsPayLoad);
+    }
+
+    /**
+     * Get single setting for this Company
+     *
+     * @param string $settingKey
+     *
+     * @return mixed|null
+     */
+    public function getSetting($settingKey)
+    {
+        $allSettings = $this->getSettings();
+        if (!key_exists($settingKey, $allSettings)) {
+            return null;
+        }
+        return $allSettings[$settingKey];
+    }
+
+    /**
+     * Set a single setting for this Company
+     *
+     * @param string $settingKey
+     * @param mixed $settingValue
+     *
+     * @return boolean
+     *
+     * @throws \Exception When issue
+     */
+    public function setSetting($settingKey, $settingValue)
+    {
+        $settingsPayLoad = ["{$settingKey}" => $settingValue];
+        return $this->postSuperviseCompanySettings($settingsPayLoad);
+    }
+
+    /**
+     * Sends a payload to the POST /supervise/company/{intCompanyId}/settings endpoint
+     *
+     * @param array $payload Payload of settings changes
+     *
+     * @return boolean
+     *
+     * @throws \Exception When primaryKey not provided
+     */
+    protected function postSuperviseCompanySettings($payload)
+    {
+        $companyId = $this->getPrimaryKey();
+        if (empty($companyId)) {
+            throw new \Exception('postSuperviseCompanySettings does not support updating Company without primaryKey');
+        }
+
+        $response = $this->getWrapper()->client->post(
+            "supervise/company/{$companyId}/settings",
+            $payload
+        );
+        if ($response === false) {
+            $this->setErrorsFromResponse($this->getWrapper()->client->getLastError());
+            return false;
+        }
+        return true;
+    }
+
+    /**
+     * Sends a request to the GET /supervise/company/{intCompanyId}/settings endpoint
+     *
+     * @return boolean
+     *
+     * @throws \Exception When primaryKey not provided
+     */
+    protected function getSuperviseCompanySettings()
+    {
+        $companyId = $this->getPrimaryKey();
+        if (empty($companyId)) {
+            throw new \Exception('getSuperviseCompanySettings cannot support getting settings for Company without primaryKey');
+        }
+
+        $response = $this->getWrapper()->client->get(
+            "supervise/company/{$companyId}/settings"
+        );
+        if ($response === false) {
+            $this->setErrorsFromResponse($this->getWrapper()->client->getLastError());
+            return false;
+        }
+        return $response;
+    }
+}

src/Model/CustomField.php

@@ -0,0 +1,32 @@
+<?php
+
+namespace CommunityDS\Deputy\Api\Model;
+
+use CommunityDS\Deputy\Api\Schema\DataType\Integer;
+use CommunityDS\Deputy\Api\Schema\Registry;
+use DateTime;
+
+/**
+ * @property integer $id
+ * @property string $system
+ * @property string $name
+ * @property string $apiName
+ * @property string $deputyField The corresponding property used on CustomFieldData
+ * @property integer $sortOrder
+ * @property string $default
+ * @property integer $type ID number of the Data Type
+ * @property string $valueList
+ * @property string $validation
+ * @property string $helpText
+ * @property integer $creator
+ * @property DateTime $created
+ * @property DateTime $modified
+ */
+class CustomField extends Record
+{
+
+    public function getDataType()
+    {
+        return Registry::getDataTypeById($this->type);
+    }
+}

src/Model/CustomFieldData.php

@@ -0,0 +1,121 @@
+<?php
+
+namespace CommunityDS\Deputy\Api\Model;
+
+use CommunityDS\Deputy\Api\Schema\ResourceInfo;
+use DateTime;
+
+/**
+ * @property integer $id
+ *
+ * @property string $system
+ * @property string $f01                DeputyField (Blob)
+ * @property string $f02                DeputyField (Blob)
+ * @property string $f03                DeputyField (Blob)
+ * @property string $f04                DeputyField (Blob)
+ * @property string $f05                DeputyField (Blob)
+ * @property string $f06                DeputyField (Blob)
+ * @property string $f07                DeputyField (Blob)
+ * @property string $f08                DeputyField (Blob)
+ * @property string $f09                DeputyField (Blob)
+ * @property string $f10                DeputyField (Blob)
+ * @property string $f11                DeputyField (Blob)
+ * @property string $f12                DeputyField (Blob)
+ * @property string $f13                DeputyField (Blob)
+ * @property string $f14                DeputyField (Blob)
+ * @property string $f15                DeputyField (Blob)
+ * @property string $f16                DeputyField (Blob)
+ * @property integer $creator
+ * @property DateTime $created
+ * @property DateTime $modified
+ */
+class CustomFieldData extends Record
+{
+
+    /**
+     * Support the setting of CustomFieldData by using either:
+     * - the fXX property directly (or any other property)
+     * - or if the a CustomField 'ApiName' (aka alias) is set then also set the fXX property
+     *
+     * Example of CustomField properties:
+     *  "Name": "Travel Time",
+     *  "ApiName": "traveltime",
+     *  "DeputyField": "f02",
+     *
+     * eg. if $var is "traveltime" then ALSO set $this->f02 = $value
+     *
+     * @param string $var
+     * @param mixed $value
+     *
+     * @return CustomFieldData this instance
+     */
+    public function __set($var, $value)
+    {
+        $propertyName = $this->getPropertyName($var);
+        if ($var != $propertyName) {
+            // Also set the relevant fXX (ie. DeputyField) to match the alias supplied in $var (ie. ApiFieldname)
+            $this->$propertyName = $value;
+        }
+
+        return parent::__set($var, $value);
+    }
+
+    /**
+     * Override Record::getSchema() to add other potential customFields configured through UI of Deputy
+     * Merge the base fields for CustomFieldData (ie. F01, F02, etc)
+     * with any CustomField(s) (eg. traveltime)
+     *
+     * @return ResourceInfo|null
+     */
+    public function getSchema()
+    {
+        $cacheKey = strtolower('resource-customFieldData-schema');
+        $schemaRecourceInfo = $this->getWrapper()->persistent->get($cacheKey, null);
+
+        if ($schemaRecourceInfo === null) {
+            // Get CustomFieldData Schema fields and update/merge with any Custom Fields
+            $schemaRecourceInfo = $this->getWrapper()->schema->resource($this->getResourceName());
+            $schemaRecourceInfo->fields = array_merge(
+                $this->getSchemaFieldsForCustomFields(),
+                $schemaRecourceInfo->fields
+            );
+
+            $this->getWrapper()->persistent->set($cacheKey, $schemaRecourceInfo);
+        }
+        return $schemaRecourceInfo;
+    }
+
+    /**
+     * Get fields partial for CustomFields
+     * an array that merged with 'fields' schema for CustomFieldData
+     * eg. ['traveltime' => 'Integer']
+     *
+     * @return array With format ['<apiName>' => '<DateType Class Name>']
+     */
+    protected function getSchemaFieldsForCustomFields()
+    {
+        $schemaPartialForCustomFields = [];
+        foreach ($this->getWrapper()->getCustomFieldsCached() as $customField) {
+            $dataTypeClassName = end(explode('\\', get_class($customField->getDataType())));
+            $schemaPartialForCustomFields[$customField->apiName] = $dataTypeClassName;
+        }
+        return $schemaPartialForCustomFields;
+    }
+
+    /**
+     * Get Property Name, also checking customField collection
+     *
+     * @param string $name Property Name (potentially a CustomField 'apiName'/alias)
+     *
+     * @return string If property name is found in customField collection then return the customField->deputyField (ie. 'fXX'); otherwise $name
+     */
+    private function getPropertyName($name)
+    {
+        $customField = $this->getWrapper()->getCustomFieldByApiName($name);
+        if (empty($customField)) {
+            return $name;
+        }
+        // CustomField detected
+        return $customField->deputyField;
+    }
+}