>> Table of Contents >> Developer's Manual

File system

How do I get the content of directories?

The function dirlist() returns a sorted list of files and directories for a directory . The compulsory directory entries "." and ".." are not listed. Files whose filenames begin with the character "." will also not be listed. This applies in particular file names such as ".htaccess" or ".password". The file names contain no paths. Directory names do not contain a final dash "/".

The optional parameter $filter can be used to limit the results to certain file extensions. Wildcards are not permitted. The file filter can only contain alphanumeric characters, as well as the characters '.', ' -' and ' _'. Other characters are removed automatically.

list all items in a directory:
<?php 
echo implode("<br>"dirlist("foo/"));
?>

Output:

foo1.foo2
foo3.foo2
foo4.foo5
foo6.foo7

list all entries with a certain file extension:
<?php 
echo implode("<br>"dirlist('foo/''*.foo2'));
?>

Output:

foo1.foo2
foo3.foo2


... with multiple file extensions:

<?php 
echo implode("<br>"dirlist('foo/''*.foo2|*.foo5'));
?>

Output:

foo1.foo2
foo3.foo2
foo4.foo5

using OO-style notation:

<?php 
$dirStream = new DirStream("foo/");
$dirStream->read();
$dirlist $dirStream->dirlist('*.foo2|*.foo5');
echo implode("<br>"$dirlist);

/* Note: setting the file filter has a permanent effect. */

$dirStream->dirlist('*.foo2|*.foo5');
echo $dirStream->length();
/* Output: 2 */

echo count($dirStream->get());
/* Output: 2 */

/* A new call to dirlist() resets the file filter */
$dirStream->dirlist("");
echo $dirStream->length();
/* Output: 4 */
?>

How do I create or delete directories?

The functions $dirStream->create($mode) and $dirStream->delete() are responsible for creating and deleting directories. The optional parameter $mode can be used to set permissions of directories for LINUX / UNIX operating systems. The default value is 777.

Examples of valid values for $mode are listed in the following table. Where "r" is "readable", "w" is "writable", and "x" is "executable.

Owner Group Other users Value

rwx

rwx

rwx

777

rw-

rw-

---

660

rw-

rw-

rw-

666

rwx

r-x

r-x

755

rwx

r-x

---

750

rwx

---

---

700

Examples of valid values (corresponding to Unix: CHMOD)

<?php 
$dirStream = new DirStream("foo/");
$dirStream->read();

/* create directory "foo/" */
$dirStream->create();

/* directory "foo/" with access restrictions set to 660 */
$dirStream->create(660);

/* get number of files in a directory */
print "Directory 'foo/' contains ".$dirStream->length()." files.";

/* delete directory "foo/" */
$dirStream->delete();

/* delete directory "foo/" including all files and subdirectories */
$dirStream->delete(true);

/* check if directory exists */
$test $dirStream->exists();
if ($test === true) {
    print "directory exists";
} else if ($test === false) {
    print "directory does NOT exist";
}
?>

How do I read the contents of a configuration file or SML file?

The function SML::getFile() reads the specified configuration file in SML format and returns the contents as a PHP variable.

<?php 
/* read contents from file and return result as an array */
$array SML::getFile("foo.config");

/* transform keys to capital letters */
$array SML::getFile("foo.config"CASE_UPPER);

/* transform keys to in small letters */
$array SML::getFile("foo.config"CASE_LOWER);

/* leave keys untouched (default) */
$array SML::getFile("foo.config"CASE_MIXED);

/* ... or: */
$array SML::getFile(file("foo.config"));

/* ... or: */
$array SML::decode(file_get_contents("foo.config"));

/* create and decode an SML-encoded string */
$input_array  = array(1,2,3,array(4,5),'a'=>6,'B'=>7);
$output_array SML::decode(SML::encode($input_array));
$input_array == $output_array// true

/* OO-style, mixed key case */
$configFile = new ConfigFile("foo.config");
$configFile->read();
$array $configFile->get();

/* OO-style capitalized key names */
$smlFile = new SML("foo.config");
$smlFile->read();
$array $smlFile->get();
?>

Navigating within a SML file:

Given the file "foo.config" with the following contents:

<ROOT>
	<FOO1>
		<FOO2>text</FOO2>
		<FOO3>
			<0>1</0>
			<1>foo</1>
		</FOO3>
	</FOO1>
</ROOT>

<?php 
$mixed $smlFile->get("ROOT.FOO1");
print_r($mixed);
?>

This query returns the subtree ROOT.FOO1 with FOO1 as the root element.

Output:

array(
	"FOO2" => "text",
	"FOO3" => array (
		0 => 1,
		1 => "foo"
	)
)

How do I write a variable to a config file or SML file?

The function SML::encode() returns a representation of a specified variable as SML code. The input must be either a variable with a scalar value or an array.

Pleas note: the function "SML: encode" does not detect infinite recursion. Therefore data fields need to be free of recursion. Otherwise, the compiler will present an error message.

Save the contents of an array to "foo.config":

<?php 
$string SML::encode($array"ROOT");
file_put_contents("foo.sml"$string);
?>

Replace "ROOT" with the name of the root element!

Using capital, small and mixed writing is the same as in SML::decode():

<?php 
$string SML::encode($array"ROOT"CASE_UPPER); // capital letters
$string SML::encode($array"ROOT"CASE_LOWER); // small 
$string SML::encode($array"ROOT"CASE_MIXED); // mixed (default)
?>

OO-style notation, mixed case:

<?php 
$configFile = new SML("foo.sml");
$configFile->read();
$configFile->create();
$configFile->insert($string);
$configFile->write();
?>

oo-style notation, keys capitalized:

<?php 
$smlFile = new SML("foo.sml"CASE_UPPER);
$smlFile->read();
$smlFile->create();
$smlFile->insert($string);
$smlFile->write();
?>

How do I copy a file?

To copy a file, all YANA classes that represent files, implement a function "copy". When copying the file you may also set access restrictions. If the directory, in which the file is to be copied, does not exist, it can be created automatically. The latter is optional.

The following are some examples.

copy a file:

<?php 
$foo = new SecureFileStream("foo.txt");
$foo->copy("bar.txt");

$foo->copy("bar.txt"); // error: file already exists
?>

copy a file and overwrite existing files:

<?php 
$foo->copy("bar.txt"true);

$foo->copy("bar/foo2.txt"); // error: directory 'bar' does not exist
?>

copy a file and create missing files automatically:

<?php 
$foo->copy("bar/foo2.txt"falsetrue);

/* The directory 'bar/' has been created and file 'foo2.txt' has been stored in it.
   Access restrictions of this directory have been set to 766 by default. */

/* deleting the directory */
$dir = new DirStream("bar");
$dir->delete(true);
?>

copy a file and set access restrictions of the copied file to 655:

<?php 
$foo->copy("bar/foo2.txt"falsefalse655);

/* directory 'bar/' has been created again.
   The access restrictions for the directory have been set to 655 -
   as for the file. */
?>

Author: Thomas Meyer, www.yanaframework.net