pgsrc/Help%2FAnalyseAccessLogSqlPlugin

   1 Date: Fri,  7 Dec 2012 14:58:45 +0000
   2 Mime-Version: 1.0 (Produced by PhpWiki 1.4.0)
   3 Content-Type: application/x-phpwiki;
   4   pagename=Help%2FAnalyseAccessLogSqlPlugin;
   5   flags=PAGE_LOCKED;
   6   markup=2;
   7   charset=UTF-8
   8 Content-Transfer-Encoding: binary
   9
  10 The **~AnalyseAccessLogSql** [[Help:WikiPlugin|plugin]] provides a framework to analyse the SQL access log
  11 and display the results.
  12 This information may be sensitive and therefore this plugin is limited to
  13 administrator access only.
  14
  15 A small number of queries that may (or might not) use the ~MySQL
  16 specific dialect of SQL are provided in ##lib/plugin/~AnalyseAccessLogSql.php##.
  17 For more information, please see the section *Adding new queries* below.
  18
  19 == Usage ==
  20
  21 Experimental! Will change a lot.
  22
  23 {{{
  24 <<AnalyseAccessLogSql mode=<QUERY NAME> >>
  25 }}}
  26
  27 == Parameters ==
  28
  29 {| class="bordered"
  30 |-
  31 ! Argument
  32 ! Description
  33 ! Default value
  34 |-
  35 | **mode**
  36 | The name of the query to execute. See *Adding new queries* below. Required parameter.
  37 | referring_domains
  38 |-
  39 | **period**
  40 | Use in combination with the _count_ parameter. The type of history period to retrieve from the SQL access log. Blank (the default) for all history, or one of "*weeks*", "*days*", "*hours*", or "*minutes*".
  41 |
  42 |-
  43 | **count**
  44 | Use in combination with the _period_ parameter. Must be a number. The number of periods to retrieve from the access log.
  45 | 0
  46 |-
  47 | **caption**
  48 | The value of this parameter is used as the caption for the output. If not set, the caption on the table defaults to the mode.
  49 |
  50 |-
  51 | **center**
  52 | If set, the table is centered on the page, otherwise left justified.
  53 |
  54 |-
  55 | **debugShowQuery**
  56 | If set, the SQL will be displayed in the table footer. Useful while debugging new queries or just for interest.
  57 |
  58 |-
  59 | **user**
  60 | Blank (the default) to retrieve all users, or a specific user, or "*<NONE>*" for SQL access log entries with no user.
  61 |
  62 |-
  63 | **host**
  64 | Blank (the default) to retrieve all remote_hosts, or a specific host.
  65 |
  66 |-
  67 | **referrer**
  68 | Blank (the default) to retrieve all referrers, "*<NONE>*" to retrieve entries with no referrer, otherwise any referrer that matches this parameter, truncating longer referrers before matching. So a parameter of referrer='~http://localhost' will match '~http://localhost/wiki/index.php', '~http://localhost/wiki/index.php/~HomePage' etc.
  69 |
  70 |-
  71 | **local_referrers**
  72 | If set (the default), return all referrers. If not set, return only external referring sites, excluding references from within the wiki.
  73 | true
  74 |}
  75
  76 == Adding new queries ==
  77
  78 The file ##lib/plugin/~AnalyseAccessLogSql.php## contains a default set of queries against the SQL access log.
  79 Feel free to change this file to suit your own needs, but please note that this requires filesystem access to the web server where ~PhpWiki is running.
  80 In particular, this file may need to be modified to correctly query databases other than MySQL.
  81 The queries supplied by default are: "*Referring URLs*", "*Referring Domains*", "*Remote Hosts*", "*Users*" and "*Host Users*".
  82
  83 To add a new query, add a new section towards the end of the file, using one of the existing queries as a template. An example of an existing query is:
  84 <pre>
  85 } elseif ($mode=="Users") {
  86     $query = "SELECT "
  87         ."remote_user AS User, "
  88         ."count(*) AS 'Access Count' "
  89         ."FROM $accesslog "
  90         .($whereConditions ? 'WHERE '.$whereConditions : '')
  91         ."GROUP BY User";
  92 </pre>
  93
  94 If you do add a query, please consider contributing it back to the ~PhpWiki project at http://sourceforge.net/projects/phpwiki
  95
  96 == API for ~AnalyseAccessLogSql ==
  97
  98 * input arguments:
  99   - *$mode* contains the name of the query requested in the plugin parameters.
 100   - *$accesslog* contains the qualified name of the accesslog table, which may or may not be equal to "accesslog".
 101   - *$whereConditions* contains the conditions (specific user, etc.) requested in the plugin parameters.
 102
 103 * output:
 104   - *$query* must contain the final SQL query to be executed.
 105
 106 * conventions:
 107   - While constructing the query string,
 108     * each clause is on a separate line and
 109     * each clause contains the required trailing punctuation or space.
 110   - The mode parameter is, by default, displayed as the caption in the final output, so please choose a user friendly name.
 111   - The column names displayed on the wiki page are generated from the SQL column names defined in the queries, so please choose user friendly names. MySQL allows column names to include spaces.  If spaces are not allowed, then "*_*" is probably the next best choice.
 112
 113 * language hints for PHP newbies - please remember:
 114   - terminate statements with "*;*",
 115   - assignment uses "*=*" and comparison uses "*==*",
 116   - concatenate strings using the "*.*" operator,
 117   - the parentheses around the expression "*=($whereConditions ? 'WHERE '.$whereConditions : '' )=*" are essential,
 118   - strings enclosed in single quotes may not contain substrings enclosed in single quotes (actually the truth is more complex but let's leave it like that here), and
 119   - strings enclosed in double quotes will evaluate and replace variable names so that, for example, *"FROM $accesslog "* might be evaluated to *"FROM phpwiki_accesslog "*.
 120
 121 == Authors ==
 122 * [[PhpWiki:CharlesCorrigan|Charles Corrigan]]
 123 * Changes by [[Help:Reini Urban|Reini Urban]]
 124
 125 <noinclude>
 126 ----
 127 [[PhpWikiDocumentation]] [[CategoryWikiPlugin]]
 128 </noinclude>