Documenting classes and methods

The following code is the Bravo class that has been used for the date amfPHP tutorials. It has phpdoc tags added for the documentation example. This tutorial requires you to:

  • Follow what is written in this code sample
  • Compare the tags used in the code sample with the phpdoc.org website
  • View the generated output

Make sure you check out my other tutorial on documenting properties.

Just be careful if you copy and paste because Drupal has done some interesting things with the hyperlinks in the source code.

<?php
/**
* Bravo.php
*
* this is a page-level doc.  Stuff related to this package or file would normally be placed here...
* @package RPC
* @author brent
* @version 1
*/
 
require_once 'VO/DataLine.php';
 
 
/**
* This object is used for demonstration purposes of RPC with Flex.  
*
* In Flex I will connect to this object via the default AMFChannel.  An example of {@link <a href="http://www.brentknigge.com/?q=node/497">http://www.brentknigge.com/?q=node/497</a> setting up the Channel} is available on this website.
*
* Make sure you check (expand the method) token_call and insert_date for additional tags that I have used.
* @package 		RPC
* @author       Brent Knigge
* @copyright    20 January 2013
* @version 1
* @link <a href="http://www.brentknigge.com/?q=node/504">http://www.brentknigge.com/?q=node/504</a> View the contents of this file.
* @TODO tidy up the code a bit more, and add some private / protected methods for demonstration.
*/
class Bravo
//********************************************************************
{
/**
* @var resource 
* database connection
*/
private $dbc;
 
/**
* short description is written here
*
* An extended longer version is written here.  It is shown when you click on the thingy...
* @return void
*/
public function __construct()
//--------------------------------------------------------------------
{
$this->dbc = new PDO('mysql:dbname=DB_NAME;host=localhost', 'USERNAME', 'PASSWORD');
}
 
 
/**
* get_date
*
* This method demonstrates how to create a Date in PHP and pass it to Flex using AMFphp
* @return VO\DataLine
*/
public function get_date()
//--------------------------------------------------------------------
{
//lets create a dataline object, and populate it with some data...
$return_data = new DataLine();
 
//ANZAC Day Dawn Service
$date = new DateTime('2013-04-25 04:10:00');
 
//Amfphp_Core_Amf_Types_Date expects a UNIX timestamp in milliseconds.
$unix_date = $date->format('U');
 
//PHP can return UNIX timestamp in seconds, therefore we must multiple by
//1000 to pass in the correct value otherwise we will get a very strange date.
$return_data->some_date = new Amfphp_Core_Amf_Types_Date($unix_date * 1000); //this works.
 
return $return_data;
}
 
 
/**
* insert_date
*
* A sample method that has been written to test inserting a date into a MySQL database from Flex.  Make sure you check out the {@link <a href="http://help.adobe.com/en_US/as3/dev/WS5b3ccc516d4fbf351e63e3d118a9b90204-7f10.html#WS5b3ccc516d4fbf351e63e3d118a9b90204-7f0c">http://help.adobe.com/en_US/as3/dev/WS5b3ccc516d4fbf351e63e3d118a9b90204...</a> valid string formats} for creating Flex Dates.
*
* <code>
* var trial : DataLineFlex = new DataLineFlex();
* trial.some_char = 'trial of AMFPHP';
* trial.some_int  = 9;
* trial.some_date = new Date("Wed Apr 25 2012 4:00:00 PM");
*				
* Bravo.insert_date(trial);
* </code>
*
* @param DataLine $p_data object containing the data to be inserted into the table
*
* @return void
*/
public function insert_date($p_data)
//-----------------------------------------------------------------
{
//-----
//--prepare the insert query
//-----
$query = "INSERT INTO table1 VALUES (NULL, :i_int, :i_char, :i_date)";
 
$insert_stmt = $this->dbc->prepare($query);
//-----
 
//-----
//--prepare the date parameter
//-----
if(!empty($p_data->some_date))
  {  
  //-- Remember we get the time stamp from Flex in milliseconds, so we need to divide by 
  //-- 1000 so that we have seconds that we can use with PHP.
  $insert_date = DateTime::createFromFormat('U', $p_data->some_date->timeStamp / 1000); 
  $insert_date->setTimezone(new DateTimeZone('Australia/Sydney'));
  $myDate = $insert_date->format('YmdHis');
  }
else
  {
  $myDate = date('Ymd');
  }
//-----
 
 
//-----
//--bind the parameters, execute the query and get the insertId
//-----
$insert_stmt->bindParam('i_char', $p_data->some_char, PDO::PARAM_STR);
$insert_stmt->bindParam('i_int',  $p_data->some_int,  PDO::PARAM_INT);
$insert_stmt->bindParam('i_date', $myDate, PDO::PARAM_INT);
 
$insert_stmt->execute();
}
 
 
/**
* get_random_record
*
* Returns a random record.
* @return DataLine
*/
public function get_random_record()
//-----------------------------------------------------------------
{
$query = "SELECT table1_id, some_char, some_int, some_date
          FROM   table1
		  ORDER BY RAND()";
 
$result = $this->dbc->query($query);
 
$row = $result->fetchObject();
 
$return_data = new DataLine();
 
$return_data->some_id   = (int)$row->table1_id;
$return_data->some_int  = (int)$row->some_int;
$return_data->some_char = (string)$row->some_char;
$return_data->some_date =  new DateTime($row->some_date);
 
return $return_data;
}
 
 
/**
* get_record_at
*
* Returns a record based on the primary key that is passed in.  If no entry exists, then an empty object is returned.
* @param  int $p_index_id primary key of the record you wish to retrieve
* @return DataLine
*/
public function get_record_at($p_index_id)
//-----------------------------------------------------------------
{
$query = "SELECT table1_id, some_char, some_int,            
				 UNIX_TIMESTAMP(some_date) as mod_date1,
          FROM   table1
		  WHERE  table1_id = :index_id";
 
$stmt = $this->dbc->prepare($query);
$stmt->bindParam('index_id', $p_index_id, PDO::PARAM_INT);
$stmt->execute();
 
$row = $stmt->fetchObject();
 
$return_data = new DataLine;
 
if($row)
  {  
  $return_data->some_id   = (int)$row->table1_id;
  $return_data->some_int  = '(int)$row->some_int';
  $return_data->some_char = (string)$row->some_char;
  $return_data->some_date =  new Amfphp_Core_Amf_Types_Date($row->mod_date1 * 1000); //this works.
  }
 
return $return_data;
}
 
 
/**
* get_all_records
*
* Returns all the records in the table. 
* @return array of DataLine
*/
public function get_all_records()
//-----------------------------------------------------------------
{
$query = "SELECT table1_id, some_char, some_int, 
                 some_date as mod1,
				 UNIX_TIMESTAMP(some_date) as mod2
          FROM   table1";
 
$result = $this->dbc->query($query);
 
$return_data = array();
while($row = $result->fetchObject())
  {
  $temp = new DataLine();
 
  $temp->some_id   = (int)$row->table1_id;
  $temp->some_int  = (int)$row->some_int;
  $temp->some_char = (string)$row->some_char;
  $temp->some_date = new Amfphp_Core_Amf_Types_Date($row->mod2 * 1000);  //amfphp
 
  $return_data[] = $temp;
  }
 
return $return_data;
}
 
/**
* insert_record
*
* Inserts a DataLine object into Table1
* @param VO/DataLine  
* @return array of DataLine
*/
public function insert_record($p_data)
//-----------------------------------------------------------------
{
//-----
//--prepare the insert query
//-----
$query = "INSERT INTO table1 VALUES (NULL, :i_int, :i_char, :i_date)";
 
$insert_stmt = $this->dbc->prepare($query);
//-----
 
 
//-----
//--prepare the date parameter
//-----
if(!empty($p_data->some_date))
  {
  //--31 Aug 2011 00:00:00
  //-- this is for ZendAMF.  Notice the format.
  //-- $insert_date = DateTime::createFromFormat('j M Y H:i:s', $p_data->some_date);
 
  //-- this is for AMFPHP (which converts to a timestamp in UTC)
  //TODO investigate timezone more and see if I can make this code a bit cleaner.
  $insert_date = DateTime::createFromFormat('U', $p_data->some_date->timeStamp / 1000, new DateTimeZone('Europe/London')); 
  $insert_date->setTimezone(new DateTimeZone('Australia/Sydney'));
  $myDate = $insert_date->format('YmdHis');
  }
else
  {
  $myDate = date('YmdHis');
  $p_data->some_date = new dateTime();
  $p_data->some_date->setTimezone(new DateTimeZone('Australia/Sydney'));
  $p_data->some_date = $p_data->some_date->format('U') * 1000;
  }
//-----
 
 
//-----
//--bind the parameters, execute the query and get the insertId
//-----
$insert_stmt->bindParam('i_char', $p_data->some_char, PDO::PARAM_STR);
$insert_stmt->bindParam('i_int',  $p_data->some_int,  PDO::PARAM_INT);
$insert_stmt->bindParam('i_date', $myDate, PDO::PARAM_INT);
 
$insert_stmt->execute();
 
$p_data->some_id = (int)$this->dbc->lastInsertId();
//-----
 
return $p_data;
}
 
 
/**
* token_call
*
* A method that has been designed to test the ASyncToken class from Flex.  
*
* * First call takes 10 seconds
* * Second call takes 5 seconds 
* * Third call takes 15 seconds.
* 
* When the button is hit in rapid succession, ABC is passed to PHP.  BAC is returned to Flex based on the time delay. 
* @param string a letter of either A, B or C  
* @return string a simple statement is returned. 
*/
public function token_call($p_letter)
//-----------------------------------------------------------------
{
$statement = 'default';
switch($p_letter)
  {
  case 'A' : 
    sleep(10);
	$statement = 'a bit slow is A';
	break;
 
  case 'B' : 
    sleep(5);
	$statement = 'a bit quicker is B';
	break;
 
  case 'C' :
    sleep(15);
	$statement = 'even slower is C';
	break;
  }
 
return $statement;
}
 
 
};
 
?>