Submitting Code

ADOdb is a community project, and its continued existence is reliant on both feature added by the maintainers and user submissions. To minimize wasted coding time and elongated discussion threads, here are a few guidelines

What is ADOdb?

Many people simply use ADOdb for single platform coding, to minimize the learning time involved in using PHP level database drivers. But ADOdb is also a cross database extraction layer, which allows the same code to be used across multiple platforms. So if you submit feature, it should be usable across multiple databases. Firstly, here's how we rank the drivers:

Importance	Drivers
Tier 1	Native MySQL [mysqli], Native PostgreSQL [pgsql], Native SQL Server [mssqlnative], Native Oracle [oci8]
Tier 2	PDO (alltypes)[pdo_],ODBC(all types) [odbc],SQLite [sqlite3], Non-native SQL Server(mssql), IBM DB2(db2), Firebird(fbsql)
Tier 3	Everything else

This means that if you propose a new feature, i.e. one that will require it's own page in the documentation, it should be available on most, if not all of the Tier 1 drivers at release to production. We understand that you may not be able to code that yourself, so you've got to be prepared to get help and agreement (probably from one of the maintainers).

Basic Rules

Scenario	Expected Actions
You want to make a change that has no effect on the default functionality	- create an issue,explain the problem or feature. - If the change affects existing installations, explain how you would support that
You want to change a feature	- If the feature change creates a scenario where the documentation would say “for all drivers except xxxx, do this. Otherwise do this”, expect the request to be declined. - If you cannot provide feature for Tier 1 drivers, open an issue and ask for help
You want to add new feature	Open an issue and explain the feature. You will be expected to provide some end user documentation that the maintainers can use as the basis for the docuwiki. Maintainers may decline to accept submissions where the only way of understanding the feature is dissecting the code. You should be able to provide at least one Tier 1 driver. The more drivers you can provide code for the more likely the maintainers are to accept the submission

Scenarios

You found a bug

If you find a bug in a single driver, open an issue explaining the problem, if possible showing both what is happening and what should happen. If the maintainers agree it's a problem, and you have a fix for it, create a github pull request, referencing an issue.

You believe the current behavior in a driver is incorrect

These are often the most contentious discussions because we're likely to ask you to show how the behavior is wrong in general, and not just in your particular use case. In addition, if there is a problem, we need to be able to ensure that users who have relied on the apparently faulty behavior (possibly for years) aren't going to have problems if they upgrade to a version of ADOdb that has corrected behavior. That might mean, in the short term, an optional, parameterized change. Remember, ADOdb isn't an obscure little side project, there are normally 100-200 downloads per week, continually over a period of nearly 20 years.

You want to enhance the functionality of a specific function

Say, for example, you wanted to add the ability of the mysqli connector to use SSL connections to connect to the database.

Start first by seeing how you can use the existing methods to provide access into your new codes. Don't, for example, modify the format of the connect function to require new, or modified parameters.
You might, for example, use the setConnectionParameter method to inject the SSL parameters into the connection.
If you need to add new class variables or methods, make sure the connection doesn't fail if they are not set.
Make sure that your feature doesn't interfere with existing configurations.

Adding A New Feature

You might decide to offer a new method year, that provides a database independent method of obtaining a 4 digit year from a date field. If you use MySQL, then you might recognize the correct syntax as

SELECT DATE_FORMAT(FIELD,'%Y');

You would then add the code into the drivers/adodb-mysql.inc.php file in a function like this

/**
* Formats the date into year only format YYYY
*
* @param	str		$field	The name of the date to format
*
* @return	str		The SQL text
*/
public function year($fld) 
{
    $x = "DATE_FORMAT($fld,'%Y')";
    return $x;
}

In order to fulfill the requirement for cross database compatibility, you should research the method of obtaining the same information from at least other Tier 1 databases. You would find that you would need to add code like this

SELECT YEAR(FIELD) //mssqlnative, mssql drivers
SELECT TO_CHAR(FIELD,'YYYY') // oci8 drivers, postgres drivers

Even if you cannot test these yourself because you have no access to the database, you can code them into your branch and put out a call on the issues page for help testing.

You need also to create some end user documentation, that can be used as a basis for docuwiki pages.

[standards, coding]

Table of Contents