sifbuilder is and Open Source program to create web sites. It lists, downloads and installs PHP components. Normally, these PHP components are wcm cores, modules, blocks and themes. It may backup and restore a web site and synchronize it with the packages registered in the update server. Complementing the automatic generation of web sites, it includes a module generator that generates the code of a functional module on the basis of the declarative definition of a relational schema.

Instructions may be passed to the program as script parameters or in a declarative xml file available either locally or via a url.

The basic components of the installation process are the sif packages -a sif package is referred to as a sip- containing the logic to download, explode, copy, activate and configure modules, blocks and themes to build the target site.

To abstract the building process, sifbuilder relies on the SIF framework that implements an API to common installation and configuration functions. These, available via the site object avaliable from each installation package, are implemented as classes covering module, block, panel and theme objects. Each installation package may extend the common API within thier own sip and export them form a dao. Currently, frameworks exist for PostNuke, OpenStar, XOOPS and MDPro. Cores that are automatically installed with sifbuilder but without a configuration API yet include drupal, joomla, sugarcrm, mantisbt and dotProject.

Sifbuilder may be used in the following scenarios.

php sifcmd.php i PostNuke07_core_postnuke

Will find the last release available for PostNuke, will download it from the package server and will install it in a site with parameters that will be prompted to the user.

php sifcmd.php b PostNuke07_script_intranet01

Will create a site with the packages specified in the build file for the PostNuke07_script_intranet01 sip. If the intention is to install the site onto the previously created instance, the command may be complemented with the -x option.

php sifcmd.php b PostNuke07_script_sifmoduler

Will create a module according to the relational model described in PostNuke07_script_sifmoduler_0_0_2_build.xml.

php sifcmd.php b --sifpacksdir=../sifpacksdir --sifnetsite=sis_sbos_at_localhost.xml 
--dev --reinstall OpenStar4_script_sifbuilderweb 
--buildfile=OpenStar4_script_sifbuilderweb_0_0_2_build_siftheme.xml

Will create, in forced mode and with pod pre-cleaning, a site as defined in OpenStar4_script_sifbuilderweb_0_0_2_build_siftheme.xml according to the site definition in sis_sbos_at_localhost.xml

php sifcmd.php b XOOPS2_core_xoops --sifnetsite=sbx2_at_localhost

Will create a core xoops site pre-cleaning the site database and filesystem if exist.

php sifcmd.php b XOOPS2_script_sif

Will create a composite xoops site as defined inthe xml build file in the XOOPS2_script_sif sip directory.

The main purpose of sifbuilder is to create a fully operational and configured web site with a single command instruction following the specifications in an xml site definition file.

It is still possible to install modules or blocks, apply themes or create module entities, such as publications or topics, on an existing web site.

In general, the sifbuilder process may be read as follows:

The general program usage is

php sifcmd.php [sifaction] [params] [sips]

A sifaction, or sifop, corresponds to a methods of the SifApi class. An important subset of these functions apply to sips and are aimed to transpose, transfer, install, remove, update or build packages onto sites. Some sif actions, however, refer to the program or to the site and do not require specification of sips as parameters.

params may be siteParams that refer to the usual parameters that determine the site to be generated and runParams that influence the way in which the program is run. Syntactically they are identical and siteParams could be considered as a subset of runParmas. However, siteParams may be specified other than as command options and are addressed separately in the code.

sip(s) are installation packages associated to PHP programs, modules, themes, blocks or scripts that encapsulate the generative logic. sips have associated specific sipParams that are defined from the .rcd file in the sip directory.

Besides the runParams, the siteParams and the sipParams, the configParams defined at the sifConfigParmas.php file complete the group of parameter sets that define the execution context and conform the behavior of the program.

Details of options are listed with # php sifcmd.php

sif actions are normally indicated as the first parameter in the command line following the sifcmd.php script file. They correlate to public methods in the SifApi class (preceeded by the 'sif_' prefix) and may correspond also to sip functions (proceeded by the 'sip_' prefix) in the sip classes.

The siteParams define the target site that sifbuilder will create or configure. siteParams may be passed as options to the sifbuilder script. The following command will install the PostNuke core on the site defined by the parameters in the instruction:

php sifcmd.php i --site_host=localhost --site_name=sifbuilder --site_pod=pn 
   --db_server=localhost --db_database=pn --db_prefix=pn --db_dbtype=mysql 
  --db_tabletype=myisam --db_username=root --db_password=pwd_root 
  --site_admin_username=admin --site_admin_password=pwd_admin 
  --dir_fs_document_root=D:/htdocs/ --sys_temp=pnTemp --encodedpwd=1
  --enable_ssl=0 PostNuke07_core_postnuke
        

These parameters may also be set interactively and saved to the sifSiteParams.xml file by the config_site sif action, then listed by show_config. Various sif actions will directly call config_site and invite the use to set the site configuration params.

The following table lists the site parameters, which are normally used to build the configuration file in a new installation and to accreditate the program as admin within an existing site to preform the installation tasks:

The siteParams are dependent of the core web content management system or modular PHP application. The following table shows typical parameters with some wcms.

A sample siteParams file, that should be customized for each wcm site, is:

<xml>    
  <site_host>localhost</site_host>    
  <site_name>sifbuilder</site_name>    
  <site_pod>os2</site_pod>    
  <db_server>localhost</db_server>    
  <db_database>os2</db_database>    
  <db_prefix>os_</db_prefix>    
  <db_dbtype>mysql</db_dbtype>    
  <db_tabletype>myisam</db_tabletype>    
  <db_username>root</db_username>    
  <db_password>pwd_root</db_password>    
  <site_admin_username>admin</site_admin_username>    
  <site_admin_password>pwd_admin</site_admin_password>    
  <dir_fs_document_root>d:/htdocs/</dir_fs_document_root>    
  <sys_temp>pnTemp</sys_temp>    
  <encodedpwd>1</encodedpwd>    
  <enable_ssl>0</enable_ssl>    
  </xml>
             

An option not to configure the siteParams each time that sample siteParams file, that should be customized for each wcm site, is to refer to the properties defined in a site class in sifnet_config_local.php or sifnet_config.php, if the local file has not been created. Thus,

php sifcmd.php i --sifnetsite=sbpn07_at_localhost PostNuke07_core_postnuke
        

will create a site wit hthe parameters defined in the sbpn07_at_localhost class. Those parameters may be passed also via a file. Thus,

php sifcmd.php i --sifnetsite=file://sbpn07_at_localhost.xml PostNuke07_core_postnuke
        

will take the siteParams from the local sbpn07_at_localhost.xml. The uri may refer to a xml file on the net:

php sifcmd.php i --sifnetsite=http://www.sifbuilder.com/downloads/sbpn07_at_localhost.xml 
               PostNuke07_core_postnuke
        

runParams are options that influence the behavior of the sifbuilder program. When passed in the command line they may either be switches, in the form of -s or --switch that set an option to true or false, or as parameters as --runParam=value. The runParams switches are the following:

Some switches are sometimes referred to as modifiers. The reason for this terminological distinction is that, when passed to the program, modifiers have a particularly strong impact on the behavior of the program. They are not inherited when there is a possibility of recursivity.

The modifiers have to do with the pre-removal of a site: clean_site, clean_pod, empty_site and empty_pod; with the forced installation of a package even if it appears as already installed: reinstall; the addition of dependencies to the list of packages to process: complete; and with the run mode that eliminates interaction with the user: force .

The list of runParams, i.e.. of the options that are passed to the program with a value, excluding the siteParams, are:

The installation of site components -modules, blocks, themes- is done by the sif packages (sips), usually on the basis of site packages that may have been downloaded from the servers where they are hosted. sips are composed of at least two files, a xml file ('sipRelease_rcd.xml') describing the package record, and a php file ('sipRelease_sip.php') that implements the processing logic.

sips usually contain a third component, xml files called build files, that encapsulate the logic to integrate a module into a target site. The build files are used by the sip_build_site sif action, which, by default, employs build file named sipRelease_build.xml, where sipRelease corresponds to the identifying name of the sip. Others may be included with the sip and referred to using the --buildfile=value runParam.

For most functions in sifbuilder, site packages including wcm cores, modules, blocks, themes and plugins, are normally downloded, exploded, transferred to the site directory, installed, activated and configured.

Ideally, the package is downloaded from the original download server. Then, it is exploded into the sifpacks directory. By default, if the tar ball is present, the download stepped is bypassed. Similarly, if the corresponding directory in the sifpacks directory is not empty, the package is not exploded. The transpose action, that includes the download and uncompression, is implied by default by the install action. This default behaviour may be modified with options such as --get, that forces the download of the site package, --exploded, that forces the decompression of the tar ball. The integrity of the files is controlled by the md5 signature that is defined at the moment in which the package is registered by sif.

The transcripts related to the core files mirror the 'example' module. However, to generalize the classes associated to entities, the generated pnuserapi. and pnadminapi.php files simply contain the user and admin apis for each of the tables in the relational schema.

Data manipulation functions implemented as sql instructions. It would be possible to generate them as object methods.

The main core transcripts and the functions in the files or classes that they generate are the following.

Template transcripts generate the xanthia templates that called by pnRender. The are grouped by scope, appl or table, and by permissions, admin or user.

Sip functions may be called form buildFiles. The PostNuke07_script_sifmoduler_0_0_2_build_example.xml build file contains the declaration of a module comparable to the 'example' module included in the PostNuke distribution.

The module, that will be named sifExample as defined in the declarative file, may be generated with the following instruction.

The sips available in the local distribution of sifbuilder may be listed with the list_sips sif action.

php sifcmd.php list_sips

The sips available in the update server may be listed with the rlist action and download with rsync to the local environment.

php sifcmd.php rlist

A script refers to an xml file that contains instructions associated to sips. When this file plays the main role of a sip the sip itself is considered as being of type script. Every sip may have associated one or more buildFiles and be run with the sip_build_site action associated to that sip, eventually with the --buildfile to specify an alternative buildFile. In may contexts, script and buildFile may be used indistinctively.

buildFiles may have a full mode and a reduced one. When specified in full mode, a buildFile starts with the sip_build_site xml element directly under the xml document element. This element may contain ore or more site elements, each one eventually with its own runParams and therefore with its own siteParams. The purpose of providing this option is to support the installation of sites including various cores, such as PostNuke and sugarcrm, that may be correlated, such as with pnSugar.

Besides the runParams, which otherwise are inherited from the command line, a site element must have a sips sub-element that will itself contain a number of elements corresponding to sips resident in sifbuilder. Each sip contains a buildParams element that will contain the functions and arguments specific to that sip. As a result, a possible chain of xml elements would be: xml, sip_build_site, site, sips, PostNuke07_core_postnuke, buildParams.

In their simplified mode, the contents of build files correspond to the contents of the buildParams element in the general model.

The following are examples of build files associated to script-type sips that encapsulate many of the functions and possibilities of sifbuilder. The sip associated to the script is usually derived from the name of the script itself. They may be run with the instruction: php sifcmd.php sip_build_site sip --buildfile=script

net functions are the methods of a sif relation. A sif relation is composed of a lochost, a nethost and a connection. net functions may be of three types: actions from a lochost to the nethost, such as upload; from the nethost to the lochost, such as download; or at the nethost, such as a sif action on the nethost. They are built according to the type of the hosts (linux or windows) and of the connection (local windows or linux, ssh2key windows or linux and ssh2key or linux).

Calls to net functions are normally included in use cases. Use cases are usually defined as a combination of sif actions to be run in a nethost with specific runParams. The most important nefunction is sifnet_sifop_run that will remotely execute a sif action on a nethost. Others may support the installation and update of sifbuilder in a remote host.

usecases are functions in the sifnet_usecases.php file that normally create a sifrelation and call a series of net functions. The major different from running sifops directly from the command line, apart from the fact that various actions may be serialized, is the possibility to predefine the lochost and the nethost, so that a sif action directly may be run on a remote host.

Besides this, the purpose of the usecases, that originally were named testcases, is to list functions to be run and tested before releasing a new version of sifbuilder.

use cases may be listed with: # php sifcmd.php list_usecases

The general syntax to call a use case is:

php sifcmd.php run_usecase [options] {usecase}

Except for the modifyers, the runParams passed to the command line are parameters passed to the use case. Some parameters are specific to the execution of use case and particularly relevant.

Since lochost and nethost run params are defaulted to devhost and localhost in sifConfigParmams, use cases will not run properly if localhost has not been defined properly in sifnetconfigfile. For admin sifops, such as build_program, nethost should not be set to devhost. However, for normal site operations, the easiest way to run usecases may be to set devhost in sifnetconfigfile depending of the os and run run_usecase with --sifnethost=devhost.

build a sip on a site

A typical usecase corresponds to the application of the sip_build_site sifop to a sip, in this case to a script sip. In fact, since scripts usually cover multiple sips, checking the scripts is a good method to check the consistency of the program. Besides this, scripts are usually intended to build complete sites. Therefore, they constitute a section the usecases file. The example that is listed below refers to the creation of a commerce site with the shop module. The usecase should be run as follows:

php sifcmd.php run_usecase --siflochost=devhost --sifnetsite=sbpn07_at_localhost --sifnethost=devhost -f tc6201

In this case, the use case tc6201 is run on the nethost defined by the class 'localhost' with siteParams defined in the class 'sbpn07_at_localhost'. This is the code of that usecase:

  function tc6201($args=array()) 
  {	
    $desc = 'PostNuke07_script_commerce01 based on PostNuke07_mod_shop';
    SifDebug::info($desc,__FUNCTION__  . '::');
    if ($args['runParams']['op'] == 'sif_run_usecase') {
        $usecaseParams = array();
        $usecaseParams['sifop'] = 'sip_build_site';
        $usecaseParams['options'] = ' --dev ';
        $usecaseParams['sips'][] = 'PostNuke07_script_commerce01';
        $args['usecaseParams'] = $usecaseParams;
        $args['runParams']['sifpacksdir'] = '../sifpacksdir';
        $sifnet_relation = sifnet_relation_factory::sifnet_get_sifnet_relation($args);
        $sifnet_relation->sifnet_sifop_run();
    }
  }

Functions corresponding to usecases usually start by a call to the info debug that is run with the list_usecase sifop. Then there is a procedural part that is called by the 'run_usecase'

Install PostNuke and install/remove/update a module

This usecase installs the latest available version of PostNuke after having removed the file system and database environment of the target site. Afterwards, It will install a module, specifically Netquery, then remove it, then install it again and finally upgrade it to the latest avalable version.

     function tc1117($args=array()) 
  { 
    $desc = 'pn/remove/install/upgrade noupd - PostNuke07_mod_netquery';
    SifDebug::info($desc,__FUNCTION__  . '::');
    if ($args['runParams']['op'] == 'sif_run_usecase') {
      $usecaseParams = array();
      $usecaseParams['sips']=array();
      $usecaseParams['sifop']='sip_install_site';
      $usecaseParams['options'] = $options . ' --emptypod ';
      $usecaseParams['sips'][]='PostNuke07_core_postnuke';
      $args['runParams']['sifpacksdir'] = '../sifpacksdir';
      $args['usecaseParams'] = $usecaseParams;
      $sifnet_relation = sifnet_relation_factory::sifnet_get_sifnet_relation($args);
      $sifnet_relation->sifnet_sifop_run();
    
      // build
      $usecaseParams['sips']=array();
      $usecaseParams['sifop']='sip_build_site';
      $usecaseParams['options'] = $options . ' --dev ';
      $usecaseParams['sips'][]='PostNuke07_mod_netquery';
      $args['runParams']['sifpacksdir'] = '../sifpacksdir';
      $args['usecaseParams'] = $usecaseParams;
      $sifnet_relation = sifnet_relation_factory::sifnet_get_sifnet_relation($args);
      $sifnet_relation->sifnet_sifop_run();
    
      // remove
      $usecaseParams['sips']=array();
      $usecaseParams['sifop']='sip_remove_site';
      $usecaseParams['options'] = $options . ' ';
      $usecaseParams['sips'][]='PostNuke07_mod_netquery';
      $args['runParams']['sifpacksdir'] = '../sifpacksdir';
      $args['usecaseParams'] = $usecaseParams;
      $sifnet_relation = sifnet_relation_factory::sifnet_get_sifnet_relation($args);
      $sifnet_relation->sifnet_sifop_run();
    
      // build
      $usecaseParams['sips']=array();
      $usecaseParams['sifop']='sip_build_site';
      $usecaseParams['options'] = $options . ' --noupd ';
      $usecaseParams['sips'][]='PostNuke07_mod_netquery_3_1';
      $args['runParams']['sifpacksdir'] = '../sifpacksdir';
      $args['usecaseParams'] = $usecaseParams;
      $sifnet_relation = sifnet_relation_factory::sifnet_get_sifnet_relation($args);
      $sifnet_relation->sifnet_sifop_run();
    
      // upgrade
      $usecaseParams['sips']=array();
      $usecaseParams['sifop']='sip_upgrade_site';
      $usecaseParams['options'] = $options . ' --dev ';
      $usecaseParams['sips'][]='PostNuke07_mod_netquery';
      $args['runParams']['sifpacksdir'] = '../sifpacksdir';
      $args['usecaseParams'] = $usecaseParams;
      $sifnet_relation = sifnet_relation_factory::sifnet_get_sifnet_relation($args);
      $sifnet_relation->sifnet_sifop_run();
    }
  }

Before running this usecase, it is fundamental to check a number of issues. Because of the way in which sifcmd.php is run, the current working directory must be the sifbuilder program root. The usecase assigns the value '../sifpacksdir' to the sifpacksdir runParam. This means that the packages that will be downloaded, in particular the PostNuke core and the various versions of the module, will be placed in a sibling directory. Thus, if the current working directory in win is d:/sifbuilder_1_0_0, the site packages will be downloaded to d:/sifpackages.

The first part of the use case calls the sip_install_site sifop with the PostNuke07_core_postnuke sip. This will install the PostNuke core. If necessary, the corresponding site package will be downloaded and uncompressed. Before creating the sifnet_relation, that will construct the sif instructions, the --emptypod is set. This means that the pod where the site will be created will be first remove and its database emptied.

Since there is no reference to the siteParmas, the default applies. This means that both lochost and nethost are assigned to devhost. The sifnetsite is associated to sbpn07_at_localhost. devhost and sbpn07_at_localhost are two classes defined at sifnet_config_local.php or, if this file does not exist in the sifbuilder root, defaulted in sifnet_config.php

The --emptypod option, which is synonym of -x, implies that the site pod directory of the nethost (as defined in the sifnetconfigfile) will be removed and its database emptied.

Then , the sip_build_site sipop will get and install the site package corresponding to the sip, in this case Netquery. Then, the sip_remove_site sifop will remove the module.

In the second part of the usecase, sip_build_site is called again, this time with the --noupd option, that means that the legacy site package versions will be taken into account. Furher, the specific package version is specified: PostNuke07_mod_netquery_3_1. This means that version 3.1 of that module will be downloaded, if available, then installed and eventually configured.

Finnnaly, sip_upgrade_site will be called with the same sip but without specification of the site package version. Thus, the latest one available will be transfered. In fact, since the --dev option is set, also development versions of the module will be considered. Since a previous version of the module is installed on the site, the package upgrade function will be called.

This usecase will be run with th following command.

php sifcmd.php t tc1118 -f -v

The same result could be obtained with a series of direct calls to sifbuilder:

php sifcmd.php i -x PostNuke07_core_postnuke --sifpacksdir=../sifpacksdir --sifnetsite=sbpn07_at_localhost
php sifcmd.php b PostNuke07_mod_netquery --dev  --sifpacksdir=../sifpacksdir --sifnetsite=sbpn07_at_localhost
php sifcmd.php r PostNuke07_mod_netquery --sifnetsite=sbpn07_at_localhost
php sifcmd.php b PostNuke07_mod_netquery_3_1 --noupd  --sifpacksdir=../sifpacksdir --sifnetsite=sbpn07_at_localhost
php sifcmd.php u PostNuke07_mod_netquery --dev --sifpacksdir=../sifpacksdir --sifnetsite=sbpn07_at_localhost

The sif framework includes the following objects.

sif packages usually go through the following operations

The installation action may be divided into initialization and activation. Activation of a theme usually means making it the default one. Activation of a block usually means making it visible.