This is user-contributed information determined by looking through the samples and code files. Documentation and code for third-party reports can be added as "child pages" below this page.

Others have blogged about this: see Alastiar A's CiviCRM – Creating a Custom Report and Artful Robot's How I wrote a CiviCRM Custom Report

Steps to add your own report.

1. Find an existing one under CRM/Report/Form/ that is similar to one you want.
2. Set up custom php and template folders as described at http://wiki.civicrm.org/confluence/display/CRMDOC/Customize Built-in, Profile, Contribution and Event Registration Screens
3. Copy the .php file to <custom_php_path>/CRM/Report/Form/XXX where XXX depends on what type of report it is and where you want it to live. For example if it's a basic report about contacts you might want to put it under Contact.
4. Change the class name in the file to correspond to the path where you put it.
5. Either copy the corresponding .tpl from templates/CRM/Report/Form/... into <custom_template_path>/CRM/Report/Form/XXX, or create a .tpl file with just the following line to get the standard template:
   {include file="CRM/Report/Form.tpl"}
6. Under Administer CiviCRM >> CiviReport >> Manage Templates add your own template. This is straightforward except for URL you can put whatever you want, and then that is appended to /civicrm/report in the actual url to reach it. For example if you put contact/mine, your report will be at http://<server>/civicrm/report/contact/mine

Customizing php form:

Consider the following "civicrm_contact" table for example:

Case I: Use shortcut method to build a Report to just display the content of the above table

Step A: Copy essentials over from an existing report. These statements are conditional on the kind of data you want to report on, so start off with a report that is similar to what you want (Step 1, above). For instance, a template on Contact Relationships starts with the following code.  Note the open ellipsis after the class statement, you'll need a closing ellipsis after the postProcess function.

Step B: Assuming you don't have any input criteria initialize $this->_columns as

Step C: Define postProcess() method:

Step D: Make sure the tpl has {include file="CRM/Report/Form.tpl"} as content.

Step E: Add the template to CiviCRM per Step 6 above.

And you're done!  

Case II: Use standard method and make report work based on display columns selected.

1. Now since we want user to decide which columns to display:

2. Build select clause based on columns selected: Please note: below method may need not be written for v3.3 or later, as select clause is built by parent class.

3. Build from clause:

4. You are done. But if postProcess() was supposed to be implemented, this is how it would be:

Done.

Information about the structure and parameters in the .php file

This is not a comprehensive list.

function __construct()

This is where you put the field and filter definitions.

$this->_columns

Assign $this->_columns to an array of table definitions. The key is any name you want, but it makes sense to use the table name unless you need to use the same table twice in the query.

|| Parameter || Value || Description ||

fields

fields is the list of fields that the user can select to display or not.

The way name, alias, and dbAlias work together is that if you set dbAlias directly, then it's whatever you set it to. Otherwise dbAlias gets computed as alias.name .

Then beyond that it seems that as long as you make what you use in select() and other functions match what you did here, it will work. Basically you use whatever combination of the array key, name, alias, and dbAlias so that you have enough uniqueness and that it generates valid SQL.

filters

filters is a list of filters related to the table that the user can use to filter the results.

group_bys

group_bys is a list of fields from the table that the user can select to group the results.

Using grouping will likely require you to customize most of the functions like select(). Also be on the lookout for table joins you might be making that might have multiple rows on the right side of the join, such as activities to targets. It may also require you to set rules to prevent users from making selections that don't make sense. The user may choose to unselect grouping too.

Contribute/Summary.php seems to be a good example of using group_bys.

|| Parameter || Value || Description ||

order_bys

order_bys is a list of fields from the table the user can select to affect the ordering of the results. For each array element, the array key should be equal to the field being exposed for sorting.

Contact/Summary.php is a good example of using order_bys.

Defining order_bys for columns that are not indexed may negatively affect performance. You may wish to examine the database schema to check for and/or define indexes on order_by columns.

|| Parameter || Value || Description ||

adding custom fields

As of 3.1 (earlier?) you can add custom fields to a report by adding / modifying the 'extends' line

If this line is in the php file then all searchable (check: Is this Field Searchable?) custom data fields that relate to Contact, Individual, Household, or Organisation will be available in the report. Note that 'Contact' ONLY refers to the custom data groups that extend all contacts and does not also include those that extend Individual. This functionality is not limited to 'contact' related fields and activity, relationship etc fields can be added.

All searchable fields of that type will be added. There is not currently a simple option to only select some.

auto-including custom fields as order_bys

If the property $this->_autoIncludeIndexedFieldsAsOrderBys is set to TRUE, the report will automatically create order_by options for the custom fields added in $this->_customGroupExtends.  Since all custom fields are indexed, this does not negatively affect performance.

functions select() and where()

Most of the time you can probably copy these as is. But see note about group_bys.

function from()

This is where you define the tables and joins by setting $this->_from to an SQL string.

function groupBy()

This is where you define the grouping clauses by setting $this->_groupBy to an SQL string.

function alter_display()

This is where you can reformat column values to be links and such.

It also seems to be where you replace values with labels, as opposed to doing it in the SQL? (Can someone confirm if this is the "right" way?)

function statistics()

This is where you set and execute the query to compute aggregates. As noted above you may need to customize if using grouping.

function formRule()

Return an array of strings listing any errors you wish to display to the user based on their selections.