1 of 7

Basic Osclass

Basic osclass development related information.

Contribute to Osclass

Contributing to Osclass

We are glad to hear you want to contribute to the Osclass project. Osclass is an open source solution for your classifieds site, developed by and for its users, like you. There are several ways to help Osclass grow and improve, even if you don't know to code, you could still help Osclass.

Documentation

Documentation is done by everyone who wants to do it! This documentation is available on our public GitHub Repo

Translations

It is work in progress to allow everyone to contribute with translations.

Support Forums

~~Users' participation and involvement are essential to maintain our support forums.~~

Currently we do not have any official forums but you can get help at which is an active public forum with active community.

We will update this list here if we found more places where you can actively seek or give support.

Development

Do you know PHP, JS or MySQL? Get involved in Osclass development. Help us write code, add features and fix bugs!

Visit our project and check out our repositories. You can sign in and help us improve our core, themes or plugins. The best way to do this is through “Pull request” and help us fixing bugs by applying changes to the code. For any doubt, look up the help section for any doubt.

Testing Osclass

Even if you don’t know to code, you can also contribute to Osclass. You can help us test the previous releases of Osclass as well as our themes and plugins.

Reporting bugs/suggest features

Tell your friends about Osclass

We will be happy if you tell your friends about Osclass, share a link or display a small banner on your site. More users -> stronger community -> better Osclass!

Donations

Osclass is and will always be free,. Sending money to Osclass developers is another way to support the community. If any theme or plugin makes your life a little bit easier, contact the author and show your support. Sometimes developers just need to hear users are happy to use their plugins/themes.

Coding Style

Basic Introduction to Osclass coding style

Coding Style

This small guide is partly based in the coding style guide of Zend Framework :

PHP Code Demarcation

PHP code must always be delimited by the full-form, standard PHP tags:

Short tags are never allowed. For files containing only PHP code, the closing tag must always be omitted (See General standards).

Variables

Variables should follow the Hungarian Notation ( ), that means they should start with a character indicating the type of variable, for example i for integer, a for arrays, o for objects, s for strings ... Also, each first character of a word should be uppercase.

Note: SQL column's names should follow a similar notation, but the first character should follow an underscore. Words are separated by an underscore, all in lowercase. If the column is a primary key, it should be preceded by "pk_" if it's a foreign key by "fk_"

Classes

Class Declaration

The brace should always be written on the line underneath the class name.

Every class must have a documentation block that conforms to the PHPDocumentor standard. The following is an example of an acceptable class declaration:

Control Statements

If/Else/Elseif

Control statements based on the if and elseif constructs must have a single space before the opening parenthesis of the conditional and a single space after the closing parenthesis.

The opening brace is written on the same line as the conditional statement.

The closing brace is always written on its own line. Any content within the braces must be indented using four spaces.

It's required ALWAYS to put the braces.

The following if statements is not valid

Switch

Control statements written with the "switch" statement must have a single space before the opening parenthesis of the conditional statement and after the closing parenthesis.

All content within the "switch" statement must be indented using four spaces. Content under each "case" statement must be indented using an additional four spaces.

The construct default should never be omitted from a switch statement.

Documentation Format

More information

Debug PHP Errors

The OSC_DEBUG constant, added in version 2.3, controls the display of php errors and warnings. If this setting is not defined in config.php, the default value is false.

When the OSC_DEBUG is false, the error reporting level is E_ALL ^ E_NOTICE ^ E_USER_NOTICE. In that case, we're not showing notice and strict php errors. However, if we set the constant to true, the error reporting level is E_ALL | E_STRICT and display_error value is 1.

The OSC_DEBUG_LOG constant, added in version 2.3, logs these errors to a file called debug.log in oc-content. If Apache doesn't have write permissions, you may need to create the file first and set the appropriate permissions (i.e. use 666).

/**
 * Copy this code to config.php file
 * This will disable notice and strict errors
 */
define('OSC_DEBUG', false) ;

/**
 * Copy this code to config.php file
 * This will show all error notices and warnings on the site
 */
define('OSC_DEBUG', true) ;

/**
 * Copy this code to config.php file
 * This will log all error notices and warnings to a file called debug.log in oc-content
 */
define('OSC_DEBUG', true) ;
define('OSC_DEBUG_LOG', true) ;

Debug SQL Queries

Note: This will have a performance impact on your site, so make sure to turn this off in your production site.

The OSC_DEBUG_DB constant, added in version 2.3, saves the database queries to an array and at the end of the execution the queries are displayed at the end the page. The information saves each query: the sql string, how long that query took to execute, the sql number error and string if there has been some sql error.

The OSC_DEBUG_DB_LOG constant, added in version 2.3, logs the sql queries to a file called queries.log in oc-content. If you want to debug the sql queries of the AJAX calls or cron, you must use OSC_DEBUG_DB_LOG because we can't print these at the end of the page. If Apache doesn't have write permissions, you may need to create the file first and set the appropriate permissions (i.e. use 666).

The OSC_DEBUG_DB_EXPLAIN constant, added in version 2.3, run an EXPLAIN query for each select query and logs the result to a file called explain_queries.log queries. It should be used only during the development of OSClass, themes or plugins to see the performance of the queries. Remember, if Apache doesn't have write permissions, you may need to create the file first and set the appropriate permissions (i.e. use 666).

/**
 * Copy this code to config.php file
 *
 * This will show SQL queries at the bottom of the site
 */
define('OSC_DEBUG_DB', true) ;

/**
 * Copy this code to config.php file
 *
 * This will log all sql to a file called queries.log in oc-content.
 * 
 * If Apache doesn't have write permissions, you may need to create the file first 
 * and set the appropriate permissions (i.e. use 666).
 */
define('OSC_DEBUG_DB', true) ;
define('OSC_DEBUG_DB_LOG', true) ;

/**
 * Copy this code to config.php file
 *
 * This will run a EXPLAIN sql query for each SELECT sql statement.
 * The results will be logged to a file called explain_queries.log in oc-content.
 * 
 * If Apache doesn't have write permissions, you may need to create the file first 
 * and set the appropriate permissions (i.e. use 666).
 */
define('OSC_DEBUG_DB_EXPLAIN', true) ;

How to write a bug report

We don’t like bugs, neither you do. I’ve seen a post in talking about this and I’ve found really interesting. I’m going to reproduce it here:

Here’s a great rule: If we can’t reproduce the bug, we can’t fix the bug.

When you report a bug to us, here’s what happens:

We read the bug report
One of us tries to reproduce the bug
If we can reproduce it, we investigate what’s broken and fix it
But if we can’t reproduce the bug…
Often bug reports don’t include enough information. Meaning we have go back and ask for details so we can investigate. If you want to increase the odds we fix an issue, and fix it fast, help us out.

A great bug report includes the following:

What were you trying to do?
What did you click on or do last?
What happened / what did you see?
What browser are you using?
What version of OSClass?
What hosting provider? (And if you know, what version of PHP do they use?)
The bug is reported to the right place:
2. Plugins: Specify the plugin and the version
3. Themes: Specify the theme and the version

Bonus points for reviewing known issues before submitting, as your problem might already have been reported and have a patch or a workaround.

We work hard to have you deal with as few issues as possible, but if you want to improve the odds we can fix your issue fast, please take a extra minute to write a bug report that’s easier for us to use. Thanks.

Database model and diagram

This diagram could be a bit difficult to understand at first and follow all the relations. To be able to use an interactive version of the same diagram, please use the MySQL Workbench and follow these steps.

Download MySQL Workbench (it's free and cross-platform!)
Install it and open it
Select Create EER Model From SQL Script
Look for your file 'struct.sql (your_osclass_folder/oc-includes/osclass/installer/struct.sql)
Check Place imported object on a diagram
Click on Execute, Next, Finish
Re-arrange the boxes (tables) as you wish

Relations will highlight if you place your mouse over the tables or the relations.

Debug SQL Queries

Note: This will have a performance impact on your site, so make sure to turn this off in your production site.

/**
 * Copy this code to config.php file
 *
 * This will show SQL queries at the bottom of the site
 */
define('OSC_DEBUG_DB', true) ;

/**
 * Copy this code to config.php file
 *
 * This will log all sql to a file called queries.log in oc-content.
 * 
 * If Apache doesn't have write permissions, you may need to create the file first 
 * and set the appropriate permissions (i.e. use 666).
 */
define('OSC_DEBUG_DB', true) ;
define('OSC_DEBUG_DB_LOG', true) ;

/**
 * Copy this code to config.php file
 *
 * This will run a EXPLAIN sql query for each SELECT sql statement.
 * The results will be logged to a file called explain_queries.log in oc-content.
 * 
 * If Apache doesn't have write permissions, you may need to create the file first 
 * and set the appropriate permissions (i.e. use 666).
 */
define('OSC_DEBUG_DB_EXPLAIN', true) ;

Coding Style

Basic Introduction to Osclass coding style

Coding Style

This small guide is partly based in the coding style guide of Zend Framework :

PHP Code Demarcation

PHP code must always be delimited by the full-form, standard PHP tags:

Short tags are never allowed. For files containing only PHP code, the closing tag must always be omitted (See General standards).

Variables

Classes

Class Declaration

The brace should always be written on the line underneath the class name.

Every class must have a documentation block that conforms to the PHPDocumentor standard. The following is an example of an acceptable class declaration:

/**
* Documentation Block Here
*/
class Foo
{
    /**
     * Documentation Block Here
     */
    public function bar()
    {
        // all contents of function
        // must be indented four spaces
    }
}

Control Statements

If/Else/Elseif

Control statements based on the if and elseif constructs must have a single space before the opening parenthesis of the conditional and a single space after the closing parenthesis.

The opening brace is written on the same line as the conditional statement.

The closing brace is always written on its own line. Any content within the braces must be indented using four spaces.

if ($a != 2) {
    $a = 2;
} else {
    $a = 7;
}
 
if ($a != 2) {
    $a = 2;
} elseif ($a == 3) {
    $a = 4;
} else {
    $a = 7;
}

It's required ALWAYS to put the braces.

The following if statements is not valid

if($a != 2)
    $a = 2;

Switch

Control statements written with the "switch" statement must have a single space before the opening parenthesis of the conditional statement and after the closing parenthesis.

All content within the "switch" statement must be indented using four spaces. Content under each "case" statement must be indented using an additional four spaces.

switch ($numPeople) {
    case 1:
        break;
 
    case 2:
        break;
 
    default:
        break;
}

The construct default should never be omitted from a switch statement.

Documentation Format

All documentation blocks ("docblocks") must be compatible with the phpDocumentor format. Describing the phpDocumentor format is beyond the scope of this document. For more information, visit: »

More information

This small guide is partly based in the coding style guide of Zend Framework :