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

Initialization function, similar to __construct()

initialize() 

since 0.1

Intercept IPTC and EXIF parse errors

mla_IPTC_EXIF_error_handler(int $type, string $string, string $file, int $line) : boolean

since 1.81

Parameters

$type

int

the level of the error raised

$string

string

the error message

$file

string

the filename that the error was raised in

$line

int

the line number the error was raised at

Returns

booleantrue, to bypass PHP error handler

Apply field-level format options to field-level content

mla_apply_field_level_format(string $value, array $args) : string

since 2.10

Parameters

$value

string

field-level content

$args

array

format code and aguments

Returns

stringformatted field-level content

Get the total number of attachment posts

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

Compatibility shim for MLAQuery::mla_count_list_table_items

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, xmp, 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

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. Also used with the audio/video 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 ''

Retrieve an Attachment array given a $post_id

mla_get_attachment_by_id(integer $post_id, boolean $add_references) : 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

integer

The ID of the attachment post

$add_references

boolean

True to add references, false to skip references

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'

Format printable version of binary data

mla_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

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.

Parse a PDF date string

mla_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

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

Compatibility shim for MLAQuery::mla_query_list_table_items

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

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

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

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

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

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 ')'

Search the namespace array for a non-empty value

_nonempty_value(array $namespace_array, string $namespace, string $key) : string

since 2.10

Parameters

$namespace_array

array

namespace array

$namespace

string

namespace

$key

string

key

Returns

stringtrimmed value of the key within the namespace

Process an argument list within a field-level parameter format specification

_parse_arguments(string $argument_string) : array

since 2.02

Parameters

$argument_string

string

arguments, e.g., ('d/m/Y H:i:s' , "arg, \" two" ) without parens

Returns

arrayindividual arguments, e.g. array( 0 => 'd/m/Y H:i:s', 1 => 'arg, \" two' )

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 an XMP array value, stripping namespace prefixes and Seq/Alt/Bag arrays

_parse_xmp_array(array $values) : mixed

since 2.10

Parameters

$values

array

XMP multi-valued element

Returns

mixedSimplified array or string value

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

Convert an EXIF rational value to a formatted string

_rational_to_string(string $rational, string $integer_format, string $fraction_format, string $mixed_format) : mixed

since 2.02

Parameters

$rational

string

numerator/denominator

$integer_format

string

format for integer values

$fraction_format

string

format for fractional values from -1 to +1

$mixed_format

string

format for integer.fraction values

Returns

mixedformatted value or boolean false if no value available

Remove terms from an attachment's assignments

_remove_terms(integer $post_id, array $terms, object $taxonomy_obj) : array

since 0.40

Parameters

$post_id

integer

The ID of the attachment to be updated

$terms

array

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

$taxonomy_obj

object

The taxonomy object

Returns

arrayTerm ids/names of the surviving terms

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
 

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_alt_text_view, use_postmeta_view, use_orderby_view, alt_text_value, postmeta_key, postmeta_value, patterns, detached, orderby, order, mla-metavalue, debug (also in search_parameters)

since 0.30
 

WP_Query 'posts_search' filter "parameters"

$search_parameters : array

This array defines parameters for the query's posts_search filter, which uses 'search_string' to add a clause to the query's WHERE clause. It is shared between the list_table-query functions here and the mla_get_shortcode_attachments function in class-mla-shortcodes.php. This array passes the relevant parameters to the filter.

Array index values are: ['mla_terms_search']['phrases'] ['mla_terms_search']['taxonomies'] ['mla_terms_search']['radio_phrases'] => AND/OR ['mla_terms_search']['radio_terms'] => AND/OR ['s'] => numeric for ID/parent search ['mla_search_fields'] => 'content', 'title', 'excerpt', 'alt-text', 'name', 'terms' Note: 'alt-text' is not supported in [mla_gallery] ['mla_search_connector'] => AND/OR ['sentence'] => entire string must match as one "keyword" ['exact'] => entire string must match entire field value ['debug'] => internal element, console/log/shortcode/none ['tax_terms_count'] => internal element, shared with JOIN and GROUP BY filters

since 2.00
 

UTF-8 replacements for invalid SQL characters

$utf8_chars : array

since 1.41
 

Passes IPTC/EXIF parse errors between mla_IPTC_EXIF_error_handler and mla_fetch_attachment_image_metadata

$mla_IPTC_EXIF_errors : array

since 1.81
 

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