This type allows you to control an arbitrary number of attachments on a given object.
It can only operate if the storage implementation provides it with a Midgard Object.
The storage location provided by the schema is unused at this time, as attachment
operations cannot be undone. Instead, the direct parameter calls are used to manage
the list of attachments in a parameter associated to the domain of the type. The
storage IO calls will not do much, except synchronizing data where necessary.
The type can manage an arbitrary number of attachments. Each attachment is identified
by a handle (not its name!). It provides management functions for existing attachments,
which allow you to add, delete and update them in all variants. These functions
are executed immediately on the storage object, no undo is possible.
This type serves as a base class for other, more advanced blob types, like the image type.
Available configuration options:
- boolean sortable: Should the attachments list be sortable. True if the sorting should
be turned on, false if they should be sorted alphabetically.
Methods
_sort_attachments_info_callback (array $a, array $b)
User-defined array sorting callback, used for sorting $attachments_info.
Static
See the usort() documentation for further details.
Parameters
$a
array
The first attachment info array.
$b
array
The second attachment info array.
Returns
int
A value according to the rules from strcmp().
add_attachment (string $identifier, string $filename, string $title, string $mimetype, string $tmpname, boolean $autodelete)
Adds a new attachment based on a file on-disk.
This is a wrapper for add_attachment_by_handle() which works with an existing
file based on its name, not handle. The file is deleted after successful processing,
unless you set the fourth parameter to false.
This file version will automatically evaluate the file with getimagesize so that
convenience methods of them are available.
Parameters
$identifier
string
The identifier of the new attachment.
$filename
string
The filename to use after processing.
$title
string
The title of the attachment to use.
$mimetype
string
The MIME Type of the file.
$tmpname
string
The name of the source file.
$autodelete
boolean
Set this to true (the default) to automatically delete the
file after successful processing.
Returns
boolean
Indicating success.
add_attachment_by_handle (string $identifier, string $filename, string $title, string $mimetype, resource $source, boolean $autoclose, string $tmpfile)
Adds a new attachment based on a file on-disk.
This call will create a new attachment object based on the given file, add it to the
attachment list and synchronize all attachment operations. It works on an open file
handle, which is closed after successful processing, unless you set the forth parameter
to false.
Parameters
$identifier
string
The identifier of the new attachment.
$filename
string
The filename to use after processing.
$title
string
The title of the attachment to use.
$mimetype
string
The MIME Type of the file.
$source
resource
A file handle prepared to read of the the source file.
$autoclose
boolean
Set this to true if the file handle should automatically be closed
after successful processing.
$tmpfile
string
In case you have a filename to the source handle, you should specify
it here. It will be used to load getimagesize information directly (rather then doing a
temporary copy). The default null indicates that the source file location is unknown.
Returns
boolean
Indicating success.
convert_from_csv ($source)
convert_from_storage ($source)
This function loads all known attachments from the storage object.
It will leave the field empty in case the storage object is null.
Parameters
$source
delete_all_attachments ()
This call will unconditionally delete all attachments currently contained by the type.
Returns
boolean
Indicating success.
delete_attachment (string $identifier)
Deletes an existing attachment.
Parameters
$identifier
string
The identifier of the attachment that should be deleted.
Returns
boolean
Indicating success.
file_sanity_checks (string $filepath, string $filename)
Makes sanity checks on the uploaded file, used by add_attachment and update_attachment
Parameters
$filepath
string
path to file to check
$filename
string
actual name of the file to use with attachment
Returns
boolean
indicating sanity
file_sanity_checks_avscan ($filepath)
Scans the file for virii
Parameters
$filepath
Returns
boolean
indicating sanity
file_sanity_checks_sizenotzero ($filepath)
Make sure given file is larger than zero bytes
Parameters
$filepath
Returns
boolean
indicating sanity
sort_attachments_cmp (\midcom_db_attachment $a, \midcom_db_attachment $b)
Compares two attachments by score and name, to be used with the sorting routines
Static
See the usort() documentation for further details.
Parameters
$a
\midcom_db_attachment
The first attachment.
$b
\midcom_db_attachment
The second attachment.
Returns
int
A value according to the rules from strcmp().
update_attachment (string $identifier, string $filename, string $title, string $mimetype, string $tmpname, boolean $autodelete)
Update an existing attachment with a new file (this keeps GUIDs stable).
Parameters
$identifier
string
The identifier of the attachment to update.
$filename
string
The filename to use after processing.
$title
string
The new title of the attachment, set this to null to
keep the original title unchanged.
$mimetype
string
The new MIME Type of the file, set this to null to
keep the original title unchanged. If you are unsure of the mime type,
set this to '' not null, this will enforce a redetection.
$tmpname
string
The name of the source file.
$autodelete
boolean
Set this to true (the default) to automatically delete the
file after successful processing.
Returns
boolean
Indicating success.
update_attachment_by_handle (string $identifier, string $filename, string $title, string $mimetype, resource $source, boolean $autoclose, string $tmpfile)
Update an existing attachment with a new file (this keeps GUIDs stable).
Parameters
$identifier
string
The identifier of the new attachment.
$filename
string
The filename of the new attachment.
$title
string
The new title of the attachment, set this to null to
keep the original title unchanged.
$mimetype
string
The new MIME Type of the file, set this to null to
keep the original title unchanged. If you are unsure of the mime type,
set this to '' not null, this will enforce a redetection.
$source
resource
A file handle prepared to read of the source file.
$autoclose
boolean
Set this to true if the file handle should automatically be closed
after successful processing.
$tmpfile
string
In case you have a filename to the source handle, you should specify
it here. It will be used to load getimagesize information directly (rather then doing a
temporary copy). The default null indicates that the source file location is unknown.
Returns
boolean
Indicating success.
update_attachment_title (string $identifier, string $title)
Updates the title field of the specified attachment.
This will automatically update the attachment info as well.
Parameters
$identifier
string
The identifier of the new attachment.
$title
string
The new title of the attachment, set this to null to
keep the original title unchanged.
Returns
boolean
Indicating success.
_set_attachment_info_additional (string $identifier, string $filename)
This is a simple helper which looks at the original file and adds additional information to the
attachment.
With images, it evaluates the imagesize information of a given file and adds that information as
parameters to the attachment identified by its identifier.
Parameters
$identifier
string
Attachment identifier
$filename
string
Original file name
_sort_attachments ()
This function sorts the attachment lists by filename.
It has to be called after each attachment operation. It uses a
user-defined ordering function for each of the two arrays to be sorted:
sort_attachments_cmp() and _sort_attachments_info_callback().
_store_att_map_parameters (string $identifier, \midgard_attachment $attachment)
Stores the field mapping info to the attachment object itself as well
For now these are only used for backup purposes but in the future we'll move to use them as main source
Parameters
$identifier
string
identifier of the attachment
$attachment
\midgard_attachment
&$attachment reference to the attachment object to operare on.
_update_attachment_info (mixed $identifier)
Synchronizes the attachments info array with the attachment referenced by the
identifier.
Parameters
$identifier
mixed
The identifier of the attachment to update
_generate_unique_name ($filename)
Make sure we have unique filename
todo |
Isn't there a reflector method that already does this (for filenames)? |
Parameters
$filename
_index_attachment ($attachment)
helper function to index the attachment - also checks if it should be indexed
_load_attachment (string $identifier, string $guid)
This function will load a given attachment from the disk, and then calls
a function which updates the $attachments_info listing.
Parameters
$identifier
string
The identifier of the attachment to load.
$guid
string
The guid of the attachment to load.
_save_attachment_listing ()
This function synchronizes the attachment listing parameter of this field with the
current attachment state.
_update_attachment_info_additional (\$info $info, \midcom_db_attachment $att)
Read additional information from the attachment and add to the information array
With images, it evaluates reads image size information from parameters.
Parameters
$info
\$info
Information array
$att
\midcom_db_attachment
Attachment to update information from
Properties
array $_sorted_list
Sorted attachments list
Array $attachments
All attachments covered by this field.
The array contains midcom_db_attachment objects indexed by their
identifier within the field.
See the $attachments_info member for a more general approach easily usable
within styles.
Array $attachments_info
This member is populated and synchronized with all known changes to the
attachments listing.
It contains a batch of metadata that makes presenting them easy. The
information is kept in an array per attachment, again indexed
by their identifiers. The following keys are defined:
- filename: The name of the file (useful to produce nice links).
- mimetype: The MIME Type.
- url: A complete URL valid for the current site, which delivers the attachment.
- filesize and formattedsize: The size of the file, as integer, and as formatted number
with thousand-separator.
- lastmod and isoformattedlastmod: The UNIX- and ISO-formatted timestamp of the
last modification to the attachment file.
- id, guid: The ID and GUID of the attachment.
- description: The title of the attachment, usually used as a caption.
- size_x, size_y and size_line: Only applicable for images, holds the x and y
sizes of the image, along with a line suitable for inclusion in the
tags.
- object: This is a reference to the attachment object (in $attachments).
- identifier: The identifier of the attachment (for reverse-lookup purposes).
The information in this listing should be considered read-only. If you want to
change information like the Title of an attachment, you need to do this using
the attachment object directly.
integer $max_count
Maximum amount of blobs allowed to be stored in the same field
boolean $sortable
Should the widget offer sorting feature