[Savannah-hackers-public] Savannah/savane's PHP configuration, content files and UI structure

[Assaf Gordon]

Hello all,

Here's some more technical information about savannah's php UI structure, for future developers (and future me). These should complement the existing information in http://savannah.gnu.org/maintenance/RunningSavaneLocally/ .

The repository is  

  http://git.savannah.gnu.org/cgit/administration/savane.git

  git://git.sv.gnu.org/administration/savane.git

PHP code is in <savane>/frontend/php .

On 'frontend.sv.gnu.org', the code is in /usr/src/savane .

Configuration File Location

===========================

The environment variable SAVANE_CONF determines the location of the main configuration file.

It could be set in Apache's configurations file (/etc/apache2/sites-available/sv.inc)

or in '.htaccess' files (/usr/src/savane/frontend/php/.htaccess):

      SetEnv SAVANE_CONF /etc/savane

This variable is used in <savane>/frontend/php/include/init.php to read a hard-coded file named '.savane.conf.php' from the specified directory.

'init.php' also seems to accept a fall-back variable SV_LOCAL_INC_PREFIX, e.g.:

   sites-available/sv.nongnu.inc:SetEnv SV_LOCAL_INC_PREFIX /etc/savane/nongnu-conf

** On current production savannah, none of these are defined for the gnu side **

The code in 'init.php' falls back to:

  # go back to default location
  if (file_exists('/etc/savane/.savane.conf.php'))
    include('/etc/savane/.savane.conf.php');

Configuration File content

==========================

    # cd /etc/savane

    # ls -la
    -rwxr-x---  1 root  www-data    950 Aug  9  2015 .savane.conf.php
    -rw-r--r--  1 root  root     127632 Sep 10 22:03 cgitrepos
    drwxrwsr-x  5 68632     5038   4096 Jun  1  2013 content
    drwxr-xr-x  2 root  root       4096 Dec 18  2010 nongnu-conf
    -rwxr-x---  1 root  www-data   8426 Aug  9  2015 savane.conf.pl
    -rw-r-----  1 root  www-data     82 Aug  9  2015 savane.ini
    -rw-r-----  1 root  www-data      9 Dec 18  2010 savane.pass
    drwxr-xr-x  2 root  root       4096 Jun 28  2007 test-conf

The files must be group-readable by apache (www-data user).

Some of the content of the php configuration file:

    # cat .savane.conf.php 
    <?php
    $sys_default_domain="savannah.gnu.org";
    $sys_https_host="$sys_default_domain";
    $sys_brother_domain="savannah.nongnu.org";
    $sys_dbhost="x.x.x.x";
    $sys_dbname="xxxx";
    $sys_dbuser="xxxx";
    $sys_dbpasswd=rtrim(file_get_contents(dirname(__FILE__).'/savane.pass'));
    $sys_incdir="/etc/savane/content/gnu-content";

    ...

This file is included by every PHP file on savannah.

The directory pointed by '$sys_incdir' is used for fragments of

php code that is inserted at various pages (more on that below).

These variables are initialized to a default value in 'init.php',

and then '.savana.conf.php' is parsed and some default values are overridden.

Throughout the code, these variables are accessed using the php's '$GLOBAL' hash, e.g.:

    $ git grep sys_logo
    include/init.php:$sys_logo_name = 'floating.png';
    include/sitemenu.php:  if ($GLOBALS['sys_logo_name'])

    include/sitemenu.php:      print '          '.utils_link($GLOBALS['sys_home'],   

       html_image($GLOBALS['sys_logo_name'],array('alt'=>sprintf(_("Back to %s Homepage"),

       $GLOBALS['sys_name'])), 0));

    $ git grep sys_incdir

    include/init.php:$sys_incdir = '/etc/savane/content';

    [...]
    include/vars.php:require($GLOBALS['sys_incdir'].'/hashes.txt');

The above example of 'hashses.txt' (the list of licenses) is discussed in details in this thread:

  http://lists.gnu.org/archive/html/savannah-hackers-public/2016-09/msg00007.html

Textual 'content' files

========================

Throughout the code, there are calls to 'utils_get_content':

   $ git grep utils_get_content

   include/sitemenu.php:  utils_get_content("menu");

   index.php:utils_get_content("homepage");
   account/login.php:  utils_get_content("account/login");
   [...]

The function 'utils_get_content' is defined 'include/utils.php':

   # This function permit including site specific content with ease
   function utils_get_content_filename ($file) 
   {
      if (is_file($GLOBALS['sys_incdir'].'/'.$file.'.'.$GLOBALS['locale']))
        // there is localized version of the file :
        return $GLOBALS['sys_incdir'].'/'.$file.'.'.$GLOBALS['locale'];
      elseif (is_file($GLOBALS['sys_incdir'].'/'.$file.'.txt'))
       return $GLOBALS['sys_incdir'].'/'.$file.'.txt';
      else
        return null;
   }

On the production site, these files are under '/etc/savane/content/gnu-content'

(based on '$sys_incdir' defined in '/etc/savane/.savane.conf.php).

Thus, when the php code calls 'utils_get_content("homepage")',

These are the relevant files:

    frontend:/etc/savane/content/gnu-content# ls -l homepa*
    -rw-r--r-- 1 root 5038 1922 Aug 17  2013 homepage.fr_FR.UTF-8
    -rw-r--r-- 1 root 5038 1516 Aug 17  2013 homepage.txt

** These are PHP files despite the '.txt' extension. They must be valid PHP code.

For some of these files, there's additional requirement of not generating ANY whitespace.

Such restrictions are mentioned in the comments in the files. **

The content directory (/etc/savane/content/gnu-content) is structured similarly

to the PHP code. Example (file list abbreviated for brevity):

     $ cd /usr/src/savane/frontend/php

     $ find  -iname "*.php"

     ./index.php

     ./my/groups.php
     ./my/index.php

     ./people/index.php

     ./account/index.php

     ./git/index.php

     $ cd /etc/savane/content/gnu-content

     $ find  -iname "*.txt"

     ./homepage.txt

     ./my/groups.txt
     ./my/items.txt

     ./people/index.txt

     ./account/login.txt

     ./git/index.txt

UI Structure examples

=====================

In the attached screenshots,

'.php' files are those under <savane>/frontend/php ,

'.txt' files are the content files in '/etc/savane/content/gnu-content'.

'$sys_variables' are those defined in '/etc/savane/.savane.conf.php' (or default values in ./frontend/php/include/init.php' ).

comments welcomed,

 - assaf