Dolphin 8: new programming approaches

Dolphin 8 has new programming approaches which all Dolphin programmers must follow. This is an extension of the existing Dolphin coding convention, most of the old rules still apply and new ones are added. I'm publishing it as early as possible, so you can start adjusting your code from now to comply with new standards. I believe that it will help everyone to write more secure and easy to read code.

Small programming remarks

1. Get rid of short php tag.
2. Get rid of closing php tag at the end of file.
3. Change license text in the beginning of php file.
4. Make sure that all classes are inherited from BxDol (there is no BxDolMistake class now).
5. Make sure that parent class is called in the constructor.
6. Remove any require_once, replace with bx_import. Don't use require_once at all - the only place you can use in the files like index.php, faq.php, etc - the files which are actually displayed in the browser.
7. Use bx_import in the beginning of the file if class is used in all cases, for example in the constructor. If class is used sometimes and not often, then place bx_import inline.
8. Always set error reporting to E_ALL and get rid of any warnings and even notices.
9. Check for BX_DOL define in all "include" files, to prevent direct execution.
10. Replace RSSAggrCont html with BxTemplFunctions::getInstance()->getRssHolder.
11. Use BxTemplPaginate instead of BxDolPaginate.
12. Get rid of GLOBALS['some object'], remake to Class::getInstance or bx_instance() call.
13. Use BxDolProfileQuery for all SQL queries related to basic profiles functionality, if there is no suitable function there, create one, hold on here for a while.
14. Remove bx_import('BxDolAlerts'); This class is imported in header.inc.php and available everywhere.
15. Don't use $_page and $_page_cont global variables, use template class with appropriate functions instead.
16. Use only predefined constants for name_index(PageNameIndex).
17. Add more classes to templates folder, to allow to customise it in custom template.

Singleton for one instance classes

Implement singleton interface for the following classes (change new Class() to Class::getInstance):

BxDolSubscriptions
BxDolPermalinks
BxTmplMenu
BxTmplFunctions
BxTemplConfig
BxDolTemplate
BxDolTemplateAdmin
BxDolModuleDb (or remake it BxDolService at least)   
BxDolDb
BxDolParams
BxDolProfileQuery

more is coming... feel free to ask and add

Common design element in user and studio parts

All classes which are used in user and studio parts need Template parameter in constructor to pass the right template object.

The following classes are already changed and call to this functions need to be changed, where needed. In user part template object can be detected by default, but in admin part Template object need to be passes explicitly

BxTemplForm
BxTemplPaginate

more is coming... feel free to ask and add

Database queries and data filtering

Get rid of process_db_input, process_pass_data and BxDolDb::unescape functions !

• to validate user input always use bx_process_input
• to save data to database always use db prepare statements
• to output data always use bx_process_output

apply above approach to any user data - GET, POST, REQUEST, COOKIE, or any other sources of untrusted data!

always use the same data type for the same data in both function bx_process_input and bx_process_output

Call BxDolDb::prepare function in particular db class function for your functionality. If there is no such class - create it, every piece of code should have SQL queries in separate class.

Sample db classes are:

BxDolSessionQuery for BxDolSession
BxDolVotingQuery for BxDolVoting

Don't call BxDolDb::prepare function in the code, use it only in db class function just before executing the query. If it is impossible or totally inconvenient to use "prepare" function (for example BxDolSessionQuery::save), then use bxDolDb::escape function.

Don't call bx_process_input and/or bx_process_output in db class function, call these function in the code. It is better to call bx_process_input function as earlier as possible, before using any user/untrusted input.

It is better to call bx_process_output function as late as possible, just before printing it out. Don't forget about other functions for output:

bx_js_string
bx_html_attribute

Code commenting

There is separate post for this

Templates

• Fugue icons only, don't change original names from the set !
• Use default styles as much as possible, add them as additional class, refer to default.css for the whole list:
  1. colors - use predefined styles from default.css for all colors:
     * page background
     * block background
     * form background
     
  2. margin/padding
  3. border
  4. font
• Predefined styles for all looks alike elements, like thumbs, etc
• Validate HTML/CSS for every page (in Web Developer Firefox toolbar: Tools -> Validate *)
• Write css with the following order:
  1. positioning (display, float, clear, visibility, position, top, right, bottom, left, z-index, etc)
  2. size (width, height, overflow, padding, margin, etc)
  3. border (border, outline, etc)
  4. colors (opacity, background*)
  5. font (font-*, text-*, line-height, white-space, vertical-align, color, etc)
  6. others (list-style, cursor, etc)
• css classes and ids must be named as following:
  bx-* - system css classes and ids
  bx-pre-* - module css classes and ids
  if there are several classes for some particular functionality, add some prefix for it too, for example all comments classes should have classes and ids with the following prefix bx-cmts-*

EDITOR

• Editor must use \n symbol as new line.
• Editor must insert spaces when tab is pressed.
• Tab must be set as 4 spaces.

Changelog: - 2011-06-14: documentation block is moved to separate post and heavily extended