File/attach API with the potential for revision control. More...

Functions
	z_mime_content_type ($filename)
	Guess the mimetype from file ending. More...

	attach_count_files ($channel_id, $observer, $hash= '', $filename= '', $filetype= '')
	Count files/attachments. More...

	attach_list_files ($channel_id, $observer, $hash= '', $filename= '', $filetype= '', $orderby= 'created desc', $start=0, $entries=0, $since= '', $until= '')
	Returns a list of files/attachments. More...

	attach_by_hash ($hash, $observer_hash, $rev=0)
	Find an attachment by hash and revision. More...

	attach_can_view_folder ($uid, $ob_hash, $folder_hash)

	attach_by_hash_nodata ($hash, $observer_hash, $rev=0)
	Find an attachment by hash and revision. More...

	attach_store ($channel, $observer_hash, $options= '', $arr=null)
	Stores an attachment from a POST file upload. More...

	z_readdir ($channel_id, $observer_hash, $pathname, $parent_hash= '')
	Read a virtual directory and return contents. More...

	attach_mkdir ($channel, $observer_hash, $arr=null)
	Create directory. More...

	attach_mkdirp ($channel, $observer_hash, $arr=null)
	Create directory (recursive). More...

	attach_change_permissions ($channel_id, $resource, $allow_cid, $allow_gid, $deny_cid, $deny_gid, $recurse=false, $sync=false)
	Changes permissions of a file. More...

	attach_delete ($channel_id, $resource, $is_photo=0)
	Delete a file/directory from a channel. More...

	attach_drop_photo ($channel_id, $resource)

	get_cloudpath ($arr)
	Returns path to file in cloud/. More...

	get_cloud_url ($channel_id, $channel_name, $attachHash)
	Returns path to parent folder in cloud/. This function cannot be used with mod/dav as it always returns a path valid under mod/cloud. More...

	find_folder_hash_by_attach_hash ($channel_id, $attachHash, $recurse=false)
	Return the hash of an attachment's folder. More...

	find_folder_hash_by_path ($channel_id, $path)
	Return the hash of an attachment's folder. More...

	find_filename_by_hash ($channel_id, $attachHash)
	Returns the filename of an attachment in a given channel. More...

	pipe_streams ($in, $out, $bufsize=16384)
	Pipes $in to $out in 16KB chunks. More...

	file_activity ($channel_id, $object, $allow_cid, $allow_gid, $deny_cid, $deny_gid, $verb, $notify)
	Activity for files. More...

	get_file_activity_object ($channel_id, $hash, $url)
	Create file activity object. More...

	attach_recursive_perms ($arr_allow_cid, $arr_allow_gid, $arr_deny_cid, $arr_deny_gid, $folder_hash)
	Returns recursive permissions array or false if nobody has recursive permissions. More...

	filepath_macro ($s)

	attach_export_data ($channel, $resource_id, $deleted=false)

	get_attach_binname ($s)
	Strip off 'store/nickname/' from the provided path. More...

	get_dirpath_by_cloudpath ($channel, $path)

	get_filename_by_cloudname ($cloudname, $channel, $storepath)

	copy_folder_to_cloudfiles ($channel, $observer_hash, $srcpath, $cloudpath)
	recursively copy a directory into cloud files More...

	attach_move ($channel_id, $resource_id, $new_folder_hash)

	attach_folder_select_list ($channel_id)

	attach_folder_rpaths ($all_folders, $that_folder)

	attach_syspaths ($channel_id, $attach_hash)
	Given a channel_id and attach_hash, return an array with the full relative path and os_path. More...

	attach_upgrade ()

	save_chunk ($channel, $start, $end, $len)

Detailed Description

File/attach API with the potential for revision control.

Todo:

A filesystem storage abstraction which maintains security (and 'data' contains a system filename which is inaccessible from the web). This could get around PHP storage limits and store videos and larger items, using fread or OS methods or native code to read/write or chunk it through.

Also an 'append' option to the storage function might be a useful addition.

Function Documentation

attach_by_hash	(	$hash,
		$observer_hash,
		$rev = `0`
	)

Find an attachment by hash and revision.

Returns the entire attach structure including data.

This could exhaust memory so most useful only when immediately sending the data.

Parameters

string	$hash
string	$observer_hash
int	$rev	(optional) Revision default 0

Returns: array

Referenced by Zotlabs\Module\Attach\init(), Zotlabs\Module\Getfile\post(), and sync_files().

attach_by_hash_nodata	(	$hash,
		$observer_hash,
		$rev = `0`
	)

Find an attachment by hash and revision.

Returns the entire attach structure excluding data.

See Also: attach_by_hash()

Parameters

string	$hash
string	$observer_hash
int	$rev	(optional) revision default 0

Returns

associative array with everything except data

boolean success boolean true or false
string message (optional) only when success is false
array data array of attach DB entry without data component

Referenced by Zotlabs\Module\Photos\get(), Zotlabs\Module\Mail\post(), Zotlabs\Module\Item\post(), and send_message().

attach_can_view_folder	(	$uid,
		$ob_hash,
		$folder_hash
	)

Referenced by attach_by_hash(), attach_by_hash_nodata(), Zotlabs\Module\Embedphotos\embedphotos_widget_album(), photos_albums_list(), Zotlabs\Widget\Portfolio\widget(), and Zotlabs\Widget\Album\widget().

attach_change_permissions	(	$channel_id,
		$resource,
		$allow_cid,
		$allow_gid,
		$deny_cid,
		$deny_gid,
		$recurse = `false`,
		$sync = `false`
	)

Changes permissions of a file.

Parameters

int	$channel_id	The id of the channel
array	$resource
string	$allow_cid
string	$allow_gid
string	$deny_cid
string	$deny_gid
boolean	$recurse	(optional) default false
boolean	$sync	(optional) default false

Referenced by Zotlabs\Module\Filestorage\post().

attach_count_files	(	$channel_id,
		$observer,
		$hash = `''`,
		$filename = `''`,
		$filetype = `''`
	)

Count files/attachments.

Parameters

int	$channel_id
string	$observer
string	$hash	(optional)
string	$filename	(optional)
string	$filetype	(optional)

Returns

associative array with:

boolean success
int|boolean results amount of found results, or false
string message with error messages if any

attach_delete	(	$channel_id,
		$resource,
		$is_photo = `0`
	)

Delete a file/directory from a channel.

If the provided resource hash is from a directory it will delete everything recursively under this directory.

Parameters

int	$channel_id	The id of the channel
string	$resource	The hash to delete
int	$is_photo	(optional) default 0

Returns: void

Referenced by channel_remove(), Zotlabs\Module\Filestorage\get(), Zotlabs\Module\Photos\post(), and sync_files().

attach_drop_photo	(	$channel_id,
		$resource
	)

Referenced by attach_delete().

attach_export_data	(	$channel,
		$resource_id,
		$deleted = `false`
	)

Referenced by api_file_export(), attach_change_permissions(), attach_store(), Zotlabs\Module\Filestorage\get(), Zotlabs\Module\Profile_photo\get(), Zotlabs\Module\File_upload\post(), Zotlabs\Module\Wall_attach\post(), Zotlabs\Module\Profile_photo\post(), Zotlabs\Module\Photos\post(), and Zotlabs\Daemon\Importfile\run().

attach_folder_rpaths	(	$all_folders,
		$that_folder
	)

Referenced by attach_folder_select_list().

attach_folder_select_list ( $channel_id )

Used to generate a select input box of all your folders

attach_list_files	(	$channel_id,
		$observer,
		$hash = `''`,
		$filename = `''`,
		$filetype = `''`,
		$orderby = `'created desc'`,
		$start = `0`,
		$entries = `0`,
		$since = `''`,
		$until = `''`
	)

Returns a list of files/attachments.

Parameters

$channel_id
$observer
$hash	(optional)
$filename	(optional)
$filetype	(optional)
$orderby
$start
$entries

Returns

associative array with:

boolean success
array|boolean results array with results, or false
string message with error messages if any

Referenced by api_attach_list().

attach_mkdir	(	$channel,
		$observer_hash,
		$arr = `null`
	)

Create directory.

Parameters

array	$channel	channel array of owner
string	$observer_hash	hash of current observer
array	$arr	parameter array to fulfil request Required: string filename string folder hash of parent directory, empty string for root directory Optional: string hash precomputed hash for this node tring allow_cid string allow_gid string deny_cid string deny_gid

Returns: array

Referenced by attach_mkdirp(), attach_store(), and Zotlabs\Module\File_upload\post().

attach_mkdirp	(	$channel,
		$observer_hash,
		$arr = `null`
	)

Create directory (recursive).

Parameters

array	$channel	channel array of owner
string	$observer_hash	hash of current observer
array	$arr	parameter array to fulfil request Required: string pathname string folder hash of parent directory, empty string for root directory Optional: string allow_cid string allow_gid string deny_cid string deny_gid

Returns: array

Referenced by attach_store(), copy_folder_to_cloudfiles(), and Zotlabs\Module\Webpages\post().

attach_move	(	$channel_id,
		$resource_id,
		$new_folder_hash
	)

This function performs an in place directory-to-directory move of a stored attachment or photo. The data is physically moved in the store/nickname storage location and the paths adjusted in the attach structure (and if applicable the photo table). The new 'album name' is recorded for photos and will show up immediately there. This takes a channel_id, attach.hash of the file to move (this is the same as a photo resource_id), and the attach.hash of the new parent folder, which must already exist. If $new_folder_hash is blank or empty, the file is relocated to the root of the channel's storage area.

Parameters

int	$channel_id
int	$resource_id
string	$new_folder_hash

Returns: void|boolean

Fixme:

Referenced by Zotlabs\Module\Photos\post().

attach_recursive_perms	(	$arr_allow_cid,
		$arr_allow_gid,
		$arr_deny_cid,
		$arr_deny_gid,
		$folder_hash
	)

Returns recursive permissions array or false if nobody has recursive permissions.

Parameters

array	$arr_allow_cid
array	$arr_allow_gid
array	$arr_deny_cid
array	$arr_deny_gid
string	$folder_hash

Referenced by file_activity().

attach_store	(	$channel,
		$observer_hash,
		$options = `''`,
		$arr = `null`
	)

Stores an attachment from a POST file upload.

This function stores an attachment. It can be a new one, a replacement or a new revision depending on value set in $options.

Note: Requires an input field userfile and does not accept multiple files in one request.; A lot going on in this function, and some of it is old cruft and some is new cruft and the entire thing probably needs to be refactored. It started out just storing files, before we had DAV. It was made extensible to do extra stuff like edit an existing file or optionally store a separate revision using $options to choose between different storage models. Along the way we moved from DB data storage to file system storage. Then DAV came along and used different upload methods depending on whether the file was stored as a DAV directory object or updated as a file object. One of these is essentially an update and the other is basically an upload, but doesn't use the traditional PHP upload workflow. Then came hubzilla and we tried to merge photo functionality with the file storage. Most of that integration occurs within this function. This required overlap with the old photo_upload stuff and photo albums were completely different concepts from directories which needed to be reconciled somehow. The old revision stuff is kind of orphaned currently. There's new revision stuff for photos which attaches (2) etc. onto the name, but doesn't integrate with the attach table revisioning. That's where it sits currently. I repeat it needs to be refactored, and this note is here for future explorers and those who may be doing that work to understand where it came from and got to be the monstrosity of tangled unrelated code that it currently is.

Parameters

array	$channel	channel array of owner
string	$observer_hash	hash of current observer
string	$options	(optional) one of update, replace, revision
array	$arr	(optional) associative array

Returns: void|array

Hooks:: photo_upload_begin Called when attempting to upload a photo.

Hooks:

photo_upload_file Called to generate alternate filenames for an upload.

string src - return value, default empty
string filename - return value, default empty
number filesize - return value, default 0
string type - return value, default empty

Hooks:

attach_upload_file Called when uploading a file.

string src - return value, default empty
string filename - return value, default empty
number filesize - return value, default 0
string type - return value, default empty

Hooks:: photo_upload_end Called when a photo upload has been processed.

Hooks:: photo_upload_end Called when a photo upload has been processed.

Hooks:: photo_upload_end Called when a photo upload has been processed.

Hooks:: photo_upload_end Called when a photo upload has been processed.

Hooks:: photo_upload_end Called when a photo upload has been processed. This would've been called already with a success result in photos_upload() if it was a photo.

Referenced by copy_folder_to_cloudfiles(), fix_attached_file_permissions(), Zotlabs\Module\File_upload\post(), Zotlabs\Module\Wall_attach\post(), Zotlabs\Module\Cover_photo\post(), Zotlabs\Module\Profile_photo\post(), Zotlabs\Module\Photos\post(), Zotlabs\Daemon\Importfile\run(), and send_message().

attach_syspaths	(	$channel_id,
		$attach_hash
	)

Given a channel_id and attach_hash, return an array with the full relative path and os_path.

Referenced by attach_move(), and attach_upgrade().

attach_upgrade ( )

in earlier releases we did not fill in os_path and display_path in the attach DB structure. (It was not needed or used). Going forward we intend to make use of these fields. A cron task checks for empty values (as older attachments may have arrived at our site in a clone operation) and executes attach_syspaths() to generate these field values and correct the attach table entry. The operation is limited to 100 DB entries at a time so as not to overload the system in any cron run. Eventually it will catch up with old attach structures and switch into maintenance mode to correct any that might arrive in clone packets from older sites.

Referenced by Zotlabs\Daemon\Cron\run().

copy_folder_to_cloudfiles	(	$channel,
		$observer_hash,
		$srcpath,
		$cloudpath
	)

recursively copy a directory into cloud files

Parameters

array	$channel
string	$observer_hash
string	$srcpath
string	$cloudpath

Returns: boolean

Referenced by Zotlabs\Module\Webpages\post().

file_activity	(	$channel_id,
		$object,
		$allow_cid,
		$allow_gid,
		$deny_cid,
		$deny_gid,
		$verb,
		$notify
	)

Activity for files.

Parameters

int	$channel_id
array	$object
string	$allow_cid
string	$allow_gid
string	$deny_cid
string	$deny_gid
string	$verb
boolean	$notify

Referenced by attach_delete(), attach_store(), and Zotlabs\Module\Filestorage\post().

filepath_macro ( $s )

Referenced by attach_store(), and Zotlabs\Module\Photos\get().

find_filename_by_hash	(	$channel_id,
		$attachHash
	)

Returns the filename of an attachment in a given channel.

Parameters

int	$channel_id	The id of the channel
string	$attachHash	The hash of the attachment

Returns: string The filename of the attachment

Referenced by get_cloud_url(), get_dirpath_by_cloudpath(), and get_filename_by_cloudname().

find_folder_hash_by_attach_hash	(	$channel_id,
		$attachHash,
		$recurse = `false`
	)

Return the hash of an attachment's folder.

Parameters

int	$channel_id	The id of the channel
string	$attachHash	The hash of the attachment
boolean	$recurse	(optional) default false

Returns: string

Referenced by attach_store(), and get_cloud_url().

find_folder_hash_by_path	(	$channel_id,
		$path
	)

Return the hash of an attachment's folder.

Parameters

int	$channel_id
string	$path

Returns: string

get_attach_binname ( $s )

Strip off 'store/nickname/' from the provided path.

Parameters

string $s

Returns: string

Referenced by sync_files().

get_cloud_url	(	$channel_id,
		$channel_name,
		$attachHash
	)

Returns path to parent folder in cloud/. This function cannot be used with mod/dav as it always returns a path valid under mod/cloud.

Parameters

int	$channel_id	The id of the channel
string	$channel_name	The name of the channel
string	$attachHash

Returns: string with the full folder path

Referenced by attach_delete(), Zotlabs\Module\Filestorage\get(), and Zotlabs\Module\Filestorage\post().

get_cloudpath ( $arr )

Returns path to file in cloud/.

Warning: This function cannot be used with mod/dav as it always returns a path valid under mod/cloud.

Parameters

array

$arr

associative array with:

int uid the channel's uid
string folder
string filename

Returns: string path to the file in cloud/

Referenced by Zotlabs\Module\Filestorage\get().

get_dirpath_by_cloudpath	(	$channel,
		$path
	)

Referenced by Zotlabs\Module\Webpages\post(), and scan_webpage_elements().

get_file_activity_object	(	$channel_id,
		$hash,
		$url
	)

Create file activity object.

Parameters

int	$channel_id
string	$hash
string	$url

Returns: array An associative array for the specified file.

Referenced by attach_delete(), attach_store(), and Zotlabs\Module\Filestorage\post().

get_filename_by_cloudname	(	$cloudname,
		$channel,
		$storepath
	)

Referenced by scan_webpage_elements().

pipe_streams	(	$in,
		$out,
		$bufsize = `16384`
	)

Pipes $in to $out in 16KB chunks.

Parameters

resource	$in	File pointer of input
resource	$out	File pointer of output
int	$bufsize	size of chunk, default 16384

Returns: number with the size

Referenced by attach_store(), Zotlabs\Module\Attach\init(), Zotlabs\Module\Photo\init(), Zotlabs\Module\Getfile\post(), save_chunk(), Zotlabs\Thumbs\Video\Thumb(), and Zotlabs\Thumbs\Pdf\Thumb().

save_chunk	(	$channel,
		$start,
		$end,
		$len
	)

Chunked uploader for integration with the blueimp jquery-uploader This is currently used.

Referenced by Zotlabs\Module\File_upload\post(), Zotlabs\Module\Wall_attach\post(), and Zotlabs\Module\Photos\post().

z_mime_content_type ( $filename )

Guess the mimetype from file ending.

This function takes a file name and guess the mimetype from the filename extension.

Parameters

string $filename a string filename

Returns: string The mimetype according to a file ending.

Referenced by attach_store(), and Zotlabs\Daemon\Importdoc\update_docs_dir().

z_readdir	(	$channel_id,
		$observer_hash,
		$pathname,
		$parent_hash = `''`
	)

Read a virtual directory and return contents.

Also checking permissions of all parent components.

Parameters

integer	$channel_id
string	$observer_hash	hash of current observer
string	$pathname
string	$parent_hash	(optional)

Returns

array $ret

boolean success boolean true or false
string message error message if success is false
array data array of attach DB entries without data component

Functions

Detailed Description

Function Documentation