Flatpress Documentation

FLATPRESS DOCUMENTATION v0.1 BETA

This document uses the revision 399 of Flatpress' SVN Repository.
License of the document: public domain.

=== 1. General constants ===
Flatpress has some general and useful constants.
These are:

  * DUMB_MODE_ENABLED (declared in defaults.php line 19)

  * FILE_PERMISSIONS (declared in defaults.php line 22)
    This is the default permission for files in the octal format.

  * DIR_PERMISSIONS (declared in defaults.php line 23)
    This is the default permission for directories in the octal format.

  * SESSION_PATH (declared in defaults.php line 31)
    If you have troubles with sessions files, you can define here where you want
    to save sessions.
    If the constant is empty (and this is its default value) the default
    webserver's configuration will be used.

  * ABS_PATH (declared in defaults.php line 34)
    This is the absolute path to your Flatpress installation.

  * FP_DEFAULTS (declared in defaults.php line 39)
    This is the directory of the default configuration files.

  * FP_CONTENT (declared in defaults.php line 43)
    This is the writeable directory. All files that need to be changed by
    Flatpress should go here.

  * CONFIG_DIR (declared in defaults.php line 46)
    This is the directory where are saved the configuration files.

  * CONFIG_FILE
    This is the name of the main configuration file.

  * HASHSALT_FILE
    This is the name of the file where is contained the hash salt for passwords.

  * CONFIG_DEFAULT
    This is the name of the file that has the default configuration.

  * USERS_DIR
    This is the directory where are placed the files about users.

  * CONTENT_DIR
    The directory where entries, comments and static pages are saved.

  * FP_INCLUDES
    The directory that contains all includes files.

  * INCLUDES_DIR
    The directory of core scripts.

  * SMARTY_DIR
    The directory of smarty template engine.

TODO: Continue the list

=== 2. File system functions ===

==== 2.1 Low level io functions ====
/**
 * io_write_file
 *
 * This function writes some contents in a file and then sets the
 * FILE_PERMISSIONS chmods to it.
 * It also creates the directory of the file if it does not exist.
 *
 * @param string $filename: The file to write
 * @param mixed $data: The content to write
 * @return boolean: Did it succeed on writing?
 * @filesource fp-includes/core/core.fileio.php
 */

/**
 * io_load_file
 *
 * This function reads a file.
 *
 * @param string $filename: The file to read
 * @return mixed: The content or the boolean "false" on error.
 * @filesource fp-includes/core/core.fileio.php
 */

==== 2.2 fs_filelister class ====
/**
 * fs_filelister (class)
 *
 * This class makes the list of the files of a directory and optionally also
 * the files of its subdirectories.
 *
 * It can be easely extended by other classes.
 *
 * @filesource fp-includes/core/core.filesystem.php
 */

/**
 * Variable _list
 *
 * This variable is an array with the files.
 *
 * @var array
 */

/**
 * Variable _directory
 *
 * The directory to list.
 *
 * @var string
 */

/**
 * Variable count
 *
 * This variable is set by the count method and it's the number of elements in
 * $this->_list.
 *
 * @var integer
 */

/**
 * fs_filelister (constructor function)
 *
 * This is the constructor of the class.
 * It sets $this->_directory (if the $directory is not null) and starts the
 * listing.
 *
 * @param string $directory: The directory to list. It's optional.
 */

/**
 * _checkFile
 *
 * This function is called when a file or a subdirectory is found.
 * It has to add it to the list and it has to return what the _listFiles
 * function has to do:
 *   0 means go on
 *   1 means recurse the directory
 *   2 means exit the function
 *
 * By default this function just checks if the second param is not a directory
 * and return 0 (do not recurse sub directories).
 *
 * @param string $directory: The directory of the $file
 * @param string $file: The file name
 * @return integer: See the description
 */

/**
 * _exitingDir
 *
 * This function is called when _listFiles has done the recurse.
 * By default it does not do anything.
 *
 * @param string $directory: The directory of the $file
 * @param string $file: The file name
 * @return void
 */

/**
 * _listFiles
 *
 * This function makes the list of the files of a directory.
 *
 * @param string $directory: The directory to list
 * @return boolean: Does it succeed on listing?
 */

/**
 * getList
 *
 * This function returns $this->_list
 *
 * @return array: $this->_list
 */

/**
 * count
 *
 * Returns the number of elements in $this->_list.
 *
 * @return integer: See the description
 */

==== 2.3 Classes that extends fs_filelister ====
/**
 * fs_pathlister class
 *
 * This class extends the fs_filelister class but it recurses the directories.
 * The only overwritten method it's _checkFile
 *
 * @extends fs_filelister
 * @filesource fp-includes/core/core.filesystem.php
 */

===== 2.3.1 fs_chmodder =====
/**
 * class fs_chmodder
 *
 * Perform a recursive reset of file permission in the given $path
 * and its subdirectories to FILE_PERMISSIONS and DIR_PERMISSIONS.
 *
 * @extends fs_filelister
 * @filesource fp-includes/core/core.filesystem.php
 */

/**
 * variable _chmod_dir
 *
 * This is the octal chmod for directories.
 *
 * @var integer
 */

/**
 * variable _chmod_file
 *
 * This is the octal chmod for files.
 *
 * @var integer
 */

/**
 * method fs_chmodder (constructor)
 *
 * It sets the instance variables and starts the listing.
 *
 * @param string $directory: The directory where it has to operate
 * @param integer $ch_file: The chmod for files (default FILE_PERMISSIONS)
 * @param integer $ch_dir: The chmod for directories (default DIR_PERMISSIONS)
 */

/**
 * method _checkFile
 *
 * It sets the chmod and if it fails it adds to the list the file that it
 * couldn't set.
 *
 * @param string $directory: The directory of the $file
 * @param string $file: The file name
 * @return integer: 0 for files and 1 (recurse) for directories
 */

===== 2.3.2 cache_filelister =====
There is a class that caches fs_filelister but it uses a B+Tree Algorithm that I
can't document because is beyond my capabilities.
I'm sorry because it could be very interesting for people that studies Flat
Files in PHP.

==== 2.4 Other procedural functions ====
/**
 * fs_list_dirs
 *
 * I think that this function makes the list of a directory but it calls an
 * undefined function (lang_id) so I don't know what it does very well.
 *
 * @return array: The list of files
 * @filesource fp-includes/core/core.filesystem.php
 */

/**
 * fs_mkdir
 *
 * Recursively creates dirs.
 * Returns true on success, else false
 *
 * @param string $path: Directory or directories to create
 * @param integer $mode: octal permissions; default DIR_PERMISSIONS constant
 * @return boolean: Does it succeed on creation?
 * @link http://www.php.net/function.mkdir.php
 * @filesource fp-includes/core/core.filesystem.php
 */

/**
 * fs_delete
 *
 * Deletes a file and recursively deletes dirs, if they're empty.
 *
 * It "deletes" also non-existent files but return 2 if the file does not exist.
 * Otherwise, it it exists, it return a boolean value (true on success, false on
 * failure.
 *
 * @return mixed: see the descriprtion.
 * @filesource fp-includes/core/core.filesystem.php
 */

/**
 * fs_chmod_recursive
 *
 * This function create an instance of fs_chmodder.
 *
 * @param string $fpath: $directory to fs_chmodder
 * @return array: List of files that it couldn't set the chmod
 * @filesource fp-includes/core/core.filesystem.php
 * @see fs_chmodder
 */

/**
 * fs_delete_recursive
 *
 * This function first deletes recursively the files and the subdirectories of a
 * directory then deletes the directory.
 *
 * @param string $path: The directory to delete
 * @return boolean: True always
 * @filesource fp-includes/core/core.filesystem.php
 */

/**
 * fs_copy
 *
 * This function makes the copy of a file.
 *
 * @param string $source: The file to copy
 * @param string $dest: The name of the copy
 * @return boolean: Does it succeed?
 * @filesource fp-includes/core/core.filesystem.php
 */