From 539e753b8089944193b724e06e5304f379e71d32 Mon Sep 17 00:00:00 2001 From: alext Date: Wed, 6 Sep 2017 15:22:11 +0200 Subject: [PATCH] Adjusted phpdoc blocks in controller classes. --- src/application/controllers/Appointments.php | 81 ++++---- src/application/controllers/Backend.php | 93 +++++---- src/application/controllers/Backend_api.php | 185 +++++++++++------- src/application/controllers/Captcha.php | 1 - src/application/controllers/Errors.php | 8 + src/application/controllers/Google.php | 50 +++-- src/application/controllers/Installation.php | 7 +- src/application/controllers/User.php | 6 +- .../controllers/api/v1/Availabilities.php | 4 +- 9 files changed, 247 insertions(+), 188 deletions(-) diff --git a/src/application/controllers/Appointments.php b/src/application/controllers/Appointments.php index dc1d7eeb..eecd63d8 100755 --- a/src/application/controllers/Appointments.php +++ b/src/application/controllers/Appointments.php @@ -49,7 +49,7 @@ class Appointments extends CI_Controller { * is provided then it means that the customer followed the appointment * manage link that was send with the book success email. * - * @param string $appointment_hash The db appointment hash of an existing record. + * @param string $appointment_hash DB appointment hash of an existing record (default ''). */ public function index($appointment_hash = '') { if (!is_ea_installed()) { @@ -134,15 +134,11 @@ class Appointments extends CI_Controller { /** * Cancel an existing appointment. * - * This method removes an appointment from the company's schedule. - * In order for the appointment to be deleted, the hash string must - * be provided. The customer can only cancel the appointment if the - * edit time period is not over yet. + * This method removes an appointment from the company's schedule. In order for the appointment to be deleted, the + * hash string must be provided. The customer can only cancel the appointment if the edit time period is not over + * yet. Provide the $_POST['cancel_reason'] parameter to describe the cancellation reason. * - * @param string $appointment_hash This is used to distinguish the - * appointment record. - * @param string $_POST['cancel_reason'] The text that describes why - * the customer cancelled the appointment. + * @param string $appointment_hash This is used to distinguish the appointment record. */ public function cancel($appointment_hash) { try { @@ -239,7 +235,7 @@ class Appointments extends CI_Controller { /** * GET an specific appointment book and redirect to the success screen. * - * @param int $appointment_id Contains the id of the appointment to retrieve. + * @param int $appointment_id Contains the ID of the appointment to retrieve. */ public function book_success($appointment_id) { //if the appointment id doesn't exist or zero redirect to index @@ -273,17 +269,19 @@ class Appointments extends CI_Controller { /** * [AJAX] Get the available appointment hours for the given date. * - * This method answers to an AJAX request. It calculates the available hours - * for the given service, provider and date. + * This method answers to an AJAX request. It calculates the available hours for the given service, provider and + * date. * - * @param numeric $_POST['service_id'] The selected service's record id. - * @param numeric|string $_POST['provider_id'] The selected provider's record id, can also be 'any-provider'. - * @param string $_POST['selected_date'] The selected date of which the available hours we want to see. - * @param numeric $_POST['service_duration'] The selected service duration in minutes. - * @param string $_POST['manage_mode'] Contains either 'true' or 'false' and determines the if current user + * Required POST parameters: + * + * - int $_POST['service_id'] Selected service record ID. + * - int|string $_POST['provider_id'] Selected provider record id, can also be 'any-provider'. + * - string $_POST['selected_date'] Selected date for availabilities. + * - int $_POST['service_duration'] Selected service duration in minutes. + * - string $_POST['manage_mode'] Contains either 'true' or 'false' and determines the if current user * is managing an already booked appointment or not. * - * @return Returns a json object with the available hours. + * Outputs a JSON string with the availabilities. */ public function ajax_get_available_hours() { $this->load->model('providers_model'); @@ -341,7 +339,7 @@ class Appointments extends CI_Controller { /** * [AJAX] Register the appointment to the database. * - * @return string Returns a JSON string with the appointment database ID. + * Outputs a JSON string with the appointment ID. */ public function ajax_register_appointment() { try { @@ -482,11 +480,11 @@ class Appointments extends CI_Controller { /** * [AJAX] Get Unavailable Dates * - * Get an array with the available dates of a specific provider, service and month - * of the year. Provide the "provider_id", "service_id" and "selected_date" as GET - * parameters to the request. The "selected_date" parameter must have the Y-m-d format. + * Get an array with the available dates of a specific provider, service and month of the year. Provide the + * "provider_id", "service_id" and "selected_date" as GET parameters to the request. The "selected_date" parameter + * must have the Y-m-d format. * - * @return string Returns a JSON array with the dates that are unavailable. + * Outputs a JSON string with the unavailable dates. that are unavailable. */ public function ajax_get_unavailable_dates() { try { @@ -544,12 +542,12 @@ class Appointments extends CI_Controller { /** * Check whether the provider is still available in the selected appointment date. * - * It might be times where two or more customers select the same appointment date and time. - * This shouldn't be allowed to happen, so one of the two customers will eventually get the - * preferred date and the other one will have to choose for another date. Use this method - * just before the customer confirms the appointment details. If the selected date was taken - * in the mean time, the customer must be prompted to select another time for his appointment. - * + * It might be times where two or more customers select the same appointment date and time. This shouldn't be + * allowed to happen, so one of the two customers will eventually get the preferred date and the other one will have + * to choose for another date. Use this method just before the customer confirms the appointment details. If the + * selected date was taken in the mean time, the customer must be prompted to select another time for his + * appointment. + * * @return bool Returns whether the selected datetime is still available. */ protected function _check_datetime_availability() { @@ -614,20 +612,19 @@ class Appointments extends CI_Controller { /** * Get an array containing the free time periods (start - end) of a selected date. * - * This method is very important because there are many cases where the system needs to - * know when a provider is available for an appointment. This method will return an array - * that belongs to the selected date and contains values that have the start and the end - * time of an available time period. + * This method is very important because there are many cases where the system needs to know when a provider is + * available for an appointment. This method will return an array that belongs to the selected date and contains + * values that have the start and the end time of an available time period. * - * @param numeric $provider_id The provider's record id. - * @param string $selected_date The date to be checked (MySQL formatted string). - * @param array $exclude_appointments This array contains the ids of the appointments that - * will not be taken into consideration when the available time periods are calculated. + * @param int $provider_id Provider record ID. + * @param string $selected_date Date to be checked (MySQL formatted string). + * @param array $exclude_appointments Array containing the IDs of the appointments that will not be taken into + * consideration when the available time periods are calculated. * * @return array Returns an array with the available time periods of the provider. */ protected function _get_provider_available_time_periods($provider_id, $selected_date, - $exclude_appointments = array()) { + $exclude_appointments = array()) { $this->load->model('appointments_model'); $this->load->model('providers_model'); @@ -765,7 +762,7 @@ class Appointments extends CI_Controller { * * This method will return the database ID of the provider with the most available periods. * - * @param numeric $service_id The requested service ID. + * @param int $service_id The requested service ID. * @param string $selected_date The date to be searched. * * @return int Returns the ID of the provider that can provide the service at the selected date. @@ -802,10 +799,10 @@ class Appointments extends CI_Controller { * are broken down to 15 min and if the service fit in each quarter then a new * available hour is added to the "$available_hours" array. * - * @param array $empty_periods Contains the empty periods as generated by the - * "_get_provider_available_time_periods" method. + * @param array $empty_periods Contains the empty periods as generated by the "_get_provider_available_time_periods" + * method. * @param string $selected_date The selected date to be search (format ) - * @param numeric $service_duration The service duration is required for the hour calculation. + * @param int $service_duration The service duration is required for the hour calculation. * @param bool $manage_mode (optional) Whether we are currently on manage mode (editing an existing appointment). * @param string $availabilities_type Optional ('flexible'), the service availabilities type. * diff --git a/src/application/controllers/Backend.php b/src/application/controllers/Backend.php index 7acf5dc5..a501f48a 100644 --- a/src/application/controllers/Backend.php +++ b/src/application/controllers/Backend.php @@ -36,17 +36,18 @@ class Backend extends CI_Controller { /** * Display the main backend page. * - * This method displays the main backend page. All users login permission can - * view this page which displays a calendar with the events of the selected - * provider or service. If a user has more privileges he will see more menus - * at the top of the page. + * This method displays the main backend page. All users login permission can view this page which displays a + * calendar with the events of the selected provider or service. If a user has more privileges he will see more + * menus at the top of the page. * - * @param string $appointment_hash If given, the appointment edit dialog will - * appear when the page loads. + * @param string $appointment_hash Appointment edit dialog will appear when the page loads (default ''). */ public function index($appointment_hash = '') { $this->session->set_userdata('dest_url', site_url('backend')); - if (!$this->_has_privileges(PRIV_APPOINTMENTS)) return; + + if (!$this->_has_privileges(PRIV_APPOINTMENTS)) { + return; + } $this->load->model('appointments_model'); $this->load->model('providers_model'); @@ -70,7 +71,7 @@ class Backend extends CI_Controller { $view['calendar_view'] = $user['settings']['calendar_view']; $this->set_user_data($view); - if ($this->session->userdata('role_slug') == DB_SLUG_SECRETARY) { + if ($this->session->userdata('role_slug') === DB_SLUG_SECRETARY) { $secretary = $this->secretaries_model->get_row($this->session->userdata('user_id')); $view['secretary_providers'] = $secretary['providers']; } else { @@ -78,7 +79,8 @@ class Backend extends CI_Controller { } $results = $this->appointments_model->get_batch(array('hash' => $appointment_hash)); - if ($appointment_hash != '' && count($results) > 0) { + + if ($appointment_hash !== '' && count($results) > 0) { $appointment = $results[0]; $appointment['customer'] = $this->customers_model->get_row($appointment['id_users_customer']); $view['edit_appointment'] = $appointment; // This will display the appointment edit dialog on page load. @@ -98,7 +100,10 @@ class Backend extends CI_Controller { */ public function customers() { $this->session->set_userdata('dest_url', site_url('backend/customers')); - if (!$this->_has_privileges(PRIV_CUSTOMERS)) return; + + if (!$this->_has_privileges(PRIV_CUSTOMERS)) { + return; + } $this->load->model('providers_model'); $this->load->model('customers_model'); @@ -124,15 +129,17 @@ class Backend extends CI_Controller { /** * Displays the backend services page. * - * Here the admin user will be able to organize and create the services - * that the user will be able to book appointments in frontend. + * Here the admin user will be able to organize and create the services that the user will be able to book + * appointments in frontend. * - * NOTICE: The services that each provider is able to service is managed - * from the backend services page. + * NOTICE: The services that each provider is able to service is managed from the backend services page. */ public function services() { $this->session->set_userdata('dest_url', site_url('backend/services')); - if (!$this->_has_privileges(PRIV_SERVICES)) return; + + if (!$this->_has_privileges(PRIV_SERVICES)) { + return; + } $this->load->model('customers_model'); $this->load->model('services_model'); @@ -156,13 +163,15 @@ class Backend extends CI_Controller { /** * Display the backend users page. * - * In this page the admin user will be able to manage the system users. - * By this, we mean the provider, secretary and admin users. This is also - * the page where the admin defines which service can each provider provide. + * In this page the admin user will be able to manage the system users. By this, we mean the provider, secretary and + * admin users. This is also the page where the admin defines which service can each provider provide. */ public function users() { $this->session->set_userdata('dest_url', site_url('backend/users')); - if (!$this->_has_privileges(PRIV_USERS)) return; + + if (!$this->_has_privileges(PRIV_USERS)) { + return; + } $this->load->model('providers_model'); $this->load->model('secretaries_model'); @@ -191,14 +200,16 @@ class Backend extends CI_Controller { /** * Display the user/system settings. * - * This page will display the user settings (name, password etc). If current user is - * an administrator, then he will be able to make change to the current Easy!Appointment - * installation (core settings like company name, book timeout etc). + * This page will display the user settings (name, password etc). If current user is an administrator, then he will + * be able to make change to the current Easy!Appointment installation (core settings like company name, book + * timeout etc). */ public function settings() { $this->session->set_userdata('dest_url', site_url('backend/settings')); if (!$this->_has_privileges(PRIV_SYSTEM_SETTINGS, FALSE) - && !$this->_has_privileges(PRIV_USER_SETTINGS)) return; + && !$this->_has_privileges(PRIV_USER_SETTINGS)) { + return; + } $this->load->model('settings_model'); $this->load->model('user_model'); @@ -222,24 +233,22 @@ class Backend extends CI_Controller { } /** - * Check whether current user is logged in and has the required privileges to - * view a page. + * Check whether current user is logged in and has the required privileges to view a page. * - * The backend page requires different privileges from the users to display pages. Not all - * pages are available to all users. For example secretaries should not be able to edit the - * system users. + * The backend page requires different privileges from the users to display pages. Not all pages are available to + * all users. For example secretaries should not be able to edit the system users. * - * @see Constant Definition In application/config/constants.php + * @see Constant definition in application/config/constants.php. * - * @param string $page This argument must match the roles field names of each section - * (eg "appointments", "users" ...). - * @param bool $redirect (OPTIONAL - TRUE) If the user has not the required privileges - * (either not logged in or insufficient role privileges) then the user will be redirected - * to another page. Set this argument to FALSE when using ajax. + * @param string $page This argument must match the roles field names of each section (eg "appointments", "users" + * ...). + * @param bool $redirect If the user has not the required privileges (either not logged in or insufficient role + * privileges) then the user will be redirected to another page. Set this argument to FALSE when using ajax (default + * true). * - * @return bool Returns whether the user has the required privileges to view the page or - * not. If the user is not logged in then he will be prompted to log in. If he hasn't the - * required privileges then an info message will be displayed. + * @return bool Returns whether the user has the required privileges to view the page or not. If the user is not + * logged in then he will be prompted to log in. If he hasn't the required privileges then an info message will be + * displayed. */ protected function _has_privileges($page, $redirect = TRUE) { // Check if user is logged in. @@ -265,13 +274,13 @@ class Backend extends CI_Controller { } /** - * This method will update the installation to the latest available - * version in the server. IMPORTANT: The code files must exist in the - * server, this method will not fetch any new files but will update + * This method will update the installation to the latest available version in the server. + * + * IMPORTANT: The code files must exist in the server, this method will not fetch any new files but will update * the database schema. * - * This method can be used either by loading the page in the browser - * or by an ajax request. But it will answer with json encoded data. + * This method can be used either by loading the page in the browser or by an ajax request. But it will answer with + * JSON encoded data. */ public function update() { try { diff --git a/src/application/controllers/Backend_api.php b/src/application/controllers/Backend_api.php index f60a0fa9..1b005152 100644 --- a/src/application/controllers/Backend_api.php +++ b/src/application/controllers/Backend_api.php @@ -139,10 +139,12 @@ class Backend_api extends CI_Controller { * This method returns the database appointments and unavailable periods for the * user selected date period and record type (provider or service). * - * @param numeric $_POST['record_id'] Selected record id. - * @param string $_POST['filter_type'] Could be either FILTER_TYPE_PROVIDER or FILTER_TYPE_SERVICE. - * @param string $_POST['start_date'] The user selected start date. - * @param string $_POST['end_date'] The user selected end date. + * Required POST Parameters: + * + * - int $_POST['record_id'] Selected record id. + * - string $_POST['filter_type'] Could be either FILTER_TYPE_PROVIDER or FILTER_TYPE_SERVICE. + * - string $_POST['start_date'] The user selected start date. + * - string $_POST['end_date'] The user selected end date. */ public function ajax_get_calendar_appointments() { try { @@ -206,8 +208,10 @@ class Backend_api extends CI_Controller { /** * [AJAX] Save appointment changes that are made from the backend calendar page. * - * @param array $_POST['appointment_data'] (OPTIONAL) Array with the appointment data. - * @param array $_POST['customer_data'] (OPTIONAL) Array with the customer data. + * Required POST Parameters: + * + * - array $_POST['appointment_data'] (OPTIONAL) Array with the appointment data. + * - array $_POST['customer_data'] (OPTIONAL) Array with the customer data. */ public function ajax_save_appointment() { try { @@ -347,12 +351,13 @@ class Backend_api extends CI_Controller { /** * [AJAX] Delete appointment from the database. * - * This method deletes an existing appointment from the database. Once this - * action is finished it cannot be undone. Notification emails are send to both - * provider and customer and the delete action is executed to the Google Calendar - * account of the provider, if the "google_sync" setting is enabled. + * This method deletes an existing appointment from the database. Once this action is finished it cannot be undone. + * Notification emails are send to both provider and customer and the delete action is executed to the Google + * Calendar account of the provider, if the "google_sync" setting is enabled. * - * @param int $_POST['appointment_id'] The appointment id to be deleted. + * Required POST Parameters: + * + * - int $_POST['appointment_id'] The appointment id to be deleted. */ public function ajax_delete_appointment() { try { @@ -445,11 +450,12 @@ class Backend_api extends CI_Controller { /** * [AJAX] Disable a providers sync setting. * - * This method deletes the "google_sync" and "google_token" settings from the - * database. After that the provider's appointments will be no longer synced - * with google calendar. + * This method deletes the "google_sync" and "google_token" settings from the database. After that the provider's + * appointments will be no longer synced with google calendar. * - * @param string $_POST['provider_id'] The selected provider record id. + * Required POST Parameters: + * + * - string $_POST['provider_id'] The selected provider record id. */ public function ajax_disable_provider_sync() { try { @@ -479,9 +485,11 @@ class Backend_api extends CI_Controller { /** * [AJAX] Filter the customer records with the given key string. * - * @param string $_POST['key'] The filter key string. + * Required POST Parameters: * - * @return array Returns the search results. + * - string $_POST['key'] The filter key string. + * + * Outputs the search results. */ public function ajax_filter_customers() { try { @@ -535,7 +543,9 @@ class Backend_api extends CI_Controller { /** * [AJAX] Insert of update unavailable time period to database. * - * @param array $_POST['unavailable'] JSON encoded array that contains the unavailable period data. + * Required POST Parameters: + * + * - array $_POST['unavailable'] JSON encoded array that contains the unavailable period data. */ public function ajax_save_unavailable() { try { @@ -600,7 +610,9 @@ class Backend_api extends CI_Controller { /** * [AJAX] Delete an unavailable time period from database. * - * @param numeric $_POST['unavailable_id'] Record id to be deleted. + * Required POST Parameters: + * + * - int $_POST['unavailable_id'] Record id to be deleted. */ public function ajax_delete_unavailable() { try { @@ -648,7 +660,9 @@ class Backend_api extends CI_Controller { /** * [AJAX] Save (insert or update) a customer record. * - * @param array $_POST['customer'] JSON encoded array that contains the customer's data. + * Require POST Parameters: + * + * - array $_POST['customer'] JSON encoded array that contains the customer's data. */ public function ajax_save_customer() { try { @@ -677,7 +691,9 @@ class Backend_api extends CI_Controller { /** * [AJAX] Delete customer from database. * - * @param numeric $_POST['customer_id'] Customer record id to be deleted. + * Required POST Parameters: + * + * - int $_POST['customer_id'] Customer record id to be deleted. */ public function ajax_delete_customer() { try { @@ -698,7 +714,9 @@ class Backend_api extends CI_Controller { /** * [AJAX] Save (insert or update) service record. * - * @param array $_POST['service'] Contains the service data (json encoded). + * Required POST Parameters: + * + * - array $_POST['service'] Contains the service data (json encoded). */ public function ajax_save_service() { try { @@ -727,7 +745,9 @@ class Backend_api extends CI_Controller { /** * [AJAX] Delete service record from database. * - * @param numeric $_POST['service_id'] Record id to be deleted. + * Required POST Parameters: + * + * - int $_POST['service_id'] Record id to be deleted. */ public function ajax_delete_service() { try { @@ -748,9 +768,11 @@ class Backend_api extends CI_Controller { /** * [AJAX] Filter service records by given key string. * - * @param string $_POST['key'] Key string used to filter the records. + * Required POST Parameters: * - * @return array Returns a json encoded array back to client. + * - string $_POST['key'] Key string used to filter the records. + * + * Outputs a JSON encoded array back to client. */ public function ajax_filter_services() { try { @@ -776,8 +798,10 @@ class Backend_api extends CI_Controller { /** * [AJAX] Save (insert or update) category record. * - * @param array $_POST['category'] Json encoded array with the category data. If an id - * value is provided then the category is going to be updated instead of inserted. + * Required POST Parameters: + * + * - array $_POST['category'] Json encoded array with the category data. If an ID value is provided then the + * category is going to be updated instead of inserted. */ public function ajax_save_service_category() { try { @@ -806,7 +830,7 @@ class Backend_api extends CI_Controller { /** * [AJAX] Delete category record from database. * - * @param numeric $_POST['category_id'] Record id to be deleted. + * - int $_POST['category_id'] Record id to be deleted. */ public function ajax_delete_service_category() { try { @@ -827,9 +851,11 @@ class Backend_api extends CI_Controller { /** * [AJAX] Filter services categories with key string. * - * @param string $_POST['key'] The key string used to filter the records. + * Required POST Parameters: * - * @return array Returns a json encoded array back to client with the category records. + * - string $_POST['key'] The key string used to filter the records. + * + * Outputs a JSON encoded array back to client with the category records. */ public function ajax_filter_service_categories() { try { @@ -852,9 +878,11 @@ class Backend_api extends CI_Controller { /** * [AJAX] Filter admin records with string key. * - * @param string $_POST['key'] The key string used to filter the records. + * Required POST Parameters: * - * @return array Returns a json encoded array back to client with the admin records. + * - string $_POST['key'] The key string used to filter the records. + * + * Outputs a JSON encoded array back to client with the admin records. */ public function ajax_filter_admins() { try { @@ -882,11 +910,12 @@ class Backend_api extends CI_Controller { /** * [AJAX] Save (insert or update) admin record into database. * - * @param array $_POST['admin'] A json encoded array that contains the admin data. If an 'id' + * Required POST Parameters: + * + * - array $_POST['admin'] A json encoded array that contains the admin data. If an 'id' * value is provided then the record is going to be updated. * - * @return array Returns an array with the operation status and the record id that was - * saved into the database. + * Outputs an array with the operation status and the record id that was saved into the database. */ public function ajax_save_admin() { try { @@ -918,9 +947,11 @@ class Backend_api extends CI_Controller { /** * [AJAX] Delete an admin record from the database. * - * @param numeric $_POST['admin_id'] The id of the record to be deleted. + * Required POST Parameters: * - * @return string Returns the operation result constant (AJAX_SUCCESS or AJAX_FAILURE). + * - int $_POST['admin_id'] The id of the record to be deleted. + * + * Outputs the operation result constant (AJAX_SUCCESS or AJAX_FAILURE). */ public function ajax_delete_admin() { try { @@ -941,9 +972,11 @@ class Backend_api extends CI_Controller { /** * [AJAX] Filter provider records with string key. * - * @param string $_POST['key'] The key string used to filter the records. + * Required POST Parameters: * - * @return array Returns a json encoded array back to client with the provider records. + * - string $_POST['key'] The key string used to filter the records. + * + * Outputs a JSON encoded array back to client with the provider records. */ public function ajax_filter_providers() { try { @@ -971,11 +1004,12 @@ class Backend_api extends CI_Controller { /** * [AJAX] Save (insert or update) a provider record into database. * - * @param array $_POST['provider'] A json encoded array that contains the provider data. If an 'id' + * Required POST Parameters: + * + * - array $_POST['provider'] A json encoded array that contains the provider data. If an 'id' * value is provided then the record is going to be updated. * - * @return string Returns the success constant 'AJAX_SUCCESS' so javascript knows that - * everything completed successfully. + * Outputs the success constant 'AJAX_SUCCESS' so javascript knows that everything completed successfully. */ public function ajax_save_provider() { try { @@ -1012,9 +1046,11 @@ class Backend_api extends CI_Controller { /** * [AJAX] Delete a provider record from the database. * - * @param numeric $_POST['provider_id'] The id of the record to be deleted. + * Required POST Parameters: * - * @return string Returns the operation result constant (AJAX_SUCCESS or AJAX_FAILURE). + * - int $_POST['provider_id'] The id of the record to be deleted. + * + * Outputs the operation result constant (AJAX_SUCCESS or AJAX_FAILURE). */ public function ajax_delete_provider() { try { @@ -1035,9 +1071,11 @@ class Backend_api extends CI_Controller { /** * [AJAX] Filter secretary records with string key. * - * @param string $_POST['key'] The key string used to filter the records. + * Required POST Parameters: * - * @return array Returns a json encoded array back to client with the secretary records. + * - string $_POST['key'] The key string used to filter the records. + * + * Outputs a JSON encoded array back to client with the secretary records. */ public function ajax_filter_secretaries() { try { @@ -1065,11 +1103,12 @@ class Backend_api extends CI_Controller { /** * [AJAX] Save (insert or update) a secretary record into database. * - * @param array $_POST['secretary'] A json encoded array that contains the secretary data. + * Required POST Parameters: + * + * - array $_POST['secretary'] A json encoded array that contains the secretary data. * If an 'id' value is provided then the record is going to be updated. * - * @return string Returns the success constant 'AJAX_SUCCESS' so javascript knows that - * everything completed successfully. + * Outputs the success constant 'AJAX_SUCCESS' so JavaScript knows that everything completed successfully. */ public function ajax_save_secretary() { try { @@ -1099,9 +1138,11 @@ class Backend_api extends CI_Controller { /** * [AJAX] Delete a secretary record from the database. * - * @param numeric $_POST['secretary_id'] The id of the record to be deleted. + * Required POST Parameters: * - * @return string Returns the operation result constant (AJAX_SUCCESS or AJAX_FAILURE). + * - int $_POST['secretary_id'] The id of the record to be deleted. + * + * Outputs the operation result constant (AJAX_SUCCESS or AJAX_FAILURE). */ public function ajax_delete_secretary() { try { @@ -1122,12 +1163,13 @@ class Backend_api extends CI_Controller { /** * [AJAX] Save a setting or multiple settings in the database. * - * This method is used to store settings in the database. It can be either system - * or user settings, one or many. Use the $_POST variables accordingly. + * This method is used to store settings in the database. It can be either system or user settings, one or many. + * Use the $_POST variables accordingly. * - * @param array $_POST['settings'] Contains an array with settings. - * @param bool $_POST['type'] Determines the settings type, can be either SETTINGS_SYSTEM - * or SETTINGS_USER. + * Required POST Parameters: + * + * - array $_POST['settings'] Contains an array with settings. + * - bool $_POST['type'] Determines the settings type, can be either SETTINGS_SYSTEM or SETTINGS_USER. */ public function ajax_save_settings() { try { @@ -1157,8 +1199,10 @@ class Backend_api extends CI_Controller { /** * [AJAX] This method checks whether the username already exists in the database. * - * @param string $_POST['username'] Record's username to validate. - * @param bool $_POST['record_exists'] Whether the record already exists in database. + * Required POST Parameters: + * + * - string $_POST['username'] Record's username to validate. + * - bool $_POST['record_exists'] Whether the record already exists in database. */ public function ajax_validate_username() { try { @@ -1177,10 +1221,11 @@ class Backend_api extends CI_Controller { /** * [AJAX] Change system language for current user. * - * The language setting is stored in session data and retrieved every time the user - * visits any of the system pages. + * The language setting is stored in session data and retrieved every time the user visits any of the system pages. * - * @param string $_POST['language'] Selected language name. + * Required POST Parameters: + * + * - string $_POST['language'] Selected language name. */ public function ajax_change_language() { try { @@ -1193,8 +1238,9 @@ class Backend_api extends CI_Controller { } } - if (!$found) + if (!$found) { throw new Exception('Translations for the given language does not exist (' . $_POST['language'] . ').'); + } $this->session->set_userdata('language', $_POST['language']); $this->config->set_item('language', $_POST['language']); @@ -1211,11 +1257,12 @@ class Backend_api extends CI_Controller { /** * This method will return a list of the available google calendars. * - * The user will need to select a specific calendar from this list to sync his - * appointments with. Google access must be already granted for the specific - * provider. + * The user will need to select a specific calendar from this list to sync his appointments with. Google access must + * be already granted for the specific provider. * - * @param string $_POST['provider_id'] Provider record id. + * Required POST Parameters: + * + * - string $_POST['provider_id'] Provider record id. */ public function ajax_get_google_calendars() { try { @@ -1247,8 +1294,10 @@ class Backend_api extends CI_Controller { * * All the appointments will be synced with this particular calendar. * - * @param numeric $_POST['provider_id'] Provider record id. - * @param string $_POST['calendar_id'] Google calendar's id. + * Required POST Parameters: + * + * - int $_POST['provider_id'] Provider record id. + * - string $_POST['calendar_id'] Google calendar's id. */ public function ajax_select_google_calendar() { try { diff --git a/src/application/controllers/Captcha.php b/src/application/controllers/Captcha.php index c4483884..45c436bf 100644 --- a/src/application/controllers/Captcha.php +++ b/src/application/controllers/Captcha.php @@ -17,7 +17,6 @@ * @package Controllers */ class Captcha extends CI_Controller { - /** * Class Constructor */ diff --git a/src/application/controllers/Errors.php b/src/application/controllers/Errors.php index 27a73c6d..c7fcd65b 100644 --- a/src/application/controllers/Errors.php +++ b/src/application/controllers/Errors.php @@ -22,7 +22,9 @@ class Errors extends CI_Controller { */ public function __construct() { parent::__construct(); + $this->load->library('session'); + // Set user's selected language. if ($this->session->userdata('language')) { $this->config->set_item('language', $this->session->userdata('language')); @@ -32,10 +34,16 @@ class Errors extends CI_Controller { } } + /** + * Display the 404 error page. + */ public function index() { $this->e404(); } + /** + * Display the 404 error page. + */ public function error404() { $this->load->helper('google_analytics'); $this->load->model('settings_model'); diff --git a/src/application/controllers/Google.php b/src/application/controllers/Google.php index 7a463e03..0bdd1bab 100644 --- a/src/application/controllers/Google.php +++ b/src/application/controllers/Google.php @@ -30,9 +30,8 @@ class Google extends CI_Controller { /** * Authorize Google Calendar API usage for a specific provider. * - * Since it is required to follow the web application flow, in order to retrieve - * a refresh token from the Google API service, this method is going to authorize - * the given provider. + * Since it is required to follow the web application flow, in order to retrieve a refresh token from the Google API + * service, this method is going to authorize the given provider. * * @param int $provider_id The provider id, for whom the sync authorization is made. */ @@ -48,16 +47,13 @@ class Google extends CI_Controller { /** * Callback method for the Google Calendar API authorization process. * - * Once the user grants consent with his Google Calendar data usage, the Google - * OAuth service will redirect him back in this page. Here we are going to store - * the refresh token, because this is what will be used to generate access tokens - * in the future. + * Once the user grants consent with his Google Calendar data usage, the Google OAuth service will redirect him back + * in this page. Here we are going to store the refresh token, because this is what will be used to generate access + * tokens in the future. * - * IMPORTANT! Because it is necessary to authorize the application - * using the web server flow (see official documentation of OAuth), every - * Easy!Appointments installation should use its own calendar api key. So in every - * api console account, the "http://path-to-e!a/google/oauth_callback" should be - * included in an allowed redirect url. + * IMPORTANT: Because it is necessary to authorize the application using the web server flow (see official + * documentation of OAuth), every Easy!Appointments installation should use its own calendar api key. So in every + * api console account, the "http://path-to-e!a/google/oauth_callback" should be included in an allowed redirect URL. */ public function oauth_callback() { if (isset($_GET['code'])) { @@ -67,12 +63,9 @@ class Google extends CI_Controller { // Store the token into the database for future reference. if (isset($_SESSION['oauth_provider_id'])) { $this->load->model('providers_model'); - $this->providers_model->set_setting('google_sync', TRUE, - $_SESSION['oauth_provider_id']); - $this->providers_model->set_setting('google_token', $token, - $_SESSION['oauth_provider_id']); - $this->providers_model->set_setting('google_calendar', 'primary', - $_SESSION['oauth_provider_id']); + $this->providers_model->set_setting('google_sync', TRUE, $_SESSION['oauth_provider_id']); + $this->providers_model->set_setting('google_token', $token, $_SESSION['oauth_provider_id']); + $this->providers_model->set_setting('google_calendar', 'primary', $_SESSION['oauth_provider_id']); } else { echo '

Sync provider id not specified!

'; } @@ -84,17 +77,20 @@ class Google extends CI_Controller { /** * Complete synchronization of appointments between Google Calendar and Easy!Appointments. * - * This method will completely sync the appointments of a provider with his Google Calendar - * account. The sync period needs to be relatively small, because a lot of API calls might - * be necessary and this will lead to consuming the Google limit for the Calendar API usage. + * This method will completely sync the appointments of a provider with his Google Calendar account. The sync period + * needs to be relatively small, because a lot of API calls might be necessary and this will lead to consuming the + * Google limit for the Calendar API usage. * - * @param numeric $provider_id Provider record to be synced. + * @param int $provider_id Provider record to be synced. */ public function sync($provider_id = NULL) { try { // The user must be logged in. $this->load->library('session'); - if ($this->session->userdata('user_id') == FALSE) return; + + if ($this->session->userdata('user_id') == FALSE) { + return; + } if ($provider_id === NULL) { throw new Exception('Provider id not specified.'); @@ -110,9 +106,9 @@ class Google extends CI_Controller { // Check whether the selected provider has google sync enabled. $google_sync = $this->providers_model->get_setting('google_sync', $provider['id']); + if (!$google_sync) { - throw new Exception('The selected provider has not the google synchronization ' - . 'setting enabled.'); + throw new Exception('The selected provider has not the google synchronization setting enabled.'); } $google_token = json_decode($this->providers_model->get_setting('google_token', $provider['id'])); @@ -139,8 +135,7 @@ class Google extends CI_Controller { 'company_email' => $this->settings_model->get_setting('company_email') ); - // Sync each appointment with Google Calendar by following the project's sync - // protocol (see documentation). + // Sync each appointment with Google Calendar by following the project's sync protocol (see documentation). foreach($appointments as $appointment) { if ($appointment['is_unavailable'] == FALSE) { $service = $this->services_model->get_row($appointment['id_services']); @@ -214,7 +209,6 @@ class Google extends CI_Controller { } echo json_encode(AJAX_SUCCESS); - } catch(Exception $exc) { echo json_encode(array( 'exceptions' => array(exceptionToJavaScript($exc)) diff --git a/src/application/controllers/Installation.php b/src/application/controllers/Installation.php index 0c4baadf..a09a483c 100644 --- a/src/application/controllers/Installation.php +++ b/src/application/controllers/Installation.php @@ -53,9 +53,10 @@ class Installation extends CI_Controller { /** * [AJAX] Installs Easy!Appointments on the server. * - * @param array $_POST['admin'] Contains the initial admin user data. The App needs at - * least one admin user to work. - * @param array $_POST['company'] Contains the basic company data. + * Required POST Parameters + * + * - array $_POST['admin'] Contains the initial admin user data. The App needs at least one admin user to work. + * - array $_POST['company'] Contains the basic company data. */ public function ajax_install() { try { diff --git a/src/application/controllers/User.php b/src/application/controllers/User.php index ee4ec396..f8e16ba7 100644 --- a/src/application/controllers/User.php +++ b/src/application/controllers/User.php @@ -135,8 +135,10 @@ class User extends CI_Controller { * Regenerate a new password for the current user, only if the username and * email address given correspond to an existing user in db. * - * @param string $_POST['username'] - * @param string $_POST['email'] + * Required POST Parameters: + * + * - string $_POST['username'] Username to be validated. + * - string $_POST['email'] Email to be validated. */ public function ajax_forgot_password() { try { diff --git a/src/application/controllers/api/v1/Availabilities.php b/src/application/controllers/api/v1/Availabilities.php index 88ae3dde..c5d50cb6 100644 --- a/src/application/controllers/api/v1/Availabilities.php +++ b/src/application/controllers/api/v1/Availabilities.php @@ -81,7 +81,7 @@ class Availabilities extends API_V1_Controller { * that belongs to the selected date and contains values that have the start and the end * time of an available time period. * - * @param numeric $provider_id The provider's record id. + * @param int $provider_id The provider's record id. * @param string $selected_date The date to be checked (MySQL formatted string). * @param array $exclude_appointments This array contains the ids of the appointments that * will not be taken into consideration when the available time periods are calculated. @@ -232,7 +232,7 @@ class Availabilities extends API_V1_Controller { * @param array $empty_periods Contains the empty periods as generated by the * "_getProviderAvailableTimePeriods" method. * @param string $selected_date The selected date to be search (format ) - * @param numeric $service_duration The service duration is required for the hour calculation. + * @param int $service_duration The service duration is required for the hour calculation. * @param bool $manage_mode (optional) Whether we are currently on manage mode (editing an existing appointment). * @param string $availabilities_type Optional ('flexible'), the service availabilities type. *