Manual

Provides methods to create and manipulate .htaccess files.

Introduction

Introduction – what are .htaccess files

What is File_HtAccess?

File_HtAccess provides common methods to create and manipulate Apache / NCSA style .htaccess files. These files together with accompanying password files are used to protect webserver directories. Since File_HtAccess does not provide any means to manipulate or create password files you should use it together with File_Passwd.

What are .htaccess files?

The most common and the original purpose of .htaccess files is to create per-directory password protection of resources. With modern webservers there is vast amount of other things .htaccess files can do. These include: custom error pages, ip based access control, redirecting users automatically, denying directory listing and using different files as an index file.

File_HtAccess concentrates only to password protection of directories, although it is possible to use it to control other things mentioned above too.

A .htaccess file is built from the following basic directives. They differ a bit whether youre using Basic or Digest authentication.

Directives
Directive	Purpose
AuthType	Authentication type being used, "Basic" or "Digest".
AuthName	Authentication realm or name.
AuthUserFile	Full path to password file if using Basic authentication.
AuthGroupFile	Full path to group file if using Basic authentication.
AuthDigestFile	Full path to password file if using Digest authentication.
AuthDigestGroupFile	Full path to group file if using Digest authentication.
Require	Requirements which must be met to grant access.

File_HtAccess provides method accessor methods with corresponding names for each of these directives, such as getAuthType() and setAuthType().

A typical .htaccess file looks like this:

AuthName "Protected"
AuthType Basic
AuthUserFile /usr/local/apache/conf/users.dat
require valid-user

What is Basic authentication

When a client requests resource protected with basic authentication webserver responds with a 401 Authentication Required header. When client receives 401 header it asks the user for username and password. If authentication succeeds, the protected resource will be sent to the client. Otherwise the access will be denied.

What is Digest authentication

Even though the passwords are stored encrypted on serverside they are sent cleartext between client and server when using Basic authentication. With Digest authentication the passwords are never sent cleartext but as a MD5 digest instead. The caveat is, most browsers do not support Digest authentication.

File_HtAccess::file_htaccess()

File_HtAccess::file_htaccess() – constructor

Synopsis

object new File_HtAccess ( string $file='.htaccess' , array $params )

Description

Creates an instance of a File_HtAccess object.

Parameter

string $file - filename to use. Defaults to .htaccess
array $params - a array of parameters which can be:
- $params['authname'] - authname
- $params['authtype'] - authtype
- $params['authuserfile'] - authuserfile
- $params['authgroupfile'] - authgroupfile
- $params['require'] - require
- $params['additional'] - additional

Return value

object - instance of File_HtAccess

Example

How to create new instance of File_HtAccess

<?php
require_once('File/HtAccess.php');
$fh = new File_HtAccess('.htaccess');
?>

File_HtAccess::load

File_HtAccess::load() – load the contents of existing .htaccess file

Synopsis

mixed File_HtAccess::load ( )

Description

Load the contents of .htaccess file.

Return value

mixed - Returns TRUE on success, PEAR_Error on failure.

Note

This function can not be called statically.

Example

Using File_HtAccess::load()

<?php
require_once('File/HtAccess.php');

$fh     = new File_HtAccess('.htaccess');
$status = $fh->load();

if (PEAR::isError($status)) {
  // handle errors
} else {
  // continue processing
}
  
?>

File_HtAccess::save()

File_HtAccess::save() – saves the .htaccess file

Synopsis

mixed File_HtAccesss:save ( )

Description

Saves the contents of File_HtAccess object as a corresponding .htaccess file on the disc.

Return value

mixed - Returns TRUE on success, PEAR_Error on failure.

Note

This function can not be called statically.

Example

Using File_HtAccess::save()

<?php
require_once('File/HtAccess.php');

/* create a new .htaccess file with given parameters */
$params['authname']      = 'Private';
$params['authtype']      = 'Basic';
$params['authuserfile']  = '/path/to/.htpasswd';
$params['authgroupfile'] = '/path/to/.htgroup';
$params['require']       = array('group', 'admins');

$fh     = new File_HtAccess('.htaccess', $params);
$status = $fh->save();

if (PEAR::isError($status)) {
    // handle errors
} else {
    // continue processing
}

?>

File_HtAccess::setRequire()

File_HtAccess::setRequire() – set the value of require property

Synopsis

void File_HtAccess::setRequire ( mixed $require )

Description

Sets the value of require property.This overwrites the previous value. If you need to add a value (user) to require use File_HtAccess::addRequire() instead. Using this method you can control which users will be able to access the protected resources.

Parameter

mixed $require - value the requre property to be set to. Can be given as a string or an array. If given as a string separate multiple values with a space.

Return value

void

Note

This function can not be called statically.

See

Example

Using File_HtAccess::setRequire()

<?php
require_once('File/HtAccess.php');

/* let any valid user access the resource */
$fh = new File_HtAccess('.htaccess');
$fh->load();
$fh->setRequire('valid-user');
$fh->save();

/* let user tuupola or panula access the resource  */
$fh = new File_HtAccess('.htaccess');
$fh->load();
$fh->setRequire(array('user', 'tuupola', 'panula'););
$fh->save();

/* let anyone from group admins to access the resource  */
$fh = new File_HtAccess('.htaccess');
$fh->load();
$fh->setRequire(array('group', 'admins'););
$fh->save();

?>

File_HtAccess::addRequire()

File_HtAccess::addRequire() – add a value into require property

Synopsis

void File_HtAccess::addRequire ( string $require )

Description

Adds a value (user) into require property. Using this method you can control which users will be able to access the protected resources.

Parameter

string $require - value (user) to be added to require property.

Return value

void

Note

This function can not be called statically.

See

Example

Using File_HtAccess::addRequire()

<?php
require_once('File/HtAccess.php');

/* add user tuupola to list of users to be granted access */
$fh = new File_HtAccess('.htaccess');
$fh->load();
$fh->addRequire('tuupola');
$fh->save();

?>

File_HtAccess::delRequire()

File_HtAccess::delRequire() – remove a value from require property

Synopsis

void File_HtAccess::delRequire ( string $require )

Description

Remove a value (user) from require property. Using this method you can control which users will be able to access the protected resources.

Parameter

string $require - value (user) to be added to require property.

Return value

void

Note

This function can not be called statically.

See

Example

Using File_HtAccess::delRequire()

<?php
require_once('File/HtAccess.php');

/* remove user viemero from list of users to be granted access */
$fh = new File_HtAccess('.htaccess');
$fh->load();
$fh->delRequire('viemero');
$fh->save();

?>

File_HtAccess::getRequire()

File_HtAccess::getRequire() – get the value(s) of require property

Synopsis

array File_HtAccess::getRequire ( )

Description

Get the value(s) of require property as an array. Require property contains the usernames or groups users who are allowed to access protected resources. Value valid-user means all users listed in password file are allowed to access.

Parameter

string $type - if 'string' return value will be a string with usernames separated by a space character. Otherwise return value will be an array(). Defaults to an array.

Return value

mixed string or array depending on $type parameter.

Note

This function can not be called statically.

See

Example

Using File_HtAccess::getrequire()

<?php
require_once('File/HtAccess.php');

/* add user tuupola and viemero to list of users to be granted access */
$fh = new File_HtAccess('.htaccess');
$fh->addRequire('tuupola');
$fh->addRequire('viemero');

$require1 = $fh->getRequire();
$require2 = $fh->getRequire('string');

print_r($require1);

/* Array              */
/* (                  */
/*    [0] => tuupola  */
/*    [1] => viemero  */
/* )                  */

print_r($require2);

/* tuupola viemero    */

?>

File_HtAccess::setProperties()

File_HtAccess::setProperties() – set the values of objects properties

Synopsis

void File_HtAccess::setProperties ( array $params )

Description

Set the values of objects properties as defined by hash given as a parameter. You can use this method as an alternative to passing property values in constructor .

Parameter

$params['authname'] - authname
$params['authtype'] - authtype
$params['authuserfile'] - authuserfile
$params['authgroupfile'] - authgroupfile
$params['require'] - require
$params['additional'] - additional

Return value

void

Note

This function can not be called statically.

See

File_HtAccess::file-htaccess()

Example

Using File_HtAccess::setProperties()

<?php
require_once('File/HtAccess.php');

/* let any valid user access the resource */
$fh = new File_HtAccess('.htaccess');

$params['authname']      = 'Private';
$params['authtype']      = 'Basic';
$params['authuserfile']  = '/path/to/.htpasswd';
$params['authgroupfile'] = '/path/to/.htgroup';
$params['require']       = array('group', 'admins');

$fh->setProperties($params);

?>

File_HtAccess::setAuthUserFile()

File_HtAccess::setAuthUserFile() – set the value of authuserfile property

Synopsis

void File_HtAccess::setAuthUserFile ( string $file )

Description

Sets the value of authuserfile property. AuthUserFile is the password file which contains username:password pairs for Basic authentication. You must give full path to the password file in order for it to work.

Parameter

string $file - absolute pathname to the password file.

Return value

void

Note

This function can not be called statically.

See

File_HtAccess::getAuthDigestFile()

Example

Using File_HtAccess::setAuthUserFile()

<?php
require_once('File/HtAccess.php');

/* set the password file to /etc/htpasswd */
$fh = new File_HtAccess('.htaccess');
$fh->load();
$fh->setAuthUserFile('/etc/htpasswd');
$fh->save();

/* set the password file to .htpasswd in current working directory */
$file = getcwd() . '/.htpasswd'; 
$fh = new File_HtAccess('.htaccess');
$fh->load();
$fh->setAuthUserFile($file);
$fh->save();

?>

File_HtAccess::setAuthGroupFile()

File_HtAccess::setAuthGroupFile() – set the value of authgroupfile property

Synopsis

void File_HtAccess::setAuthGroupFile ( string $file )

Description

Sets the value of authgroupfile property. AuthGroupFile a file containing names of the groups and usernames belonging to the group. You must give full path to the group file in order for it to work.

Parameter

string $file - absolute pathname to the group file.

Return value

void

Note

This function can not be called statically.

Example

Using File_HtAccess::setauthgroupfile()

<?php
require_once('File/HtAccess.php');

/* set the group file to /etc/htgroup */
$fh = new File_HtAccess('.htaccess');
$fh->load();
$fh->setAuthGroupFile('/etc/htgroup');
$fh->save();

?>

File_HtAccess::setAuthType

File_HtAccess::setAuthType – set the value of authtype property

Synopsis

void File_HtAccess::setAuthType ( string $type='Basic' )

Description

Sets the value of authtype property. Almost allways you will be using Basic authentication. Since most browsers don't yet support Digest authentication you should only use Digest if you can control what browsers will be accessing the resources.

Parameter

string $type - authentication type to use. Should be Basic os Digest. Defaults to Basic.

Return value

void

Note

This function can not be called statically.

Example

Using File_HtAccess::setAuthType()

<?php
require_once('File/HtAccess.php');

/* use Digest authentication  */
$fh = new File_HtAccess('.htaccess');
$fh->load();
$fh->setAuthType('Digest');
$fh->save();

?>

File_HtAccess::setAuthDigestFile

File_HtAccess::setAuthDigestFile – set the value of authdigestfile property

Synopsis

void File_HtAccess::setAuthDigestFile ( string $file )

Description

Sets the value of authdigestfile property. AuthDigestFile is the password file which contains username:realm:password pairs for Digest authentication. You must give full path to the password file in order for it to work.

Parameter

string $file - absolute pathname to the password file.

Return value

void

Note

This function can not be called statically.

See

File_HtAccess::setAuthUserFile()

Example

Using File_HtAccess::setauthdigestfile()

<?php
require_once('File/HtAccess.php');

/* set the password file to /etc/htdigest */
$fh = new File_HtAccess('.htaccess');
$fh->load();
$fh->setauthdigestfile('/etc/htdigest');
$fh->save();

?>