Talk In Code

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"

It is sometimes necessary to block people from using your site, dependent on their IP address. A users IP address can be detected by PHP using the $_SERVER superglobal and the parameter REMOTE_ADDR.

The code includes two ways to load the list of IP addresses. The first is by hard coding it into an array, and the second is by the use of a plain text file called "blocked_ips.txt". The format of this file is simply a list of IP addresses, with one address on each line. Through the use of the file() function this file is loaded as an array into of addresses.

if(!file_exists('blocked_ips.txt')){
 $deny_ips = array(
  '127.0.0.1',
  '192.168.1.1',
  '83.76.27.9',
  '192.168.1.163'
 );
}else{
 $deny_ips = file('blocked_ips.txt');
}
// read user ip adress:
$ip = isset($_SERVER['REMOTE_ADDR']) ? trim($_SERVER['REMOTE_ADDR']) : '';
 
// search current IP in $deny_ips array
if((array_search($ip, $deny_ips))!== FALSE){
 // address is blocked:
 echo 'Your IP adress ('.$ip.') was blocked!';
 exit;
}

There are two things you should be aware of when using this method.
The first is that a users IP address can change due to many factors. They could either move to a different building or their ISP could assign a different IP address for them.
The second thing to be aware of is that you should be careful when entering IP addresses so that you don’t block search engine spiders from looking at your site. Instead of spidering your content they will just index the phrase "Your IP address (0.0.0.0) was blocked!"