Class MLA (Media Library Assistant) Data provides database and template file access for MLA needs

The _template functions are inspired by the book "WordPress 3 Plugin Development Essentials." Templates separate HTML markup from PHP code for easier maintenance and localization.

package Media Library Assistant
since 0.1

 Methods

Format printable version of binary data

_hex_dump(string $data, integer $limit, \intger $bytes_per_row, integer $offset) : string

since 0.90

Parameters

$data

string

Binary data

$limit

integer

Bytes to format, default = 0 (all bytes)

$bytes_per_row

\intger

Bytes to format on each line

$offset

integer

offset of initial byte, or -1 to suppress printing offset information

Returns

stringPrintable representation of $data

Initialization function, similar to __construct()

initialize() 

since 0.1

Get the total number of attachment posts

mla_count_list_table_items(array $request, int $offset, int $count) : integer

since 0.30

Parameters

$request

array

Query variables, e.g., from $_REQUEST

$offset

int

(optional) number of rows to skip over to reach desired page

$count

int

(optional) number of rows on each page

Returns

integerNumber of attachment posts

Analyze a template, expanding Field-level Markup Substitution Parameters

mla_expand_field_level_parameters(string $tpl, array $query, array $markup_values, integer $post_id, boolean $keep_existing, string $default_option) : array

Field-level parameters must have one of the following prefix values: template, request, query, custom, terms, meta, iptc, exif, pdf. All but request and query require an attachment ID.

since 1.50

Parameters

$tpl

string

A formatting string containing [+placeholders+]

$query

array

Optional: an array of values from the query, if any, e.g. shortcode parameters

$markup_values

array

Optional: an array of values to add to the returned array

$post_id

integer

Optional: attachment ID for attachment-specific placeholders

$keep_existing

boolean

Optional: for option 'multi', retain existing values

$default_option

string

Optional: default option value

Returns

array( parameter => value ) for all field-level parameters and anything in $markup_values

Returns information about an attachment's parent, if found

mla_fetch_attachment_parent_data(int $parent_id) : array

since 0.1

Parameters

$parent_id

int

post ID of attachment's parent, if any

Returns

arrayParent information; post_date, post_title and post_type

Find Featured Image and inserted image/link references to an attachment

mla_fetch_attachment_references(int $ID, int $parent) : array

Searches all post and page content to see if the attachment is used as a Featured Image or inserted in the post as an image or link.

since 0.1

Parameters

$ID

int

post ID of attachment

$parent

int

post ID of attachment's parent, if any

Returns

arrayReference information; see $references array comments

Finds the value of a key in a possibly nested array structure

mla_find_array_element(string $needle, array $haystack, string $option, boolean $keep_existing) : mixed

Used primarily to extract fields from the _wp_attachment_metadata custom field. Could also be used with the ID3 metadata exposed in WordPress 3.6 and later.

since 1.30

Parameters

$needle

string

key value, e.g. array1.array2.element

$haystack

array

PHP nested arrays

$option

string

data option 'text'|'single'|'export'|'array'|'multi'

$keep_existing

boolean

keep existing values - for 'multi' option

Returns

mixedstring or array value matching key(.key ...) or ''

Invalidates the $mla_galleries or $galleries array and cached values

mla_flush_mla_galleries(string $option_name) : void

since 1.00

Parameters

$option_name

string

name of the gallery's cache/option variable

Retrieve an Attachment array given a $post_id

mla_get_attachment_by_id(int $post_id) : NULL | array

The (associative) array will contain every field that can be found in the posts and postmeta tables, and all references to the attachment.

since 0.1
uses \global\$post

Parameters

$post_id

int

The ID of the attachment post

Returns

NULLarrayNULL on failure else associative array

Analyze a template, returning an array of the placeholders it contains

mla_get_template_placeholders(string $tpl, string $default_option) : array

since 0.90

Parameters

$tpl

string

A formatting string containing [+placeholders+]

$default_option

string

Optional: default option value

Returns

arrayPlaceholder information: each entry is an array with ['prefix'] => string, ['value'] => string, ['option'] => string 'text'|single'|'export'|'array'|'multi'

Load an HTML template from a file

mla_load_template(string $source, string $type) : string | array | false | NULL

Loads a template to a string or a multi-part template to an array. Multi-part templates are divided by comments of the form , where "key" becomes the key part of the array.

since 0.1

Parameters

$source

string

Complete path and name of the template file, option name or the raw template

$type

string

Optional type of template source; 'path', 'file' (default), 'option', 'string'

Returns

stringarrayfalseNULLstring for files that do not contain template divider comments, array for files containing template divider comments, false if file or option does not exist, NULL if file could not be loaded.

Expand a template, replacing placeholders with their values

mla_parse_array_template(string $tpl, array $markup_values) : mixed

Will return an array of values if one or more of the placeholders returns an array.

since 1.50

Parameters

$tpl

string

A formatting string containing [+placeholders+]

$markup_values

array

An associative array containing keys and values e.g. array('key' => 'value')

Returns

mixedstring or array, depending on placeholder values. Placeholders corresponding to the keys of the markup_values will be replaced with their values.

Expand a template, replacing placeholders with their values

mla_parse_template(string $tpl, array $markup_values) : \strng

A simple parsing function for basic templating.

since 0.1

Parameters

$tpl

string

A formatting string containing [+placeholders+]

$markup_values

array

An associative array containing keys and values e.g. array('key' => 'value')

Returns

\strngPlaceholders corresponding to the keys of the markup_values will be replaced with their values.

Retrieve attachment objects for list table display

mla_query_list_table_items(array $request, int $offset, int $count) : array

Supports prepare_items in class-mla-list-table.php. Modeled after wp_edit_attachments_query in wp-admin/post.php

since 0.1

Parameters

$request

array

query parameters from web page, usually found in $_REQUEST

$offset

int

number of rows to skip over to reach desired page

$count

int

number of rows on each page

Returns

arrayattachment objects (posts) including parent data, meta data and references

Retrieve attachment objects for the WordPress Media Manager

mla_query_media_modal_items(array $request, int $offset, int $count) : array

Supports month-year and taxonomy-term filters as well as the enhanced search box

since 1.20

Parameters

$request

array

query parameters from Media Manager

$offset

int

number of rows to skip over to reach desired page

$count

int

number of rows on each page

Returns

arrayattachment objects (posts)

Adds a JOIN clause, if required, to handle sorting/searching on custom fields or ALT Text

mla_query_posts_join_filter(string $join_clause) : string

Defined as public because it's a filter.

since 0.30

Parameters

$join_clause

string

query clause before modification

Returns

stringquery clause after "LEFT JOIN view ON post_id" item modification

Adds a ORDERBY clause, if required

mla_query_posts_orderby_filter(string $orderby_clause) : string

Expands the range of sort options because the logic in WP_Query is limited. Defined as public because it's a filter.

since 0.30

Parameters

$orderby_clause

string

query clause before modification

Returns

stringupdated query clause

Adds a keyword search to the WHERE clause, if required

mla_query_posts_search_filter(string $search_string, object $query_object) : string

Defined as public because it's a filter.

since 0.60

Parameters

$search_string

string

query clause before modification

$query_object

object

WP_Query object

Returns

stringquery clause after keyword search addition

Adds a WHERE clause for detached items

mla_query_posts_where_filter(string $where_clause) : string

Modeled after _edit_attachments_query_helper in wp-admin/post.php. Defined as public because it's a filter.

since 0.1

Parameters

$where_clause

string

query clause before modification

Returns

stringquery clause after "detached" item modification

Invalidates $mla_galleries and $galleries arrays and cached values after post, page or attachment updates

mla_save_post_action(integer $post_id) : void

since 1.00

Parameters

$post_id

integer

ID of post/page/attachment; not used at this time

Replaces a WordPress function deprecated in v3.7

mla_search_terms_tidy(string $term) : string

Defined as public because it's a callback from array_map().

since 1.51

Parameters

$term

string

search term before modification

Returns

stringcleaned up search term

Update a single item; change the "post" data, taxonomy terms and meta data for a single attachment

mla_update_single_item(int $post_id, array $new_data, array $tax_input, array $tax_actions) : array

since 0.1

Parameters

$post_id

int

The ID of the attachment to be updated

$new_data

array

Field name => value pairs

$tax_input

array

Optional taxonomy term values, default null

$tax_actions

array

Optional taxonomy actions (add, remove, replace), default null

Returns

arraysuccess/failure message and NULL content

Replace SQL incorrect characters (0x80 - 0xFF) with their UTF-8 equivalents

_bin_to_utf8(string $string) : string

since 1.41

Parameters

$string

string

unencoded string

Returns

stringUTF-8 encoded string

Builds the $mla_galleries or $galleries array

_build_mla_galleries(string $option_name, array $galleries_array, string $shortcode, boolean $exclude_revisions) : boolean

since 0.70

Parameters

$option_name

string

name of the gallery's cache/option variable

$galleries_array

array

by reference to the private static galleries array variable

$shortcode

string

the shortcode to be searched for and processed

$exclude_revisions

boolean

true to exclude revisions from the search

Returns

booleantrue if the galleries array is not empty

Build an array of indirect object definitions

_build_pdf_indirect_objects(string $string) : void

Creates the array of indirect object offsets and lengths

since 1.50

Parameters

$string

string

The entire PDF document, passsed by reference

Analyze a field-level "template:" element, expanding Field-level Markup Substitution Parameters

_evaluate_template_array_node(array $node, array $markup_values) : mixed

Will return an array of values if one or more of the placeholders returns an array.

since 1.50

Parameters

$node

array

A field-level template element node

$markup_values

array

An array of markup substitution values

Returns

mixedstring or array, depending on placeholder values. Placeholders corresponding to the keys of the markup_values will be replaced with their values.

Analyze a field-level "template:" element, expanding Field-level Markup Substitution Parameters

_evaluate_template_node(array $node, array $markup_values) : string

since 1.50

Parameters

$node

array

A field-level template element node

$markup_values

array

An array of markup substitution values

Returns

stringString with expanded values, if any

Add filters, run query, remove filters

_execute_list_table_query(array $request) : object

since 0.30

Parameters

$request

array

query parameters from web page, usually found in $_REQUEST

Returns

objectWP_Query object with query results

Analyze a field-level "template:" element, expanding Field-level Markup Substitution Parameters

_expand_field_level_template(string $tpl, array $markup_values, boolean $return_arrays) : mixed

since 1.50

Parameters

$tpl

string

A formatting string containing [+placeholders+]

$markup_values

array

An array of markup substitution values

$return_arrays

boolean

True to return array value(s), false to return a string

Returns

mixedElement with expanded string/array values, if any

Extract dictionary from traditional cross-reference + trailer documents

_extract_pdf_trailer(string $file_name, integer $file_offset) : mixed

since 1.50

Parameters

$file_name

string

full path to the desired file

$file_offset

integer

offset within file of the cross-reference table

Returns

mixedarray of "PDF dictionary arrays", newest first, or NULL on failure

Find the offset, length and contents of an indirect object containing a dictionary

_find_pdf_indirect_dictionary(string $file_name, integer $object, integer $generation) : mixed

The function searches the entire file, if necessary, to find the last/most recent copy of the object. This is required because Adobe Acrobat does NOT increment the generation number when it reuses an object.

since 1.50

Parameters

$file_name

string

full path and file name

$object

integer

The object number

$generation

integer

The object generation number; default zero (0)

Returns

mixedNULL on failure else array( 'start' => offset in the file, 'length' => object length, 'content' => dictionary contents )

Find a complete template, balancing opening and closing delimiters

_find_template_substring(string $tpl) : string

since 1.50

Parameters

$tpl

string

A string possibly starting with '[+template:'

Returns

string'' or template string starting with '[+template:' and ending with the matching '+]'

Find a complete (test) element, balancing opening and closing delimiters

_find_test_substring(string $tpl) : string

since 1.50

Parameters

$tpl

string

A string possibly starting with '('

Returns

string'' or template string starting with '(' and ending with the matching ')'

Convert field-level "template:" string into its component parts

_parse_field_level_template(string $tpl) : array

since 1.50

Parameters

$tpl

string

Template content with string, test and choice elements

Returns

array( node => array( type => "string | test | choice | template", length => bytes, value => string | node(s) ) )

Parse a ISO 8601 Timestamp

_parse_iso8601_date(string $source_string) : string

since 1.50

Parameters

$source_string

string

ISO string of the form YYYY-MM-DDTHH:MM:SS-HH:MM (inc time zone)

Returns

stringformatted date string YYYY-MM-DD HH:mm:SS

Parse a PDF Linearization Parameter Dictionary object

_parse_pdf_LPD_dictionary(string $source_string, integer $filesize) : mixed

Returns an array of dictionary contents, classified by object type: boolean, numeric, string, hex (string), indirect (object), name, array, dictionary, stream, and null. The array also has a '/length' element containing the number of bytes occupied by the dictionary in the source string, excluding the enclosing delimiters, if passed in.

since 1.50

Parameters

$source_string

string

data within which the object occurs, typically the start of a PDF document

$filesize

integer

filesize of the PDF document, for validation purposes, or zero (0) to ignore filesize

Returns

mixedarray of dictionary objects on success, false on failure

Parse a PDF Unicode (16-bit Big Endian) object

_parse_pdf_UTF16BE(string $source_string) : string

since 1.50

Parameters

$source_string

string

PDF string of 16-bit characters

Returns

stringUTF-8 encoded string

Parse a PDF date string

_parse_pdf_date(string $source_string) : string

since 1.50

Parameters

$source_string

string

PDF date string of the form D:YYYYMMDDHHmmSSOHH'mm

Returns

stringformatted date string YYYY-MM-DD HH:mm:SS

Parse a PDF dictionary object

_parse_pdf_dictionary(string $source_string, integer $offset) : array

Returns an array of dictionary contents, classified by object type: boolean, numeric, string, hex (string), indirect (object), name, array, dictionary, stream, and null. The array also has a '/length' element containing the number of bytes occupied by the dictionary in the source string, excluding the enclosing delimiters.

since 1.50

Parameters

$source_string

string

data within which the string occurs

$offset

integer

offset within the source string of the opening '<<' characters or the first content character.

Returns

array( '/length' => length, key => array( 'type' => type, 'value' => value ) ) for each dictionary field

Parse a PDF string object

_parse_pdf_string(string $source_string, integer $offset) : array

Returns an array with one dictionary entry. The array also has a '/length' element containing the number of bytes occupied by the string in the source string, including the enclosing parentheses.

since 1.50

Parameters

$source_string

string

data within which the string occurs

$offset

integer

offset within the source string of the opening '(' character.

Returns

array( key => array( 'type' => type, 'value' => value, '/length' => length ) ) for the string

Parse a cross-reference table section into the array of indirect object definitions

_parse_pdf_xref_section(string $file_name, integer $file_offset) : integer

Creates the array of indirect object offsets and lengths

since 1.50

Parameters

$file_name

string

full path and file name

$file_offset

integer

offset within the file of the xref id and count entry

Returns

integerlength of the section

Parse a cross-reference steam into the array of indirect object definitions

_parse_pdf_xref_stream(string $file_name, integer $file_offset, string $entry_parms_string) : integer

Creates the array of indirect object offsets and lengths

since 1.50

Parameters

$file_name

string

full path and file name

$file_offset

integer

offset within the file of the xref id and count entry

$entry_parms_string

string

"/W" entry, representing the size of the fields in a single entry

Returns

integerlength of the stream

Parse a cross-reference table subsection into the array of indirect object definitions

_parse_pdf_xref_subsection(string $xref_section, integer $offset, integer $object_id, integer $count) : void

A cross-reference subsection is a sequence of 20-byte entries, each with offset and generation values.

since 1.50

Parameters

$xref_section

string

buffer containing the subsection

$offset

integer

offset within the buffer of the first entry

$object_id

integer

number of the first object in the subsection

$count

integer

number of entries in the subsection

Sanitize and expand query arguments from request variables

_prepare_list_table_query(array $raw_request, int $offset, int $count) : array

Prepare the arguments for WP_Query. Modeled after wp_edit_attachments_query in wp-admin/post.php

since 0.1

Parameters

$raw_request

array

query parameters from web page, usually found in $_REQUEST

$offset

int

Optional number of rows (default 0) to skip over to reach desired page

$count

int

Optional number of rows on each page (0 = all rows, default)

Returns

arrayrevised arguments suitable for WP_Query

Process an markup field array value according to the supplied data-format option

_process_field_level_array(array $record, string $option, boolean $keep_existing) : array

since 1.50

Parameters

$record

array

an array of scalar values

$option

string

data option 'text'|'single'|'export'|'array'|'multi'

$keep_existing

boolean

Optional: for option 'multi', retain existing values

Returns

array( parameter => value ) for all field-level parameters and anything in $markup_values

Convert an EXIF GPS rational value to a PHP float value

_rational_to_decimal(array $rational) : float

since 1.50

Parameters

$rational

array

array( 0 => numerator, 1 => denominator )

Returns

floatnumerator/denominator

Remove tags from a term ids list

_remove_tags(array $terms_before, array $tags, object $taxonomy_obj) : array

since 0.40

Parameters

$terms_before

array

The term ids currently assigned

$tags

array

| string The term ids (array) or names (string) to remove

$taxonomy_obj

object

The taxonomy object

Returns

arrayTerm ids of the surviving tags

Search the $mla_galleries or $galleries array

_search_mla_galleries(array $galleries_array, int $attachment_id) : array

since 0.70

Parameters

$galleries_array

array

by reference to the private static galleries array variable

$attachment_id

int

the attachment ID to be searched for and processed

Returns

arrayAll posts/pages with one or more galleries that include the attachment. The array key is the parent_post ID; each entry contains post_title and post_type.

Adds or replaces the value of a key in a possibly nested array structure

_set_array_element(string $needle, mixed $value, array $haystack) : boolean

since 1.51

Parameters

$needle

string

key value, e.g. array1.array2.element

$value

mixed

replacement value, string or array, by reference

$haystack

array

PHP nested arrays, by reference

Returns

booleantrue if $needle element set, false if not

Deletes the value of a key in a possibly nested array structure

_unset_array_element(string $needle, array $haystack) : boolean

since 1.51

Parameters

$needle

string

key value, e.g. array1.array2.element

$haystack

array

PHP nested arrays, by reference

Returns

booleantrue if $needle element found, false if not

 Properties

 

IPTC Dataset friendly name/slug and identifiers

$mla_iptc_keys : array

This array contains the sanitized names and identifiers of Datasets defined in the "IPTC-NAA Information Interchange Model Version No. 4.1".

since 0.90
 

Objects containing [gallery] shortcodes

$galleries : array

This array contains all of the objects containing one or more [gallery] shortcodes and array(s) of which attachments each [gallery] contains. The arrays are built once each page load and cached for subsequent calls.

The outer array is keyed by post_id. It contains an associative array with: ['parent_title'] post_title of the gallery parent, ['parent_type'] 'post' or 'page' or the custom post_type of the gallery parent, ['results'] array ( ID => ID ) of attachments appearing in ANY of the parent's galleries. ['galleries'] array of [gallery] entries numbered from one (1), containing: galleries[X]['query'] contains a string with the arguments of the [gallery], galleries[X]['results'] contains an array ( ID ) of post_ids for the objects in the gallery.

since 0.70
 

Provides a unique name for the ALT Text/custom field SQL View

$mla_alt_text_view : array

since 0.40
 

Objects containing [mla_gallery] shortcodes

$mla_galleries : array

This array contains all of the objects containing one or more [mla_gallery] shortcodes and array(s) of which attachments each [mla_gallery] contains. The arrays are built once each page load and cached for subsequent calls.

since 0.70
 

IPTC Dataset descriptions

$mla_iptc_descriptions : array

This array contains the descriptions of Datasets defined in the "IPTC-NAA Information Interchange Model Version No. 4.1".

since 0.90
 

IPTC file format identifiers and descriptions

$mla_iptc_formats : array

This array contains the file format identifiers and descriptions defined in the "IPTC-NAA Information Interchange Model Version No. 4.1" for dataset 1#020.

since 0.90
 

IPTC image type identifiers and descriptions

$mla_iptc_image_types : array

This array contains the image type identifiers and descriptions defined in the "IPTC-NAA Information Interchange Model Version No. 4.1" for dataset 2#130, octet 2.

since 0.90
 

IPTC Dataset identifiers and names

$mla_iptc_records : array

This array contains the identifiers and names of Datasets defined in the "IPTC-NAA Information Interchange Model Version No. 4.1".

since 0.90
 

Cache the results of mla_count_list_table_items for reuse in mla_query_list_table_items

$mla_list_table_items : array

since 1.40
 

Array of PDF indirect objects

$pdf_indirect_objects : array

This array contains all of the indirect object offsets and lengths. The array key is ( object ID * 1000 ) + object generation. The array value is array( number, generation, start, optional /length )

since 1.50
 

WP_Query filter "parameters"

$query_parameters : array

This array defines parameters for the query's join, where and orderby filters. The parameters are set up in the _prepare_list_table_query function, and any further logic required to translate those values is contained in the filters.

Array index values are: use_postmeta_view, postmeta_key, postmeta_value, patterns, detached, orderby, order, mla-metavalue, debug, s, mla_search_connector, mla_search_fields, sentence, exact

since 0.30
 

UTF-8 replacements for invalid SQL characters

$utf8_chars : array

since 1.41

 Constants

 

Provides a unique suffix for the ALT Text/custom field SQL View

MLA_ALT_TEXT_VIEW_SUFFIX 

The SQL View is used to sort the Media/Assistant submenu table on ALT Text and custom field columns.

since 0.40