FishEye: file osCommerce/tags/oscommerce-2.2ms2-20051113/STANDARD

Annotated File View

hpdl	477	1	$Id: STANDARD,v 1.13 2003/06/09 21:13:13 hpdl Exp $
		2
		3	osCommerce Coding Standards
		4
		5	Coding standards are defined to keep the codebase in a maintainable state.
		6
		7	The more developers working within the codebase means the more ways php
		8	logic can be written.
		9
		10	If every developer follows the standards then everyone is able to review
		11	the codebase and not waste time thinking about why a certain style was
		12	used in a particular area compared to another area.
		13
		14	File Format
		15	-----------
		16
		17	The source code should be saved in Unix format - meaning with Unix
		18	linefeeds.
		19
		20	Most editors are able to set the preferred format method of Windows,
		21	Unix, or Macintosh.
		22
		23	Some editors add a line to the bottom of the file. This is safe to have
		24	as long as a further character (including the space character) does not
		25	exist. Characters that exist at the end of the file may interfer when
		26	redirections occur as text has been sent to the client already.
		27
		28	The filename of the files must be all lowercass characters and contain
		29	no more than 31 characters to be Apple/Mac compatible.
		30
		31	Indentation
		32	-----------
		33
		34	Indentation of logic should be 2 whitespace characters.
		35
		36	TABs should not be used.
		37
		38	Starting and Ending PHP Logic
		39	-----------------------------
		40
		41	When starting PHP logic, the tag should be written as "<?php", not in the
		42	short form of "<?" or in ASP compatible tags such as "<%".
		43
		44	The end tag to mark the end of the PHP logic should be written as "?>".
		45
		46	A valid example:
		47
		48	<?php
		49	echo "Hello World!";
		50	?>
		51
		52	Defining Constants
		53	------------------
		54
		55	Constants must be defined before they are being used - which also includes
		56	constants called from include()'d/require()'d files.
		57
		58	Variable Scope*
		59	--------------
		60
		61	All variables must be accessed and set within their scope as:
		62
		63	$HTTP_GET_VARS['variable']
		64	$HTTP_POST_VARS['variable']
65	$HTTP_COOKIE_VARS['variable']
66	$variable (either local, or session)
67
68	* This needs to be updated when the codebase has been made compatible with
69	the register_global parameter. Session variables are then accessed and set
70	within its scope as:
71
72	$HTTP_SESSION_VARS['variable']
73
74	When PHP3 support is dropped, the following scope will be used:
75
76	$_GET['variable']
77	$_POST['variable']
78	$_COOKIE['variable']
79	$_SESSION['variable']
80
81	PHP 4.0.x does not support the above scope which was introduced in PHP 4.1.x.
82	The following can be used which is not compatible with PHP 3.x:
83
84	$_GET =& $HTTP_GET_VARS;
85	$_POST =& $HTTP_POST_VARS;
86	$_COOKIE =& $HTTP_COOKIE_VARS;
87	$_SESSION =& $HTTP_SESSION_VARS;
88
89	include() vs require()
90	----------------------
91
92	The use of include() will include the specified file when needed, whereas
93	the use of require() will always include the specified file regardless if it
94	is needed or not.
95
96	Example:
97
98	<?php
99	require('file.php');
100
101	if (condition == true) {
102	include('file_true.php');
103	} else {
104	...
105	}
106	?>
107
108	Instantiating Classes
109	---------------------
110
111	When instantiating classes into objects, the following style must be used:
112
113	<?php
114	// without class parameters*
115	$object = new className;
116
117	// with class parameters
118	$object = new className($parameter1);
119	?>
120
121	* PHP3 does not support the following style which includes an empty bracket
122	set:
123
124	<?php
125	$object = new className();
126	?>
127
128	Displaying Strings
129	------------------
130
131	Strings or values should be displayed as:
132
133	<?php
134	echo 'Hello Mr Mister!';
135	?>
136
137	The following styles should be avoided:
138
139	<?php
140	print $variable;
141	?>
142
143	<?=$variable;?>
144
145	Singe-Quotes vs Double-Quotes
146	-----------------------------
147
148	When displaying strings single quote characters should be used.
149
150	Double quote characters should be used only when control characters are
151	needed.
152
153	For example:
154
155	<?php
156	echo 'Hello Mr Mister!' . "\n";
157	?>
158
159
160	Custom Functions
161	----------------
162
163	All custom functions should start with tep_ so that the developer knows
164	a native PHP function is not being called.*
165
166	An example custom function style:
167
168	<?php
169	function tep_my_function($parameter, $optional = '') {
170	global $HTTP_GET_VARS, $another_variable;
171
172	....
173
174	return true;
175	}
176	?>
177
178	* When 2.2 is finalized the custom functions should be renamed to osc_*
179	as "tep" refers to the previous name of the project.
180
181	Class Names
182	-----------
183
184	There are two types of styles to use when classes are used.
185
186	The first type of class set are the static classes that can be found in
187	the includes/classes directory.
188
189	If the class name contains more than one word, the words in the filename
190	are separated with an underscore character. The actual class name is one
191	whole word where words from the second onwards being capitalized.
192
193	For example, a class name of myOwnClass has a filename of
194	my_own_class.php.
195
196	The second type of class set are the dynamic modules that can be found
197	in the includes/modules/* directories.
198
199	The class names must match the filename as most of them are include()'d
200	dynamicly.
201
202	For example, a class filename of my_own_module.php has a class name of
203	my_own_module.
204
205	Class Structure
206	---------------
207
208	The class should be written in the following structure:
209
210	<?php
211	class myclass {
212	var $variable;
213
214	// class constuctor
215	function myclass() {
216
217	....
218
219	return true;
220	}
221
222	// class methods
223	function do_something() {
224
225	$this->variable = 'set';
226
227	return true;
228	}
229	}
230
231	$class = new myclass;
232	$class->do_something();
233	?>
234
235	Database Queries
236	----------------
237
238	Database queries are wrapped around custom functions and should be
239	structured as:
240
241	<?php
242	// multi-result set
243	$action_query = tep_db_query("select column1, ...");
244	while ($action = tep_db_fetch_array($action_query)) {
245	echo $action['column1'];
246	}
247
248	// single result set
249	$action_query = tep_db_query("select column1, ...");
250	$action = tep_db_fetch_array($action_query);
251
252	echo $action['column1'];
253
254	// return number of rows
255	$action_query = tep_db_query("select count(*) as total from ...");
256	$action = tep_db_fetch_array($action_query);
257
258	echo $action['total'];
259
260	// query with parameters
261	$action_query = tep_db_query("select column1 from table where field = '" . tep_db_input($some_id) . "'");
262	while ($action = tep_db_fetch_array($action_query)) {
263	....
264	}
265	?>
266
267	Unlike displaying strings, double quote characters are wrapped around the sql query.
268
269	The following is currently for the Administration Tool but will also be implemented
270	in the Catalog module.
271
272	Before data can be entered in the database, it must be protected against possible
273	attacks residing in the user input. The data is first prepared and then protected
274	when inserting it into the table. The following structure is used:
275
276	<?php
277	$value1 = tep_db_prepare_input($HTTP_POST_VARS['value1']);
278
279	tep_db_query("update table set column = '" . tep_db_input($value1) . "' where id = '" . (int)$id . "'");
280	?>
281
282	Variable type casting should be performed directly for integer based values, such
283	as column IDs: (int)$variable
284
285	Multiple values can be parsed, protected and inserted into the table in an easier
286	fashion:
287
288	<?php
289	$value1 = tep_db_prepare_input($HTTP_POST_VARS['value1']);
290	$value2 = tep_db_prepare_input($HTTP_POST_VARS['value2']);
291	$value3 = tep_db_prepare_input($HTTP_POST_VARS['value3']);
292
293	$sql_data_array = array('column1' => $value1,
294	'column2' => $value2,
295	'column3' => $value3);
296
297	tep_db_perform('table', $sql_data_array);
298	?>
299
300	A similar structure can be used for updating values in a table:
301
302	<?php
303	$value1 = tep_db_prepare_input($HTTP_POST_VARS['value1']);
304	$value2 = tep_db_prepare_input($HTTP_POST_VARS['value2']);
305	$value3 = tep_db_prepare_input($HTTP_POST_VARS['value3']);
306
307	$sql_data_array = array('column1' => $value1,
308	'column2' => $value2,
309	'column3' => $value3);
310
311	tep_db_perform('table', $sql_data_array, 'update', "id = '" . (int)$id . "'");
312	?>
313
314	Table names should not directly be entered in the query, but the constant
315	parameter assigned to that table. A list of defined constant table names
316	can currently be found in includes/database_tables.php.
317
318	Function Output
319	---------------
320
321	All custom functions should return strings; not directly via echo().
322
323	For example:
324
325	<?php
326	function tep_my_function($string) {
327	return $string;
328	}
329	?>
330
331	and not:
332
333	<?php
334	function tep_my_function($string) {
335	echo $string;
336	}
337	?>
338
339	Condition Statements
340	--------------------
341
342	If statements should be written as:
343
344	<?php
345	if (condition == true) {
346	....
347	} else {
348	....
349	}
350	?>
351
352	If the condition is to check for a boolean value, this should be added
353	to the condition (as above) for clarity.
354
355	The following should not be used:
356
357	<?php
358	if (!$condition) {
359	....
360	}
361	?>
362
363	instead use the following:
364
365	<?php
366	if ($condition == false) {
367	....
368	}
369	?>
370
371	Multiple conditions should reside in their own parenthesis, as:
372
373	<?php
374	if ( (condition == true) && (condition == true) ) {
375	....
376	}
377	?>
378
379	Simple boolean expressions can be written as:
380
381	<?php
382	$value = (($condition == true) ? 'true' : 'false');
383	?>
384
385	Simple statements can be written as:
386
387	<?php
388	if ($condition == true) ....
389	?>
390
391	Functions do not need to be checked with a true/false
392	statement. For the following valid example:
393
394	<?php
395	if (empty($string)) {
396	...
397	}
398
399	if ( (isset($variable)) && (tep_not_null($string)) ) {
400	...
401	}
402	?>
403
404	Switch-Case statements should be written as:
405
406	<?php
407	switch ($value) {
408	case '1':
409	....
410	break;
411	case '2':
412	....
413	break;
414	default:
415	....
416	break;
417	}
418	?>
419
420	Condition Checking
421	------------------
422
423	To see if a variable exists, use the following structure:
424
425	<?php
426	if (isset($variable)) {
427	...
428	}
429	?>
430
431	and not:
432
433	<?php
434	if ($variable) {
435	...
436	}
437	?>
438
439	Repetitive Statements
440	---------------------
441
442	while loops should be written as:
443
444	<?php
445	while (condition == true) {
446	....
447	}
448	?>
449
450	Walking through an array should be written as:
451
452	<?php
453	// for php3 compatibility
454	reset($array);
455	while (list($key, $value) = each($array)) {
456	....
457	}
458
459	// the php4 way
460	foreach ($array as $key => $value) {
461	....
462	}
463	?>
464
465	for loops should be written as:
466
467	<?php
468	for ($i=0, $n=sizeof($array); $i<$n; $i++) {
469	....
470	}
471	?>
472
473	Mixing HTML and PHP
474	-------------------
475
476	Common HTML tags started in HTML must end in HTML, and
477	tags started in PHP must end in PHP.
478
479	Wrong:
480
481	<td><?php echo "Hello</td>"; ?>
482
483	Correct:
484
485	<td><?php echo "Hello"; ?></td>
486
487	Correct:
488
489	<?php
490	echo '<td>Hello</td>';
491	?>
492
493	Exceptions to this standard include the tep_draw_form()
494	function:
495
496	<?php
497	echo tep_draw_form();
498	?>
499	[form input fields are placed here]
500	</form>
501	?>

FishEye

View

Diff

Annotations

Annotated File View