# MLAData

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

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

    _bin_to_utf8( $string) : string

static

since | 1.41

### Arguments

#### $string

``

### Response

`string`

UTF-8 encoded string

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

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

static

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

since | 1.50

### Arguments

#### $node

``

#### $markup_values

``

### Response

`mixed`

string 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( $node,  $markup_values = array()) : string

static

since | 1.50

### Arguments

#### $node

``

#### $markup_values

``

### Response

`string`

String with expanded values, if any

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

    _expand_field_level_template( $tpl,  $markup_values = array(),  $return_arrays = false) : mixed

static

since | 1.50

### Arguments

#### $tpl

``

#### $markup_values

``

#### $return_arrays

``

### Response

`mixed`

Element with expanded string/array values, if any

## Find a complete template, balancing opening and closing delimiters

    _find_template_substring( $tpl) : string

static

since | 1.50

### Arguments

#### $tpl

``

### Response

`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( $tpl) : string

static

since | 1.50

### Arguments

#### $tpl

``

### Response

`string`

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

## Search the namespace array for a non-empty value

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

static

since | 2.10

### Arguments

#### $namespace_array

``

#### $namespace

``

#### $key

``

### Response

`string`

trimmed value of the key within the namespace

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

    _parse_arguments( $argument_string) : array

static

since | 2.02

### Arguments

#### $argument_string

``

### Response

`array`

individual 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( $tpl) : array

static

since | 1.50

### Arguments

#### $tpl

``

### Response

`array`

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

## Parse a ISO 8601 Timestamp

    _parse_iso8601_date( $source_string) : string

static

since | 1.50

### Arguments

#### $source_string

``

### Response

`string`

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

## Parse an XMP array value, stripping namespace prefixes and Seq/Alt/Bag arrays

    _parse_xmp_array( $values) : mixed

static

since | 2.10

### Arguments

#### $values

``

### Response

`mixed`

Simplified array or string value

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

    _process_field_level_array( $record,  $option = 'text',  $keep_existing = false) : array

static

since | 1.50

### Arguments

#### $record

``

#### $option

``

#### $keep_existing

``

### Response

`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( $rational) : float

static

since | 1.50

### Arguments

#### $rational

``

### Response

`float`

numerator/denominator

## Convert an EXIF rational value to a formatted string

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

static

since | 2.02

### Arguments

#### $rational

``

#### $integer_format

``

#### $fraction_format

``

#### $mixed_format

``

### Response

`mixed`

formatted value or boolean false if no value available

## Remove terms from an attachment's assignments

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

static

since | 0.40

### Arguments

#### $post_id

``

#### $terms

``

#### $taxonomy_obj

``

### Response

`array`

Term ids/names of the surviving terms

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

    _set_array_element( $needle,  &$value,  &$haystack) : boolean

static

since | 1.51

### Arguments

#### $needle

``

#### $value

``

#### $haystack

``

### Response

`boolean`

true if $needle element set, false if not

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

    _unset_array_element( $needle,  &$haystack) : boolean

static

since | 1.51

### Arguments

#### $needle

``

#### $haystack

``

### Response

`boolean`

true if $needle element found, false if not

## Initialization function, similar to __construct()

    initialize()

static

since | 0.1

## Apply field-level format options to field-level content

    mla_apply_field_level_format( $value,  $args) : string

static

since | 2.10

### Arguments

#### $value

``

#### $args

``

### Response

`string`

formatted field-level content

## Get the total number of attachment posts

    mla_count_list_table_items( $request,  $offset = NULL,  $count = NULL) : integer

static

Compatibility shim for MLAQuery::mla_count_list_table_items

since | 0.30

### Arguments

#### $request

``

#### $offset

``

#### $count

``

### Response

`integer`

Number of attachment posts

## Parse one EXIF metadata field

    mla_exif_metadata_value( $exif_key,  $item_metadata,  $option = 'text',  $keep_existing = false) : mixed

static

Also handles the special pseudo-values 'ALL_EXIF' and 'ALL_IPTC'.

since | 1.13

### Arguments

#### $exif_key

``

#### $item_metadata

``

#### $option

``

#### $keep_existing

``

### Response

`mixed`

string/array representation of metadata value or an empty string

## Analyze a template, expanding Field-level Markup Substitution Parameters

    mla_expand_field_level_parameters( $tpl,  $query = NULL,  $markup_values = array(),  $post_id,  $keep_existing = false,  $default_option = 'text',  $upload_metadata = NULL) : array

static

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

### Arguments

#### $tpl

``

#### $query

``

#### $markup_values

``

#### $post_id

``

#### $keep_existing

``

#### $default_option

``

#### $upload_metadata

``

### Response

`array`

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

## Fetch and filter ID3 metadata for an audio or video attachment

    mla_fetch_attachment_id3_metadata( $post_id,  $path = '') : array

static

Adapted from /wp-admin/includes/media.php functions wp_add_id3_tag_data, wp_read_video_metadata and wp_read_audio_metadata

since | 2.13

### Arguments

#### $post_id

``

#### $path

``

### Response

`array`

Meta data variables, including 'audio' and 'video'

## Fetch and filter IPTC and EXIF, XMP or PDF metadata for an image attachment

    mla_fetch_attachment_image_metadata( $post_id,  $path = '') : array

static

since | 0.90

### Arguments

#### $post_id

``

#### $path

``

### Response

`array`

Meta data variables, IPTC and EXIF or PDF

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

    mla_find_array_element( $needle,  $haystack,  $option,  $keep_existing = false,  $glue = ', ') : mixed

static

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

### Arguments

#### $needle

``

#### $haystack

``

#### $option

``

#### $keep_existing

``

#### $glue

``

### Response

`mixed`

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

## Retrieve an Attachment array given a $post_id

    mla_get_attachment_by_id( $post_id,  $add_references = true) : NULL|array

static

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 | WordPress global variable

### Arguments

#### $post_id

``

#### $add_references

``

### Response

`NULL|array`

NULL on failure else associative array

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

    mla_get_template_placeholders( $tpl,  $default_option = 'text') : array

static

since | 0.90

### Arguments

#### $tpl

``

#### $default_option

``

### Response

`array`

Placeholder 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( $data,  $limit,  $bytes_per_row = 16,  $offset = -1) : string

static

since | 0.90

### Arguments

#### $data

``

#### $limit

``

#### $bytes_per_row

``

#### $offset

``

### Response

`string`

Printable representation of $data

## Parse one ID3 (audio/visual) metadata field

    mla_id3_metadata_value( $id3_key,  $id3_metadata,  $option,  $keep_existing) : mixed

static

Also handles the special pseudo-value 'ALL_ID3'.

since | 2.13

### Arguments

#### $id3_key

``

#### $id3_metadata

``

#### $option

``

#### $keep_existing

``

### Response

`mixed`

string/array representation of metadata value or an empty string

## Intercept IPTC and EXIF parse errors

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

static

since | 1.81

### Arguments

#### $type

``

#### $string

``

#### $file

``

#### $line

``

### Response

`boolean`

true, to bypass PHP error handler

## Parse one IPTC metadata field

    mla_iptc_metadata_value( $iptc_key,  $item_metadata,  $option = 'text',  $keep_existing = false) : mixed

static

since | 1.41

### Arguments

#### $iptc_key

``

#### $item_metadata

``

#### $option

``

#### $keep_existing

``

### Response

`mixed`

string/array representation of metadata value or an empty string

## Expand a template, replacing placeholders with their values

    mla_parse_array_template( $tpl,  $markup_values) : mixed

static

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

since | 1.50

### Arguments

#### $tpl

``

#### $markup_values

``

### Response

`mixed`

string 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( $source_string) : string

static

since | 1.50

### Arguments

#### $source_string

``

### Response

`string`

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

## Expand a template, replacing placeholders with their values

    mla_parse_template( $tpl,  $markup_values) : \strng

static

A simple parsing function for basic templating.

since | 0.1

### Arguments

#### $tpl

``

#### $markup_values

``

### Response

`\strng`

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

## Extract XMP meta data from a file

    mla_parse_xmp_metadata( $file_name,  $file_offset) : mixed

static

since | 2.10

### Arguments

#### $file_name

``

#### $file_offset

``

### Response

`mixed`

array of metadata values or NULL on failure

## Parse one PDF metadata field

    mla_pdf_metadata_value( $pdf_key,  $item_metadata) : mixed

static

Also handles the special pseudo-value 'ALL_PDF'.

since | 1.50

### Arguments

#### $pdf_key

``

#### $item_metadata

``

### Response

`mixed`

string/array representation of metadata value or an empty string

## Retrieve attachment objects for list table display

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

static

Compatibility shim for MLAQuery::mla_query_list_table_items

since | 0.1

### Arguments

#### $request

``

#### $offset

``

#### $count

``

### Response

`array`

attachment 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( $post_id) : void

static

since | 1.00

### Arguments

#### $post_id

``

## Update custom field and "meta:" data for a single attachment

    mla_update_item_postmeta( $post_id,  $new_meta) : string

static

since | 1.40

### Arguments

#### $post_id

``

#### $new_meta

``

### Response

`string`

success/failure message(s)

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

    mla_update_single_item( $post_id,  $new_data,  $tax_input = NULL,  $tax_actions = NULL) : array

static

since | 0.1

### Arguments

#### $post_id

``

#### $new_data

``

#### $tax_input

``

#### $tax_actions

``

### Response

`array`

success/failure message and NULL content

## Update "meta:" data for a single attachment

    mla_update_wp_attachment_metadata( &$current_values,  $new_meta) : string

static

since | 1.51

### Arguments

#### $current_values

``

#### $new_meta

``

### Response

`string`

success/failure message(s); empty string if no changes.

## Parse one XMP metadata field

    mla_xmp_metadata_value( $xmp_key,  $xmp_metadata,  $option = 'text',  $keep_existing = false) : mixed

static

Also handles the special pseudo-value 'ALL_XMP'.

since | 2.10

### Arguments

#### $xmp_key

``

#### $xmp_metadata

``

#### $option

``

#### $keep_existing

``

### Response

`mixed`

string/array representation of metadata value or an empty string

### Properties

## WP_Query filter "parameters"

    query_parameters : array

static

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 |
var |

### Type(s)

`array`

## WP_Query 'posts_search' filter "parameters"

    search_parameters : array

static

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'] => 'title', 'name', 'alt-text', 'excerpt', 'content', 'file' ,'terms' Note: 'alt-text' and 'file' are 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 |
var |

### Type(s)

`array`

## UTF-8 replacements for invalid SQL characters

    utf8_chars : array

static

since |
var |

### Type(s)

`array`

## IPTC Dataset identifiers and names

    mla_iptc_records : array

static

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

since |
var |

### Type(s)

`array`

## IPTC Dataset friendly name/slug and identifiers

    mla_iptc_keys : array

static

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

since |
var |

### Type(s)

`array`

## IPTC Dataset descriptions

    mla_iptc_descriptions : array

static

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

since |
var |

### Type(s)

`array`

## IPTC file format identifiers and descriptions

    mla_iptc_formats : array

static

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 |
var |

### Type(s)

`array`

## IPTC image type identifiers and descriptions

    mla_iptc_image_types : array

static

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 |
var |

### Type(s)

`array`

## Passes IPTC/EXIF parse errors between mla_IPTC_EXIF_error_handler and mla_fetch_attachment_image_metadata

    mla_IPTC_EXIF_errors : array

static

since |
var |

### Type(s)

`array`