CONTRIBUTING.md 4.19 KB
Newer Older
Till Brehm's avatar
Till Brehm committed
1 2 3 4
# Which code branch to use

The master branch is used for code (mostly new features) that shall go into the next major release (e.g. 3.2, 3.3 and so on). The stable branch (e.g. stable-3.1, stable-3.2) is the branch for the current intermediate and bugfix releases. Bugfixes shall be committed to the current stable branch and not the master branch. The stable branch is merged to the master automatically from time to time, please do not submit bugfixes a second time against the master.

5
# Some guidelines for web development with php.
6
-----------------------------------------------------
7
* Unix Line Breaks Only, NO windows breaks please.
8
* Tabs to indent lines, NO spaces
9
* no accidental _<?php space before, within or after a file
10 11
* every PHP file starts and end with <?php ?> no spaces before or after
* error_reporting(E_ALL|E_STRICT), yep PHP 5
12
* Magic quotes is gone, get used to it now. config = magic_quotes_gpc() Everything must be quoted
13 14
* Don't use ereg, split and other old function -> gone in PHP 5.4
* Don't use features that are not supported in PHP 5.3, for compatibility with LTS OS releases, ISPConfig must support PHP 5.3+
15
* Don't use shorttags. A Shorttag is <? and that is confusing with <?xml -> always usw <?php
16
* Don't use namespaces
tbrehm's avatar
tbrehm committed
17 18 19
* Column names in database tables and database table names are in lowercase
* Classes for the interface are located in interface/lib/classes/ and loaded with $app->uses() or $app->load() functions.
* Classes for the server are located in server/lib/classes/ and loaded with $app->uses() or $app->load() functions.
20
* please mark any section that need review or work on with /* TODO: short description */
21
* Make function / var names on the following way, first word lower, next word(s) first letter upper like. getFirstResult();
22
* always a space but NO newline before opening braces, e. g.
Marius Burkard's avatar
Marius Burkard committed
23
```
24 25 26 27 28 29 30
class abc {
	public function cde() {
		if($a == $b) {
			return false;
		}
	}
}
Marius Burkard's avatar
Marius Burkard committed
31
```
32
* no spaces after function/method or control names, e. g.
Marius Burkard's avatar
Marius Burkard committed
33
```
34 35 36 37 38
function abc($x, $y) {
	if($condition == true) {
		$x = 2;
	}
}
Marius Burkard's avatar
Marius Burkard committed
39
```
40
and NOT
Marius Burkard's avatar
Marius Burkard committed
41
```
42 43 44 45 46
function abc ($x, $y) {
	if ( $condition == true ) {
	
	}
}
Marius Burkard's avatar
Marius Burkard committed
47
```
48

Marius Burkard's avatar
Marius Burkard committed
49
# Commenting style
50 51

The comments break down into the following types
Marius Burkard's avatar
Marius Burkard committed
52
```
53 54
// is uses for removing lines and debug dev etc
/* 
55
	is used to comment out blocks
56
*/
57

58
/** is used to create documentaion
59 60 61
 * thats over 
 * lines
 */
Marius Burkard's avatar
Marius Burkard committed
62
```
63
If you need to block out a section then use
Marius Burkard's avatar
Marius Burkard committed
64
```
65 66
/*
function redundant_code(){
67
	something here
68 69
}
*/
Marius Burkard's avatar
Marius Burkard committed
70
```
71 72 73 74 75
To block out single lines use // and all // are assumed to be redundant test code and NOT comments

// print_r($foo);

Do not use the phpdoc on every function, eg 
Marius Burkard's avatar
Marius Burkard committed
76
```
77
/**
78
* Login a user
79 80 81 82
* @param string user  username
* @param string password of user
*/
function login($user, $pass){
83
	
84
}
Marius Burkard's avatar
Marius Burkard committed
85
```
86
as this function is self-explaining, the following clean code will suffice
Marius Burkard's avatar
Marius Burkard committed
87
```
88
function login($user, $pass){
89
	
90
}
Marius Burkard's avatar
Marius Burkard committed
91
```
92

Marius Burkard's avatar
Marius Burkard committed
93
# Where to store custom settings
94

Marius Burkard's avatar
Marius Burkard committed
95
## Interface settings
96 97 98 99 100

The recommended place to store global interface settings is the ini style global config system 
(see system.ini.master file in install/tpl/ to set defaults). The settings file 
gets stored inside the ispconfig database. Settings can be accessed with the function:

Marius Burkard's avatar
Marius Burkard committed
101
```
102 103
$app->uses('ini_parser,getconf');
$interface_settings = $app->getconf->get_global_config('modulename');
Marius Burkard's avatar
Marius Burkard committed
104
```
105 106 107 108 109 110

where modulename corresponds to the config section in the system.ini.master file.
To make the settings editable under System > interface config, add the new configuration
fields to the file interface/web/admin/form/system_config.tform.php and the corresponding
tempalte file in the templates subfolder of the admin module.

Marius Burkard's avatar
Marius Burkard committed
111
## Server settings
112 113 114 115 116 117 118

Server settings are stored in the ini style server config system (see server.ini.master template file)
The settings file gets stored inside the ispconfig database in the server table. Settings can be 
accessed with the function $app->getconf->get_server_config(....)

Example to access the web configuration:

Marius Burkard's avatar
Marius Burkard committed
119
```
120 121
$app->uses('ini_parser,getconf');
$web_config = $app->getconf->get_server_config($server_id,'web');
Marius Burkard's avatar
Marius Burkard committed
122
```
123

Marius Burkard's avatar
Marius Burkard committed
124
# Learn about the form validators
125 126
There are form validators in interface/lib/classes/tform.inc.php to make validating forms easier.
Read about: REGEX,UNIQUE,NOTEMPTY,ISEMAIL,ISINT,ISPOSITIVE,ISIPV4,CUSTOM