====== phpPathFinder ======
{{:docs:phpPathFinder:logo.png?nolink&width=48 |phpPathFinder}}
phpPathFinder is a multiuser php filemanager,
with configurable autorization level in one text file (no db required).\\

===== Demo =====
You can view an online demo here:
[[http://lnx.utillyty.eu/utillyty.php/pathfinder|online demo]]

<note warning>
Tested on 
  * Firefox 3.5
  * Opera 10.10 
  * Safari 3.0 
  * Chrome 3.0 
  * Internet Explorer 8.0
  * Konqueror 3.5
</note>

===== Download =====

last stable version: **0.1.0, 10 Jan 2010**

phpPathFinder comes as part of **utillyt.php** (still under development).\\
You can get it from
[[http://sourceforge.net/projects/phppathfinder]]

===== Install =====

Download and extract the latest **utillyty.php** release archive from [[https://sourceforge.net/projects/phppathfinder/|sourceforge]].\\
Enter the pathfinder folder and edit config.php and .pfaccess for your requirements (see [[docs:phppathfinder#configuration|Configuration]] below).\\
FTP to your site.\\

<note>PHP 5.3.1 or later required</note>
<note important>
phpPathFinder comes as part of utillyty.php.\\
You need the entire utillyty.php folder to get it working.
</note>

===== Configuration =====

Before running phpPathFinder you must configure it. 
Enter the ..utillyty.php/pathfinder folder. There are two file you must edit to set configuration:
  * config.php
  * .pfaccess (path-finder access)
Optionally you can change the styling editing the pathfinder.css file.

==== config.php ====

There are 5 configurable global variables in the config.php file:

== PFACCESS ==

Relative path and file name of the .pfaccess auth file.\\
e.g.:

<code>
$PFACCESS = ".pfaccess";
</code>

== TITLE ==

Title of the html page, also displayed in the top of the html document.\\
e.g.:
<code>
$TITLE = "UTillyty $APPNAME";
</code>

== DESCRIPTION ==

Page description (below the login form, left to the list).\\
Can be any html.\\
e.g.:

<code>
$DESCRIPTION = 
"
$APPNAME <br/> v$APPVERSION <br/> demo version 
";
</code>

== SIDENOTE ==

sidenote (right side)

<code>
$SIDENOTE = 
"
put any html inside
"
</code>

<note>
the $APPNAME and $APPVERSION are predefined global vars in the phpPathFinder.php file
</note>

==== .pfaccess ====

There are 8 configurable permission parameters:
  * **root**: the absolute or relative (to phpPathFinder.php) path of the top folder the user can work on (mandatory);
  * **whitelist**: a dot ('.') separated list of file extension the user can work on (default = empty);
  * **blacklist**: a dot ('.') separated list of file extension the user is forbidden to work on (default = empty);
  * **browse**: 0 or 1. if 1 the user can browse files/folders (default = 0)
  * **download**: 0 or 1. if 1 the user can download (default = 0)
  * **edit**: 0 or 1. if 1 the user can copy/move/rename files/folders (default = 0);
  * **remove**: 0 or 1. if 1 the user can delete files/folders (default = 0);
  * **upload**: 0 or 1. if 1 the user can upload files (default = 0);

Only the root parameter is mandatory, all others have defaults.
Each permission is independent from the others

The .pfaccess file store information in records grouped in 4 sections.\\
A section is started with the '@' token.
Each record is a text line with a comma separated name/value list of parameters.\\
Each parameter is in the form: 'name:value'.\\
You can put line comments anywhere in the file, **except the @passwords section**, using the '#' token.\\

== Sections ==

== @default ==
This section contains one record with the default user permissions parameters either for anonymous user, or if a parameter is not explicitly declared neither in the group nor in the user record of a logged user.\\
Syntax:\\
username:@anonymous, group:@anonymous, root: [, browse: , download: , edit: , remove: , upload: , whitelist: , blacklist]
<note important>
'@anonymous' is a RESERVED key value for the @default user username, and group name and will be set automatically by the system. You cannot use this values for users records.
</note>

== @groups ==
This section contains group permissions parameters for logged users.\\
Syntax:\\
username:, group: [, root: , browse: , download: , edit: , remove: , upload: , whitelist: , blacklist]

== @users ==
Each line on this section contains the user's user name and group name. Optionally authorization parameter in the group section can be overridden here.\\
Syntax:\\
name: [, root: , browse: , download: , edit: , remove: , upload: , whitelist: , blacklist]

== @passwords ==
Each line contain a record with username and MD5 encryped password.\\
Syntax:\\
username:MD5password\\

== Precedence ==

When a user log in to phpPathFinder, the system first check the username and password,
than set each the permission parameters with this precedence:
  * the user record in the @users section
  * the group record (where group.name = user.gruopname) in the @groups section
  * the @default record
If no login is provided the @default section parameters are used.

<note>
If you don't want anonymous user not even browse list, remove the browse permission from the @default section (or set it to 0).
</note>

<note important>
Remember to instruct your web server not to allow direct access to the root folder, i.e. by means of an .htaccess file (view .htacees_sample file).
</note>

The full content of a .pfaccess sample file follows:

<code>
# default ====================

@default
root: ../test/playground, browse:1, blacklist:.php.asp.perl

# groups =====================

@groups

name: admins, root: ../test/playground, download: 1, edit: 1, remove: 1, upload: 1
name: users, root: ../test/playground, download: 1, upload:1
name: guests, root: ../test/playground, download: 1

# users ======================
 
@users

username: admin, group: admins
username: user, group: users
username: guest, group: guests


# passwords ==================
#
# <username>:password
# NB: you can't put any comment below this section!

@passwords

admin:21232f297a57a5a743894a0e4a801fc3
user:ee11cbb19052e40b07aac0ca060c23ee
guest:084e0343a0486ff05530df6c705c8bb4

</code>

===== Licence =====
<code>
Copyright (C) 2010 Attilio Pavone <tilly@utillyty.eu>

phpPathFinder is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

phpPathFinder is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You can find a copy of the GNU General Public License in the file
LICENSE, or can see <http://www.gnu.org/licenses/>.
</code>
This program use the following open source software:
  * MD5.js 	(Copyright (c) 1996 Henri Torgemane. )
  * logo.png 	([[http://commons.wikimedia.org/wiki/File:Folder-web.png]])
  * fugue icons	([[http://www.pinvoke.com/]])
  * silk icons 	([[http://www.famfamfam.com/lab/icons/silk/]])

===== Develope =====

**utillyty.php** cvs repository is stored at:
[[https://sourceforge.net/projects/u-omnibus/|UTillyty.Omnibus]] under the utillyty.php cvs module.

===== Revision history =====

=== version 0.1.0 (alpha), 09 Jan 2010 ===

This is the first alpha version.

===== Forum =====

[[talk:docs:phppathfinder|Talk:phpPathFinder]]