Configuration

How to best configure phpDiveLog

Configuration of the web application mostly takes place in text files, and for the system wide configuration the relevant file is inc/config.inc. To provide you with an easy way for updates to later versions, where this file could be replaced, there is a special feature: If found, inc/config_local.inc will be included right after inc/config.inc and overwrite its settings. So if you want to change some settings, the best way is:

1. copy inc/config.inc to inc/config_local.inc
2. remove all settings you do not intend to change from config_local.inc. Feel free to remove all comments as well.
3. now, in config_local.inc adjust the remaining settings to the preferred values.

Big advantage of this: If there comes an update and introduces new settings, they will take effect via the new inc/config.inc - while your customized settings in inc/config_local.inc remain untouched.

Settings explained

General Settings

Some of the General Settings can be overridden by URL parameters, which is especially useful if you plan to access the dive log(s) in two different ways: directly (stand-alone), where you have the full browser window available for PDL, and integrated in a frame of your website, where space is a bit limited. So in the latter case you don't care about additional URL parameters to limit e.g. the rows per page in lists, while in the first case you want to use the additional space and have longer lists. The column URL Override tells you the parameter name, if available.

Setting	Default	URL Override	Explanation
$database["type"]	"csv"	-	in which way the divers data will be provided. Right now you can set this to "csv" only. In the future, there may be more formats available, such as UDDF for the Universal Dive Data Format (again a file), or even "real databases" such as MySQL, PostgreSQL, etc.
$display_limit	12	displaylimit	with pages containing lists, as e.g. the sitelist, this value will advise PDL how many entries (i.e. table data rows) to display per page. This saves you from scrolling through long pages - but of course you can set this to e.g. 999999999 and everything will fit on one page (but not necessarily one screen).
$template_set	"aqua"	tpl	to which template set PDL should default. Right now the values "aqua" and "default" are available. The visitor can overwrite this value (for his/her browser session only, of course) by selecting a different template set on the preferences page.
$lang	"en"	lang	the default language to use (if no other language was specified via the users preferences). This is a 2 character ISO code, like "en" for English or "de" for German. You can set this to any language you like - if no translations are found, PDL will fall back to English. You can tell available languages by investigation of the lang/ directory. See the CustomizationManual for details on how to add missing translations.
$title	"Demos phpDiveLog"	-	for now the site name to be displayed in the browsers title bar. At the end of this, some page information will be added: if you e.g. set the title to "MyDiveLog", by browsing the dive #5 the browsers title probably looks like "MyDiveLog: Dive# 5" - where "Dive" could be localized even…
$enable_index	TRUE	-	whether visitors should be allowed to browse the buddylist. Needs to be set to "TRUE" if you want to use $default_page="index" (see below).
$default_page	"user"	-	what to do if there's no diver specified with the URL (and thus PDL does not know where to look for the data - normally this has to be done on the URL with the diver=nickname parameter)? Available options are "user" ($default_user must be set to a valid user then), "index" (display the index page with available nicks, needs $enable_index=TRUE - see above), and "error" (display an error message to the visitor)
$default_user	"demo"	-	only evaluated if $default_page="user": which is the default logbook we should route the request to? Must be a valid account, otherwise results in $default_page="error".

Geographical Stuff

Setting	Default	Explanation
$mapsite	"Google"	If you recorded GPS coordinates with your dive sites, phpDiveLog creates a link to a given mapsite to look up the place. You may chose between "Mapquest" and "Google" (the latter refers, of course, to Google Maps)
$global_kml	TRUE	The "global KML file" lists all available divers KMZ files as "network links" (one link per diver) - which works fine with Google Maps. Google Earth, however, seems to request all listed network links simultaneously - which the server may interprete as DoS attack and reject some of the requests (the user can, however, reload missing files manually then in most cases). So if you are affected by this, you may turn the global KML processing off here.

Graph Settings

Setting	Default	Explanation
$sitepix_on_divepage	0	if you want pictures from the corresponding dive site to be generally displayed together with the pictures from the dive when viewing the dive page, set this to 1.
$sitepix_first	0	only has effect with $sitepix_on_divepage not set to "0" and decides whether site pictures precede the dive pictures (1) or follow them (0)
$sitepix_separate	0	only has effect with $sitepix_on_divepage not set to "0" and decides whether they are separated from the dive pictures (1) or simply added (0)
$sitepix_if_no_divepix	1	only has effect with $sitepix_on_divepage not set to "0" and decides whether site pictures will be included on a dive page if there are no dive pictures available. Other than with $sitepix_on_divepage, this would not include site pictures on the dive page if there are dive pictures available.
$use_dyn_profile_png	0	Though the Aqua DiveLog Conduit creates graph images for the dive profiles, these images vary much in their dimensions. To keep the design more clear, you may want to generate these profiles dynamically by setting this option to "1" (see also DynamicGraphs). Note that this requires GD support in your PHP installation - plus a directory named profiles in each divers home, writable for the web server process. The image then will be generated in two cases: If it does not already exist, or if the profile CSV file is newer.
$schedule_graph	"integrated"	These graphs are not provided by the conduit, so phpDiveLog will have to generate them if you want them (which means, $use_dyn_profile_png must be enabled for this - see also DynamicGraphs). With the $schedule_graph configuration option, you can tell phpDiveLog how you want your schedule graph to be drawn: "integrated" into the profile graph (if possible, falls back to next otherwise), as a "separate" graph in the Schedule section of the page, or "none" if you don't want it at all.
$hide_schedule_table	TRUE	Since the graph says more than thousand table rows, you may not want to waste space on the page for the raw data. Here you can decide whether to hide (TRUE) or display (FALSE) them.
$values_in_statgraphs	"auto"	On the statistics page for each diver you also find some graphs, e.g. for dives per year. They can have the values printed within the bars - but if you are to list up statistics for more than 20 years, or have several hundreds (or even more) dives per year, this may not look as nice as you would expect - so you have the choice to: always have the values displayed in the bars ("yes"), never have them there ("no"), or let the app decide ("auto"). The latter should be fine for the average diver. Note: The values are always displayed when hovering the mouse over the corresponding bar - so don't be afraid they could be completely missing.
$graph_bg_transparent	FALSE	This setting decides whether to use transparent background for the graphs (TRUE) or not (FALSE).
$ignore_zero_degrees	TRUE	If you did not enter any water temperature in ADL, the conduit would export this as "0°C" - so phpDiveLog cannot decide between "no temperature entered" and "real 0°C". Though this temperature is really unlikely to be dived in, we want to leave you the questionable fun of doing so by setting this variable to FALSE.
$ignore_zero_degrees_comment	TRUE	If $ignore_zero_degrees was set to TRUE, shall we place a note below the temperature graph to indicate this?
$temp_stat_interval	10	Temperature intervals for the corresponding statistics graph. You may set this to either 5 or 10.
$time_stat_interval	10	Time interval (in minutes) for the Dives by Duration graph. Set this to either 10 or 20 (30 should also work).
$depth_stat_interval	5	Interval (in meters) for the Dives by Depth graph. Valid settings are 5, 10, and 20.

Data Transfer Settings

Setting	Default	Explanation
$pwdfile	"/etc/pdlpwd"	If you want to allow your buddies to transfer their divelog data using a single OS account (see MultiUser Issues), you need to set up a password file (so only the diver him-/herself can import their transfered data into the PDL installation). This file should NOT reside inside your web tree, but it must be readable by the web server. A good idea is to let this file be owned by the web servers users group, and apply read permission for the group. The web server should not have write permission to the file.
$transfer_dir	"/home/pdl/transfer/"	The base directory for the transfered logbook data when using the "single OS user transfer" (see MultiUser Issues). This should be the directory containing the diver directories directly below it (i.e. the counterpart to the PDL diver/ directory).

Sorting and Ordering

These are the default sort settings if one enters the logbook resp. sitelist first time on the visit, and did not yet apply a custom sort (i.e. did not yet click one of the up/down arrows next to the column names). The *_order can be either "asc" or "desc". For the *_sort are the following values valid:

• logbook: date, time, location, place, rating, depth, buddy
• sitelist: location, place, depth

As with some of the General Settings, you can override these with URL parameters.

Setting	Default	URL Override	Explanation
$logbook_default_sort	"date"	sort	Sorting the logbook (dive list)
$logbook_default_order	"desc"	order	Ordering the logbook
$sitelist_default_sort	"location"	sort	Sorting the site list
$sitelist_default_order	"asc"	order	Ordering the site list

PDF Settings

If these settings shall have any effect, you need to have  TCPDF installed on your server. You can download and install the full distribution from their site (>10MB zipped size), or decide to install the "stripped variant" from the  IzzySoft APT/YUM repository (minimal install: ~1MB, including the API plus the font definitions - recommended install: ~4MB, including the API and the basic fonts), if your system supports *.deb or *.rpm packages.

Setting	Default	Explanation
$tcpdf_path	"/usr/share/tcpdf/"	Where the TCPDF files are installed. If you installed TCPDF from our repository, you don't need to touch this.
$pdf_page_format	"A5"	Page size to use for PDF. Valid settings are everything between A0 to A5 and B0 to B5. The default (A5) should be a good choice together with the detault for $pdf_page_orientation (Portrait), since you can easily print two pages on one A4 page then (letting the printer driver print 2 pages on one with multiple pages exported, it should be able to handle duplex as well).
$pdf_page_orientation	"P"	Orientation of the page: Portrait or Landscape. The default assumes you want to print two A5 pages on one piece of A4 paper. If you have trouble to convince your printer, try A4 with landscape.
$pdf_page_gutter	25	Space to be used to file the pages into your book. PDL takes care to have it on the right side of the pages (left for odd, right for even numbers)
$pdf_page_margin	5	Space on the side opposite to the gutter
$pdf_no_profile	"dummy"	What shall be used for the dive profile if we have none available: "dummy" places a "dummy profile", "blank" just leaves the space blank.
$pdf_with_fotos	TRUE	Would you like to have some photos included with your logbook pages (if there are dive photos connected)? Setting this to TRUE will include the first three dive photos (if available), or all dive photos if there are less than three.
$pdf_enable	TRUE	Whether PDF functions should be available (if the API is found then). You can use this option to disable PDF support when you feel "too many users on the public servers play with it, and the server load increases too much", for example.
$pdf_max_notechars	1900	To make sure the notes fit in the template, they will be truncated when exceeding this value
$pdf_chars_per_pix	10	For each 10px picture height, we lose one line of text space - which is about 100 chars, and thus corresponds to 10 chars per pixel
$pdf_create_missing_graph	1	Missing profile graphs can be created on-the-fly when generating the PDF - so this setting can be overridden on the page for "mass-export". If set to "1", missing (and outaged) profiles will be (re)created. If set to "0", the static graph will be substituted (if found), or the setting of $pdf_no_profile will be applied.

Configuration Overrides by Divers system.conf

Setting	Default	Explanation
$override_protection	"explicit"	How to tell which settings may be overridden by the divers system.conf settings. "implicit" means the behaviour as it has been until v0.4.0: all configuration variables except for those specified by $allow_override have been "protected" (i.e. the divers could not override them). In a less restrictive environment, the $allow_override list could get quite long - hence the new default is "explicit": all configuration variables can be overridden by the divers system.conf - except for those explicitly mentioned in $protected_options
$allow_override	(depends on version)	here we define which configuration variables may be overridden by the diver/*/system.conf file (see divers configuration) when $override_protection is set to "implicit". The value of this parameter is a space separated list of options - and is completely ignored when $override_protection is set to "explicit".
$protected_options	(depends on version)	which configuration variables may not be overridden when $override_protection is set to "explicit" (otherwise, this setting is completely ignored). As $allow_override, this is a space separated list.

Debug Settings

Setting	Default	Explanation
$debug_level	"EW"	What information shall be logged. This can be a combination of events (chose the bold letter): Errors, Warnings, Notices, All. By default, errors and warnings should be reported. Notices may be useful for debugging purposes.
$debug_show	0	Whether debug info should be displayed in the browser window itself (1) - a very bad idea for "production" systems, since internal (private) information would be presented to each visitor. This is really simply to ease debugging - you should always turn it off (0) otherwise.
$debug_log	1	Whether to store error messages to the web servers error.log file (1) or not (0). It is always a good idea to have this turned on - so you can verify if a certain error already exists for a while, and since when.

Robot Settings

These settings are intended to handle search engine crawlers, and especially prevent their recursion through too many levels plus limit their visits, if possible:

Setting	Default	Explanation
$robots_index_lists	"index,follow"	How robots shall deal with lists (site list, dive list, buddy list). The default is set to not change the previous behavior: They shall keep the pages content in their databases (index), plus follow all links (follow). It could also be useful to set this to "noindex,follow" - since the lists themselves may not be that useful to the search engine visitor. Note, however, that "nofollow" could take the whole divelog away from engines respecting these settings.
$robots_index_pages	"index,nofollow"	Similar to above, but for the detail pages. Here it makes much sense to set nofollow, to prevent the crawlers from looping through everything - all useful information is contained on the page already.
$robots_index_prefs	"noindex,nofollow"	Makes absolutely no sense to give these pages to the search engines, so "noindex,nofollow" is the only useful setting here. However: If you feel different, you may change it here.
$robots_revisit_lists	14	After how many days a search engine crawler may return to check for updated content. We keep this a bit lower for lists, so new dive/site entries will make it into the search engines index. Note that not all crawlers respect this setting.
$robots_revisit_pages	60	Once the content has been set up, it's rarely subject to change - so you may even increase this value. If you, however, tend to change existing entries frequently, you may also decrease it.
$robots_revisit_prefs	9999	We don't want this content indexed - so we don't care if the crawler revisits them at all. Feel free to add a few digits

Miscellaneous Settings

Setting	Default	Explanation
$emoticon_file	"inc/emoticons.csv"	Emoticon definition file (see Emoticons). Comment out if you don't want to have emoticons to be used.