Skip to content

Developing

Jump to bottom Edit New page
tenzap edited this page Mar 18, 2022 · 4 revisions

Kalkun is written in PHP, uses the CodeIgniter Framework and follow the MVC (Model-View-Controller) pattern. It makes use of jQuery.

Reading suggestions

Architecture

General architecture is as follows:

╔════════╗   ╔═══════════╗   ╔════════════╗   ╔═════════════╗
║ Kalkun ║ ⟷ ║ DB Engine ║ ⟷ ║ Gammu-SMSD ║ ⟷ ║ Phone/Modem ║
╚════════╝   ╚═══════════╝   ╚════════════╝   ╚═════════════╝

Set the CodeIgnitter Environment

To see the errors (PHP, CodeIgniter, Database...) you will have to enable it. This can be done with the CI_ENV environment variable of your web server configuration. By default we left it to development. In that case there errors are reported. They are not reported if this value is set to testing or development. Double check the value that is set for you.

For example, if your web server is Apache, set the CI_ENV variable in the .htaccess file.

More details in the CodeIgniter documentation.

I18n guidelines

Kalkun uses the MessageFormatter class for format messages that are displayed to the user. This is handy when it comes about translating parametrized strings. That's why Kalkun doesn't use the lang() function of CodeIgniter directly but wraps it into a call to tr()

When you want to output a label in the PHP source code, please enclose it in a call to the tr(...). This function is defined in the i18n_helper.php which is usually already loaded. It applies htmlentities() to the labels. In some rare cases you may prefer to no have the label escaped by htmlentities. You can then use tr_raw() instead.

Note that if this PHP call is made for output in a javascript file or in the javascript part of a HTML document, quoting is handled differently. In that case, call tr_js() instead of tr(). This will escape the characters usually escaped in JSON + the HTML entities. It returns a JSON encoded string. So it is already quoted. As a consequence, you should not quote it again. See example below.

Example

  • To load the i18n helper (usually you don't need to do it as it is already loaded in most cases)
$this->load->helper('i18n');
  • To get the translated label
tr('Folders');
  • If you are in javascript. (Note that is not enclosed in quotes. This is because tr_js returns a JSON encoded string that is already quoted).
var my_variable = <?php echo tr_js('Folders') ?>;
  • In the language file, for Folders there is:
$lang['Folders'] = 'Mappen';
  • As a side note, there is a third function:
tr_addcslashes('"', 'Folders');

Profile of the tr(), tr_raw() & tr_js() functions

  • 1st parameter: Label as it will be displayed in english
  • 2nd parameter (optional): a context that permits to differenciate between same labels in english but with a different meaning or usage. So they might be translated differently in other languages. This is never rendered on screen. It is just used for translation identification purposes.
  • as many additional parameters as needed. They are used as values for the placeholders used in the original label. See MessageFormatter class for

For example:

tr('{0} character(s) / {1} message(s)', NULL, 350, 5);

Will output:

350 character(s) / 5 message(s)

Profile of the tr_addcslashes() function

  • Same as for tr() except we add an additional parameter before the 1st one. Its value is the character to escape.
  • For example, if you quote text with " in js, put this character as value of that new parameter. See example above.

Pull request checklist

  • For any change to the database schema, do the change for all three DB backends: MySQL, PostreSQL & SQLite3
  • Use CI3's form_open() & form_close() instead of the HTML <form> tag. Otherwise you will break CSRF protection.
  • Properly mitigate for XSS attacks. More info in the Cross Site Scripting Prevention Cheat Sheet:
    • In HTML & PHP, especially in the views, be sure to escape the html entities to protect again XSS attacks. Do it this way:
    echo htmlentities($value_to_display, ENT_QUOTES);
    • Same applies for JS. Be sure to properly escape the code to protect again XSS attacks. Use the json_protect() function of Kalkun this way:
    echo json_protect($value_to_insert_in_js);
  • Add the labels in the translation files (you may run the utils/check_translation.php script or see the result in the job that runs on the PR)
  • Check that the code respects the coding style (you may run the utils/fix_code_style.sh script or see the result in the job that runs on the PR)

Database schema

Current app version is 0.3 Current schema version is 0.2.10

Kalkun use gammu-smsd database schema with some additional tables and fields to suit the application.

Database schema - 0.2.10

Tables with orange mark is derived from gammu-smsd tables. To learn description for each table see SMSD Database Structure. Tables with blue mark is kalkun original tables.

Additional fields

inbox

  • id_folder
  • readed

sentitems

  • id_folder

pbk

  • id_user

pbk_groups

  • id_user

Table description

  • user - Information about user (username, password, phone number, level)
  • user_settings - User preferences (language, paging, delivery report, etc)
  • user_inbox - User permission for inbox
  • user_outbox - User permission for outbox
  • user_sentitems - User permission for sentitems
  • user_folders - Custom user folders to archive SMS
  • sms_used - Track SMS used by user based on date
  • member - Save registered member, only used if SMS Member enabled
  • user_group - Table to handle multiple group value on phonebook

Please note that tables relationship is handled by application coding, not database.

Version numbering guidelines

Follow these guidelines for version numbering.

These are to keep the order of version number correct in github release page (especially for -beta-X version), and in Debian packages (especially for -dev version).

Version numbering is set in application/config/kalkun_settings.php.

When tagging a commit for a release:

  • Remove the -dev suffix. You may also increase the version number.
  • Set the version application/config/kalkun_settings.php (without leading v. Eg. 0.8.0-beta-1) on devel branch.
  • Then merge all changes from devel branch to master branch.
  • Then create the tag on the master branch with the leading v (eg. v0.8.0-beta-1)
  • Immediately, update the version in application/config/kalkun_settings.php to a newer version and add the -dev suffix.
  • Commit and push the master & devel branch, and the tags.
  • A release will be created automatically by a Github Actions job. (triggered by the tag event)

For the version number in application/config/kalkun_settings.php follow the order as defined in Debian comparison rules. To make it simple and with examples you may do it this way. Don't go from -dev to -beta (because -dev is considered higher than -beta), but from X.X.X-dev to X.X.X. X.X.X is considered higher than X.X.X-dev. X.X.X is also higher than X.X.

Don't use beta9 → beta10 because in Gihub, beta10 is considered lower than beta9. So we do beta-9, then beta-10

A correct scheme would be:

From 0.7.1          --> TAG on master
Then 0.8-alpha-dev  --> on devel
Then 0.8-alpha      --> TAG on master
Then 0.8-beta-1-dev --> on devel
Then 0.8-beta-1     --> TAG on master
Then 0.8-beta-2-dev --> on devel
Then 0.8-beta-2     --> TAG on master
Then 0.8-rc-1-dev   --> on devel
Then 0.8-rc-1       --> TAG on master
Then 0.8            --> TAG on master

As for 0.8 we used 0.8-dev, we can't then pass to 0.8-beta which would be lower, so we go with 0.8.0-beta. We use this order which respects version ordering.

Kalkun version       Debian equivalent version
0.8-dev           →  0.8~dev
0.8.0-beta-1      →  0.8.0~beta~1
0.8.0-beta-2-dev  →  0.8.0~beta~2~dev
0.8.0-beta-2      →  0.8.0~beta~2
0.8.0-rc-1-dev    →  0.8.0~rc~1~dev
0.8.0             →  0.8.0

Extracts from debian comparison rule

Ref: Debian comparison rules

The strings are compared from left to right.

First the initial part of each string consisting entirely of non-digit characters is determined. These two parts (one of which may be empty) are compared lexically. If a difference is found it is returned. The lexical comparison is a comparison of ASCII values modified so that all the letters sort earlier than all the non-letters and so that a tilde sorts before anything, even the end of a part. For example, the following parts are in sorted order from earliest to latest: ~~, ~~a, ~, the empty part, a.

Then the initial part of the remainder of each string which consists entirely of digit characters is determined. The numerical values of these two parts are compared, and any difference found is returned as the result of the comparison. For these purposes an empty string (which can only occur at the end of one or both version strings being compared) counts as zero.

These two steps (comparing and removing initial non-digit strings and initial digit strings) are repeated until a difference is found or both strings are exhausted.

That's why in the debian package, we replace - by ~ in the version number. So that 0.8.0 is considered newer than 0.8.0-beta-1.

Add a custom footer
Clone this wiki locally