diff --git a/src/application/models/Admins_model.php b/src/application/models/Admins_model.php index 94d61acc..e51d605a 100644 --- a/src/application/models/Admins_model.php +++ b/src/application/models/Admins_model.php @@ -37,7 +37,9 @@ class Admins_Model extends CI_Model { * Add (insert or update) an admin user record into database. * * @param array $admin Contains the admin user data. + * * @return int Returns the record id. + * * @throws Exception When the admin data are invalid (see validate() method). */ public function add($admin) { @@ -59,9 +61,10 @@ class Admins_Model extends CI_Model { /** * Check whether a particular admin record exists in the database. * - * @param array $admin Contains the admin data. The 'email' value is required to be present - * at the moment. + * @param array $admin Contains the admin data. The 'email' value is required to be present at the moment. + * * @return bool Returns whether the record exists or not. + * * @throws Exception When the 'email' value is not present on the $admin argument. */ public function exists($admin) { @@ -85,7 +88,9 @@ class Admins_Model extends CI_Model { * Insert a new admin record into the database. * * @param array $admin Contains the admin data. + * * @return int Returns the new record id. + * * @throws Exception When the insert operation fails. */ public function insert($admin) { @@ -121,7 +126,9 @@ class Admins_Model extends CI_Model { * Update an existing admin record in the database. * * @param array $admin Contains the admin record data. + * * @return int Returns the record id. + * * @throws Exception When the update operation fails. */ public function update($admin) { @@ -152,9 +159,10 @@ class Admins_Model extends CI_Model { /** * Find the database record id of an admin user. * - * @param array $admin Contains the admin data. The 'email' value is required in order to - * find the record id. + * @param array $admin Contains the admin data. The 'email' value is required in order to find the record id. + * * @return int Returns the record id + * * @throws Exception When the 'email' value is not present on the $admin array. */ public function find_record_id($admin) { @@ -181,6 +189,7 @@ class Admins_Model extends CI_Model { * Validate admin user data before add() operation is executed. * * @param array $admin Contains the admin user data. + * * @return bool Returns the validation result. * * @throws Exception When data are invalid. @@ -257,11 +266,12 @@ class Admins_Model extends CI_Model { /** * Delete an existing admin record from the database. * - * @param numeric $admin_id The admin record id to be deleted. + * @param int $admin_id The admin record id to be deleted. + * * @return bool Returns the delete operation result. - * @throws Exception When the $admin_id is not a valid numeric value. - * @throws Exception When the record to be deleted is the only one admin user left on - * the system. + * + * @throws Exception When the $admin_id is not a valid int value. + * @throws Exception When the record to be deleted is the only one admin user left on the system. */ public function delete($admin_id) { if (!is_numeric($admin_id)) { @@ -288,9 +298,11 @@ class Admins_Model extends CI_Model { /** * Get a specific admin record from the database. * - * @param numeric $admin_id The id of the record to be returned. + * @param int $admin_id The id of the record to be returned. + * * @return array Returns an array with the admin user data. - * @throws Exception When the $admin_id is not a valid numeric value. + * + * @throws Exception When the $admin_id is not a valid int value. */ public function get_row($admin_id) { if (!is_numeric($admin_id)) { @@ -316,10 +328,12 @@ class Admins_Model extends CI_Model { * Get a specific field value from the database. * * @param string $field_name The field name of the value to be returned. - * @param numeric $admin_id Record id of the value to be returned. + * @param int $admin_id Record id of the value to be returned. + * * @return string Returns the selected record value from the database. + * * @throws Exception When the $field_name argument is not a valid string. - * @throws Exception When the $admin_id is not a valid numeric. + * @throws Exception When the $admin_id is not a valid int. * @throws Exception When the admin record does not exist in the database. * @throws Exception When the selected field value is not present on database. */ @@ -352,8 +366,9 @@ class Admins_Model extends CI_Model { /** * Get all, or specific admin records from database. * - * @param string|array $where_clause (OPTIONAL) The WHERE clause of the query to be executed. - * Use this to get specific admin records. + * @param string|array $where_clause (OPTIONAL) The WHERE clause of the query to be executed. Use this to get + * specific admin records. + * * @return array Returns an array with admin records. */ public function get_batch($where_clause = '') { @@ -388,7 +403,8 @@ class Admins_Model extends CI_Model { * Validate Records Username * * @param string $username The provider records username. - * @param numeric $user_id The user record id. + * @param int $user_id The user record id. + * * @return bool Returns the validation result. */ public function validate_username($username, $user_id) { diff --git a/src/application/models/Appointments_model.php b/src/application/models/Appointments_model.php index c5b424d8..3c7de79a 100644 --- a/src/application/models/Appointments_model.php +++ b/src/application/models/Appointments_model.php @@ -20,12 +20,12 @@ class Appointments_Model extends CI_Model { /** * Add an appointment record to the database. * - * This method adds a new appointment to the database. If the - * appointment doesn't exists it is going to be inserted, otherwise - * the record is going to be updated. + * This method adds a new appointment to the database. If the appointment doesn't exists it is going to be inserted, + * otherwise the record is going to be updated. + * + * @param array $appointment Associative array with the appointment data. Each key has the same name with the + * database fields. * - * @param array $appointment Associative array with the appointment - * data. Each key has the same name with the database fields. * @return int Returns the appointments id. */ public function add($appointment) { @@ -45,14 +45,16 @@ class Appointments_Model extends CI_Model { /** * Check if a particular appointment record already exists. * - * This method checks whether the given appointment already exists - * in the database. It doesn't search with the id, but by using the - * following fields: "start_datetime", "end_datetime", "id_users_provider", - * "id_users_customer", "id_services". + * This method checks whether the given appointment already exists in the database. It doesn't search with the id, + * but by using the following fields: "start_datetime", "end_datetime", "id_users_provider", "id_users_customer", + * "id_services". + * + * @param array $appointment Associative array with the appointment's data. Each key has the same name with the + * database fields. * - * @param array $appointment Associative array with the appointment's - * data. Each key has the same name with the database fields. * @return bool Returns whether the record exists or not. + * + * @throws Exception If appointment fields are missing. */ public function exists($appointment) { if (!isset($appointment['start_datetime']) @@ -60,8 +62,8 @@ class Appointments_Model extends CI_Model { || !isset($appointment['id_users_provider']) || !isset($appointment['id_users_customer']) || !isset($appointment['id_services'])) { - throw new Exception('Not all appointment field values ' - . 'are provided: ' . print_r($appointment, TRUE)); + throw new Exception('Not all appointment field values are provided: ' + . print_r($appointment, TRUE)); } $num_rows = $this->db->get_where('ea_appointments', array( @@ -78,9 +80,12 @@ class Appointments_Model extends CI_Model { /** * Insert a new appointment record to the database. * - * @param array $appointment Associative array with the appointment's - * data. Each key has the same name with the database fields. + * @param array $appointment Associative array with the appointment's data. Each key has the same name with the + * database fields. + * * @return int Returns the id of the new record. + * + * @throws Exception If appointment record could not be inserted. */ protected function _insert($appointment) { $appointment['book_datetime'] = date('Y-m-d H:i:s'); @@ -96,14 +101,12 @@ class Appointments_Model extends CI_Model { /** * Update an existing appointment record in the database. * - * The appointment data argument should already include the record - * id in order to process the update operation. + * The appointment data argument should already include the record ID in order to process the update operation. * - * @expectedException DatabaseException Raises when the update operation - * fails to complete successfully. + * @param array $appointment Associative array with the appointment's data. Each key has the same name with the + * database fields. * - * @param array $appointment Associative array with the appointment's - * data. Each key has the same name with the database fields. + * @throws Exception If appointment record could not be updated. */ protected function _update($appointment) { $this->db->where('id', $appointment['id']); @@ -115,17 +118,17 @@ class Appointments_Model extends CI_Model { /** * Find the database id of an appointment record. * - * The appointment data should include the following fields in order - * to get the unique id from the database: "start_datetime", "end_datetime", - * "id_users_provider", "id_users_customer", "id_services". + * The appointment data should include the following fields in order to get the unique id from the database: + * "start_datetime", "end_datetime", "id_users_provider", "id_users_customer", "id_services". * - * IMPORTANT! The record must already exists in the - * database, otherwise an exception is raised. + * IMPORTANT: The record must already exists in the database, otherwise an exception is raised. * - * @param array $appointment Array with the appointment data. The - * keys of the array should have the same names as the db fields. - * @return int Returns the db id of the record that matches the appointment - * data. + * @param array $appointment Array with the appointment data. The keys of the array should have the same names as + * the db fields. + * + * @return int Returns the db id of the record that matches the appointment data. + * + * @throws Exception If appointment could not be found. */ public function find_record_id($appointment) { $this->db->where(array( @@ -146,11 +149,13 @@ class Appointments_Model extends CI_Model { } /** - * Validate appointment data before the insert or update operations - * are executed. + * Validate appointment data before the insert or update operations are executed. * * @param array $appointment Contains the appointment data. + * * @return bool Returns the validation result. + * + * @throws Exception If appointment validation fails. */ public function validate($appointment) { $this->load->helper('data_validation'); @@ -161,8 +166,7 @@ class Appointments_Model extends CI_Model { $num_rows = $this->db->get_where('ea_appointments', array('id' => $appointment['id']))->num_rows(); if ($num_rows == 0) { - throw new Exception('Provided appointment id does not ' - . 'exist in the database.'); + throw new Exception('Provided appointment id does not exist in the database.'); } } @@ -214,11 +218,11 @@ class Appointments_Model extends CI_Model { /** * Delete an existing appointment record from the database. * - * @expectedException InvalidArgumentException Raises when the $appointment_id - * is not an integer. + * @param int $appointment_id The record id to be deleted. * - * @param numeric $appointment_id The record id to be deleted. * @return bool Returns the delete operation result. + * + * @throws Exception If $appointment_id argument is invalid. */ public function delete($appointment_id) { if (!is_numeric($appointment_id)) { @@ -238,50 +242,54 @@ class Appointments_Model extends CI_Model { /** * Get a specific row from the appointments table. * - * @param numeric $appointment_id The record's id to be returned. - * @return array Returns an associative array with the selected - * record's data. Each key has the same name as the database - * field names. + * @param int $appointment_id The record's id to be returned. + * + * @return array Returns an associative array with the selected record's data. Each key has the same name as the + * database field names. + * + * @throws Exception If $appointment_id argumnet is invalid. */ public function get_row($appointment_id) { if (!is_numeric($appointment_id)) { - throw new Exception('Invalid argument given. Expected ' - . 'integer for the $appointment_id: ' . $appointment_id); + throw new Exception('Invalid argument given. Expected integer for the $appointment_id: ' + . $appointment_id); } - return $this->db->get_where('ea_appointments', - array('id' => $appointment_id))->row_array(); + + return $this->db->get_where('ea_appointments', array('id' => $appointment_id))->row_array(); } /** * Get a specific field value from the database. * * @param string $field_name The field name of the value to be returned. - * @param numeric $appointment_id The selected record's id. + * @param int $appointment_id The selected record's id. + * * @return string Returns the records value from the database. + * + * @throws Exception If $appointment_id argument is invalid. + * @throws Exception If $field_name argument is invalid. + * @throws Exception If requested appointment record was not found. + * @throws Exception If requested field name does not exist. */ public function get_value($field_name, $appointment_id) { if (!is_numeric($appointment_id)) { - throw new Exception('Invalid argument given, expected ' - . 'integer for the $appointment_id: ' . $appointment_id); + throw new Exception('Invalid argument given, expected integer for the $appointment_id: ' + . $appointment_id); } if (!is_string($field_name)) { - throw new Exception('Invalid argument given, expected ' - . 'string for the $field_name: ' . $field_name); + throw new Exception('Invalid argument given, expected string for the $field_name: ' . $field_name); } - if ($this->db->get_where('ea_appointments', - array('id' => $appointment_id))->num_rows() == 0) { + if ($this->db->get_where('ea_appointments', array('id' => $appointment_id))->num_rows() == 0) { throw new Exception('The record with the provided id ' . 'does not exist in the database: ' . $appointment_id); } - $row_data = $this->db->get_where('ea_appointments', - array('id' => $appointment_id))->row_array(); + $row_data = $this->db->get_where('ea_appointments', array('id' => $appointment_id))->row_array(); if (!isset($row_data[$field_name])) { - throw new Exception('The given field name does not ' - . 'exist in the database: ' . $field_name); + throw new Exception('The given field name does not exist in the database: ' . $field_name); } return $row_data[$field_name]; @@ -292,8 +300,9 @@ class Appointments_Model extends CI_Model { * * @example $this->Model->getBatch('id = ' . $recordId); * - * @param string $where_clause (OPTIONAL) The WHERE clause of - * the query to be executed. DO NOT INCLUDE 'WHERE' KEYWORD. + * @param string $where_clause (OPTIONAL) The WHERE clause of the query to be executed. DO NOT INCLUDE 'WHERE' + * KEYWORD. + * * @return array Returns the rows from the database. */ public function get_batch($where_clause = '') { @@ -307,10 +316,8 @@ class Appointments_Model extends CI_Model { /** * Generate a unique hash for the given appointment data. * - * This method uses the current date-time to generate a unique - * hash string that is later used to identify this appointment. - * Hash is needed when the email is send to the user with an - * edit link. + * This method uses the current date-time to generate a unique hash string that is later used to identify this + * appointment. Hash is needed when the email is send to the user with an edit link. * * @return string Returns the unique appointment hash. */ @@ -323,7 +330,11 @@ class Appointments_Model extends CI_Model { * Inserts or updates an unavailable period record in the database. * * @param array $unavailable Contains the unavailable data. + * * @return int Returns the record id. + * + * @throws Exception If unavailability validation fails. + * @throws Exception If provider record could not be found in database. */ public function add_unavailable($unavailable) { // Validate period @@ -361,37 +372,42 @@ class Appointments_Model extends CI_Model { /** * Delete an unavailable period. * - * @param numeric $unavailable_id Record id to be deleted. + * @param int $unavailable_id Record id to be deleted. + * + * @return bool Returns the delete operation result. + * + * @throws Exception If $unavailable_id argument is invalid. */ public function delete_unavailable($unavailable_id) { if (!is_numeric($unavailable_id)) { - throw new Exception('Invalid argument type $unavailable_id (value:"' . - $unavailable_id . '")'); + throw new Exception('Invalid argument type $unavailable_id: ' . $unavailable_id); } - $num_rows = $this->db->get_where('ea_appointments', array('id' => $unavailable_id)) - ->num_rows(); + $num_rows = $this->db->get_where('ea_appointments', array('id' => $unavailable_id))->num_rows(); + if ($num_rows == 0) { return FALSE; // Record does not exist. } $this->db->where('id', $unavailable_id); + return $this->db->delete('ea_appointments'); } /** * Clear google sync IDs from appointment record. * - * @param numeric $provider_id The appointment provider record id. + * @param int $provider_id The appointment provider record id. + * + * @throws Exception If $provider_id argument is invalid. */ public function clear_google_sync_ids($provider_id) { if (!is_numeric($provider_id)) { - throw new Exception('Invalid argument type $provider_id (value: "' - . $provider_id . '")'); + throw new Exception('Invalid argument type $provider_id: ' . $provider_id); } $this->db->update('ea_appointments', array('id_google_calendar' => NULL), - array('id_users_provider' => $provider_id)); + array('id_users_provider' => $provider_id)); } /** diff --git a/src/application/models/Customers_model.php b/src/application/models/Customers_model.php index eb863d8e..16b7da0f 100644 --- a/src/application/models/Customers_model.php +++ b/src/application/models/Customers_model.php @@ -20,12 +20,12 @@ class Customers_Model extends CI_Model { /** * Add a customer record to the database. * - * This method adds a customer to the database. If the customer - * doesn't exists it is going to be inserted, otherwise the - * record is going to be updated. + * This method adds a customer to the database. If the customer doesn't exists it is going to be inserted, otherwise + * the record is going to be updated. + * + * @param array $customer Associative array with the customer's data. Each key has the same name with the database + * fields. * - * @param array $customer Associative array with the customer's - * data. Each key has the same name with the database fields. * @return int Returns the customer id. */ public function add($customer) { @@ -51,13 +51,15 @@ class Customers_Model extends CI_Model { /** * Check if a particular customer record already exists. * - * This method checks whether the given customer already exists in - * the database. It doesn't search with the id, but with the following - * fields: "email" + * This method checks whether the given customer already exists in the database. It doesn't search with the id, but + * with the following fields: "email" + * + * @param array $customer Associative array with the customer's data. Each key has the same name with the database + * fields. * - * @param array $customer Associative array with the customer's - * data. Each key has the same name with the database fields. * @return bool Returns whether the record exists or not. + * + * @throws Exception If customer email property is missing. */ public function exists($customer) { if (!isset($customer['email'])) { @@ -79,9 +81,12 @@ class Customers_Model extends CI_Model { /** * Insert a new customer record to the database. * - * @param array $customer Associative array with the customer's - * data. Each key has the same name with the database fields. + * @param array $customer Associative array with the customer's data. Each key has the same name with the database + * fields. + * * @return int Returns the id of the new record. + * + * @throws Exception If customer record could not be inserted. */ protected function _insert($customer) { // Before inserting the customer we need to get the customer's role id @@ -104,12 +109,14 @@ class Customers_Model extends CI_Model { /** * Update an existing customer record in the database. * - * The customer data argument should already include the record - * id in order to process the update operation. + * The customer data argument should already include the record ID in order to process the update operation. * - * @param array $customer Associative array with the customer's - * data. Each key has the same name with the database fields. - * @return int Returns the updated record id. + * @param array $customer Associative array with the customer's data. Each key has the same name with the database + * fields. + * + * @return int Returns the updated record ID. + * + * @throws Exception If customer record could not be updated. */ protected function _update($customer) { // Do not update empty string values. @@ -129,15 +136,16 @@ class Customers_Model extends CI_Model { /** * Find the database id of a customer record. * - * The customer data should include the following fields in order to - * get the unique id from the database: "email" + * The customer data should include the following fields in order to get the unique id from the database: "email" * - * IMPORTANT! The record must already exists in the - * database, otherwise an exception is raised. + * IMPORTANT: The record must already exists in the database, otherwise an exception is raised. * - * @param array $customer Array with the customer data. The - * keys of the array should have the same names as the db fields. - * @return int Returns the id. + * @param array $customer Array with the customer data. The keys of the array should have the same names as the + * database fields. + * + * @return int Returns the ID. + * + * @throws Exception If customer record does not exist. */ public function find_record_id($customer) { if (!isset($customer['email'])) { @@ -165,7 +173,10 @@ class Customers_Model extends CI_Model { * Validate customer data before the insert or update operation is executed. * * @param array $customer Contains the customer data. + * * @return bool Returns the validation result. + * + * @throws Exception If customer validation fails. */ public function validate($customer) { $this->load->helper('data_validation'); @@ -218,8 +229,11 @@ class Customers_Model extends CI_Model { /** * Delete an existing customer record from the database. * - * @param numeric $customer_id The record id to be deleted. + * @param int $customer_id The record id to be deleted. + * * @return bool Returns the delete operation result. + * + * @throws Exception If $customer_id argument is invalid. */ public function delete($customer_id) { if (!is_numeric($customer_id)) { @@ -237,10 +251,12 @@ class Customers_Model extends CI_Model { /** * Get a specific row from the appointments table. * - * @param numeric $customer_id The record's id to be returned. - * @return array Returns an associative array with the selected - * record's data. Each key has the same name as the database - * field names. + * @param int $customer_id The record's id to be returned. + * + * @return array Returns an associative array with the selected record's data. Each key has the same name as the + * database field names. + * + * @throws Exception If $customer_id argumnet is invalid. */ public function get_row($customer_id) { if (!is_numeric($customer_id)) { @@ -252,10 +268,15 @@ class Customers_Model extends CI_Model { /** * Get a specific field value from the database. * - * @param string $field_name The field name of the value to be - * returned. + * @param string $field_name The field name of the value to be returned. * @param int $customer_id The selected record's id. + * * @return string Returns the records value from the database. + * + * @throws Exception If $customer_id argument is invalid. + * @throws Exception If $field_name argument is invalid. + * @throws Exception If requested customer record does not exist in the database. + * @throws Exception If requested field name does not exist in the database. */ public function get_value($field_name, $customer_id) { if (!is_numeric($customer_id)) { @@ -290,8 +311,9 @@ class Customers_Model extends CI_Model { * * @example $this->Model->getBatch('id = ' . $recordId); * - * @param string $whereClause (OPTIONAL) The WHERE clause of - * the query to be executed. DO NOT INCLUDE 'WHERE' KEYWORD. + * @param string $whereClause (OPTIONAL) The WHERE clause of the query to be executed. DO NOT INCLUDE 'WHERE' + * KEYWORD. + * * @return array Returns the rows from the database. */ public function get_batch($where_clause = '') { diff --git a/src/application/models/Providers_model.php b/src/application/models/Providers_model.php index 7ffeeb27..ba74d7c1 100644 --- a/src/application/models/Providers_model.php +++ b/src/application/models/Providers_model.php @@ -14,8 +14,7 @@ /** * Providers_Model Class * - * Contains the database operations for the service provider users of - * Easy!Appointments. + * Contains the database operations for the service provider users of Easy!Appointments. * * Data Structure: * 'fist_name' @@ -48,11 +47,13 @@ class Providers_Model extends CI_Model { /** * Add (insert - update) a service provider record. * - * If the record already exists (id value provided) then it is going to be updated, - * otherwise inserted into the database. + * If the record already exists (id value provided) then it is going to be updated, otherwise inserted into the + * database. * * @param array $provider Contains the service provider data. + * * @return int Returns the record id. + * * @throws Exception When the record data validation fails. */ public function add($provider) { @@ -74,9 +75,10 @@ class Providers_Model extends CI_Model { /** * Check whether a particular provider record already exists in the database. * - * @param array $provider Contains the provider data. The 'email' value is required - * in order to check for a provider. + * @param array $provider Contains the provider data. The 'email' value is required in order to check for a provider. + * * @return bool Returns whether the provider record exists or not. + * * @throws Exception When the 'email' value is not provided. */ public function exists($provider) { @@ -100,7 +102,9 @@ class Providers_Model extends CI_Model { * Insert a new provider record into the database. * * @param array $provider Contains the provider data (must be already validated). + * * @return int Returns the new record id. + * * @throws Exception When the insert operation fails. */ protected function _insert($provider) { @@ -135,7 +139,9 @@ class Providers_Model extends CI_Model { * Update an existing provider record in the database. * * @param array $provider Contains the provider data. + * * @return int Returns the record id. + * * @throws Exception When the update operation fails. */ protected function _update($provider) { @@ -168,9 +174,10 @@ class Providers_Model extends CI_Model { /** * Find the database record id of a provider. * - * @param array $provider Contains the provider data. The 'email' value is required - * in order to find the record id. + * @param array $provider Contains the provider data. The 'email' value is required in order to find the record id. + * * @return int Returns the record id. + * * @throws Exception When the provider's email value is not provided. */ public function find_record_id($provider) { @@ -197,7 +204,10 @@ class Providers_Model extends CI_Model { * Validate provider data before the insert or update operation is executed. * * @param array $provider Contains the provider data. + * * @return bool Returns the validation result. + * + * @throws Exception If provider validation fails. */ public function validate($provider) { $this->load->helper('data_validation'); @@ -226,7 +236,7 @@ class Providers_Model extends CI_Model { // Validate provider services. if (!isset($provider['services']) || !is_array($provider['services'])) { throw new Exception('Invalid provider services given: ' . print_r($provider, TRUE)); - } else { // Check if services are valid numeric values. + } else { // Check if services are valid int values. foreach($provider['services'] as $service_id) { if (!is_numeric($service_id)) { throw new Exception('A provider service with invalid id was found: ' @@ -289,9 +299,11 @@ class Providers_Model extends CI_Model { /** * Delete an existing provider record from the database. * - * @param numeric $customer_id The record id to be deleted. + * @param int $customer_id The record id to be deleted. + * * @return bool Returns the delete operation result. - * @throws Exception When the provider id value is not numeric. + * + * @throws Exception When the provider id value is not int. */ public function delete($provider_id) { if (!is_numeric($provider_id)) { @@ -310,8 +322,10 @@ class Providers_Model extends CI_Model { * Get a specific provider record from the database. * * @param int $provider_id The id of the record to be returned. - * @return array Returns an associative array with the selected record's data. Each key - * has the same name as the database field names. + * + * @return array Returns an associative array with the selected record's data. Each key has the same name as the + * database field names. + * * @throws Exception When the selected record does not exist in database. */ public function get_row($provider_id) { @@ -349,11 +363,12 @@ class Providers_Model extends CI_Model { * Get a specific field value from the database. * * @param string $field_name The field name of the value to be returned. - * @param numeric $provider_id Record id of the value to be returned. + * @param int $provider_id Record id of the value to be returned. + * * @return string Returns the selected record value from the database. * * @throws Exception When the $field_name argument is not a valid string. - * @throws Exception When the $provider_id is not a valid numeric. + * @throws Exception When the $provider_id is not a valid int. * @throws Exception When the provider record does not exist in the database. * @throws Exception When the selected field value is not present on database. */ @@ -428,8 +443,7 @@ class Providers_Model extends CI_Model { /** * Get the available system providers. * - * This method returns the available providers and the services that can - * provide. + * This method returns the available providers and the services that can provide. * * @return array Returns an array with the providers data. */ @@ -478,14 +492,13 @@ class Providers_Model extends CI_Model { /** * Get a providers setting from the database. * - * @param string $setting_name The setting name that is going to be - * returned. + * @param string $setting_name The setting name that is going to be returned. * @param int $provider_id The selected provider id. + * * @return string Returns the value of the selected user setting. */ public function get_setting($setting_name, $provider_id) { - $provider_settings = $this->db->get_where('ea_user_settings', - array('id_users' => $provider_id))->row_array(); + $provider_settings = $this->db->get_where('ea_user_settings', array('id_users' => $provider_id))->row_array(); return $provider_settings[$setting_name]; } @@ -496,7 +509,7 @@ class Providers_Model extends CI_Model { * * @param string $setting_name The setting's name. * @param string $value The setting's value. - * @param numeric $provider_id The selected provider id. + * @param int $provider_id The selected provider id. */ public function set_setting($setting_name, $value, $provider_id) { $this->db->where(array('id_users' => $provider_id)); @@ -507,7 +520,10 @@ class Providers_Model extends CI_Model { * Save the provider settings (used from insert or update operation). * * @param array $settings Contains the setting values. - * @param numeric $provider_id Record id of the provider. + * @param int $provider_id Record id of the provider. + * + * @throws Exception If $provider_id argument is invalid. + * @throws Exception If $settings argument is invalid. */ protected function save_settings($settings, $provider_id) { if (!is_numeric($provider_id)) { @@ -533,9 +549,10 @@ class Providers_Model extends CI_Model { * Save the provider services in the database (use on both insert and update operation). * * @param array $services Contains the service ids that the selected provider can provide. - * @param numeric $provider_id The selected provider record id. + * @param int $provider_id The selected provider record id. + * * @throws Exception When the $services argument type is not array. - * @throws Exception When the $provider_id argument type is not numeric. + * @throws Exception When the $provider_id argument type is not int. */ protected function save_services($services, $provider_id) { // Validate method arguments. @@ -562,7 +579,8 @@ class Providers_Model extends CI_Model { * Validate Records Username * * @param string $username The provider records username. - * @param numeric $user_id The user record id. + * @param int $user_id The user record id. + * * @return bool Returns the validation result. */ public function validate_username($username, $user_id) { diff --git a/src/application/models/Roles_model.php b/src/application/models/Roles_model.php index fcbe0cd2..45341b6e 100644 --- a/src/application/models/Roles_model.php +++ b/src/application/models/Roles_model.php @@ -20,8 +20,8 @@ class Roles_Model extends CI_Model { /** * Get the record id of a particular role. * - * @param string $role_slug The selected role slug. Slugs are - * defined in the "application/config/constants.php" file. + * @param string $role_slug The selected role slug. Slugs are defined in the "application/config/constants.php" file. + * * @return int Returns the database id of the roles record. */ public function get_role_id($role_slug) { @@ -31,18 +31,18 @@ class Roles_Model extends CI_Model { /** * Returns all the privileges (bool values) of a role slug. * - * The privilege numbers are converted into bool values of the four main actions (view, - * add, edit, delete). By checking each value you can know if the user is able to perform - * this action. + * The privilege numbers are converted into bool values of the four main actions (view, add, edit, delete). By + * checking each value you can know if the user is able to perform this action. * * @param string $slug The role slug. + * * @return array Returns the privilege value. */ public function get_privileges($slug) { $privileges = $this->db->get_where('ea_roles', array('slug' => $slug))->row_array(); unset($privileges['id'], $privileges['name'], $privileges['slug'], $privileges['is_admin']); - // Convert the numeric values to bool so that is easier to check whether a + // Convert the int values to bool so that is easier to check whether a // user has the required privileges for a specific action. foreach($privileges as &$value) { $privileges_number = $value; diff --git a/src/application/models/Secretaries_model.php b/src/application/models/Secretaries_model.php index ca52d502..6b58c9b2 100644 --- a/src/application/models/Secretaries_model.php +++ b/src/application/models/Secretaries_model.php @@ -16,20 +16,21 @@ * * Handles the db actions that have to do with secretaries. * - * Data Structure - * 'first_name' - * 'last_name' - * 'email' - * 'mobile_number' - * 'phone_number' - * 'address' - * 'city' - * 'state' - * 'zip_code' - * 'notes' - * 'id_roles' - * 'providers' >> array with provider ids that the secretary handles - * 'settings' >> array with the secretary settings + * Data Structure: + * + * 'first_name' + * 'last_name' + * 'email' + * 'mobile_number' + * 'phone_number' + * 'address' + * 'city' + * 'state' + * 'zip_code' + * 'notes' + * 'id_roles' + * 'providers' >> array with provider ids that the secretary handles + * 'settings' >> array with the secretary settings * * @package Models */ @@ -38,7 +39,9 @@ class Secretaries_Model extends CI_Model { * Add (insert or update) a secretary user record into database. * * @param array $secretary Contains the secretary user data. + * * @return int Returns the record id. + * * @throws Exception When the secretary data are invalid (see validate() method). */ public function add($secretary) { @@ -60,9 +63,10 @@ class Secretaries_Model extends CI_Model { /** * Check whether a particular secretary record exists in the database. * - * @param array $secretary Contains the secretary data. The 'email' value is required to - * be present at the moment. + * @param array $secretary Contains the secretary data. The 'email' value is required to be present at the moment. + * * @return bool Returns whether the record exists or not. + * * @throws Exception When the 'email' value is not present on the $secretary argument. */ public function exists($secretary) { @@ -86,7 +90,9 @@ class Secretaries_Model extends CI_Model { * Insert a new secretary record into the database. * * @param array $secretary Contains the secretary data. + * * @return int Returns the new record id. + * * @throws Exception When the insert operation fails. */ protected function _insert($secretary) { @@ -117,7 +123,9 @@ class Secretaries_Model extends CI_Model { * Update an existing secretary record in the database. * * @param array $secretary Contains the secretary record data. + * * @return int Returns the record id. + * * @throws Exception When the update operation fails. */ protected function _update($secretary) { @@ -147,9 +155,10 @@ class Secretaries_Model extends CI_Model { /** * Find the database record id of a secretary. * - * @param array $secretary Contains the secretary data. The 'email' value is required - * in order to find the record id. + * @param array $secretary Contains the secretary data. The 'email' value is required in order to find the record id. + * * @return int Returns the record id + * * @throws Exception When the 'email' value is not present on the $secretary array. */ public function find_record_id($secretary) { @@ -176,7 +185,10 @@ class Secretaries_Model extends CI_Model { * Validate secretary user data before add() operation is executed. * * @param array $secretary Contains the secretary user data. + * * @return bool Returns the validation result. + * + * @throws Exception If secretary validation fails. */ public function validate($secretary) { $this->load->helper('data_validation'); @@ -255,9 +267,11 @@ class Secretaries_Model extends CI_Model { /** * Delete an existing secretary record from the database. * - * @param numeric $secretary_id The secretary record id to be deleted. + * @param int $secretary_id The secretary record id to be deleted. + * * @return bool Returns the delete operation result. - * @throws Exception When the $secretary_id is not a valid numeric value. + * + * @throws Exception When the $secretary_id is not a valid int value. */ public function delete($secretary_id) { if (!is_numeric($secretary_id)) { @@ -275,9 +289,11 @@ class Secretaries_Model extends CI_Model { /** * Get a specific secretary record from the database. * - * @param numeric $secretary_id The id of the record to be returned. + * @param int $secretary_id The id of the record to be returned. + * * @return array Returns an array with the secretary user data. - * @throws Exception When the $secretary_id is not a valid numeric value. + * + * @throws Exception When the $secretary_id is not a valid int value. * @throws Exception When given record id does not exist in the database. */ public function get_row($secretary_id) { @@ -310,10 +326,12 @@ class Secretaries_Model extends CI_Model { * Get a specific field value from the database. * * @param string $field_name The field name of the value to be returned. - * @param numeric $secretary_id Record id of the value to be returned. + * @param int $secretary_id Record id of the value to be returned. + * * @return string Returns the selected record value from the database. + * * @throws Exception When the $field_name argument is not a valid string. - * @throws Exception When the $secretary_id is not a valid numeric. + * @throws Exception When the $secretary_id is not a valid int. * @throws Exception When the secretary record does not exist in the database. * @throws Exception When the selected field value is not present on database. */ @@ -346,8 +364,9 @@ class Secretaries_Model extends CI_Model { /** * Get all, or specific secretary records from database. * - * @param string|array $where_clause (OPTIONAL) The WHERE clause of the query to be executed. - * Use this to get specific secretary records. + * @param string|array $where_clause (OPTIONAL) The WHERE clause of the query to be executed. Use this to get + * specific secretary records. + * * @return array Returns an array with secretary records. */ public function get_batch($where_clause = '') { @@ -389,8 +408,11 @@ class Secretaries_Model extends CI_Model { /** * Save a secretary handling users. + * * @param array $providers Contains the provider ids that are handled by the secretary. - * @param numeric $secretary_id The selected secretary record. + * @param int $secretary_id The selected secretary record. + * + * @throws Exception If $providers argument is invalid. */ protected function save_providers($providers, $secretary_id) { if (!is_array($providers)) { @@ -414,11 +436,14 @@ class Secretaries_Model extends CI_Model { * Save the secretary settings (used from insert or update operation). * * @param array $settings Contains the setting values. - * @param numeric $secretary_id Record id of the secretary. + * @param int $secretary_id Record id of the secretary. + * + * @throws Exception If $secretary_id argument is invalid. + * @throws Exception If $settings argument is invalid. */ protected function save_settings($settings, $secretary_id) { if (!is_numeric($secretary_id)) { - throw new Exception('Invalid $provider_id argument given:' . $secretary_id); + throw new Exception('Invalid $secretary_id argument given:' . $secretary_id); } if (count($settings) == 0 || !is_array($settings)) { @@ -442,6 +467,7 @@ class Secretaries_Model extends CI_Model { * * @param string $setting_name The setting name that is going to be returned. * @param int $secretary_id The selected provider id. + * * @return string Returns the value of the selected user setting. */ public function get_setting($setting_name, $secretary_id) { @@ -457,7 +483,7 @@ class Secretaries_Model extends CI_Model { * * @param string $setting_name The setting's name. * @param string $value The setting's value. - * @param numeric $secretary_id The selected provider id. + * @param int $secretary_id The selected provider id. */ public function set_setting($setting_name, $value, $secretary_id) { $this->db->where(array('id_users' => $secretary_id)); @@ -468,7 +494,8 @@ class Secretaries_Model extends CI_Model { * Validate Records Username * * @param string $username The provider records username. - * @param numeric $user_id The user record id. + * @param int $user_id The user record id. + * * @return bool Returns the validation result. */ public function validate_username($username, $user_id) { diff --git a/src/application/models/Services_model.php b/src/application/models/Services_model.php index 6f3604e9..fd8760a8 100644 --- a/src/application/models/Services_model.php +++ b/src/application/models/Services_model.php @@ -20,10 +20,9 @@ class Services_Model extends CI_Model { /** * Add (insert or update) a service record on the database * - * @param array $service Contains the service data. If an 'id' value is provided then - * the record will be updated. + * @param array $service Contains the service data. If an 'id' value is provided then the record will be updated. * - * @return numeric Returns the record id. + * @return int Returns the record id. */ public function add($service) { $this->validate($service); @@ -43,6 +42,8 @@ class Services_Model extends CI_Model { * @param array $service Contains the service record data. * * @return int Returns the new service record id. + * + * @throws Exception If service record could not be inserted. */ protected function _insert($service) { if (!$this->db->insert('ea_services', $service)) { @@ -54,8 +55,9 @@ class Services_Model extends CI_Model { /** * Update service record. * - * @param array $service Contains the service data. The record id needs to be included in - * the array. + * @param array $service Contains the service data. The record id needs to be included in the array. + * + * @throws Exception If service record could not be updated. */ protected function _update($service) { $this->db->where('id', $service['id']); @@ -67,8 +69,12 @@ class Services_Model extends CI_Model { /** * Checks whether an service record already exists in the database. * - * @param array $service Contains the service data. Name, duration and price values - * are mandatory in order to perform the checks. + * @param array $service Contains the service data. Name, duration and price values are mandatory in order to + * perform the checks. + * + * @return bool Returns whether the service record exists. + * + * @throws Exception If required fields are missing. */ public function exists($service) { if (!isset($service['name']) @@ -93,6 +99,8 @@ class Services_Model extends CI_Model { * @param array $service Contains the service data. * * @return bool Returns the validation result. + * + * @throws Exception If service validation fails. */ public function validate($service) { $this->load->helper('data_validation'); @@ -122,7 +130,7 @@ class Services_Model extends CI_Model { . print_r($service, TRUE)); } - // Duration must be numeric + // Duration must be int if ($service['duration'] !== NULL) { if (!is_numeric($service['duration'])) { throw new Exception('Service duration is not numeric.'); @@ -154,10 +162,13 @@ class Services_Model extends CI_Model { /** * Get the record id of an existing record. * - * NOTICE! The record must exist, otherwise an exception will be raised. + * NOTICE: The record must exist, otherwise an exception will be raised. * - * @param array $service Contains the service record data. Name, duration and price values - * are mandatory for this method to complete. + * @param array $service Contains the service record data. Name, duration and price values are mandatory for this + * method to complete. + * + * @throws Exception If required fields are missing. + * @throws Exception If requested service was not found. */ public function find_record_id($service) { if (!isset($service['name']) @@ -183,9 +194,11 @@ class Services_Model extends CI_Model { /** * Delete a service record from database. * - * @param numeric $service_id Record id to be deleted. + * @param int $service_id Record id to be deleted. * * @return bool Returns the delete operation result. + * + * @throws Exception If $service_id argument is invalid. */ public function delete($service_id) { if (!is_numeric($service_id)) { @@ -203,10 +216,12 @@ class Services_Model extends CI_Model { /** * Get a specific row from the services db table. * - * @param numeric $service_id The record's id to be returned. + * @param int $service_id The record's id to be returned. * - * @return array Returns an associative array with the selected record's data. Each key - * has the same name as the database field names. + * @return array Returns an associative array with the selected record's data. Each key has the same name as the + * database field names. + * + * @throws Exception If $service_id argument is not valid. */ public function get_row($service_id) { if (!is_numeric($service_id)) { @@ -223,6 +238,11 @@ class Services_Model extends CI_Model { * @param int $service_id The selected record's id. * * @return string Returns the records value from the database. + * + * @throws Exception If $service_id argument is invalid. + * @throws Exception If $field_name argument is invalid. + * @throws Exception if requested service does not exist in the database. + * @throws Exception If requested field name does not exist in the database. */ public function get_value($field_name, $service_id) { if (!is_numeric($service_id)) { @@ -287,7 +307,9 @@ class Services_Model extends CI_Model { * * @param array $category Contains the service category data. * - * @return int Returns the record id.s + * @return int Returns the record ID. + * + * @throws Exception If service category data are invalid. */ public function add_category($category) { if (!$this->validate_category($category)) { @@ -308,9 +330,11 @@ class Services_Model extends CI_Model { /** * Delete a service category record from the database. * - * @param numeric $category_id Record id to be deleted. + * @param int $category_id Record id to be deleted. * * @return bool Returns the delete operation result. + * + * @throws Exception if Service category record was not found. */ public function delete_category($category_id) { if (!is_numeric($category_id)) { @@ -330,9 +354,12 @@ class Services_Model extends CI_Model { /** * Get a service category record data. * - * @param numeric $category_id Record id to be retrieved. + * @param int $category_id Record id to be retrieved. * * @return array Returns the record data from the database. + * + * @throws Exception If $category_id argument is invalid. + * @throws Exception If service category record does not exist. */ public function get_category($category_id) { if (!is_numeric($category_id)) { @@ -365,6 +392,8 @@ class Services_Model extends CI_Model { * @param array $category Contains the service category data. * * @return bool Returns the validation result. + * + * @throws Exception If required fields are missing. */ public function validate_category($category) { try { @@ -382,6 +411,5 @@ class Services_Model extends CI_Model { } catch(Exception $exc) { return FALSE; } - } } diff --git a/src/application/models/Settings_model.php b/src/application/models/Settings_model.php index 2d29b212..d54c9d58 100644 --- a/src/application/models/Settings_model.php +++ b/src/application/models/Settings_model.php @@ -22,11 +22,12 @@ class Settings_Model extends CI_Model { * * This method returns a system setting from the database. * - * @expectedException Exception - * * @param string $name The database setting name. * * @return string Returns the database value for the selected setting. + * + * @throws Exception If the $name argument is invalid. + * @throws Exception If the requested $name setting does not exist in the database. */ public function get_setting($name) { if (!is_string($name)) { // Check argument type. @@ -38,21 +39,22 @@ class Settings_Model extends CI_Model { } $query = $this->db->get_where('ea_settings', array('name' => $name)); - $setting = ($query->num_rows() > 0) ? $query->row() : ''; + $setting = $query->num_rows() > 0 ? $query->row() : ''; return $setting->value; } /** - * This method sets the value for a specific setting - * on the database. If the setting doesn't exist, it - * is going to be created, otherwise updated. + * This method sets the value for a specific setting on the database. * - * @expectedException Exception + * If the setting doesn't exist, it is going to be created, otherwise updated. * * @param string $name The setting name. - * @param type $value The setting value. + * @param string $value The setting value. * * @return int Returns the setting database id. + * + * @throws Exception If $name argument is invalid. + * @throws Exception If the save operation fails. */ public function set_setting($name, $value) { if (!is_string($name)) { @@ -84,11 +86,11 @@ class Settings_Model extends CI_Model { /** * Remove a setting from the database. * - * @expectedException Exception - * * @param string $name The setting name to be removed. * * @return bool Returns the delete operation result. + * + * @throws Exception If the $name argument is invalid. */ public function remove_setting($name) { if (!is_string($name)) { diff --git a/src/application/models/User_model.php b/src/application/models/User_model.php index a878f73e..e619e15a 100644 --- a/src/application/models/User_model.php +++ b/src/application/models/User_model.php @@ -22,7 +22,7 @@ class User_Model extends CI_Model { /** * Returns the user from the database for the "settings" page. * - * @param numeric $user_id User record id. + * @param int $user_id User record id. * * @return array Returns an array with user data. * @@ -83,7 +83,7 @@ class User_Model extends CI_Model { * Performs the check of the given user credentials. * * @param string $username Given user's name. - * @param type $password Given user's password (not hashed yet). + * @param string $password Given user's password (not hashed yet). * * @return array|null Returns the session data of the logged in user or null on failure. */ @@ -108,14 +108,19 @@ class User_Model extends CI_Model { /** * Get the given user's display name (first + last name). * - * @param numeric $user_id The given user record id. + * @param int $user_id The given user record id. * * @return string Returns the user display name. + * + * @throws Exception If $user_id argument is invalid. */ public function get_user_display_name($user_id) { - if (!is_numeric($user_id)) - throw new Exception ('Invalid argument given ($user_id = "' . $user_id . '").'); + if (!is_numeric($user_id)) { + throw new Exception ('Invalid argument given: ' . $user_id); + } + $user = $this->db->get_where('ea_users', array('id' => $user_id))->row_array(); + return $user['first_name'] . ' ' . $user['last_name']; } @@ -123,8 +128,8 @@ class User_Model extends CI_Model { * If the given arguments correspond to an existing user record, generate a new * password and send it with an email. * - * @param string $username - * @param string $email + * @param string $username User's username. + * @param string $email User's email. * * @return string|bool Returns the new password on success or FALSE on failure. */ @@ -139,7 +144,9 @@ class User_Model extends CI_Model { ->where('ea_user_settings.username', $username) ->get(); - if ($result->num_rows() == 0) return FALSE; + if ($result->num_rows() == 0) { + return FALSE; + } $user_id = $result->row()->id;