5. The API

5.1 Introduction

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 part 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.

5.2 Basic functions

$phpgw->link

$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 parameters.
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 parameters */
/* The the result would be */
/* <form name=copy method=post action="somepage.php?sessionid=87687693276?kp3=kjh98u80"> */

5.3 Application Functions

$phpgw->common->phpgw_header

$phpgw->phpgw_header()
Print out the start of the HTML page, including the navigation bar and includes appname/inc/header.php

$phpgw->common->phpgw_footer

$phpgw->phpgw_footer()
Prints the system footer, and includes appname/inc/footer.php

$phpgw->common->appsession

$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 parameter empty [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 receive the value back.
Example:

  $phpgw->common->appsession("/path/to/something");
  echo "Dir: " . $phpgw->common->appsession();

5.4 File functions

$phpgw->vfs->read_file

$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

$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

$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->vfs->write_userfile

$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

$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();

5.5 Email/NNTP Functions

$phpgw->send->msg

$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);