[Sommaire] [Imprimer]

   1  
   2  
   3  eGroupWare Setup
   4  
   5  June 18, 2001 
   6  Updated May 9, 2003
   7  
   8  
   9  Abstract
  10  
  11  A developer introduction to using the next generation setup
  12  application for egroupware.
  13  
  14  1 Introduction
  15  
  16  1.1 Welcome
  17  
  18  Thanks for taking the time to look over this document. If
  19  you are a developer who is new to egroupware, this document
  20  will be invaluable to your success during the life of your
  21  application. This is in addition to the other fine documentation
  22  available in the phpgwapi/doc directory in your install.
  23  Even long-time phpgw developers should benefit this document.
  24  Herein, I will attempt to outline the critical steps required
  25  in order to get along with setup3, setup-TNG, or whatever
  26  we end up calling it (Hey, how about 'setup'?)
  27  
  28  1.2 Overview
  29  
  30  With setup3, we introduce several new capabilities and technologies
  31  for the developer and end user alike. Michael Dean was kind
  32  enough to offer up schema_proc to form the core of an abstracted
  33  and database-independent upgrade process. This enables developers
  34  to write a single set of upgrades and table definitions,
  35  which should then work on MySQL and PostgreSQL, or any other
  36  database type we might add in the future.
  37  
  38  Adding to this to control the process was a good chunk of
  39  the old setup program, written by Dan Kuykendall (Seek3r).
  40  Dan had everything to do with the new dependencies support
  41  and with the format of the $setup_info array in setup3.
  42  
  43  Setup3 adds multi-language support for the setup application,
  44  a long missed feature, I would imagine.
  45  
  46  Setup3 gives each application developer control over their
  47  application install and upgrade processes, while giving
  48  them access to work within a realm formerly owned by only
  49  the former core egroupware applications. Yes, this is
  50  extra work for the developer. But it is hoped that setup3
  51  is also viewed as a tool that can truly enhance the development
  52  process.
  53  
  54  OK. Let's dive right in...
  55  
  56  2 Application setup files
  57  
  58  The files in this section are contained within each application/setup
  59  directory. Every app will some of these files in order to
  60  operate with setup3.
  61  
  62  2.1 setup.inc.php (Required)
  63  
  64  2.1.1 Basic information
  65  
  66  The values in this section must be used by all applications.
  67  
  68  The first section of setup.inc.php defines the very basic
  69  and yet critical information about the application. Take
  70  a look at the following section:
  71  
  72  $setup_info['addressbook']['name'] = 'addressbook';
  73  
  74  $setup_info['addressbook']['title'] = 'Addressbook'; - Deprecated .0.9.16+
  75  
  76  $setup_info['addressbook']['version'] = '0.9.13.002';
  77  
  78  $setup_info['addressbook']['app_order'] = 4;
  79  
  80  $setup_info['addressbook']['enable'] = 1;
  81  
  82  'name' is used throughout egroupware, typically in $phpgw_info
  83  flags such as 'currentapp' or as the 'app_name' almost everywhere
  84  else.
  85  
  86  'title' is now deprecated.  Now simply include an entry like this 
  87  in the lang file for you application:
  88  addressbook en common Address Book
  89  
  90  The 'version' string defines the version of the application
  91  and table code. This would be incremented whenever you create
  92  a new upgrade function, and typically only for table modifications.
  93  If the change is significant from the last code update,
  94  you could increment this here also. Incrementing this version
  95  string is not trivial, so please do read the rest of this
  96  document for more information about that.
  97  
  98  'app_order' determines the order of applications in the navbar.
  99  If the number you set here is the same as is set for another
 100  app, the app whose 'name' is first in the English alphabet
 101  would appear first. Smaller numbers show closer to the top
 102  or left end of the navbar, depending upon the layout.
 103  
 104  The 'enable' string is used by the egroupware API to determine
 105  whether an application is disabled, enabled, or enabled
 106  but hidden from the navbar. Most applications will want
 107  this set to a value of 1 (enabled). The notifywindow app
 108  sets this to 2, which keeps it off the navbar. An enable
 109  of 0 would disable the app by default. There is one other
 110  special case, 3, which is used primarily by the API itself.
 111  From the perspective of setup3, the API is an application
 112  just like any other application. By setting the 'enable'
 113  flag to 3, the API is still enabled, but will not be assignable
 114  to a user as a real application. It will thereby be hidden
 115  from the admin for application and user/group editing.
 116  
 117  2.1.2 Table info
 118  
 119  Only applications with database tables will use entries
 120    in this section.
 121  
 122  The next section of $setup_info values is an array defining
 123  all of the application's database tables:
 124  
 125  $setup_info['addressbook']['tables'] = array(
 126  
 127      'phpgw_addressbook',
 128  
 129      'phpgw_addressbook_extra'
 130  
 131  );
 132  
 133  This is a simple array, and must list accurately the current
 134  table names you are using in your application. This list
 135  will match a much more complex array of table specifications,
 136  as you will see below.
 137  
 138  2.1.3 Hooks
 139  
 140  Some applications will use this section.
 141  
 142  The hooks array part of $setup_info contains a simple list
 143  of hooks the application will use:
 144  
 145  $setup_info['addressbook']['hooks'][] = 'preferences';
 146  
 147  $setup_info['addressbook']['hooks'][] = 'admin';
 148  
 149  Here we also note a different method of 'stuffing the array.'
 150  In any case, this list of hooks will be required soon in
 151  order for your hook_admin.inc.php and other files to work.
 152  This is being done to cut down on the manual directory listing
 153  and file_exists loops done currently to discover hook files.
 154  Other than 'preferences' and 'admin', 'home', 'manual',
 155  'after_navbar' and 'navbar_end' are all valid hook entries.
 156  
 157  2.1.4 Dependencies
 158  
 159  All applications will have at least one entry here.
 160  
 161  The final section, or array of data, is a listing of the
 162  other applications your application requires in order to
 163  function:
 164  
 165  $setup_info['addressbook']['depends'][] = array(
 166  
 167      'appname' => 'phpgwapi', 
 168  
 169      'versions' => Array(
 170  
 171          '0.9.10',
 172  
 173          '0.9.11',
 174  
 175          '0.9.12',
 176  
 177          '0.9.13'
 178  
 179      ) 
 180  
 181  );
 182  
 183  This is the standard dependency array for all egroupware
 184  applications. It states that this application requires the
 185  phpgwapi, and lists the versions with which versions this
 186  app is compatible. This list would need to be appended upon
 187  each new API release, assuming your application is compatible
 188  with this new API version. You may list other applications
 189  here, e.g. your app might depend upon 'email' in order to
 190  work properly.
 191  
 192  Do NOT list applications here without considering this: If
 193  you do list an application here, and your app does not really
 194  require it, your application will not install unless that
 195  other application is already installed. This is handled
 196  normally within the install/upgrade process loops, which
 197  will install only applications whose dependencies are satisfied.
 198  Using a multipass function, the applications are installed
 199  in the correct order to ensure that dependencies are resolved.
 200  In all cases, the API would be installed first in every
 201  new install or upgrade, since all applications depend on
 202  the API.
 203  
 204  2.2 tables_baseline.inc.php (Recommended)
 205  
 206  2.2.1 Any application that has at least one upgrade routine will
 207    have this file.
 208  
 209  The tables_baseline file represents the earliest supported
 210  version of an application's tables. This file is used only
 211  in the upgrade process, and is critical to its success.
 212  It contains an array of database-independent table, field,
 213  key and index definitions.
 214  
 215  This array is formatted for use by the class.schema_proc_array.inc.php
 216  file in setup3. See the tables_update section below for
 217  more detail about schema_proc, but for now, here is a simple
 218  table definition in this format:
 219  
 220  $phpgw_baseline = array(
 221  
 222      'skel' => array(
 223  
 224          'fd' => array(
 225  
 226              'skel_id' => array('type' => 'auto','nullable'
 227  => false),
 228  
 229              'skel_owner' => array('type' => 'varchar','precision'
 230  => 25),
 231  
 232              'skel_access' => array('type' => 'varchar','precision'
 233  => 10),
 234  
 235              'skel_cat' => array('type' => 'int','precision'
 236  => 4),
 237  
 238              'skel_des' => array('type' => 'text'),
 239  
 240              'skel_pri' => array('type' => 'int','precision'
 241  => 4)
 242  
 243          ),
 244  
 245          'pk' => array('skel_id'),
 246  
 247          'fk' => array(),
 248  
 249          'ix' => array(),
 250  
 251          'uc' => array()
 252  
 253      ) 
 254  
 255  );
 256  
 257  This multi-dimensional array contains 1 subarray with 5 subs
 258  of its own. The first array ('skel' above) defines the table
 259  name. Below that are 5 sections, 'fd' for field definitions,
 260  'pk' to define primary keys, 'fk' to define foreign keys,
 261  'ix' to define indexed fields, and 'uc' to define columns
 262  that require unique values. In the above example, the table
 263  'skel' has 6 fields (skel_id, skel_owner, skel_access, skel_cat,
 264  skel_des, skel_pri), and 'skel_id' is defined also as the
 265  primary key for this table. More information on this array
 266  is below. But, this format was chosen as an available solution
 267  for defining tables and fields without having to maintain
 268  seperate files for different databases.
 269  
 270  2.3 tables_current.inc.php (Recommended)
 271  
 272  2.3.1 All applications with tables will need this file.
 273  
 274  The tables_current file defines the current table definition
 275  that matches the 'version' string in $setup_info as well
 276  as the current code. This file is used only for new installs,
 277  or whenever the application is removed and reinstalled.
 278  The format and name of the array in this file is the same
 279  as for the tables_baseline file listed above. In fact, whenever
 280  it is required to change your table definitions, you would
 281  start by copying the current file over to become the tables_baseline
 282  file. After having created your upgrade routines, you would
 283  then recreate the current file to match the new table definitions.
 284  
 285  2.4 tables_update.inc.php (Recommended)
 286  
 287  2.4.1 Any application which requires an upgrade to a previous
 288    version's tables will need this file.
 289  
 290  This file will be the most complex of all setup-oriented
 291  files with which you will be working. It will contain all
 292  upgrade functions capable of upgrading any possible version
 293  of your egroupware app. These upgrade routines roughly
 294  match the old setup program's upgrade functions, but the
 295  use of objects and the methods have changed dramatically.
 296  The simplest version upgrade routine would look like:
 297  
 298  $test[] = "0.9.3pre10";
 299  
 300  function addressbook_upgrade0_9_3pre10()
 301  
 302  {
 303  
 304      global $setup_info;
 305  
 306      $setup_info['addressbook']['currentver'] = '0.9.3';
 307  
 308      return $setup_info['addressbook']['currentver'];
 309  
 310  }
 311  
 312  This upgrade function merely updates the current version
 313  number. Note that there is not only an upgrade function,
 314  but also the setting of a value in the $test array. The
 315  name 'test' is a holdover from the old setup program, and
 316  is an arbitrary choice. However, this name must be used
 317  for the upgrade process to work. Prior to each of your upgrade
 318  functions, add the value of the previous version to $test.
 319  
 320  Now look at the function name. The name is important and
 321  should be structured as the application name and the version
 322  from which you are intending to upgrade. The '.'s in the
 323  version string are replaced with '_'.
 324  
 325  Inside the function, we global the $setup_info array. Next,
 326  we alter the version number in that array, for our application.
 327  Please be careful to specify YOUR application name here.
 328  The very last thing we do is to return this new version
 329  to the calling function. The upgrade process relies on the
 330  value returned, since it uses this directly to determine
 331  the new version. This may appear illogical on some level,
 332  but it does work. The reason for returning this value instead
 333  of a True or 1, etc. has to do with variable scope and lifetime.
 334  In this way, even the globaling of $setup_info inside the
 335  function may have little effect on the upgrade process.
 336  But, there may be values in this array you would want to
 337  use within the function. More on that later.
 338  
 339  There is one other variable you would need if doing any database
 340  operations here. If you global $phpgw_setup, you will then
 341  have access to db and schema_proc objects and functions.
 342  The objects of interest here are:
 343  
 344  * $phpgw_setup->oProc
 345  
 346  * $phpgw_setup->db.
 347  
 348  For most database work you should use the oProc object. This
 349  also has a db object that should be used for most standard
 350  phpgw API db class functions, including $db->query, next_record,
 351  num_rows, and f. The use of these for standard db operations
 352  is critical to the upgrade process. Schema_proc has a flag
 353  that can be set to determine what mode of upgrade we are
 354  in. This flag is set in the setup class during the upgrade
 355  process, and should not be altered locally.
 356  
 357  This flag is a decision on whether to alter the database
 358  or the schema_proc array. The tables_baseline file above
 359  is loaded by setup prior to running your upgrade routines.
 360  If the current installed version is greater than the current
 361  upgrade routine, we don't need to alter the database yet.
 362  But schema_proc instead alters the $phpgw_baseline array
 363  in memory. The maintenance of this array is done even when
 364  we do alter the database. Once our version number in the
 365  test array matches the currently installed version of an
 366  application, real work on the tables begins.
 367  
 368  'Why bother modifying this array at all', you may ask. The
 369  array must be maintained in order to keep current table
 370  definition status. This is used in some schema_proc functions
 371  when altering columns and tables. This is especially critical
 372  for pgsql schema_proc functions.
 373  
 374  By using the $phpgw_setup->oProc object for basic inserts
 375  and queries, we acheive the ability to run all upgrade functions
 376  in every upgrade cycle without actually altering the database
 377  until we reach the current version we actually want to upgrade.
 378  For example:
 379  
 380  $sql = "SELECT * FROM phpgw_addressbook_extra WHERE contact_name='notes'";
 381  
 382  $phpgw_setup->oProc->query($sql,__LINE__,__FILE__);
 383  
 384  while($phpgw_setup->oProc->next_record()) {
 385  
 386  We could have used $phpgw_setup->db or even a copy for the
 387  above activity. However, using the above method ensures
 388  that an array only upgrade does just that. If the flag was
 389  set in setup telling schema_proc to alter the array only,
 390  we do not want to touch the tables for inserts or selects
 391  yet. In this case, $phpgw_setup->oProc->next_record() returns
 392  False, and the loop is skipped. The $phpgw_baseline array
 393  does not know about table content, only table and field
 394  definitions.
 395  
 396  If the upgrade function containing this method is actually
 397  working on the tables (currentver <= the upgrade function),
 398  then next_record() is returned as the expected action of
 399  pulling the next row of data. Inside of this while loop,
 400  you can safely use $phpgw_setup->db, or preferably a copy,
 401  to do the insert/delete, etc you want to have happen here.
 402  
 403      $cid = $phpgw_setup->oProc->f('contact_id');
 404  
 405      $cvalu = $phpgw_setup->oProc->f('contact_value');
 406  
 407      $update = "UPDATE phpgw_addressbook set note='" . $cvalu
 408  . "' WHERE id=" . $cid;
 409  
 410      $db1->query($update);
 411  
 412      $delete = "DELETE FROM phpgw_addressbook_extra WHERE
 413  contact_id=" . $cid . " AND contact_name='notes'";
 414  
 415      $db1->query($delete);
 416  
 417  }
 418  
 419  $db1 is a copy of $phpgw_setup->db, to avoid potential conflicts
 420  with the rest of setup's db activities.
 421  
 422  In addition to the basic API db class functions, schema_proc
 423  introduces the following special functions:
 424  
 425  function DropTable($sTableName)
 426  
 427  function DropColumn($sTableName, $aTableDef, $sColumnName)
 428  
 429  function RenameTable($sOldTableName, $sNewTableName)
 430  
 431  function RenameColumn($sTableName, $sOldColumnName, $sNewColumnName)
 432  
 433  function AlterColumn($sTableName, $sColumnName, $aColumnDef)
 434  
 435  function AddColumn($sTableName, $sColumnName, $aColumnDef)
 436  
 437  function CreateTable($sTableName, $aTableDef)
 438  
 439  Please use these functions where appropriate in place of
 440  standard SQL CREATE, DROP, and ALTER TABLE commands. This
 441  will ensure that your upgrade script works for all supported
 442  databases.
 443  
 444  Of these functions, DropTable, RenameTable, and RenameColumn
 445  are pretty straightforward. Pass these the table names you
 446  wish to Drop/Rename, and schema_proc will handle the rest,
 447  including indexes and sequences, where applicable.
 448  
 449  The remaining functions require some explanation:
 450  
 451  * CreateTable:
 452  
 453  $phpgw_setup->oProc->CreateTable(
 454  
 455      'categories', array(
 456  
 457          'fd' => array(
 458  
 459              'cat_id' => array('type' => 'auto','nullable'
 460  => false),
 461  
 462              'account_id' => array('type' => 'int','precision'
 463  => 4,'nullable' => false, 'default' => 0),
 464  
 465              'app_name' => array('type' => 'varchar','precision'
 466  => 25,'nullable' => false),
 467  
 468              'cat_name' => array('type' => 'varchar', 'precision'
 469  => 150, 'nullable' => false),
 470  
 471              'cat_description' => array('type' => 'text',
 472  'nullable' => false)
 473  
 474          ),
 475  
 476          'pk' => array('cat_id'),
 477  
 478          'ix' => array(),
 479  
 480          'fk' => array(),
 481  
 482          'uc' => array()
 483  
 484      )
 485  
 486  );
 487  
 488  Does this look familiar? The array passed to CreateTable
 489  is in the format used also in tables_baseline and tables_current.
 490  Note a slight difference where the table name is being passed
 491  as a seperate argument. The second argument to the function
 492  is the table definition array, starting with 'fd'.
 493  
 494  * AddColumn:
 495  
 496  $phpgw_setup->oProc->AddColumn('phpgw_categories','cat_access',array('type'
 497  => 'varchar', 'precision' => 25));
 498  
 499  Here we pass the table name of an existing table, the new
 500  column name, and a field definition. This definition is
 501  merely a slice of the table arrays found earlier in this
 502  document.
 503  
 504  * AlterColumn:
 505  
 506  $phpgw_setup->oProc->AlterColumn('phpgw_sessions','session_action',array('type'
 507  => 'varchar', 'precision' => '255'));
 508  
 509  The format of this function matches AddColumn. It is also
 510  a simple case of passing the table name, field name, and
 511  field definition.
 512  
 513  * DropColumn:
 514  
 515  $newtbldef = array(
 516  
 517      "fd" => array(
 518  
 519          'acl_appname' => array('type' => 'varchar', 'precision'
 520  => 50),
 521  
 522          'acl_location' => array('type' => 'varchar', 'precision'
 523  => 255),
 524  
 525          'acl_account' => array('type' => 'int', 'precision'
 526  => 4),
 527  
 528          'acl_rights' => array('type' => 'int', 'precision'
 529  => 4)
 530  
 531      ),
 532  
 533      'pk' => array(),
 534  
 535      'ix' => array(),
 536  
 537      'fk' => array(),
 538  
 539      'uc' => array()
 540  
 541  );
 542  
 543  $phpgw_setup->oProc->DropColumn('phpgw_acl',$newtbldef,'acl_account_type');
 544  
 545  This is the most complicated function in schema_proc, from
 546  the user's perspective. Its complexity is necessitated by
 547  the requirement of some databases to recreate a table in
 548  the case of dropping a column. Note that the table definition
 549  array is being used yet again. The array defined here should
 550  match the table definition you want after this function
 551  has completed. Here, we are dropping the column 'acl_account_type'
 552  from the table 'phpgw_acl', and the table definition does
 553  not have this column defined. You could copy information
 554  from your tables_current file here and edit it to match
 555  the desired new table spec, less the column you wish to
 556  drop.
 557  
 558  There are additional functions within schema_proc, the majority
 559  of which are not to be called directly. They are used internally.
 560  If you do wish to investigate further, use class.schema_proc.inc.php
 561  as your guide. This master file includes the class.schema_proc_DBMS.inc.php
 562  and class.schema_proc_array.inc.php files. The DBMS files
 563  should not be used as a guide, since their functions are
 564  called from the master class, and the parameters are different
 565  from what you might expect relative to the master.
 566  
 567  PLEASE, DO NOT WRITE TO OR ALTER ANOTHER APPLICATION'S TABLES
 568  OR THE API TABLES IN YOUR APPLICATION UPGRADE FUNCTIONS!
 569  
 570  2.5 default_records.inc.php (Optional)
 571  
 572  2.5.1 Any application with tables that wants to load some default
 573    data will need this file.
 574  
 575  The default_records file consists of a list of SQL INSERTs
 576  using the $oProc object directly:
 577  
 578  $oProc->query("INSERT INTO phpgw_inv_statuslist (status_name)
 579  VALUES ('available')");
 580  
 581  $oProc->query("INSERT INTO phpgw_inv_statuslist (status_name)
 582  VALUES ('no longer available')");
 583  
 584  $oProc->query("INSERT INTO phpgw_inv_statuslist (status_name)
 585  VALUES ('back order')");
 586  
 587  In this case, the developer wanted to insert some status
 588  information, which was then used in a select box on an html
 589  form. Using the default_records file, every new install
 590  will have this data included. This file should consist of
 591  queries applicable to the tables defined in setup.inc.php
 592  and tables_current.inc.php.
 593  
 594  2.6 test_data.inc.php (Optional)
 595  
 596  2.6.1 Any developer wanting to test the full list of upgrade
 597    routines can use this file.
 598  
 599  test_data.inc.php is similar to default_records above. It
 600  is called only by schematoy.php and is never installed with
 601  a new install or upgrade. This is a developer-only file.
 602  The INSERTs here should be applicable to the tables_baseline
 603  table definitions.
 604  
 605  2.7 language files (Required)
 606  
 607  2.7.1 All applications should have at least a file of English
 608    translations, used for their application lang() calls.
 609  
 610  * Format of a lang file:
 611  
 612  {phrase}{TAB}{appname}{TAB}{LANG_CODE}{TAB}{translation}
 613  
 614      e.g:
 615  
 616  first name    common    en    First Name
 617  
 618  first name    common    de    Vorname
 619  
 620  * Filenames:
 621  
 622  phpgw_{LANG_CODE}.lang
 623  
 624    e.g.
 625  
 626  English: phpgw_en.lang
 627  
 628  German: phpgw_de.lang
 629  
 630  Please see the contents of the API 'languages' table for
 631  the correct setting of the LANG_CODE.
 632  
 633  3 Developer Tools
 634  
 635  3.1 sqltoarray.php
 636  
 637  3.1.1 Displays the current schema_proc array defining an application's
 638    tables.
 639  
 640  This web application reads the current table status live
 641  from the database. It then parses this information into
 642  a hopefully correct table definition array for schema_proc.
 643  Upon visiting this app, you are shown a list of currently
 644  installed applications with defined tables. You may then
 645  select one app or all apps, and then submit the form. From
 646  this form you may then download a tables_current file, suitable
 647  for commission to cvs. Please do check the format to make
 648  sure the definitions are correct.
 649  
 650  3.2 schematoy.php
 651  
 652  3.2.1 Runs the full cycle of upgrades, including optional test_data.
 653  
 654  This app is not beautiful, may bomb on you, and will definitely
 655  drop your application's tables. The display is similar to
 656  the user/admin tool, applications.php. You are shown a list
 657  of apps with tables. Select one app, and enter a target
 658  version. Upon submission of the form:
 659  
 660  * All application tables are dropped.
 661  
 662  * tables_baseline.inc.php is loaded.
 663  
 664  * test_data.inc.php is loaded
 665  
 666  * tables_update.inc.php is loaded.
 667  
 668  * a full application upgrade test begins.
 669  
 670  This will give a LOT of debugging output. Depending on your
 671  database, the process may take quite awhile. This tool should
 672  be considered as a destructive test of the full upgrade
 673  cycle. If the upgrade process is successful, you can then
 674  check the loaded test_data to see that it is still in place
 675  as expected after all the table modifications, etc. If not,
 676  it should be clear where the error has occurred. Look for
 677  the usual INVALID SQL warnings, among others.
 678  
 679  3.3 tools subdirectory
 680  
 681  3.3.1 some utilities for sql file conversion, etc.
 682  
 683  In the tools directory under setup3, there should be at least
 684  a couple of hopefully handy perl or shell scripts. These
 685  are for running on the commandline only, and might apply
 686  to converting SQL files into lang files, etc. They are not
 687  expected to be perfect, but might offer some assistance
 688  or ideas for additional utilities. Use these at your own
 689  risk or benefit.
 690  
 691  4 The install/upgrade process
 692  
 693  4.1 Overview
 694  
 695  4.1.1 Setup internal upgrade functions
 696  
 697  Setup uses a common set of functions for new installs and
 698  upgrades. These are implemented as multi-pass loops. For
 699  a single application install or upgrade, a single pass is
 700  done. For multiple application installs or upgrades, multiple
 701  passes are done automatically. The order of install in a
 702  mass install or upgrade is determined by application dependencies.
 703  The other determining factor is the order in which the application
 704  directories and setup.inc.php files are read from the filesystem.
 705  
 706  4.2 New installs
 707  
 708  4.2.1 Detection
 709  
 710  Each run of index.php or applications.php in setup3 first
 711  runs a set of detection routines. These read the data from
 712  each setup.inc.php file, and from the 'applications' or
 713  'phpgw_applications' table as appropriate, and only if one
 714  of these tables exists. This data is parsed into the $setup_info
 715  array. In this case, this array contains information about
 716  all applications. Based on the information gathered, a status
 717  flag is set to one of the following values:
 718  
 719  * U - Upgrade required/available
 720  
 721  * R - upgrade in pRogress
 722  
 723  * C - upgrade Completed successfully
 724  
 725  * D - Dependency failure
 726  
 727  * F - upgrade Failed
 728  
 729  * V - Version mismatch at end of upgrade
 730  
 731  * M - Missing files at start of upgrade (Not used, proposed
 732    only)
 733  
 734  Using this information, the setup logic in index.php determines
 735  what mode we are in. index.php is not capable of being selective
 736  about which application it found as being out of sync. It
 737  is designed only for 'Simple Application Management', which
 738  is Step 1 of the setup process. For more selective application
 739  manipulation, use applications.php. index.php then tells
 740  the user that 1) their applications are current 2) some
 741  of their applications are out of sync 3) no db exists, etc.
 742  For a new install, all applications will be out of sync,
 743  since there is not even an 'phpgw_applications' table in
 744  the database to tell setup what the status is for any application.
 745  
 746  4.2.2 Selection
 747  
 748  There is no selection for application installs in 'new install'
 749  mode. All physically present applications will be installed,
 750  or at least attempted.
 751  
 752  4.2.3 Installation
 753  
 754  Once the setup user clicks the magic button to install all
 755  applications, the following occurs:
 756  
 757  * The setup_info array is passed to the process_pass() function,
 758    using a method='new'
 759  
 760  * Applications whose status flag='U' (API on first pass)
 761    are then handed off to the process_current() function.
 762    This handles inclusion and installation of the application's
 763    tables_current.inc.php file.
 764  
 765  * The application is registered as a new application in the
 766    'phpgw_applications' table. If for some reason there is
 767    old data in this table for this application, it will be
 768    updated instead. Its hooks, if any, are registered in
 769    the 'phpgw_hooks' table.
 770  
 771  * Next, this array is passed to the process_default_records()
 772    function. If this file is present in the current application's
 773    setup directory, the queries here are run to install the
 774    data to the application's table(s).
 775  
 776  * The above is repeated until all application status flags
 777    equal 'C'. However, if an application install failed for
 778    some reason, it will then be skipped on the next pass.
 779    This keeps the loop from running away.
 780  
 781  4.3 Upgrades
 782  
 783  4.3.1 Detection
 784  
 785  Only an API version mismatch will trigger an automated request
 786  for the user to upgrade their install. Once the api is current,
 787  they can move on to applications.php for more 'Advanced
 788  Application Management', which is Step 4 of the setup process.
 789  However, if the API is out of sync, clicking 'Upgrade' in
 790  index.php will also attempt to upgrade other applications
 791  which may be out of sync, as well. As the phpgwapi continues
 792  to stabilize, it is felt that this method of upgrading will
 793  become less and less common.
 794  
 795  4.3.2 Selection
 796  
 797  Within applications.php, a color-coded matrix of application
 798  status and actions is displayed. Depending on the status
 799  flag of each application, certain actions will be either
 800  enabled or disabled. These actions include 'install', 'upgrade',
 801  'remove'. If something is very wrong with previous attempts
 802  to install or upgrade an application, another column called
 803  'resolution' will then display a link. This link will display
 804  additional information which would be helpful for determining
 805  how to resolve the problem. Assuming all is well, the user
 806  can select applications requiring upgrade from this list.
 807  Once selected, they submit the form. This runs the follow
 808  three routines in order:
 809  
 810  * remove
 811  
 812  * install
 813  
 814  * upgrade
 815  
 816  4.3.3 Upgrade
 817  
 818  The idea here is that multiple actions can be selected and
 819  run in order in one click. In any case, once they select
 820  an application for upgrade, the following occurs:
 821  
 822  * A stripped down version of the setup_info array is passed
 823    to the process_upgrade() function. This array contains
 824    only the information for the selected application
 825  
 826  * Within process_upgrade(), the tables_baseline.inc.php file
 827    for the application is loaded.
 828  
 829  * The tables_update.inc.php file for the application is loaded
 830  
 831  * The contents of the test array is used to loop through
 832    the entire list of upgrade functions for the application.
 833    The application's unique function names are rebuilt, then
 834    run.
 835  
 836  * When the currentver (installed) matches the version (available),
 837    process_upgrade() exits, setting the status flag for the
 838    app to 'C'.
 839  
 840  * Just prior to exiting, the application and its hooks are
 841    updated into the 'phpgw_applications' and 'phpgw_hooks'
 842    tables.
 843  
 844  4.4 Uninstallation/Removal
 845  
 846  4.4.1 Selection
 847  
 848  Selective removal of an application is done via applications.php,
 849  in a manner similar to the method above for upgrades.
 850  
 851  4.4.2 Uninstallation
 852  
 853  Once an application is selected for removal:
 854  
 855  * A stripped down version of the setup_info array is passed
 856    to the process_droptables() function. This function removes
 857    all of the application's defined tables, but only after
 858    first checking to see if the tables are there. In this
 859    way, we attempt to cut down on the number of errors sent
 860    to the browser.
 861  
 862  * The application's hooks are deregistered (removed from
 863    'phpgw_hooks').
 864  
 865  * The application itself is deregistered (removed from 'phpgw_applications').
 866  
 867  5 Caveats
 868  
 869  5.1 Must see info
 870  
 871  5.1.1 Auto fields
 872  
 873  For auto type fields, schema_proc creates a sequence automatically
 874  based on the table name for databases that require sequences.
 875  In the case of postgresql, the limit for this name based
 876  on our tests is 31 characters. The schema_proc format is:
 877  
 878  $sSequenceSQL = sprintf("CREATE SEQUENCE seq_%s", $sTableName);
 879  
 880  This limits the maximum length for a tablename to 27 characters.
 881  Based on the tablename standard in phpgw of 'phpgw_tablename',
 882  you are further limited to 21 characters in which to describe
 883  your table. You will need to be less descriptive in some
 884  cases, e.g. use 'phpgw_widget_cats' instead of 'phpgw_widget_info_categories'.
 885  
 886  To maintain compatibility with MySQL 3.22.X, please always
 887  add "'nullable' => False" to
 888  your field spec for an auto field. This and probably older
 889  versions of MySQL require that specification within the
 890  SQL for a field that will also be an index or unique field,
 891  which for our uses should typically be true for an auto
 892  field. MySQL 3.23.X and PostgreSQL do not have this issue.
 893  
 894  5.1.2 Default 0
 895  
 896  For int fields, a default of 0 is not assumed. Only some
 897  databases will set this default for you, MySQL being one.
 898  You will need to explicitly define this default in the table
 899  definition. Also, for auto fields, do not enter a default,
 900  since the resulting SQL query would fail on many RDBMS.