********************************************************************************* * * * CODING LAYOUT AND STANDARDS * * * ********************************************************************************* //--------- Code layout --------------------------------------------------------- Part of what makes Gazelle rock so hard is that the code is all neatly partitioned into little boxes. This is going to be a huge pain in the ass at the beginning as you'll have no idea where to find anything, but you'll learn to love it in no time - we promise you. :) This is basically how it works: A user loads a page. Let's say they load forums.php?action=viewthread&threadid=5. * forums.php includes classes/script_start.php * script_start.php includes classes/config.php, classes/class_mysql.php, and classes/class_cache.php * The bottom of script_start.php checks to see which page the user is viewing. It sees 'forums'.php, so it includes sections/forums/index.php * sections/forums/index.php is the 'gateway' into the forums section of the site. Every forum page is included through it. It decides which page to do based on a switch() statement (in some index.php gateways, an if/else is used instead depending on the situation). sections/forums/index.php sees that $_GET['action'] is 'viewthread', so it includes sections/forums/thread.php. (The gateway can do more than just act as a switch center. It can be used to handle submitted form data in cases where the handling of the data isn't complex enough to warrant its own file.) * thread.php is the "final destination" - this is where the code for the page that the user is viewing is run. In this particular example, thread.php also includes classes/class_text.php and classes/class_thread.php, because it needs access to the BBCode parser and the thread class. So, in a typical page, this is how the code flow looks: Root page (eg. forums.php). Includes: - /classes/script_start.php. Includes: - /classes/config.php - /classes/class_mysql.php (becomes $DB) - /classes/class_cache.php (becomes $Cache) - /sections/name_of_root_page/index.php. Includes: - /sections/name_of_root_page/file_that_handles_action.php //--------- script_start.php ---------------------------------------------------- script_start.php is loaded every time a user loads a page. It has the following functions: - Include the configuration - Include the mysql class, and instantiate it as $DB - Include the memcache class, and instantiate it as $Cache - Check if a user's logged in, and load the user's data if necessary - Load the names and levels of the classes - Define all the functions in the standard Gazelle library - Include the page that generates the content //--------- Classes ------------------------------------------------------------- Most of the important classes include extensive documentation The most important classes are class_mysql.php, class_cache.php, class_text.php, and class_torrent.php (in that order). The total list of Gazelle classes is: - class_artist.php - Nothing more than a template for an "ARTIST" object, used for the similar artists map - class_artists_similar.php - Similar artist map, extends class_artist.php - class_cache.php - Interface to memcache, with functions created to cache output instead of just variables - Is included on every page, and instantiated as $Cache - Includes extensive documentation at the top - Most important functions: - CACHE::get_value(string $Key) - Get a value from the cache - CACHE::cache_value(string $Key, mixed $Value, int $Duration) - Store a value in the cache - CACHE::delete_value(string $Key) - Delete a value from the cache - class_feed.php - RSS feeds - class_image.php - Wrapper for php image*() functions - Was written for class_artists_similar.php, and thus only contains the functions necessary for the similar artist map - Feel free to simply add more functions when you need them. - class_invite_tree.php - Displays the invite tree - Included on /sections/user/invitetree.php and /sections/user/user.php - Contains extensive documentation - class_log_checker.php - Class for the automated parsing of EAC log files. - Probably of 0 interest to you. - class_mysql.php - Class for easy communication with MySQL - Contains code for debugging - Contains extensive documentation - Most important functions: - DB_MYSQL::query(string $Query) - Run a query, and return the result set - DB_MYSQL::next_record($Type=MYSQLI_BOTH); - Returns the next row in the result set - class_requests.php - Class for displaying a list of requests - DB query must be built externally - Has a $Big variable, which, when set to false, creates a compact table - Is capable of handling its own caching - class_templates.php - Basically a giant str_replace() wrapper - Parses templates found in /templates/ - Only used for sending mail and generating config.php on installation - No HTML is generated by the template class. That shit is lame. - class_text.php - BBCode parser and link-ifier - Most important function: - TEXT::full_format(string $Str) - Escapes, parses bbcode, does smiles, linkifies - Includes necessary documentation - class_thread.php - Class for displaying forum threads and torrent comments - This is the class that the caching class was created for - Handles its own caching - Includes necessary documentation - class_torrent.php - Bencode parser for .torrent files - Includes 4 actual classes - BENCODE - BENCODE_LIST - BENCODE_DICT - TORRENT - Includes functions for: - Getting the file list - Setting private flag - Setting the announce URL - Includes extensive documentation - class_torrent_form.php - Displays the form used for uploading and editing torrents - Is included in 3 files - ajax/upload.php - upload/upload.php - torrents/edit.php - If TORRENT_FORM::NewTorrent is false, the form is shortened to what you see on the edit page - class_validate.php - Class for validating forms - Capable of generating javascript to do client-side validation - Includes extensive documentation - class_wiki.php - Only includes one function, to generate the revision history of any wiki table //--------- Coding standards ---------------------------------------------------- ===== php ===== - Variables are in $MixedCase, with underscores avoided if possible (you'll learn to love it) - Functions are lower_case_with_underscores - Constants are UPPER_CASE_WITH_UNDERSCORES - Class names are UPPER_CASE_WITH_UNDERSCORES - The choice between using single quotes and double quotes is made at your discretion. The general rule of thumb is to use double quotes in SQL queries and places where you would have a lot of backslashes and periods if you were to use single quotes, and single quotes everywhere else. However, this rule is flexible and not strictly applied. - Comments should be used wherever you have some potentially confusing or 'creative' code. The preferred commenting style is double slashes (//), because they're quick to type, standard, and don't cause problems when commenting out large blocks of code (a la /**/). - Use tab indentation, not space indentation. - We use short tags because they make the code look neater. - In conditinals, loops functions, etc. keep the { on the same line as the condition. Don't put it on the next line; that's really annoying. - In short, try to blend in as much as possible. ===== MySQL ===== - Use proper SQL casing ('SELECT', not 'select') - Long queries should be broken down into multiple lines, to make them easier to read - All variables which are open to user manipulation ($_GET, $_POST, $_COOKIE and $_REQUEST) should be escaped with db_string() before touching the database //--------- Miscellaneous things you should know before you start coding -------- - $LoggedUser is an associative array of information about the current user. It is created in the function update_user_data() in script_start.php. - What users can and cannot do is controlled by a highly advanced permisions system - the frontend can be found in the toolbox. The only thing controlled by the levels on the permissions are: - Forum permissions - The order of the permissions on the toolbox list - The order of the classes on the staff page - If you ever need to find out where the code is for an action or page, check the index.php in that action/page's section. If you still can't find it, use grep. - Use the error() function in script_start.php when errors are raised. For a list of how-tos, see the 'how-to' file. For miscellaneous information on running a BitTorrent tracker. see the 'miscellaneous' file.