phpGroupWare is a web based groupware application framework (API), for writing applications. Integrated applications such as +email, calendar, todo list, address book, and file manager are included. +
We have attempted to make writing application for phpGroupWare as painless as possible. +We hope any pain and suffering is cause by making your application work, but not dealing with phpGroupWare itself. +
The phpGroupWare API handles session management, user/group management, has support for multiple databases, using the PHPLIB database abstraction method, we support templates using the PHPLIB Templates class, a file system interface, and even a network i/o interface.
+On top of these standard functions, phpgroupWare provides several functions to give you the information you need about the users environment, and to properly plug into phpgroupWare.
+
These guidelines must be followed for any application that wants considered for inclusion into phpGroupWare deluxe. +
It must run on PHP3 and PHP4.
+SQL statements must be compatible with both MySQL and PostgreSQL.
+It must use our default header.inc.php include.
+It must use our $phpgw_link($url) for all links (this is for session support).
+It must respect phpGW group rights and phpGW user permissions.
+It must use our directory structure, template support and lang (multi-language) support.
+Where possible it should run on both Unix and NT platforms.
+
For applications that do not meet these requirements, they can be avalible to users via the phpGroupWare Apps project, or whatever means the developers decide.
+If you need help converting your application to templates and our lang support, we will try to connect you with someone to help.
+
Each PHP page you write will need to include the header.inc.php along with a few variables.
+This is done by putting this at the top of each PHP page.
+
+ <?php
+ $phpgw_flags["currentapp"] = "appname";
+ include("../header.inc.php");
+ ?>
+
++
It is fairly simple to add and delete applications to/from phpGroupWare. +
To make things easy for developers we go ahead and load the following files. +
You will need to create the following directories for your code
+(replace 'appname' with your application name)
+
+ `-- appname + `-- images + | `-- navbar.gif + `-- inc + | |-- functions.inc.php + | |-- header.inc.php + | `-- footer.inc.php + `-- templates + `-- default + ++
To make the application aware of your application, add your application details to the applications table. This can be done via the GUI administration screen, or via a sql script. +
+ insert into applications (app_name, app_title, app_enabled) values ('appname', 'The App name', 1);
+
+phpGroupWare attempts to provide developers with a sound directory structure to work from.
+The directory layout may seem complex at first, but after some use, you will see that it is designed to accommidate a large number of applications and functions.
+
+
+.-- addressbook +| `-- images +| | `-- navbar.gif +| `-- inc +| | |-- functions.inc.php +| | |-- header.inc.php +| | `-- footer.inc.php +| `-- templates +| `-- default +|-- admin +| `-- images +| | `-- navbar.gif +| `-- inc +| | |-- functions.inc.php +| | |-- header.inc.php +| | `-- footer.inc.php +| `-- templates +| `-- default +|-- calendar +| `-- images +| | `-- navbar.gif +| `-- inc +| | |-- functions.inc.php +| | |-- header.inc.php +| | `-- footer.inc.php +| `-- templates +| `-- default +|-- cron +|-- doc +|-- email +| `-- images +| | `-- navbar.gif +| `-- inc +| | |-- functions.inc.php +| | |-- header.inc.php +| | `-- footer.inc.php +| `-- templates +| `-- default +|-- filemanager +|-- files +| |-- groups +| `-- users +|-- inc +| |-- phpgwapi + | |-- phpgw.inc.php + | |-- phpgw_info.inc.php + | |-- phpgw_common.inc.php +| | `-- etc... +| `-- templates +| |-- default +| | |-- addressbook +| | |-- admin +| | |-- calendar +| | |-- common +| | |-- email +| | |-- filemanager +| | |-- headlines +| | |-- preferences +| | |-- todo +| | `-- tts +| `-- icons +| |-- email +| |-- calendar +| `-- tts +|-- preferences +| `-- images +| | `-- navbar.gif +| `-- inc +| | |-- functions.inc.php +| | |-- header.inc.php +| | `-- footer.inc.php +| `-- templates +| `-- default +|-- themes +`-- todo + `-- images + | `-- navbar.gif + `-- inc + | |-- functions.inc.php + | |-- header.inc.php + | `-- footer.inc.php + `-- templates + `-- default + ++
The translations are now being done thru the database, and will be configurable to use other mechanism.
+I will document all the new abilities during my next update of this document.
+
phpGroupWare attempts to provide developers with a useful API to handle common tasks.
+To do this we have created a multi-dimensional class $phpgw->.
+This allows for terrific code organization, and help developers easily identify the file that the function is in.
+All the files that are patr of this class are in the inc/core directory and are named to match the sub-class.
+Example:
+$phpgw->send->msg() is in the inc/phpgwapi/phpgw_send.inc.php file.
+
$phpgw->link($url)
+Add support for session management. ALL links must use this, that includes href's form actions and header location's.
+If you are just doing a form action back to the same page, you can use it without any paramaters.
+This function is right at the core of the class because it is used so often, we wanted to save developers a few keystrokes.
+Example:
+
+<form name=copy method=post action="<?php echo $phpgw->link();?>"> +/* If session management is done via passing url paramaters */ +/* The the result would be */ +/* <form name=copy method=post action="somepage.php?sessionid=87687693276?kp3=kjh98u80"> */ ++
+
$phpgw->common->appsession($data)
+Store important information session information that your application needs.
+$phpgw->appsession will return the value of your session data is you leave the paramater enmpty [i.e. $phpgw->appsession("")], otherwise it will store whatever data you send to it.
+You can also store a comma delimited string and use explode() to turn it back into an array when you recieve the value back.
+Example:
+
+ $phpgw->common->appsession("/path/to/something");
+ echo "Dir: " . $phpgw->common->appsession();
+
+$phpgw->vfs->read_file($file)
+Returns the data from $file.
+You must send the complete path to the file.
+Example:
+
+$data = $phpgw->vfs->read_file("/some/dir/to/file.txt");
+
-
-
-
-
-
-
-
-
-
$phpgw->vfs->write_file($file, $contents)
+Write data to $file.
+You must send the complete path to the file.
+Example:
+$data = $phpgw->vfs->write_file("/some/dir/to/file.txt");
+
++
$phpgw->vfs->read_userfile($file)
+Returns the data from $file, which resides in the users private dir.
+Example:
+
+$data = $phpgw->vfs->read_userfile("file.txt");
+
++
$phpgw->write_userfile($file, $contents)
+Writes data to $file, which resides in the users private dir.
+Example:
+
+$data = $phpgw->vfs->write_userfile("file.txt");
+
++
$phpgw->vfs->list_userfiles()
+Returns an array which has the list of files in the users private dir.
+Example:
+
+$filelist = array(); +$filelist = $phpgw->vfs->list_userfiles(); ++
+
+
$phpgw->msg->send($service, $to, $subject, $body, $msgtype, $cc, $bcc)
+Send a message via email or NNTP and returns any error codes.
+Example:
+
+$to = "someuser@domain.com";
+$subject = "Hello buddy";
+$body = "Give me a call\n Been wondering what your up to.";
+$errors = $phpgw->msg->send("email", $to, $subject, $body);
+
+phpGroupWare attempt to provide developers with as much information about the user, group, server, and application configuration as possible.
+To do this we provide a multi-dimensional array called '$phpgw_info[]', which includes all the information about your environment.
+Due to the multi-dimensional array approach. getting these values is easy.
+Here are some examples:
+
+ <?php + // To do a hello username + echo "Hello " . $phpgw_info["user"]["fullname"]; + //If username first name is John and last name is Doe, prints: 'Hello John Doe' + ?> + <?php + // To find out the location of the imap server + echo "IMAP Server is named: " . $phpgw_info["server"]["imap_server"]; + //If imap is running on localhost, prints: 'IMAP Server is named: localhost' + ?> + ++
$phpgw_info["user"]["userid"] = The user ID.
+$phpgw_info["user"]["sessionid"] = The session ID
+$phpgw_info["user"]["theme"] = Selected theme
+$phpgw_info["user"]["private_dir"] = Users private dir. Use phpgroupware core functions for access to the files.
+$phpgw_info["user"]["firstname"] = Users first name
+$phpgw_info["user"]["lastname"] = Users last name
+$phpgw_info["user"]["fullname"] = Users Full Name
+$phpgw_info["user"]["groups"] = Groups the user is a member of
+$phpgw_info["user"]["app_perms"] = If the user has access to the current application
+$phpgw_info["user"]["lastlogin"] = Last time the user logged in.
+$phpgw_info["user"]["lastloginfrom"] = Where they logged in from the last time.
+$phpgw_info["user"]["lastpasswd_change"] = Last time they changed their password.
+$phpgw_info["user"]["passwd"] = Hashed password.
+$phpgw_info["user"]["status"] = If the user is enabled.
+$phpgw_info["user"]["logintime"] = Time they logged into their current session.
+$phpgw_info["user"]["session_dla"] = Last time they did anything in their current session
+$phpgw_info["user"]["session_ip"] = Current IP address
+
$phpgw_info["group"]["group_names"] = List of groups.
+
$phpgw_info["server"]["server_root"] = Main installation directory
+$phpgw_info["server"]["include_root"] = Location of the 'inc' directory.
+$phpgw_info["server"]["temp_dir"] = Directory that can be used for temporarily storing files
+$phpgw_info["server"]["common_include_dir"] = Location of the core/shared include files.
+$phpgw_info["server"]["template_dir"] = Active template files directory. This is defaulted by the server, and changeable by the user.
+$phpgw_info["server"]["dir_separator"] = Allows compatibility with WindowsNT directory format,
+$phpgw_info["server"]["encrpytkey"] =
+$phpgw_info["server"]["site_title"] = Site Title will show in the title bar of each webpage.
+$phpgw_info["server"]["webserver_url"] = URL to phpGroupWare installation.
+$phpgw_info["server"]["charset"] = Unknown
+$phpgw_info["server"]["version"] = phpGroupWare version.
+
It is unlikely you will need these, because $phpgw_info_db will already be loaded as a database for you to use.
+$phpgw_info["server"]["db_host"] = Address of the database server. Usually this is set to localhost.
+$phpgw_info["server"]["db_name"] = Database name.
+$phpgw_info["server"]["db_user"] = User name.
+$phpgw_info["server"]["db_pass"] = Password
+$phpgw_info["server"]["db_type"] = Type of database. Currently MySQL and PostgreSQL are supported.
+
It is unlikely you will need these, because most email needs are services thru core phpGroupWare functions.
+$phpgw_info["server"]["mail_server"] = Address of the IMAP server. Usually this is set to localhost.
+$phpgw_info["server"]["mail_server_type"] = IMAP or POP3
+$phpgw_info["server"]["imap_server_type"] = Cyrus or Uwash
+$phpgw_info["server"]["imap_port"] = This is usually 143, and should only be changed if there is a good reason.
+$phpgw_info["server"]["mail_suffix] = This is the domain name, used to add to email address
+$phpgw_info["server"]["mail_login_type"] = This adds support for VMailMgr. Generally this hsould be set to 'standard'.
+$phpgw_info["server"]["smtp_server"] = Address of the SMTP server. Usually this is set to localhost.
+$phpgw_info["server"]["smtp_port"] = This is usually 25, and should only be changed if there is a good reason.
+
$phpgw_info["server"]["nntp_server"] = Address of the NNTP server.
+$phpgw_info["server"]["nntp_port"] = This is usually XX, and should only be changed if there is a good reason.
+$phpgw_info["server"]["nntp_sender"] = Unknown
+$phpgw_info["server"]["nntp_organization"] = Unknown
+$phpgw_info["server"]["nntp_admin"] = Uknown
+
Each application has the following information avalible.
+$phpgw_info["apps"]["appname"]["title"] = The title of the application.
+$phpgw_info["apps"]["appname"]["enabled"] = If the application is enabled. True or False.
+$phpgw_info["server"]["app_include_dir"] = Location of the current application include files.
+$phpgw_info["server"]["app_template_dir"] = Location of the current application tpl files.
+$phpgw_info["server"]["app_lang_dir"] = Location of the current lang directory.
+$phpgw_info["server"]["app_auth"] = If the server and current user have access to current application
+$phpgw_info["server"]["app_current"] = name of the current application.
+
phpGroupWare is built using a multi-language support scheme. This means the pages can be translated to other languages +very easily. It is done thru a series of lang files, which can be translated and selected by the user. +
Some instructions on using the lang files.
+Under inc/lang there needs to be a sub-directory for each langague. Inside the
+directory there are a number of files for each application. There is one common file
+which contains a list of words that all applications use. ie, add, delete, edit, etc...
+Words that are specific to a application should be stored with that applications include file.
+
+ function lang_todo($message, $m1 = "", $m2 = "", $m3 = "", $m4 = "")
+ {
+ $message = strtolower($message);
+ switch($message)
+ {
+ case "urgency": $s = "Urgency"; break;
+ case "completed": $s = "completed"; break;
+ [ snip ]
+ default: $s = "<b>*</b> " . $message;
+ }
+ return $s;
+ }
+
+
+$m1, $m2,
+$m3, and $m4 are used to pass extra data to be place in the middle of a sentence.+You have 29 new messages! ++ +The default should return a bold faced * and the word that wasn't found. This allows users to notice that something is missing in the files and make changes if +necessary. +
phpGroupWare is built using a templates based design. This means the display pages, stored in tpl files, can be translated to other languages, made to look completely different. +
Some instructions on using templates
+For Further info read the PHPLIBs documentation for their template class.
+
The newest version of this document can be found on our website +http://www.phpgroupware.org as SGML source, as HTML and as TEXT. +
Comments on this HOWTO should be directed to the phpGroupWare developers mailing list +phpgroupware-developers@lists.sourceforge.net. +
To subscribe, go to +http://sourceforge.net/mail/?group_id=7305
This document was written by Dan Kuykendall. +
Copyright (c) Dan Kuykendall. +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.1 +or any later version published by the Free Software Foundation +
A copy of the license is available at +GNU Free Documentation License. +
Thanks to Joesph Engo for starting phpGroupWare (at the time called webdistro). +Thanks to all the developers and users who contribute to making phpGroupWare such a success.