Gallery2:Developer Guidelines

Guidelines for Gallery2 Developers

This is a set of notes that G2 developers should read before they start doing serious work on G2. Right now it's just a brain dump of things that I want to remember. We should flesh it out as we go.

Read and obey the Gallery Coding Standards!

• Gallery Coding Standards
• Gallery Coding Guidelines

Always do an HTTP redirect after receiving a HTTP POST or GET where we actually take an action

Whenever we actually make a change to the database or the filesystem as a result of an HTTP post or GET, we want to make sure that we redirect the user to a safe page. This way, if the user hits the reload button, they will not trigger the action again! All of the core views do this and can be used as an example for ways to make sure that it is done correctly.

After making any text changes to the system, re-build all translations!

  % cd lib/tools/po
  % perl update-all-translations.pl

This will extract new strings.raw files and generate new messages.po files, but only if there's an actual change! Translators can monitor their .po files to know when they need to update the translations they own. Changes to the strings.raw files will provide a clue as to what actually changed.

Use single quotes instead of double quotes where possible

PHP must interpret the entire contents of anything inside double quotes to see if it has any variables that need to be evaluated. Use single quotes when you don't have any variables inside the string.

GalleryStorage is backend agnostic

The GalleryStorage API makes no assumptions about how the back end works. Therefore, you can not make any references to database tables, indexes, columns, rows, etc. Instead you must refer to classes and members in the API.

Rebuild Map.inc and Entity.inc as well as Database Schemas whenever You Change an Entity or Map's Structure

A G2 member is a member which has a "@g2" XML snippet in its phpdoc variable comment. We use that to generate the Entities.inc and Maps.inc files associated with every entity class and map, and also to generate the SQL database definitions. We must change the entity/map schema version number and create entity migration XML files whenever we change entity members.

 cd modules/[modulename]/classes/ && make

PHP Settings

All Gallery developers should use the following PHP settings in their development environment:

• display_errors is actively suppressed in G2. It's very important that you enable display_errors during development, else you might miss uninitialized / undefined variables or constants! In config.php, change

 @ini_set('display_errors', 0);
 to
 ini_set('display_errors', 1);

• And ensure your php.ini settings are:

 error_reporting = E_ALL
 short_open_tag = Off
 magic_quotes_gpc = On
 allow_call_time_pass_reference = Off
 register_globals = Off
 display_errors = On
 allow_url_fopen = Off
 include_path = '/bogus'

Note: Pay special attention to the warnings on the lib/tools/phpunit/index.php page. It will show if any of the above settings are wrong.