Datamanager 2 Blob management type.

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.
package midcom.helper.datamanager2

 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.

access protected

Parameters

$a

arrayThe first attachment info array.

$b

arrayThe second attachment info array.

Returns

intA 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

stringThe identifier of the new attachment.

$filename

stringThe filename to use after processing.

$title

stringThe title of the attachment to use.

$mimetype

stringThe MIME Type of the file.

$tmpname

stringThe name of the source file.

$autodelete

booleanSet this to true (the default) to automatically delete the file after successful processing.

Returns

booleanIndicating 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

stringThe identifier of the new attachment.

$filename

stringThe filename to use after processing.

$title

stringThe title of the attachment to use.

$mimetype

stringThe MIME Type of the file.

$source

resourceA file handle prepared to read of the the source file.

$autoclose

booleanSet this to true if the file handle should automatically be closed after successful processing.

$tmpfile

stringIn 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

booleanIndicating success.

convert_from_csv ($source)

Parameters

$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

convert_to_csv ()

convert_to_html ()

convert_to_raw ()

convert_to_storage ()

delete_all_attachments ()

This call will unconditionally delete all attachments currently contained by the type.

Returns

booleanIndicating success.

delete_attachment (string $identifier)

Deletes an existing attachment.

Parameters

$identifier

stringThe identifier of the attachment that should be deleted.

Returns

booleanIndicating success.

file_sanity_checks (string $filepath, string $filename)

Makes sanity checks on the uploaded file, used by add_attachment and update_attachment
see \add_attachment
see \update_attachment

Parameters

$filepath

stringpath to file to check

$filename

stringactual name of the file to use with attachment

Returns

booleanindicating sanity

file_sanity_checks_avscan ($filepath)

Scans the file for virii
see \file_sanity_checks

Parameters

$filepath

Returns

booleanindicating sanity

file_sanity_checks_sizenotzero ($filepath)

Make sure given file is larger than zero bytes
see \file_sanity_checks

Parameters

$filepath

Returns

booleanindicating 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_attachmentThe first attachment.

$b

\midcom_db_attachmentThe second attachment.

Returns

intA 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

stringThe identifier of the attachment to update.

$filename

stringThe filename to use after processing.

$title

stringThe new title of the attachment, set this to null to keep the original title unchanged.

$mimetype

stringThe 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

stringThe name of the source file.

$autodelete

booleanSet this to true (the default) to automatically delete the file after successful processing.

Returns

booleanIndicating 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

stringThe identifier of the new attachment.

$filename

stringThe filename of the new attachment.

$title

stringThe new title of the attachment, set this to null to keep the original title unchanged.

$mimetype

stringThe 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

resourceA file handle prepared to read of the source file.

$autoclose

booleanSet this to true if the file handle should automatically be closed after successful processing.

$tmpfile

stringIn 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

booleanIndicating 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

stringThe identifier of the new attachment.

$title

stringThe new title of the attachment, set this to null to keep the original title unchanged.

Returns

booleanIndicating 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

stringAttachment identifier

$filename

stringOriginal 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

stringidentifier 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

mixedThe 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

Parameters

$attachment

_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

stringThe identifier of the attachment to load.

$guid

stringThe 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

\$infoInformation array

$att

\midcom_db_attachmentAttachment 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