[Sommaire] [Imprimer]

   1  #LyX 1.1 created this file. For more info see http://www.lyx.org/
   2  \lyxformat 218
   3  \textclass docbook
   4  \begin_preamble
   5  <!entity header system "header.sgml">
   6  \end_preamble
   7  \language english
   8  \inputencoding default
   9  \fontscheme default
  10  \graphics dvips
  11  \paperfontsize default
  12  \spacing single 
  13  \papersize Default
  14  \paperpackage a4
  15  \use_geometry 0
  16  \use_amsmath 0
  17  \paperorientation portrait
  18  \secnumdepth 3
  19  \tocdepth 3
  20  \paragraph_separation indent
  21  \defskip smallskip
  22  \quotes_language english
  23  \quotes_times 2
  24  \papercolumns 1
  25  \papersides 1
  26  \paperpagestyle default
  27  
  28  \layout Title
  29  \added_space_top vfill \added_space_bottom vfill 
  30  eGroupWare Setup
  31  \layout Date
  32  
  33  June 18, 2001 
  34  \layout Author
  35  
  36  
  37  \latex latex 
  38  <firstname>Miles</firstname> <surname>Lott</surname>
  39  \layout Abstract
  40  
  41  A developer introduction to using the next generation setup application
  42   for egroupware.
  43  \layout Section
  44  
  45  Introduction
  46  \layout Subsection
  47  
  48  Welcome
  49  \layout Standard
  50  
  51  
  52  \series medium 
  53  Thanks for taking the time to look over this document.
  54   If you are a developer who is new to egroupware, this document will be
  55   invaluable to your success during the life of your application.
  56   This is in addition to the other fine documentation available in the phpgwapi/d
  57  oc directory in your install.
  58   Even long-time phpgw developers should benefit this document.
  59   Herein, I will attempt to outline the critical steps required in order
  60   to get along with setup3, setup-TNG, or whatever we end up calling it (Hey,
  61   how about 'setup'?)
  62  \layout Subsection
  63  
  64  Overview
  65  \layout Standard
  66  
  67  
  68  \series medium 
  69  With setup3, we introduce several new capabilities and technologies for
  70   the developer and end user alike.
  71   Michael Dean was kind enough to offer up schema_proc to form the core of
  72   an abstracted and database-independent upgrade process.
  73   This enables developers to write a single set of upgrades and table definitions
  74  , which should then work on MySQL and PostgreSQL, or any other database
  75   type we might add in the future.
  76  \layout Standard
  77  
  78  
  79  \series medium 
  80  Adding to this to control the process was a good chunk of the old setup
  81   program, written by Dan Kuykendall (Seek3r).
  82   Dan had everything to do with the new dependencies support and with the
  83   format of the $setup_info array in setup3.
  84  \layout Standard
  85  
  86  
  87  \series medium 
  88  Setup3 adds multi-language support for the setup application, a long missed
  89   feature, I would imagine.
  90  \layout Standard
  91  
  92  
  93  \series medium 
  94  Setup3 gives each application developer control over their application install
  95   and upgrade processes, while giving them access to work within a realm
  96   formerly owned by only the former core egroupware applications.
  97   Yes, this is extra work for the developer.
  98   But it is hoped that setup3 is also viewed as a tool that can truly enhance
  99   the development process
 100  \series default 
 101  .
 102  \layout Standard
 103  
 104  
 105  \series medium 
 106  OK.
 107   Let's dive right in...
 108  \layout Section
 109  
 110  Application setup files
 111  \layout Standard
 112  
 113  The files in this section are contained within each application/setup directory.
 114   Every app will some of these files in order to operate with setup3.
 115  \layout Subsection
 116  
 117  setup.inc.php (Required)
 118  \layout Subsubsection
 119  
 120  Basic information
 121  \layout Standard
 122  
 123  
 124  \series bold 
 125  The values in this section must be used by all applications.
 126  \layout Standard
 127  
 128  
 129  \series medium 
 130  The first section of setup.inc.php defines the very basic and yet critical
 131   information about the app
 132  \series default 
 133  lication
 134  \series medium 
 135  .
 136   Take a look at the following section:
 137  \layout Code
 138  
 139  
 140  \series medium 
 141  $setup_info['addressbook']['name'] = 'addressbook';
 142  \layout Code
 143  
 144  $setup_info['addressbook']['title'] = 'Addressbook';
 145  \layout Code
 146  
 147  $setup_info['addressbook']['version'] = '0.9.13.002';
 148  \layout Code
 149  
 150  $setup_info['addressbook']['app_order'] = 4;
 151  \layout Code
 152  
 153  $setup_info['addressbook']['enable'] = 1;
 154  \layout Standard
 155  
 156  
 157  \series medium 
 158  'name' is used throughout egroupware, typically in $phpgw_info flags such
 159   as 'currentapp' or as the 'app_name' almost everywhere else.
 160  \layout Standard
 161  
 162  
 163  \series medium 
 164  'title' would be used in the navbar, admin, preferences, as well as in the
 165   application itself.
 166  \layout Standard
 167  
 168  
 169  \series medium 
 170  The 'version' string defines the version of the application and table code.
 171   This would be incremented whenever you create a new upgrade function, and
 172   typically only for table modifications.
 173   If the change is significant from the last code update, you could increment
 174   this here also.
 175   Incrementing this version string is not trivial, so please do read the
 176   rest of this document for more information about that.
 177  \layout Standard
 178  
 179  
 180  \series medium 
 181  'app_order' determines the order of applications in the navbar.
 182   If the number you set here is the same as is set for another app, the app
 183   whose 'name' is first in the English alphabet would appear first.
 184   Smaller numbers show closer to the top or left end of the navbar, depending
 185   upon the layout.
 186  \layout Standard
 187  
 188  
 189  \series medium 
 190  The 'enable' string is used by the egroupware API to determine whether
 191   an application is disabled, enabled, or enabled but hidden from the navbar.
 192   Most applications will want this set to a value of 1 (enabled).
 193   The notifywindow app sets this to 2, which keeps it off the navbar.
 194   An enable of 0 would disable the app by default.
 195   There is one other special case, 3, which is used primarily by the API
 196   itself.
 197   From the perspective of setup3, the API is an application just like any
 198   other application.
 199   By setting the 'enable' flag to 3, the API is still enabled, but will not
 200   be assignable to a user as a real application.
 201   It will thereby be hidden from the admin for application and user/group
 202   editing.
 203  \layout Subsubsection
 204  
 205  Table info
 206  \layout Paragraph
 207  
 208  Only applications with database tables will use entries in this section.
 209  \layout Standard
 210  
 211  
 212  \series medium 
 213  The next section of $setup_info values is an array defining all of the applicati
 214  on's database tables:
 215  \layout Code
 216  
 217  
 218  \series medium 
 219  $setup_info['addressbook']['tables'] = array(
 220  \layout Code
 221  
 222      
 223  \series medium 
 224  'phpgw_addressbook',
 225  \layout Code
 226  
 227      
 228  \series medium 
 229  'phpgw_addressbook_extra'
 230  \layout Code
 231  
 232  
 233  \series medium 
 234  );
 235  \layout Standard
 236  
 237  
 238  \series medium 
 239  This is a simple array, and must list accurately the current table names
 240   you are using in your application.
 241   This list will match a much more complex array of table specifications,
 242   as you will see below.
 243  \layout Subsubsection
 244  
 245  Hooks
 246  \layout Paragraph
 247  
 248  Some applications will use this section.
 249  \layout Standard
 250  
 251  
 252  \series medium 
 253  The hooks array part of $setup_info contains a simple list of hooks the
 254   application will use:
 255  \layout Code
 256  
 257  
 258  \series medium 
 259  $setup_info['addressbook']['hooks'][] = 'preferences';
 260  \layout Code
 261  
 262  
 263  \series medium 
 264  $setup_info['addressbook']['hooks'][] = 'admin';
 265  \layout Standard
 266  
 267  
 268  \series medium 
 269  Here we also note a different method of 'stuffing the array.' In any case,
 270   this list of hooks will be required soon in order for your hook_admin.inc.php
 271   and other files to work.
 272   This is being done to cut down on the manual directory listing and file_exists
 273   loops done currently to discover hook files.
 274   Other than 'preferences' and 'admin', 'home', 'manual', 'after_navbar'
 275   and 'navbar_end' are all valid hook entries.
 276  \layout Subsubsection
 277  
 278  Dependencies
 279  \layout Paragraph
 280  
 281  All applications will have at least one entry here.
 282  \layout Standard
 283  
 284  
 285  \series medium 
 286  The final section, or array of data, is a listing of the other applications
 287   your application requires in order to function:
 288  \layout Code
 289  
 290  
 291  \series medium 
 292  $setup_info['addressbook']['depends'][] = array(
 293  \layout Code
 294  
 295      
 296  \series medium 
 297  'appname' => 'phpgwapi', 
 298  \layout Code
 299  
 300      
 301  \series medium 
 302  'versions' => Array(
 303  \layout Code
 304  
 305          
 306  \series medium 
 307  '0.9.10',
 308  \layout Code
 309  
 310          
 311  \series medium 
 312  '0.9.11',
 313  \layout Code
 314  
 315          
 316  \series medium 
 317  '0.9.12',
 318  \layout Code
 319  
 320          
 321  \series medium 
 322  '0.9.13'
 323  \layout Code
 324  
 325      
 326  \series medium 
 327  ) 
 328  \layout Code
 329  
 330  
 331  \series medium 
 332  );
 333  \layout Standard
 334  
 335  
 336  \series medium 
 337  This is the standard dependency array for all egroupware applications.
 338   It states that this application requires the phpgwapi, and lists the versions
 339   with which versions this app is compatible.
 340   This list would need to be appended upon each new API release, assuming
 341   your application is compatible with this new API version.
 342   You may list other applications here, e.g.
 343   your app might depend upon 'email' in order to work properly.
 344  \layout Standard
 345  
 346  
 347  \series medium 
 348  Do 
 349  \series bold 
 350  NOT
 351  \series medium 
 352   list applications here without considering this: If you do list an application
 353   here, and your app does not really require it, your application will not
 354   install unless that other application is already installed.
 355   This is handled normally within the install/upgrade process loops, which
 356   will install only applications whose dependencies are satisfied.
 357   Using a multipass function, the applications are installed in the correct
 358   order to ensure that dependencies are resolved.
 359   In all cases, the API would be installed first in every new install or
 360   upgrade, since all applications depend on the API.
 361  \layout Subsection
 362  
 363  tables_baseline.inc.php (Recommended)
 364  \layout Subsubsection
 365  
 366  Any application that has at least one upgrade routine will have this file.
 367  \layout Standard
 368  
 369  
 370  \series medium 
 371  The tables_baseline file represents the earliest supported version of an
 372   application's tables.
 373   This file is used only in the upgrade process, and is critical to its success.
 374   It contains an array of database-independent table, field, key and index
 375   definitions.
 376  \layout Standard
 377  
 378  
 379  \series medium 
 380  This array is formatted for use by the class.schema_proc_array.inc.php file
 381   in setup3.
 382   See the 
 383  \series default 
 384  tables_update
 385  \series medium 
 386   section below for more detail about schema_proc, but for now, here is a
 387   simple table definition in this format:
 388  \layout Code
 389  
 390  
 391  \series medium 
 392  $phpgw_baseline = array(
 393  \layout Code
 394  
 395      
 396  \series medium 
 397  'skel' => array(
 398  \layout Code
 399  
 400          
 401  \series medium 
 402  'fd' => array(
 403  \layout Code
 404  
 405              
 406  \series medium 
 407  'skel_id' => array('type' => 'auto','nullable' => false),
 408  \layout Code
 409  
 410              
 411  \series medium 
 412  'skel_owner' => array('type' => 'varchar','precision' => 25),
 413  \layout Code
 414  
 415              
 416  \series medium 
 417  'skel_access' => array('type' => 'varchar','precision' => 10),
 418  \layout Code
 419  
 420              
 421  \series medium 
 422  'skel_cat' => array('type' => 'int','precision' => 4),
 423  \layout Code
 424  
 425              
 426  \series medium 
 427  'skel_des' => array('type' => 'text'),
 428  \layout Code
 429  
 430              
 431  \series medium 
 432  'skel_pri' => array('type' => 'int','precision' => 4)
 433  \layout Code
 434  
 435          
 436  \series medium 
 437  ),
 438  \layout Code
 439  
 440          
 441  \series medium 
 442  'pk' => array('skel_id'),
 443  \layout Code
 444  
 445          
 446  \series medium 
 447  'fk' => array(),
 448  \layout Code
 449  
 450          
 451  \series medium 
 452  'ix' => array(),
 453  \layout Code
 454  
 455          
 456  \series medium 
 457  'uc' => array()
 458  \layout Code
 459  
 460      
 461  \series medium 
 462  ) 
 463  \layout Code
 464  
 465  
 466  \series medium 
 467  );
 468  \layout Standard
 469  
 470  
 471  \series medium 
 472  This multi-dimensional array contains 1 subarray with 5 subs of its own.
 473   The first array ('skel' above) defines the table name.
 474   Below that are 5 sections, 'fd' for field definitions, 'pk' to define primary
 475   keys, 'fk' to define foreign keys, 'ix' to define indexed fields, and 'uc'
 476   to define columns that require unique values.
 477   In the above example, the table 'skel' has 6 fields (skel_id, skel_owner,
 478   skel_access, skel_cat, skel_des, skel_pri), and 'skel_id' is defined also
 479   as the primary key for this table.
 480   More information on this array is below.
 481   But, this format was chosen as an available solution for defining tables
 482   and fields without having to maintain seperate files for different databases.
 483  \layout Subsection
 484  
 485  tables_current.inc.php (Recommended)
 486  \layout Subsubsection
 487  
 488  All applications with tables will need this file.
 489  \layout Standard
 490  
 491  
 492  \series medium 
 493  The tables_current file defines the current table definition that matches
 494   the 'version' string in $setup_info as well as the current code.
 495   This file is used only for new installs, or whenever the application is
 496   removed and reinstalled.
 497   The format and name of the array in this file is the same as for the tables_bas
 498  eline file listed above.
 499   In fact, whenever it is required to change your table definitions, you
 500   would start by copying the current file over to become the tables_baseline
 501   file.
 502   After having created your upgrade routines, you would then recreate the
 503   current file to match the new table definitions.
 504  \layout Subsection
 505  
 506  tables_update.inc.php (Recommended)
 507  \layout Subsubsection
 508  
 509  Any application which requires an upgrade to a previous version's tables
 510   will need this file.
 511  \layout Standard
 512  
 513  
 514  \series medium 
 515  This file will be the most complex of all setup-oriented files with which
 516   you will be working.
 517   It will contain all upgrade functions capable of upgrading any possible
 518   version of your egroupware app.
 519   These upgrade routines roughly match the old setup program's upgrade functions,
 520   but the use of objects and the methods have changed dramatically.
 521   The simplest version upgrade routine would look like:
 522  \layout Code
 523  
 524  
 525  \series medium 
 526  $test[] = "0.9.3pre10";
 527  \layout Code
 528  
 529  
 530  \series medium 
 531  function addressbook_upgrade0_9_3pre10()
 532  \layout Code
 533  
 534  
 535  \series medium 
 536  {
 537  \layout Code
 538  
 539      
 540  \series medium 
 541  global $setup_info;
 542  \layout Code
 543  
 544      
 545  \series medium 
 546  $setup_info['addressbook']['currentver'] = '0.9.3';
 547  \layout Code
 548  
 549      
 550  \series medium 
 551  return $setup_info['addressbook']['currentver'];
 552  \layout Code
 553  
 554  
 555  \series medium 
 556  }
 557  \layout Standard
 558  
 559  
 560  \series medium 
 561  This upgrade function merely updates the current version number.
 562   Note that there is not only an upgrade function, but also the setting of
 563   a value in the $test array.
 564   The name 'test' is a holdover from the old setup program, and is an arbitrary
 565   choice.
 566   However, this name must be used for the upgrade process to work.
 567   Prior to each of your upgrade functions, add the value of the previous
 568   version to $test.
 569  \layout Standard
 570  
 571  
 572  \series medium 
 573  Now look at the function name.
 574   The name is important and should be structured as the application name
 575   and the version from which you are intending to upgrade.
 576   The '.'s in the version string are replaced with '_'.
 577  \layout Standard
 578  
 579  
 580  \series medium 
 581  Inside the function, we global the $setup_info array.
 582   Next, we alter the version number in that array, for our application.
 583   Please be careful to specify YOUR application name here.
 584   The very last thing we do is to return this new version to the calling
 585   function.
 586   The upgrade process relies on the value returned, since it uses this directly
 587   to determine the new version.
 588   This may appear illogical on some level, but it does work.
 589   The reason for returning this value instead of a True or 1, etc.
 590   has to do with variable scope and lifetime.
 591   In this way, even the globaling of $setup_info inside the function may
 592   have little effect on the upgrade process.
 593   But, there may be values in this array you would want to use within the
 594   function.
 595   More on that later.
 596  \layout Standard
 597  
 598  
 599  \series medium 
 600  There is one other variable you would need if doing any database operations
 601   here.
 602   If you global $phpgw_setup, you will then have access to db and schema_proc
 603   objects and functions.
 604   The objects of interest here are:
 605  \layout Itemize
 606  
 607  
 608  \series medium 
 609  $phpgw_setup->oProc
 610  \layout Itemize
 611  
 612  
 613  \series medium 
 614  $phpgw_setup->db.
 615  \layout Standard
 616  
 617  
 618  \series medium 
 619  For most database work you should use the oProc object.
 620   This also has a db object that should be used for most standard phpgw API
 621   db class functions, including $db->query, next_record, num_rows, and f.
 622   The use of these for standard db operations is critical to the upgrade
 623   process.
 624   Schema_proc has a flag that can be set to determine what mode of upgrade
 625   we are in.
 626   This flag is set in the setup class during the upgrade process, and should
 627   not be altered locally.
 628  \layout Standard
 629  
 630  
 631  \series medium 
 632  This flag is a decision on whether to alter the database or the schema_proc
 633   array.
 634   The tables_baseline file above is loaded by setup prior to running your
 635   upgrade routines.
 636   If the current installed version is greater than the current upgrade routine,
 637   we don't need to alter the database yet.
 638   But schema_proc instead alters the $phpgw_baseline array in memory.
 639   The maintenance of this array is done even when we do alter the database.
 640   Once our version number in the test array matches the currently installed
 641   version of an application, real work on the tables begins.
 642  \layout Standard
 643  
 644  
 645  \series medium 
 646  'Why bother modifying this array at all', you may ask.
 647   The array must be maintained in order to keep current table definition
 648   status.
 649   This is used in some schema_proc functions when altering columns and tables.
 650   This is especially critical for pgsql schema_proc functions.
 651  \layout Standard
 652  
 653  
 654  \series medium 
 655  By using the $phpgw_setup->oProc object for basic inserts and queries, we
 656   acheive the ability to run all upgrade functions in every upgrade cycle
 657   without actually altering the database until we reach the current version
 658   we actually want to upgrade.
 659   For example:
 660  \layout Code
 661  
 662  
 663  \series medium 
 664  $sql = "SELECT * FROM phpgw_addressbook_extra WHERE contact_name='notes'";
 665  \layout Code
 666  
 667  
 668  \series medium 
 669  $phpgw_setup->oProc->query($sql,__LINE__,__FILE__);
 670  \layout Code
 671  
 672  
 673  \series medium 
 674  while($phpgw_setup->oProc->next_record()) {
 675  \layout Standard
 676  
 677  
 678  \series medium 
 679  We could have used $phpgw_setup->db or even a copy for the above activity.
 680   However, using the above method ensures that an array only upgrade does
 681   just that.
 682   If the flag was set in setup telling schema_proc to alter the array only,
 683   we do not want to touch the tables for inserts or selects yet.
 684   In this case, $phpgw_setup->oProc->next_record() returns False, and the
 685   loop is skipped.
 686   The $phpgw_baseline array does not know about table content, only table
 687   and field definitions.
 688  \layout Standard
 689  
 690  
 691  \series medium 
 692  If the upgrade function containing this method is actually working on the
 693   tables (currentver <= the upgrade function), then next_record() is returned
 694   as the expected action of pulling the next row of data.
 695   Inside of this while loop, you can safely use $phpgw_setup->db, or preferably
 696   a copy, to do the insert/delete, etc you want to have happen here.
 697  \layout Code
 698  
 699      $cid = $phpgw_setup->oProc->f('contact_id');
 700  \layout Code
 701  
 702      $cvalu = $phpgw_setup->oProc->f('contact_value');
 703  \layout Code
 704  
 705      
 706  \series medium 
 707  $update = "UPDATE phpgw_addressbook set note='" .
 708   $cvalu .
 709   "' WHERE id=" .
 710   $cid;
 711  \layout Code
 712  
 713      
 714  \series medium 
 715  $db1->query($update);
 716  \layout Code
 717  
 718      
 719  \series medium 
 720  $delete = "DELETE FROM phpgw_addressbook_extra WHERE contact_id=" .
 721   $cid .
 722   " AND contact_name='notes'";
 723  \layout Code
 724  
 725      
 726  \series medium 
 727  $db1->query($delete);
 728  \layout Code
 729  
 730  }
 731  \layout Standard
 732  
 733  
 734  \series medium 
 735  $db1 is a copy of $phpgw_setup->db, to avoid potential conflicts with the
 736   rest of setup's db activities.
 737  \layout Standard
 738  
 739  In addition to the basic API db class functions, schema_proc introduces
 740   the following special functions:
 741  \layout Code
 742  
 743  function DropTable($sTableName)
 744  \layout Code
 745  
 746  function DropColumn($sTableName, $aTableDef, $sColumnName)
 747  \layout Code
 748  
 749  function RenameTable($sOldTableName, $sNewTableName)
 750  \layout Code
 751  
 752  function RenameColumn($sTableName, $sOldColumnName, $sNewColumnName)
 753  \layout Code
 754  
 755  function AlterColumn($sTableName, $sColumnName, $aColumnDef)
 756  \layout Code
 757  
 758  function AddColumn($sTableName, $sColumnName, $aColumnDef)
 759  \layout Code
 760  
 761  function CreateTable($sTableName, $aTableDef)
 762  \layout Standard
 763  
 764  Please use these functions where appropriate in place of standard SQL CREATE,
 765   DROP, and ALTER TABLE commands.
 766   This will ensure that your upgrade script works for all supported databases.
 767  \layout Standard
 768  
 769  Of these functions, DropTable, RenameTable, and RenameColumn are pretty
 770   straightforward.
 771   Pass these the table names you wish to Drop/Rename, and schema_proc will
 772   handle the rest, including indexes and sequences, where applicable.
 773  \layout Standard
 774  
 775  The remaining functions require some explanation:
 776  \layout Itemize
 777  
 778  CreateTable:
 779  \layout Code
 780  
 781  $phpgw_setup->oProc->CreateTable(
 782  \layout Code
 783  
 784      'categories', array(
 785  \layout Code
 786  
 787          'fd' => array(
 788  \layout Code
 789  
 790              'cat_id' => array('type' => 'auto','nullable' => false),
 791  \layout Code
 792  
 793              'account_id' => array('type' => 'int','precision' => 4,'nullable'
 794   => false, 'default' => 0),
 795  \layout Code
 796  
 797              'app_name' => array('type' => 'varchar','precision' => 25,'nullable'
 798   => false),
 799  \layout Code
 800  
 801              'cat_name' => array('type' => 'varchar', 'precision' => 150,
 802   'nullable' => false),
 803  \layout Code
 804  
 805              'cat_description' => array('type' => 'text', 'nullable' => false)
 806  \layout Code
 807  
 808          ),
 809  \layout Code
 810  
 811          'pk' => array('cat_id'),
 812  \layout Code
 813  
 814          'ix' => array(),
 815  \layout Code
 816  
 817          'fk' => array(),
 818  \layout Code
 819  
 820          'uc' => array()
 821  \layout Code
 822  
 823      )
 824  \layout Code
 825  
 826  );
 827  \layout Standard
 828  
 829  Does this look familiar? The array passed to CreateTable is in the format
 830   used also in tables_baseline and tables_current.
 831   Note a slight difference where the table name is being passed as a seperate
 832   argument.
 833   The second argument to the function is the table definition array, starting
 834   with 'fd'.
 835  \layout Itemize
 836  
 837  AddColumn:
 838  \layout Code
 839  
 840  $phpgw_setup->oProc->AddColumn('phpgw_categories','cat_access',array('type'
 841   => 'varchar', 'precision' => 25));
 842  \layout Standard
 843  
 844  Here we pass the table name of an existing table, the new column name, and
 845   a field definition.
 846   This definition is merely a slice of the table arrays found earlier in
 847   this document.
 848  \layout Itemize
 849  
 850  AlterColumn:
 851  \layout Code
 852  
 853  $phpgw_setup->oProc->AlterColumn('phpgw_sessions','session_action',array('type'
 854   => 'varchar', 'precision' => '255'));
 855  \layout Standard
 856  
 857  The format of this function matches AddColumn.
 858   It is also a simple case of passing the table name, field name, and field
 859   definition.
 860  \layout Itemize
 861  
 862  DropColumn:
 863  \layout Code
 864  
 865  $newtbldef = array(
 866  \layout Code
 867  
 868      "fd" => array(
 869  \layout Code
 870  
 871          'acl_appname' => array('type' => 'varchar', 'precision' => 50),
 872  \layout Code
 873  
 874          'acl_location' => array('type' => 'varchar', 'precision' => 255),
 875  \layout Code
 876  
 877          'acl_account' => array('type' => 'int', 'precision' => 4),
 878  \layout Code
 879  
 880          'acl_rights' => array('type' => 'int', 'precision' => 4)
 881  \layout Code
 882  
 883      ),
 884  \layout Code
 885  
 886      'pk' => array(),
 887  \layout Code
 888  
 889      'ix' => array(),
 890  \layout Code
 891  
 892      'fk' => array(),
 893  \layout Code
 894  
 895      'uc' => array()
 896  \layout Code
 897  
 898  );
 899  \layout Code
 900  
 901  $phpgw_setup->oProc->DropColumn('phpgw_acl',$newtbldef,'acl_account_type');
 902  \layout Standard
 903  
 904  This is the most complicated function in schema_proc, from the user's perspectiv
 905  e.
 906   Its complexity is necessitated by the requirement of some databases to
 907   recreate a table in the case of dropping a column.
 908   Note that the table definition array is being used yet again.
 909   The array defined here should match the table definition you want after
 910   this function has completed.
 911   Here, we are dropping the column 'acl_account_type' from the table 'phpgw_acl',
 912   and the table definition does not have this column defined.
 913   You could copy information from your tables_current file here and edit
 914   it to match the desired new table spec, less the column you wish to drop.
 915  \layout Standard
 916  
 917  There are additional functions within schema_proc, the majority of which
 918   are not to be called directly.
 919   They are used internally.
 920   If you do wish to investigate further, use class.schema_proc.inc.php as your
 921   guide.
 922   This master file includes the class.schema_proc_DBMS.inc.php and class.schema_proc_
 923  array.inc.php files.
 924   The DBMS files should not be used as a guide, since their functions are
 925   called from the master class, and the parameters are different from what
 926   you might expect relative to the master.
 927  \layout Standard
 928  
 929  
 930  \series bold 
 931  PLEASE, DO NOT WRITE TO OR ALTER ANOTHER APPLICATION'S TABLES OR THE API
 932   TABLES IN YOUR APPLICATION UPGRADE FUNCTIONS!
 933  \layout Subsection
 934  
 935  default_records.inc.php (Optional)
 936  \layout Subsubsection
 937  
 938  Any application with tables that wants to load some default data will need
 939   this file.
 940  \layout Standard
 941  
 942  The default_records file consists of a list of SQL INSERTs using the $oProc
 943   object directly:
 944  \layout Code
 945  
 946  $oProc->query("INSERT INTO phpgw_inv_statuslist (status_name) VALUES ('available
 947  ')");
 948  \layout Code
 949  
 950  $oProc->query("INSERT INTO phpgw_inv_statuslist (status_name) VALUES ('no
 951   longer available')");
 952  \layout Code
 953  
 954  $oProc->query("INSERT INTO phpgw_inv_statuslist (status_name) VALUES ('back
 955   order')");
 956  \layout Standard
 957  
 958  In this case, the developer wanted to insert some status information, which
 959   was then used in a select box on an html form.
 960   Using the default_records file, every new install will have this data included.
 961   This file should consist of queries applicable to the tables defined in
 962   setup.inc.php and tables_current.inc.php.
 963  \layout Subsection
 964  
 965  test_data.inc.php (Optional)
 966  \layout Subsubsection
 967  
 968  Any developer wanting to test the full list of upgrade routines can use
 969   this file.
 970  \layout Standard
 971  
 972  test_data.inc.php is similar to default_records above.
 973   It is called only by schematoy.php and is never installed with a new install
 974   or upgrade.
 975   This is a developer-only file.
 976   The INSERTs here should be applicable to the tables_baseline table definitions.
 977  \layout Subsection
 978  
 979  language files (Required)
 980  \layout Subsubsection
 981  
 982  All applications should have at least a file of English translations, used
 983   for their application lang() calls.
 984  \layout Itemize
 985  
 986  Format of a lang file:
 987  \layout Code
 988  
 989  {phrase}{TAB}{appname}{TAB}{LANG_CODE}{TAB}{translation}
 990  \layout Code
 991  
 992      e.g:
 993  \layout Code
 994  
 995  first name    common    en    First Name
 996  \layout Code
 997  
 998  first name    common    de    Vorname
 999  \layout Itemize
1000  
1001  Filenames:
1002  \layout Code
1003  
1004  phpgw_{LANG_CODE}.lang
1005  \layout Code
1006  
1007    e.g.
1008  \layout Code
1009  
1010  English: phpgw_en.lang
1011  \layout Code
1012  
1013  German: phpgw_de.lang
1014  \layout Standard
1015  
1016  Please see the contents of the API 'languages' table for the correct setting
1017   of the LANG_CODE.
1018  \layout Section
1019  
1020  Developer Tools
1021  \layout Subsection
1022  
1023  sqltoarray.php
1024  \layout Subsubsection
1025  
1026  Displays the current schema_proc array defining an application's tables.
1027  \layout Standard
1028  
1029  This web application reads the current table status live from the database.
1030   It then parses this information into a hopefully correct table definition
1031   array for schema_proc.
1032   Upon visiting this app, you are shown a list of currently installed application
1033  s with defined tables.
1034   You may then select one app or all apps, and then submit the form.
1035   From this form you may then download a tables_current file, suitable for
1036   commission to cvs.
1037   Please do check the format to make sure the definitions are correct.
1038  \layout Subsection
1039  
1040  schematoy.php
1041  \layout Subsubsection
1042  
1043  Runs the full cycle of upgrades, including optional test_data.
1044  \layout Standard
1045  
1046  This app is not beautiful, may bomb on you, and will definitely drop your
1047   application's tables.
1048   The display is similar to the user/admin tool, applications.php.
1049   You are shown a list of apps with tables.
1050   Select one app, and enter a target version.
1051   Upon submission of the form:
1052  \layout Itemize
1053  
1054  All application tables are dropped.
1055  \layout Itemize
1056  
1057  tables_baseline.inc.php is loaded.
1058  \layout Itemize
1059  
1060  test_data.inc.php is loaded
1061  \layout Itemize
1062  
1063  tables_update.inc.php is loaded.
1064  \layout Itemize
1065  
1066  a full application upgrade test begins.
1067  \layout Standard
1068  
1069  This will give a LOT of debugging output.
1070   Depending on your database, the process may take quite awhile.
1071   This tool should be considered as a destructive test of the full upgrade
1072   cycle.
1073   If the upgrade process is successful, you can then check the loaded test_data
1074   to see that it is still in place as expected after all the table modifications,
1075   etc.
1076   If not, it should be clear where the error has occurred.
1077   Look for the usual INVALID SQL warnings, among others.
1078  \layout Subsection
1079  
1080  tools subdirectory
1081  \layout Subsubsection
1082  
1083  some utilities for sql file conversion, etc.
1084  \layout Standard
1085  
1086  In the tools directory under setup3, there should be at least a couple of
1087   hopefully handy perl or shell scripts.
1088   These are for running on the commandline only, and might apply to converting
1089   SQL files into lang files, etc.
1090   They are not expected to be perfect, but might offer some assistance or
1091   ideas for additional utilities.
1092   Use these at your own risk or benefit.
1093  \layout Section
1094  
1095  The install/upgrade process
1096  \layout Subsection
1097  
1098  Overview
1099  \layout Subsubsection
1100  
1101  Setup internal upgrade functions
1102  \layout Standard
1103  
1104  Setup uses a common set of functions for new installs and upgrades.
1105   These are implemented as multi-pass loops.
1106   For a single application install or upgrade, a single pass is done.
1107   For multiple application installs or upgrades, multiple passes are done
1108   automatically.
1109   The order of install in a mass install or upgrade is determined by application
1110   dependencies.
1111   The other determining factor is the order in which the application directories
1112   and setup.inc.php files are read from the filesystem.
1113  \layout Subsection
1114  
1115  New installs
1116  \layout Subsubsection
1117  
1118  Detection
1119  \layout Standard
1120  
1121  Each run of index.php or applications.php in setup3 first runs a set of detection
1122   routines.
1123   These read the data from each setup.inc.php file, and from the 'applications'
1124   or 'phpgw_applications' table as appropriate, and only if one of these
1125   tables exists.
1126   This data is parsed into the $setup_info array.
1127   In this case, this array contains information about all applications.
1128   Based on the information gathered, a status flag is set to one of the following
1129   values:
1130  \layout Itemize
1131  
1132  U - Upgrade required/available
1133  \layout Itemize
1134  
1135  R - upgrade in pRogress
1136  \layout Itemize
1137  
1138  C - upgrade Completed successfully
1139  \layout Itemize
1140  
1141  D - Dependency failure
1142  \layout Itemize
1143  
1144  F - upgrade Failed
1145  \layout Itemize
1146  
1147  V - Version mismatch at end of upgrade
1148  \layout Itemize
1149  
1150  M - Missing files at start of upgrade (Not used, proposed only)
1151  \layout Standard
1152  
1153  Using this information, the setup logic in index.php determines what mode
1154   we are in.
1155   index.php is not capable of being selective about which application it found
1156   as being out of sync.
1157   It is designed only for 'Simple Application Management', which is Step
1158   1 of the setup process.
1159   For more selective application manipulation, use applications.php.
1160   index.php then tells the user that 1) their applications are current 2)
1161   some of their applications are out of sync 3) no db exists, etc.
1162   For a new install, all applications will be out of sync, since there is
1163   not even an 'phpgw_applications' table in the database to tell setup what
1164   the status is for any application.
1165  \layout Subsubsection
1166  
1167  Selection
1168  \layout Standard
1169  
1170  There is no selection for application installs in 'new install' mode.
1171   All physically present applications will be installed, or at least attempted.
1172  \layout Subsubsection
1173  
1174  Installation
1175  \layout Standard
1176  
1177  Once the setup user clicks the magic button to install all applications,
1178   the following occurs:
1179  \layout Itemize
1180  
1181  The setup_info array is passed to the process_pass() function, using a method='n
1182  ew'
1183  \layout Itemize
1184  
1185  Applications whose status flag='U' (API on first pass) are then handed off
1186   to the process_current() function.
1187   This handles inclusion and installation of the application's tables_current.inc.p
1188  hp file.
1189  \layout Itemize
1190  
1191  The application is registered as a new application in the 'phpgw_applications'
1192   table.
1193   If for some reason there is old data in this table for this application,
1194   it will be updated instead.
1195   Its hooks, if any, are registered in the 'phpgw_hooks' table.
1196  \layout Itemize
1197  
1198  Next, this array is passed to the process_default_records() function.
1199   If this file is present in the current application's setup directory, the
1200   queries here are run to install the data to the application's table(s).
1201  \layout Itemize
1202  
1203  The above is repeated until all application status flags equal 'C'.
1204   However, if an application install failed for some reason, it will then
1205   be skipped on the next pass.
1206   This keeps the loop from running away.
1207  \layout Subsection
1208  
1209  Upgrades
1210  \layout Subsubsection
1211  
1212  Detection
1213  \layout Standard
1214  
1215  Only an API version mismatch will trigger an automated request for the user
1216   to upgrade their install.
1217   Once the api is current, they can move on to applications.php for more 'Advanced
1218   Application Management', which is Step 4 of the setup process.
1219   However, if the API is out of sync, clicking 'Upgrade' in index.php will
1220   also attempt to upgrade other applications which may be out of sync, as
1221   well.
1222   As the phpgwapi continues to stabilize, it is felt that this method of
1223   upgrading will become less and less common.
1224  \layout Subsubsection
1225  
1226  Selection
1227  \layout Standard
1228  
1229  Within applications.php, a color-coded matrix of application status and actions
1230   is displayed.
1231   Depending on the status flag of each application, certain actions will
1232   be either enabled or disabled.
1233   These actions include 'install', 'upgrade', 'remove'.
1234   If something is very wrong with previous attempts to install or upgrade
1235   an application, another column called 'resolution' will then display a
1236   link.
1237   This link will display additional information which would be helpful for
1238   determining how to resolve the problem.
1239   Assuming all is well, the user can select applications requiring upgrade
1240   from this list.
1241   Once selected, they submit the form.
1242   This runs the follow three routines in order:
1243  \layout Itemize
1244  
1245  remove
1246  \layout Itemize
1247  
1248  install
1249  \layout Itemize
1250  
1251  upgrade
1252  \layout Subsubsection
1253  
1254  Upgrade
1255  \layout Standard
1256  
1257  The idea here is that multiple actions can be selected and run in order
1258   in one click.
1259   In any case, once they select an application for upgrade, the following
1260   occurs:
1261  \layout Itemize
1262  
1263  A stripped down version of the setup_info array is passed to the process_upgrade
1264  () function.
1265   This array contains only the information for the selected application
1266  \layout Itemize
1267  
1268  Within process_upgrade(), the tables_baseline.inc.php file for the application
1269   is loaded.
1270  \layout Itemize
1271  
1272  The tables_update.inc.php file for the application is loaded
1273  \layout Itemize
1274  
1275  The contents of the test array is used to loop through the entire list of
1276   upgrade functions for the application.
1277   The application's unique function names are rebuilt, then run.
1278  \layout Itemize
1279  
1280  When the currentver (installed) matches the version (available), process_upgrade
1281  () exits, setting the status flag for the app to 'C'.
1282  \layout Itemize
1283  
1284  Just prior to exiting, the application and its hooks are updated into the
1285   'phpgw_applications' and 'phpgw_hooks' tables.
1286  \layout Subsection
1287  
1288  Uninstallation/Removal
1289  \layout Subsubsection
1290  
1291  Selection
1292  \layout Standard
1293  
1294  Selective removal of an application is done via applications.php, in a manner
1295   similar to the method above for upgrades.
1296  \layout Subsubsection
1297  
1298  Uninstallation
1299  \layout Standard
1300  
1301  Once an application is selected for removal:
1302  \layout Itemize
1303  
1304  A stripped down version of the setup_info array is passed to the process_droptab
1305  les() function.
1306   This function removes all of the application's defined tables, but only
1307   after first checking to see if the tables are there.
1308   In this way, we attempt to cut down on the number of errors sent to the
1309   browser.
1310  \layout Itemize
1311  
1312  The application's hooks are deregistered (removed from 'phpgw_hooks').
1313  \layout Itemize
1314  
1315  The application itself is deregistered (removed from 'phpgw_applications').
1316  \layout Section
1317  
1318  Caveats
1319  \layout Subsection
1320  
1321  Must see info
1322  \layout Subsubsection
1323  
1324  Auto fields
1325  \layout Standard
1326  
1327  For auto type fields, schema_proc creates a sequence automatically based
1328   on the table name for databases that require sequences.
1329   In the case of postgresql, the limit for this name based on our tests is
1330   31 characters.
1331   The schema_proc format is:
1332  \layout Code
1333  
1334  $sSequenceSQL = sprintf("CREATE SEQUENCE seq_%s", $sTableName);
1335  \layout Standard
1336  
1337  This limits the maximum length for a tablename to 27 characters.
1338   Based on the tablename standard in phpgw of 'phpgw_tablename', you are
1339   further limited to 21 characters in which to describe your table.
1340   You will need to be less descriptive in some cases, e.g.
1341   use 'phpgw_widget_cats' instead of 'phpgw_widget_info_categories'.
1342  \layout Standard
1343  
1344  To maintain compatibility with MySQL 3.22.X, please always add 
1345  \begin_inset Quotes eld
1346  \end_inset 
1347  
1348  'nullable' => False
1349  \begin_inset Quotes erd
1350  \end_inset 
1351  
1352   to your field spec for an auto field.
1353   This and probably older versions of MySQL require that specification within
1354   the SQL for a field that will also be an index or unique field, which for
1355   our uses should typically be true for an auto field.
1356   MySQL 3.23.X and PostgreSQL do not have this issue.
1357  \layout Subsubsection
1358  
1359  Default 0
1360  \layout Standard
1361  
1362  For int fields, a default of 0 is not assumed.
1363   Only some databases will set this default for you, MySQL being one.
1364   You will need to explicitly define this default in the table definition.
1365   Also, for auto fields, do not enter a default, since the resulting SQL
1366   query would fail on many RDBMS.
1367  \the_end