Talk In Code

Apache can be set up to log all sorts of information

As of Apache 2.2 the basic log file format that a fresh install of Apache will produce will have the following format:

%h %l %u %t "%r" %>s %b

Which doesn’t mean a lot to the uninitiated, so here is a short explanation of each.

• %h - The remote host. This is the IP address of the user connecting to the server.
• %l - The remote logname. This is not always present.
• %u - The remote user from auth (nothing if authentication is not used).
• %t - The time in a common log format.
• "%r" - The first line of the request, basically the method used (GET/POST) the URL that was accessed and the HTTP protocol level that was used. This is enclosed in quotes.
• %>s - %s returns the status of the original request request. For some requests Apache will internally create a secondary request, so %>s prints out the last request staus.
• %b - This is the number of bytes transmitted to the user.

This would produce the following sort out output.

127.0.0.1 - - [17/Apr/2009:14:12:20 +0100] "GET / HTTP/1.1" 200 515

This information can be converted into a database format by using the LOAD DATA command. First, lets create the table we need to store this log format.

DROP TABLE IF EXISTS `test`.`apachelog`;
CREATE TABLE  `test`.`apachelog` (
  `remote_host` varchar(17) DEFAULT NULL,
  `remote_logname` varchar(45) DEFAULT NULL,
  `remote_user` varchar(45) DEFAULT NULL,
  `time1` varchar(22) DEFAULT NULL,
  `time2` varchar(7) DEFAULT NULL,
  `first_line_of_request` text,
  `last_request_status` varchar(4) DEFAULT NULL,
  `bytes_sent` varchar(10) DEFAULT NULL
)

Here is the command that is used to convert the log file into that table.

LOAD DATA INFILE 'C:/Program Files/Apache Software Foundation/Apache2.2/logs/access.log' INTO TABLE apachelog
FIELDS TERMINATED BY ' ' OPTIONALLY ENCLOSED BY '"' ESCAPED BY ''
LINES TERMINATED BY 'rn';

Note that our table contains two fields for the time. This is because of two factors. The first is that each field is defined by a space, and because the time value contains a space it is split into two fields. The second is that although we say OPTIONALLY ENCLOSED BY '"' to stop the %r output being split apart, we can’t give the LOAD DATA command more than one of these fields. As a result the time is split into the two fields, so we just create a table with more than one field for time to accommodate this.

To improve the table we can use a different output format. Take the following slight alteration to our log file format.

LogFormat "%h,%l,%u,%t,"%r",%>s,%b"

This line can be found in your http.conf file or your httpd-vhosts.conf if you have set up virtual hosts.

This will cause our output to look like the following:

127.0.0.1,-,-,[20/Apr/2009:14:42:01 +0100],"GET / HTTP/1.1",200,515

We can now change out two time columns to a single one, setting the datatype to VARCHAR(30) and using the following LOAD DATA syntax to load our data.

LOAD DATA INFILE 'C:/Program Files/Apache Software Foundation/Apache2.2/logs/access.log' INTO TABLE apachelog
FIELDS TERMINATED BY ',' OPTIONALLY ENCLOSED BY '"' ESCAPED BY ''
LINES TERMINATED BY 'rn';

This gives us a much better set of data in our table.

You can also use the following three MySQL commands to convert from the old table format to the new one.

ALTER TABLE apachelog CHANGE time1 time VARCHAR(40);
UPDATE apachelog SET time = CONCAT(time,' ',time2);
ALTER TABLE apachelog DROP COLUMN time2;

The time2 column will now no longer exist.

This simple code example uses a combination of strrchr to find the last occurrence of a string and substr to return part of the string in order to find the file extension for a given filename. This is ideal if you want to quickly find a file extension.

$ext = substr(strrchr($fileName, '.'), 1);

This code can be used in the following way.

$fileName = '\path\to\file\afile.wibble';
$ext = substr(strrchr($fileName, '.'), 1);
echo $ext;

The output here is 'wibble';

If you followed the tutorial on installing PHPDoc then you are probably wondering how to get started actually writing the documentation. PHPDoc will parse all the files given to it and look for comment blocks, it will then use these blocks to create the documentation for your application. A valid PHPDoc comment block must start with a '/**', have a '*' on every line and finish with '*/'. The comment must appear before the section that is being commented upon and any lines within the comment without a '*' will be ignored by the parser.

To create some sample documentation we will use the following useless class.

<?php
include('another_file.php');
 
class MyClass
{
 
  public $publicVariable = 123;
  private $privateVaraible;
 
  public function aFunciton($parameter)
  {
    // some code here...
  }
 
}

The first thing we need to do is create a file comment, this comment is intended to tell people what this file contains. In this example the file contains a single class definition and an include statement.

/**
 * MyClass File (short description about the file)
 *
 * This file contains the definition of the file MyClass (a longer description about the file).
 * @author A.N. Other
 * @version 1.0
 * @package MyPackage
 */

Notice the use of the @ symbol. This is called a tag and allows PHPDoc to assign values to internal variables. So when we use @version, we are setting the version variable for our file.

define() statements, functions, classes, class methods, and class vars, include() statements, and global variables can all be documented. So the next step is to document what the include statement includes. PHPDoc will attempt to find any files referenced through include or require statements and generate documentation for those files. If present, a link will be created from this file to that file in the documentation.

/**
 * Include the another_file.php file.
 */
include('another_file.php');

Next is our class definition, which consists of two forms of description(short and long) as well as some tags relating to things like what package the class is in.

/**
 * This is a short description about the class.
 *
 * This is a longer description which should detail exactly what the class does.
 * @package test
 * @author A.N. Other
 * @version 1.0
 * @copyright A copyright notice, if any.
 */
class MyClass
{
}

The two variables within the class must also be documented.

/**
 * A description of the variable.
 * @var integer
 */
public $publicVariable = 123;
 
/**
 * This variable will only appear in our documentation is we set the --parseprivate attribute on the command line or it has been set up in the INI file.
 * @access private
 * @var string
*/
private $privateVaraible;

Finally, we document the function. The functions are documented using the two tags of @param and @return. The @param can be defined multiple times and is a descriptive list of the parameters that the function takes. The @return value can only be defined once and describes what the function returns. If more than one datatype is returned from the function then they can be separated by a pipe (|).

/**
 * This class either returns an integer or a string.
 * @param A description about the parameter $parameter
 * @return string|int This function returns a string or an integer.
 */
public function aFunciton($parameter)
{
  // some code here...
}

To add more than one parameter just add another line in that starts with @param.

You can run PHPDoc on this file by using the following command (assuming that your project is kept in a folder called "MyProject" and that you want the documentation to go in "docs" within that directory.

C:\MyProject>phpdoc -t "C:\MyProject\docs" -o HTML:frames:default -d "C:\MyProject"

After following the last post on deleting files and directories in Phing you might now be wondering if you can create things as well. The answer is yes.

To create a directory with Phing you need to use the mkdir element. The dir attribute is used to give the name of the directory to be created. The following example will create a directory called myProject_build in the current working directory (ie. where you are running phing from).

<mkdir dir="myProject_build" />

That is about as complicated as the mkdir element gets, although you can also pass a parameter to the dir attribute.

<mkdir dir="${projectDirectory}" />

To create a file with Phing you need to use the touch element. The file attribute is used to give the name of the file being created.

<touch file="README.txt" />

You can optionally include one of two date attributes in the touch element. This are datetime (as a date string) and millis (as an integer timestamp) which set the creation timestamp of the file. If you don’t include either of these attributes then the current time stamp (ie. now) will be used instead.

Although using Phing is mainly about copying files, you might also need to delete directories and files using the delete element. Remember that the default behavior of copy command copies files only if the source files are different from the destination files. A prudent approach might be to delete the build directory and then recreate it, ready for Phing to copy files into.

To delete a directory you need to use the dir attribute of the delete element, the delete element also accepts the file attribute to delete specific files. The following target will delete the directory myProject_build.

<target name="prepare">
<delete dir="myProject_build" />
</target>

The delete element can also accept a fileset element, which will delete multiple files. the following code will delete any php file from the myProject_build folder and from a sub folder called app.

<fileset dir="./" id="deleteFiles">
 <include name="myProject_build/*.php" />
 <include name="myProject_build/app/*.php" />
</fileset>
 
<target name="prepare">
  <delete>
    <fileset refid="deleteFiles" />
  </delete>
</target>

Remember when doing this to remove any dir or file attributes from the delete element as they can interfere with your fileset. Also, if you use a fileset be careful not to use the same fileset that copies the files into the build directory as the only thing you will accomplish is the deletion of your application. This is quite easy to do, I even did it whilst testing the previous example!