Class: File

Source Location: /qp_inc/files/model/_file.class.php

Class File

Class Overview

Represents a file or folder on disk. Optionnaly stores meta data from DB.

Use FileCache::get_by_root_and_path() to create an instance. This is based on DataObject for the meta data.

Located in /qp_inc/files/model/_file.class.php [line 44]

DataObject
   |
   --File

Author(s):

Information Tags:

Version:

beta

Properties

Methods

[ Top ]

Inherited Properties, Constants, and Methods

Inherited Properties

Inherited Methods

Inherited Constants

Inherited From DataObject

DataObject::$delete_cascades

DataObject::$delete_restrictions

DataObject::$ID

Inherited From DataObject

DataObject::DataObject()

Constructor

DataObject::check_delete()

Check relations for restrictions before deleting

DataObject::check_relations()

Check relations for restrictions or cascades

DataObject::confirm_delete()

Displays form to confirm deletion of this object

DataObject::dbchange()

Records a change that will need to be updated in the db

DataObject::dbdelete()

Delete object from DB.

DataObject::dbinsert()

Insert object into DB based on previously recorded changes.

DataObject::dbsave()

Inserts or Updates depending on object state.

DataObject::dbupdate()

Update the DB based on previously recorded changes

DataObject::dget()

Get a ready-to-display member param by its name

DataObject::disp()

Display a member param by its name

DataObject::get()

Get a member param by its name

DataObject::history_info_icon()

Create icon with dataobject history

DataObject::ID()

Template function: Displays object ID.

DataObject::set()

Set param value

DataObject::set_from_Request()

Set a parameter from a Request form value.

DataObject::set_param()

Set param value.

[ Top ]

Property Summary

string	$alt	Meta data: ALT text for images
string	$desc	Meta data: Description
Filetype	$Filetype	Extension, Mime type, icon, viewtype and 'allowed extension' of the file
string	$meta	Have we checked for meta data in the DB yet?
string	$title	Meta data: Long title
string	$_adfp_full_path	Full path for this file/folder, WITHOUT trailing slash.
string	$_dir	Directory path for this file/folder, including trailing slash.
boolean	$_exists	Does the File/folder exist on disk?
Fileroot	$_FileRoot	FileRoot of this file
string	$_fsgroup_name	File group. NULL if unknown
string	$_fsowner_name	File owner. NULL if unknown
boolean	$_is_dir	Is the File a directory?
boolean	$_is_image	Is the File an image? NULL if unknown
integer	$_lastmod_ts	UNIX timestamp of last modification on disk.
string	$_md5ID	MD5 hash of full pathname.
string	$_name	Name of this file/folder, without path.
integer	$_perms	Filesystem file permissions.
string	$_rdfp_rel_path	Posix subpath for this file/folder, relative the associated root (No trailing slash)
integer	$_recursive_size	Recursive directory size in bytes.
integer	$_size	File size in bytes.

[ Top ]

Method Summary

mixed	File()	Constructor, not meant to be called directly. Use FileCache::get_by_root_and_path() instead, which provides caching and checks that only one object for a unique file exists (references).
void	cb_delete_restrictions_detail()	Callback function called by DataObject::check_relations().
mixed	chmod()	Change file permissions on disk.
boolean	copy_to()	Copy this file to a new location
boolean	create()	Create the file/folder on disk, if it does not exist yet.
boolean	dbinsert()	Insert object into DB based on previously recorded changes
boolean	dbupdate()	Update the DB based on previously recorded changes
boolean	exists()	Does the File/folder exist on disk?
mixed	get()	Get a member param by its name
string	get_ads_cache()	Get the full path to the thumbnail cache for this file.
string	get_af_thumb_path()	Get the full path to the thumbnail for this file.
string	get_dir()	Get the File's directory.
string	get_ext()	Get the file's extension.
FileRoot	&get_FileRoot()	Get the File's FileRoot.
Filetype	&get_Filetype()	Get the File's Filetype object (or NULL).
NULL\|string	get_fsgroup_name()	Get the owner name of the file.
NULL\|string	get_fsowner_name()	Get the owner name of the file.
string	get_full_path()	Get the full path (directory and name) to the file.
string	get_getfile_url()	Get the URL to access a file through getfile.php.
string	get_icon()	Get icon for this file.
false\|mixed	get_image_size()	Get size of an image or false if not an image
string	get_lastmod_formatted()	Get date/time of last modification, formatted.
integer	get_lastmod_ts()	Get timestamp of last modification.
void	get_linkedit_link()	Get link to edit linked file.
string	get_linkedit_url()
string	get_md5_ID()	Get the File's ID (MD5 of path and name)
string	get_name()	Get the File's name.
mixed	get_perms()	Get permissions
string	get_prefixed_name()	Get the name prefixed either with "Directory" or "File".
string	get_preview_thumb()	Displays a preview thumbnail which is clickable and opens a view popup
string	get_rdfp_rel_path()	Get the file posix path relative to it's root (no trailing /)
string	get_rdfs_rel_path()	Get the file path relative to it's root, WITH trailing slash.
integer	get_recursive_size()	Get the "full" size of a file/dir (recursive for directories).
void	get_root_and_rel_path()	Get location of file with its root (for display)
integer	get_size()	Get file/dir size in bytes.
string	get_size_formatted()	Get size of the file, formatted to nearest unit (kb, mb, etc.)
void	get_tag()	Get a complete tag (IMG or A HREF) pointing to this file.
void	get_thumb_imgtag()	Generate the IMG THUMBNAIL tag with all the alt & title if available
void	get_thumb_url()	Get the thumbnail URL for this file
string	get_type()	Get the file type as a descriptive localized string.
void	get_url()	Get the absolute file url if the file is public
void	get_view_link()	Get Link to view the file (either with viewer of with browser, etc...)
void	get_view_url()	Get URL to view the file (either with viewer of with browser, etc...)
boolean	is_dir()	Is the File a directory?
void	is_editable()	Is the file editable?
boolean	is_image()	Is the File an image?
void	link_to_Item()
boolean	load_meta()	Attempt to load meta data.
void	load_properties()	Initializes or refreshes file properties (type, size, perms...)
boolean	move_to()	Move the file to another location
void	output_cached_thumb()	Output previously saved thumbnail for file
boolean	rename_to()	Rename the file in its current directory on disk.
void	rm_cache()	Delete cache for a file
void	save_thumb_to_cache()	Save thumbnail for file
boolean	thumbnail()	This will spit out a content-type header followed by a thumbnail for this file.
boolean	unlink()	Unlink/Delete the file or folder from disk.

[ Top ]

Properties

string $alt [line 62]

Meta data: ALT text for images

[ Top ]

string $desc [line 68]

Meta data: Description

[ Top ]

Filetype $Filetype [line 198]

Extension, Mime type, icon, viewtype and 'allowed extension' of the file

API Tags:

See:	File::get_Filetype
Access:	protected

[ Top ]

string $meta = 'unknown' [line 50]

Have we checked for meta data in the DB yet?

[ Top ]

string $title [line 56]

Meta data: Long title

[ Top ]

string $_adfp_full_path [line 89]

Full path for this file/folder, WITHOUT trailing slash.

API Tags:

Access:

protected

[ Top ]

string $_dir [line 97]

Directory path for this file/folder, including trailing slash.

API Tags:

See:	File::get_dir()
Access:	protected

[ Top ]

boolean $_exists [line 125]

Does the File/folder exist on disk?

API Tags:

See:	File::exists()
Access:	protected

[ Top ]

Fileroot $_FileRoot [line 75]

FileRoot of this file

API Tags:

Access:

protected

[ Top ]

string $_fsgroup_name [line 182]

File group. NULL if unknown

API Tags:

See:	File::get_fsgroup_name()
Access:	protected

[ Top ]

string $_fsowner_name [line 174]

File owner. NULL if unknown

API Tags:

See:	File::get_fsowner_name()
Access:	protected

[ Top ]

boolean $_is_dir [line 133]

Is the File a directory?

API Tags:

See:	File::is_dir()
Access:	protected

[ Top ]

boolean $_is_image [line 190]

Is the File an image? NULL if unknown

API Tags:

See:	File::is_image()
Access:	protected

[ Top ]

integer $_lastmod_ts [line 158]

UNIX timestamp of last modification on disk.

API Tags:

See:	File::get_lastmod_ts()
See:	File::get_lastmod_formatted()
Access:	protected

[ Top ]

string $_md5ID [line 117]

MD5 hash of full pathname.

This is useful to refer to files in hidden form fields, but might be replaced by the root_ID+relpath.

API Tags:

See:	File::get_md5_ID()
Access:	protected

Information Tags:

Todo:

(legacy): fplanque>> get rid of it

[ Top ]

string $_name [line 104]

Name of this file/folder, without path.

API Tags:

Access:

protected

[ Top ]

integer $_perms [line 166]

Filesystem file permissions.

API Tags:

See:	File::get_perms()
Access:	protected

[ Top ]

string $_rdfp_rel_path [line 82]

Posix subpath for this file/folder, relative the associated root (No trailing slash)

API Tags:

Access:

protected

[ Top ]

integer $_recursive_size [line 149]

Recursive directory size in bytes.

API Tags:

See:	File::get_recursive_size()
Access:	protected

[ Top ]

integer $_size [line 141]

File size in bytes.

API Tags:

See:	File::get_size()
Access:	protected

[ Top ]

Methods

Constructor File [line 212]

mixed File(
string
$root_type, integer
$root_ID, string
$rdfp_rel_path, [boolean
$load_meta = false] 
)

Constructor, not meant to be called directly. Use FileCache::get_by_root_and_path() instead, which provides caching and checks that only one object for a unique file exists (references).

Parameters:

string	$root_type:	Root type: 'user', 'group', 'collection' or 'absolute'
integer	$root_ID:	ID of the user, the group or the collection the file belongs to...
string	$rdfp_rel_path:	Posix subpath for this file/folder, relative to the associated root (no trailing slash)
boolean	$load_meta:	check for meta data?

API Tags:

Return:

false on failure, File object on success

[ Top ]

cb_delete_restrictions_detail [line 1976]

void cb_delete_restrictions_detail(

$params 
)

Callback function called by DataObject::check_relations().

Parameters:

$params:

API Tags:

See:	DataObject::check_relations()
Access:	public

Information Tags:

Todo:	Tblue> Offer to delete links if all items can be edited by the user (this would require checking for item edit and not view perms, obviously).
Todo:	Tblue> It looks like links don't necessarily need to point to items... Not sure if this feature is actually being used in the app.

[ Top ]

chmod [line 1310]

mixed chmod(
[string
$chmod = NULL] 
)

Change file permissions on disk.

Parameters:

string

$chmod:

chmod (octal three-digit-format, eg '777'), uses $Settings for NULL (fm_default_chmod_dir, fm_default_chmod_file)

API Tags:

Return:	new permissions on success (octal format), false on failure
Access:	public

[ Top ]

copy_to [line 1215]

boolean copy_to(
File
&$dest_File 
)

Copy this file to a new location

Also copy meta data in Object

Parameters:

File

&$dest_File:

the target file (expected to not exist)

API Tags:

Return:

true on success, false on failure

[ Top ]

create [line 259]

boolean create(
[string
$type = 'file'], [string
$chmod = NULL] 
)

Create the file/folder on disk, if it does not exist yet.

Also sets file permissions. Also inserts meta data into DB (if file/folder was successfully created).

Parameters:

string	$type:	type ('dir'\|'file')
string	$chmod:	optional permissions (octal format), otherwise the default from $Settings gets used

API Tags:

Return:

true if file/folder was created, false on failure

[ Top ]

dbinsert [line 1341]

boolean dbinsert(
)

Insert object into DB based on previously recorded changes

API Tags:

Return:

true on success, false on failure

Redefinition of:

DataObject::dbinsert(): Insert object into DB based on previously recorded changes.

[ Top ]

dbupdate [line 1377]

boolean dbupdate(
)

Update the DB based on previously recorded changes

API Tags:

Return:

true on success, false on failure / no changes

Redefinition of:

DataObject::dbupdate(): Update the DB based on previously recorded changes

[ Top ]

exists [line 302]

boolean exists(
)

Does the File/folder exist on disk?

API Tags:

Return:

true, if the file or dir exists; false if not

[ Top ]

get [line 490]

mixed get(
mixed
$parname 
)

Get a member param by its name

Parameters:

mixed

$parname:

Name of parameter

API Tags:

Return:

Value of parameter

Redefinition of:

DataObject::get(): Get a member param by its name

[ Top ]

get_ads_cache [line 1703]

string get_ads_cache(
[boolean
$create_if_needed = false] 
)

Get the full path to the thumbnail cache for this file.

ads = Absolute Directory Slash

Parameters:

boolean

$create_if_needed:

shall we create the dir if it doesn't exist?

API Tags:

Return:

absolute path or !error

[ Top ]

get_af_thumb_path [line 1759]

string get_af_thumb_path(
string
$size_name, [string
$thumb_mimetype = NULL], [boolean
$create_cache_if_needed = false] 
)

Get the full path to the thumbnail for this file.

af = Absolute File

Parameters:

string	$size_name:	size name
string	$thumb_mimetype:	mimetype of thumbnail (NULL if we're ready to take wathever is available)
boolean	$create_cache_if_needed:	shall we create the dir if it doesn't exist?

API Tags:

Return:

absolute filename or !error

[ Top ]

get_dir [line 539]

string get_dir(
)

Get the File's directory.

[ Top ]

get_ext [line 639]

string get_ext(
)

Get the file's extension.

API Tags:

Return:

the extension

[ Top ]

get_FileRoot [line 628]

FileRoot &get_FileRoot(
)

Get the File's FileRoot.

[ Top ]

get_Filetype [line 452]

Filetype &get_Filetype(
)

Get the File's Filetype object (or NULL).

API Tags:

Return:

The Filetype object or NULL

[ Top ]

get_fsgroup_name [line 849]

NULL|string get_fsgroup_name(
)

Get the owner name of the file.

Information Tags:

Todo:

(legacy): Can this be fixed for windows? filegroup() might only return 0 or 1 nad posix_getgrgid() is not available..

[ Top ]

get_fsowner_name [line 880]

NULL|string get_fsowner_name(
)

Get the owner name of the file.

Information Tags:

Todo:

(legacy): Can this be fixed for windows? fileowner() might only return 0 or 1 nad posix_getpwuid() is not available..

[ Top ]

get_full_path [line 574]

string get_full_path(
)

Get the full path (directory and name) to the file.

If the File is a directory, the Path ends with a /

API Tags:

Return:

full path

[ Top ]

get_getfile_url [line 1613]

string get_getfile_url(
)

Get the URL to access a file through getfile.php.

[ Top ]

get_icon [line 912]

string get_icon(
)

Get icon for this file.

Looks at the file's extension.

API Tags:

Return:	img tag
Usedby:	File::get_icon()
Uses:	File::get_icon()

[ Top ]

get_image_size [line 944]

false|mixed get_image_size(
[string
$param = 'widthxheight'] 
)

Get size of an image or false if not an image

Parameters:

string

$param:

imgsize()

API Tags:

Return:	false if the File is not an image, the requested data otherwise
Uses:	imgsize()

Information Tags:

Todo:

(legacy): cache this data (NOTE: we have different params here! - imgsize() does caching already!)

[ Top ]

get_lastmod_formatted [line 720]

string get_lastmod_formatted(
[
$format = '#'] 
)

Get date/time of last modification, formatted.

Parameters:

$format:

API Tags:

Return:

locale formatted date/time

[ Top ]

get_lastmod_ts [line 704]

integer get_lastmod_ts(
)

Get timestamp of last modification.

API Tags:

Return:

Timestamp

[ Top ]

get_linkedit_link [line 1495]

void get_linkedit_link(
[integer
$link_itm_ID = NULL], [string
$text = NULL], [string
$title = NULL], [string
$no_access_text = NULL], [string
$actionurl = '#'], [
$target = ''] 
)

Get link to edit linked file.

Parameters:

integer	$link_itm_ID:	ID of item to link to => will open the FM in link mode
string	$text:	link text
string	$title:	link title
string	$no_access_text:	text to display if access denied
string	$actionurl:	page url for the edit action
	$target:

[ Top ]

get_linkedit_url [line 1536]

string get_linkedit_url(
[integer
$link_itm_ID = NULL], [
$actionurl = '#'] 
)

Parameters:

integer	$link_itm_ID:	ID of item to link to => will open the FM in link mode
	$actionurl:

[ Top ]

get_md5_ID [line 478]

string get_md5_ID(
)

Get the File's ID (MD5 of path and name)

[ Top ]

get_name [line 508]

string get_name(
)

Get the File's name.

[ Top ]

get_perms [line 775]

mixed get_perms(
[string
$type = NULL] 
)

Get permissions

Possible return formats are:

'raw'=integer
'lsl'=string like 'ls -l'
'octal'=3 digits

Default value:

'r'/'r+w' for windows
'octal' for other OS

Parameters:

string

$type:

type, see desc above.

API Tags:

Return:

permissions

[ Top ]

get_prefixed_name [line 521]

string get_prefixed_name(
)

Get the name prefixed either with "Directory" or "File".

Returned string is localized.

[ Top ]

get_preview_thumb [line 1666]

string get_preview_thumb(
[string
$format_for_non_images = ''] 
)

Displays a preview thumbnail which is clickable and opens a view popup

Parameters:

string

$format_for_non_images:

what do do with files that are not images? 'fulltype'

API Tags:

Return:

HTML to display

[ Top ]

get_rdfp_rel_path [line 550]

string get_rdfp_rel_path(
)

Get the file posix path relative to it's root (no trailing /)

API Tags:

Return:

full path

[ Top ]

get_rdfs_rel_path [line 561]

string get_rdfs_rel_path(
)

Get the file path relative to it's root, WITH trailing slash.

API Tags:

Return:

full path

[ Top ]

get_recursive_size [line 1063]

integer get_recursive_size(
)

Get the "full" size of a file/dir (recursive for directories).

This is used by the FileList.

API Tags:

Return:

Recursive size of the dir or the size alone for a file.

[ Top ]

get_root_and_rel_path [line 617]

void get_root_and_rel_path(
)

Get location of file with its root (for display)

[ Top ]

get_size [line 689]

integer get_size(
)

Get file/dir size in bytes.

For the recursive size of a directory see get_recursive_size().

API Tags:

Return:

bytes

[ Top ]

get_size_formatted [line 956]

string get_size_formatted(
)

Get size of the file, formatted to nearest unit (kb, mb, etc.)

API Tags:

Return:	size as b/kb/mb/gd; or '<dir>'
Uses:	bytesreadable()

[ Top ]

get_tag [line 980]

void get_tag(
[string
$before_image = '<div class="image_block">'], [string
$before_image_legend = '<div class="image_legend">'], [string
$after_image_legend = '</div>'], [string
$after_image = '</div>'], [string
$size_name = 'original'], [string
$image_link_to = 'original'], [string
$image_class = false] 
)

Get a complete tag (IMG or A HREF) pointing to this file.

Parameters:

string	$before_image:	before_image
string	$before_image_legend:	before_image_legend NULL for no legend
string	$after_image_legend:	after_image_legend
string	$after_image:	after_image
string	$size_name:	size_name
string	$image_link_to:	image_link_to 'original'
string	$image_class:	image_class

[ Top ]

get_thumb_imgtag [line 1631]

void get_thumb_imgtag(
[
$size_name = 'fit-80x80'], [
$class = ''], [
$align = ''] 
)

Generate the IMG THUMBNAIL tag with all the alt & title if available

Parameters:

	$size_name:
	$class:
	$align:

[ Top ]

get_thumb_url [line 1572]

void get_thumb_url(
[string
$size_name = 'fit-80x80'] 
)

Get the thumbnail URL for this file

Parameters:

string

$size_name:

[ Top ]

get_type [line 657]

string get_type(
)

Get the file type as a descriptive localized string.

API Tags:

Return:

localized type name or 'Directory' or 'Unknown'

[ Top ]

get_url [line 584]

void get_url(
)

Get the absolute file url if the file is public

Get the getfile.php url if we need to check permission before delivering the file

[ Top ]

get_view_link [line 1441]

void get_view_link(
[
$text = NULL], [
$title = NULL], [
$no_access_text = NULL] 
)

Get Link to view the file (either with viewer of with browser, etc...)

Parameters:

	$text:
	$title:
	$no_access_text:

[ Top ]

get_view_url [line 1392]

void get_view_url(
[
$always_open_dirs_in_fm = true] 
)

Get URL to view the file (either with viewer of with browser, etc...)

Parameters:

$always_open_dirs_in_fm:

[ Top ]

is_dir [line 396]

boolean is_dir(
)

Is the File a directory?

API Tags:

Return:

true if the object is a directory, false if not

[ Top ]

is_editable [line 425]

void is_editable(
[boolean
$allow_locked = false] 
)

Is the file editable?

Parameters:

boolean

$allow_locked:

allow locked file types?

[ Top ]

is_image [line 409]

boolean is_image(
)

Is the File an image?

Tries to determine if it is and caches the info.

API Tags:

Return:

true if the object is an image, false if not

[ Top ]

link_to_Item [line 1942]

void link_to_Item(
Item
&$edited_Item 
)

Parameters:

Item

&$edited_Item:

[ Top ]

load_meta [line 321]

boolean load_meta(
[boolean
$force_creation = false], [object database
$row = NULL] 
)

Attempt to load meta data.

Will attempt only once and cache the result.

Parameters:

boolean	$force_creation:	create meta data in DB if it doesn't exist yet? (generates a $File->ID)
object database	$row:	row containing all fields needed to initialize meta data

API Tags:

Return:

true if meta data has been loaded/initialized.

[ Top ]

load_properties [line 370]

void load_properties(
)

Initializes or refreshes file properties (type, size, perms...)

[ Top ]

move_to [line 1155]

boolean move_to(
string
$root_type, integer
$root_ID, string
$rdfp_rel_path 
)

Move the file to another location

Also updates meta data in DB

Parameters:

string	$root_type:	Root type: 'user', 'group', 'collection' or 'absolute'
integer	$root_ID:	ID of the user, the group or the collection the file belongs to...
string	$rdfp_rel_path:	Subpath for this file/folder, relative the associated root (no trailing slash)

API Tags:

Return:

true on success, false on failure

[ Top ]

output_cached_thumb [line 1823]

void output_cached_thumb(
string
$size_name, string
$thumb_mimetype, string
2 
)

Output previously saved thumbnail for file

Parameters:

string	2:	short error code
string	$size_name:	size name
string	$thumb_mimetype:	mimetype of thumbnail

[ Top ]

rename_to [line 1085]

boolean rename_to(
string
$newname 
)

Rename the file in its current directory on disk.

Also update meta data in DB.

Parameters:

string

$newname:

new name (without path!)

API Tags:

Return:	true on success, false on failure
Access:	public

[ Top ]

rm_cache [line 1727]

void rm_cache(
)

Delete cache for a file

[ Top ]

save_thumb_to_cache [line 1794]

void save_thumb_to_cache(
resource
$thumb_imh, string
$size_name, string
$thumb_mimetype, [integer
$thumb_quality = 90] 
)

Save thumbnail for file

Parameters:

resource	$thumb_imh:
string	$size_name:	size name
string	$thumb_mimetype:	mimetype of thumbnail
integer	$thumb_quality:	JPEG image quality

[ Top ]

thumbnail [line 1861]

boolean thumbnail(
string
$req_size 
)

This will spit out a content-type header followed by a thumbnail for this file.

Parameters:

string

$req_size:

requested size: 'thumbnail'

API Tags:

Return:

True on success, false on failure.

Information Tags:

Todo:	(legacy): a million things (fp) but you get the idea... The generated thumb will be saved to a cached file here (fp) The cache will be accessed through the File object (fp)
Todo:	(legacy): cleanup memory resources

[ Top ]

unlink [line 1262]

boolean unlink(
)

Unlink/Delete the file or folder from disk.

Also removes meta data from DB.

API Tags:

Return:	true on success, false on failure
Access:	public

[ Top ]

hic sunt dracones

	files

[ class tree: files ] [ index: files ] [ all elements ]