USERCOLOR: manages user's color. More...

Functions
	get_usercolor ($t_conn_res)
	Returns the UI color data inside the 'data' property of an array. More...

	post_usercolor ($t_conn_res)
	Set's the new UI color passed by the client. More...

Variables
	$response = array('errors' => array())
	Prepare default response array with no errors. More...

Detailed Description

USERCOLOR: manages user's color.

Client perspective:

GET METHOD --> returns user color
POST METHOD --> retrieves user color

Description

This script sets the returned content type to JSON, includes the db_connection.php script

It is used to connect to MySQL and execute basic SELECT queries

and then defines the response array.

Two functions are defined:

get_usercolor($t_conn_res)

Selects the user color from the database so that the script can echo it

post_usercolor($t_conn_res)

Sets the user color inside the options table (colors param must be passed)

If the script isn't included it tries to connect to the database, and checks the request method:

if the method is GET it calls get_usercolor($t_conn_res)
if the method is POST it calls post_usercolor($t_conn_res)

When the called function ends the connection to the DB gets terminated, and data (or errors) is collected inside the response array. The response array gets echoed to the client in JSON format

Errors list:

200 - main: Method not supported by the target resource
201 - main: No data but also No errors
210 - get_usercolor(): The query returned an unexpected number of records
211 - get_usercolor(): Error during query execution
220 - post_usercolor(): Unable to change the current color for the new one (the user sent the current color or a non existing one)
221 - post_usercolor(): Unable to execute UPDATE query (query error)
222 - post_usercolor(): Parameter 'color' wasn't set"

Since: 01_01

Author: Stefano Zenaro (https://github.com/mario33881)

Copyright: MIT

Function Documentation

◆ get_usercolor()

get_usercolor ( $t_conn_res )

Returns the UI color data inside the 'data' property of an array.

The function, using the mysqli object inside the parameter $t_conn_res ($t_conn_res['connect_obj']), executes the query '$query' which collects the color previously selected by the user.

There is always a value (the default one is 'red').

If the query execution throws an error the error is collected inside the 'errors' property of the array (which is also an array). The errors inside the 'errors' array have three properties:

id: identifies the error, it is useful for the frontend
htmlcode: it is the status code of the response that will be given to the client
message: details of the error

the message is in english, language translation is going to be managed from the frontend

The user's color data is an array and is structured as following:

id: identification number from the database
color_name: name of the color
color_hex: hexadecimal value of the color

format of color_hex:
#RRGGBB

Example with no errors

GET /api/colors/usercolor.php
{
  "errors": [],
  "data": {
      "id": "4384",
      "color_name": "red",
      "color_hex": "#f44336"
  }
}

If there are errors they will be pushed inside the errors array. Possible returned errors:

210: The query returned an unexpected number of records
211: Error during query execution

Since: 01_01

Parameters

array $t_conn_res array with the connection object (connection was successful)

Returns: array $action_res array with color data or errors

◆ post_usercolor()

post_usercolor ( $t_conn_res )

Set's the new UI color passed by the client.

The function checks if a POST parameter called 'color' was passed, if so it executes the query that makes sure that the color exists inside the colors table and modifies the set color inside the options table. For last it checks if the query modified one row (as expected) and returns the color inside the 'data' property of the returned array.

Example with no errors

POST /api/colors/usercolor.php (color=red)
{
  "errors": [],
  "data": "red"
}

If there are errors they will be pushed inside the errors array. Possible returned errors:

220: Unable to change the current color for the new one (the user sent the current color or a non existing one)
221: Unable to execute UPDATE query (query error)
222: Parameter 'color' wasn't set"

The errors inside the 'errors' array have three properties:

id: identifies the error, it is useful for the frontend
htmlcode: it is the status code of the response that will be given to the client
message: details of the error

the message is in english, language translation is going to be managed from the frontend

Since: 01_01

Parameters

array $t_conn_res array with the connection object

Returns: array $action_res array with color data or errors

Variable Documentation

◆ $response

$response = array('errors' => array())

Prepare default response array with no errors.

Functions