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

Summary

Methods
Properties
Constants
initialize()
mla_parse_array_template()
mla_parse_template()
mla_apply_field_level_format()
mla_expand_field_level_parameters()
mla_get_template_placeholders()
mla_count_list_table_items()
mla_query_list_table_items()
mla_get_attachment_by_id()
mla_find_array_element()
mla_save_post_action()
mla_parse_pdf_date()
mla_parse_xmp_metadata()
mla_iptc_metadata_value()
mla_exif_metadata_value()
mla_xmp_metadata_value()
mla_id3_metadata_value()
mla_pdf_metadata_value()
mla_IPTC_EXIF_error_handler()
mla_fetch_attachment_id3_metadata()
mla_fetch_attachment_image_metadata()
mla_update_wp_attachment_metadata()
mla_update_item_postmeta()
mla_update_single_item()
mla_hex_dump()
$query_parameters
$search_parameters
$utf8_chars
$mla_iptc_keys
No constants found
No protected methods found
No protected properties found
N/A
_find_template_substring()
_find_test_substring()
_parse_field_level_template()
_evaluate_template_array_node()
_evaluate_template_node()
_expand_field_level_template()
_process_field_level_array()
_parse_arguments()
_set_array_element()
_unset_array_element()
_parse_iso8601_date()
_parse_xmp_array()
_nonempty_value()
_bin_to_utf8()
_rational_to_decimal()
_rational_to_string()
_remove_terms()
$mla_iptc_records
$mla_iptc_descriptions
$mla_iptc_formats
$mla_iptc_image_types
$mla_IPTC_EXIF_errors
N/A

Properties

$query_parameters

$query_parameters : array

WP_Query filter "parameters"

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)

Type

array

$search_parameters

$search_parameters : array

WP_Query 'posts_search' filter "parameters"

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

Type

array

$utf8_chars

$utf8_chars : array

UTF-8 replacements for invalid SQL characters

Type

array

$mla_iptc_keys

$mla_iptc_keys : array

IPTC Dataset friendly name/slug and identifiers

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

Type

array

$mla_iptc_records

$mla_iptc_records : array

IPTC Dataset identifiers and names

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

Type

array

$mla_iptc_descriptions

$mla_iptc_descriptions : array

IPTC Dataset descriptions

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

Type

array

$mla_iptc_formats

$mla_iptc_formats : array

IPTC file format identifiers and descriptions

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.

Type

array

$mla_iptc_image_types

$mla_iptc_image_types : array

IPTC image type identifiers and descriptions

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.

Type

array

$mla_IPTC_EXIF_errors

$mla_IPTC_EXIF_errors : array

Passes IPTC/EXIF parse errors between mla_IPTC_EXIF_error_handler and mla_fetch_attachment_image_metadata

Type

array

Methods

initialize()

initialize() 

Initialization function, similar to __construct()

mla_parse_array_template()

mla_parse_array_template(  $tpl,   $markup_values) : mixed

Expand a template, replacing placeholders with their values

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

Parameters

$tpl
$markup_values

Returns

mixed —

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

mla_parse_template()

mla_parse_template(  $tpl,   $markup_values) : \strng

Expand a template, replacing placeholders with their values

A simple parsing function for basic templating.

Parameters

$tpl
$markup_values

Returns

\strng —

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

mla_apply_field_level_format()

mla_apply_field_level_format(  $value,   $args) : string

Apply field-level format options to field-level content

Parameters

$value
$args

Returns

string —

formatted field-level content

mla_expand_field_level_parameters()

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

Analyze a template, expanding Field-level Markup Substitution Parameters

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.

Parameters

$tpl
$query
$markup_values
$post_id
$keep_existing
$default_option

Returns

array —

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

mla_get_template_placeholders()

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

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

Parameters

$tpl
$default_option

Returns

array —

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

mla_count_list_table_items()

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

Get the total number of attachment posts

Compatibility shim for MLAQuery::mla_count_list_table_items

Parameters

$request
$offset
$count

Returns

integer —

Number of attachment posts

mla_query_list_table_items()

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

Retrieve attachment objects for list table display

Compatibility shim for MLAQuery::mla_query_list_table_items

Parameters

$request
$offset
$count

Returns

array —

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

mla_get_attachment_by_id()

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

Retrieve an Attachment array given a $post_id

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

Parameters

$post_id
$add_references

Returns

NULL|array —

NULL on failure else associative array

mla_find_array_element()

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

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

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.

Parameters

$needle
$haystack
$option
$keep_existing
$glue

Returns

mixed —

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

mla_save_post_action()

mla_save_post_action(  $post_id) : void

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

Parameters

$post_id

mla_parse_pdf_date()

mla_parse_pdf_date(  $source_string) : string

Parse a PDF date string

Parameters

$source_string

Returns

string —

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

mla_parse_xmp_metadata()

mla_parse_xmp_metadata(  $file_name,   $file_offset) : mixed

Extract XMP meta data from a file

Parameters

$file_name
$file_offset

Returns

mixed —

array of metadata values or NULL on failure

mla_iptc_metadata_value()

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

Parse one IPTC metadata field

Parameters

$iptc_key
$item_metadata
$option
$keep_existing

Returns

mixed —

string/array representation of metadata value or an empty string

mla_exif_metadata_value()

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

Parse one EXIF metadata field

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

Parameters

$exif_key
$item_metadata
$option
$keep_existing

Returns

mixed —

string/array representation of metadata value or an empty string

mla_xmp_metadata_value()

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

Parse one XMP metadata field

Also handles the special pseudo-value 'ALL_XMP'.

Parameters

$xmp_key
$xmp_metadata
$option
$keep_existing

Returns

mixed —

string/array representation of metadata value or an empty string

mla_id3_metadata_value()

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

Parse one ID3 (audio/visual) metadata field

Also handles the special pseudo-value 'ALL_ID3'.

Parameters

$id3_key
$id3_metadata
$option
$keep_existing

Returns

mixed —

string/array representation of metadata value or an empty string

mla_pdf_metadata_value()

mla_pdf_metadata_value(  $pdf_key,   $item_metadata) : mixed

Parse one PDF metadata field

Also handles the special pseudo-value 'ALL_PDF'.

Parameters

$pdf_key
$item_metadata

Returns

mixed —

string/array representation of metadata value or an empty string

mla_IPTC_EXIF_error_handler()

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

Intercept IPTC and EXIF parse errors

Parameters

$type
$string
$file
$line

Returns

boolean —

true, to bypass PHP error handler

mla_fetch_attachment_id3_metadata()

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

Fetch and filter ID3 metadata for an audio or video attachment

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

Parameters

$post_id
$path

Returns

array —

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

mla_fetch_attachment_image_metadata()

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

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

Parameters

$post_id
$path

Returns

array —

Meta data variables, IPTC and EXIF or PDF

mla_update_wp_attachment_metadata()

mla_update_wp_attachment_metadata(  $current_values,   $new_meta) : string

Update "meta:" data for a single attachment

Parameters

$current_values
$new_meta

Returns

string —

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

mla_update_item_postmeta()

mla_update_item_postmeta(  $post_id,   $new_meta) : string

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

Parameters

$post_id
$new_meta

Returns

string —

success/failure message(s)

mla_update_single_item()

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

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

Parameters

$post_id
$new_data
$tax_input
$tax_actions

Returns

array —

success/failure message and NULL content

mla_hex_dump()

mla_hex_dump(  $data,   $limit,   $bytes_per_row = 16,   $offset = -1) : string

Format printable version of binary data

Parameters

$data
$limit
$bytes_per_row
$offset

Returns

string —

Printable representation of $data

_find_template_substring()

_find_template_substring(  $tpl) : string

Find a complete template, balancing opening and closing delimiters

Parameters

$tpl

Returns

string —

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

_find_test_substring()

_find_test_substring(  $tpl) : string

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

Parameters

$tpl

Returns

string —

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

_parse_field_level_template()

_parse_field_level_template(  $tpl) : array

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

Parameters

$tpl

Returns

array —

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

_evaluate_template_array_node()

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

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

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

Parameters

$node
$markup_values

Returns

mixed —

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

_evaluate_template_node()

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

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

Parameters

$node
$markup_values

Returns

string —

String with expanded values, if any

_expand_field_level_template()

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

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

Parameters

$tpl
$markup_values
$return_arrays

Returns

mixed —

Element with expanded string/array values, if any

_process_field_level_array()

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

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

Parameters

$record
$option
$keep_existing

Returns

array —

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

_parse_arguments()

_parse_arguments(  $argument_string) : array

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

Parameters

$argument_string

Returns

array —

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

_set_array_element()

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

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

Parameters

$needle
$value
$haystack

Returns

boolean —

true if $needle element set, false if not

_unset_array_element()

_unset_array_element(  $needle,   $haystack) : boolean

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

Parameters

$needle
$haystack

Returns

boolean —

true if $needle element found, false if not

_parse_iso8601_date()

_parse_iso8601_date(  $source_string) : string

Parse a ISO 8601 Timestamp

Parameters

$source_string

Returns

string —

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

_parse_xmp_array()

_parse_xmp_array(  $values) : mixed

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

Parameters

$values

Returns

mixed —

Simplified array or string value

_nonempty_value()

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

Search the namespace array for a non-empty value

Parameters

$namespace_array
$namespace
$key

Returns

string —

trimmed value of the key within the namespace

_bin_to_utf8()

_bin_to_utf8(  $string) : string

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

Parameters

$string

Returns

string —

UTF-8 encoded string

_rational_to_decimal()

_rational_to_decimal(  $rational) : float

Convert an EXIF GPS rational value to a PHP float value

Parameters

$rational

Returns

float —

numerator/denominator

_rational_to_string()

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

Convert an EXIF rational value to a formatted string

Parameters

$rational
$integer_format
$fraction_format
$mixed_format

Returns

mixed —

formatted value or boolean false if no value available

_remove_terms()

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

Remove terms from an attachment's assignments

Parameters

$post_id
$terms
$taxonomy_obj

Returns

array —

Term ids/names of the surviving terms