Data handling & parsing in wordpress

handle_data.php

<?php
	/**
	 * The "global" data handle function
	 * 
	 * This function can serve a lot of different purposes.
	 * Incl. merging db values from an options entry with input arguments.
	 * 
	 * Throws a fully translateable Error if no database option name was specified.
	 * Tells you from which file the Error was triggered and in which line you should search it.
	 * Also tells you the "global_$args['UID']" name of the action hook where the Error occured. 
	 * 
	 * Uses of external function calls in order of their appearance inside the function:
	 * @uses	oxo_handle_data_query_string()
	 * 
	 * @uses	isset()
	 * @link	http://php.net/manual/en/function.isset.php
	 * 
	 * @uses	wp_die()
	 * @link	http://codex.wordpress.org/Function_Reference/wp_die
	 * 
	 * @uses	printf()
	 * @link	http://php.net/manual/en/function.printf.php
	 * 
	 * @uses	_e()
	 * @link	http://codex.wordpress.org/Function_Reference/_e (i18n function)
	 * 
	 * @uses	apply_filters()
	 * @link	http://codex.wordpress.org/Function_Reference/apply_filters
	 * 
	 * @uses	wp_parse_args()
	 * @link	http://codex.wordpress.org/Function_Reference/wp_parse_args
	 * 
	 * @uses	extract()
	 * @link	http://php.net/manual/en/function.extract.php
	 * 
	 * @uses	get_option()
	 * @link	http://codex.wordpress.org/Function_Reference/get_option
	 *
	 * @uses	do_action()
	 * @link	http://codex.wordpress.org/Function_Reference/do_action
	 *
	 * @uses	return
	 * @link	http://php.net/manual/en/function.return.php
	 * 
	 * @since	0.1
	 * 
	 * @param	(mixed) $args - array of arguments - `$args['UID']` is always a must have
	 * @param	(boolean) $database - true if you want to get and modify some db-option - `$args['name']` then is a must have
	 * @param	(mixed) $output - result from the function
	 * @internal $output should not get set
	 */
	function oxo_handle_data( $args = array() )
	{
		// Default names
		$textdomain = 'the_textdomain_string';
		$opt_name = 'option_name';
		$hook = 'hook_args_';
		$filter_defaults = 'filter_defaults_';
		$filter_args = 'filter_args_';
		$filter_output = 'filter_output';

		// Set Error if we ain't got some unique identifier as argument
		if ( ! isset( $args['UID']) )
			$error_msg = __( 'You have to specify a "UID" for your data handle function.', $textdomain );

		// Set Error if an option should get retrieved from the database, but no option name was specified
		if ( ! isset( $args['name'] ) )
			$error_msg = printf(
				__(
					'You have to specify the "name" of a db-entry as argument inside a %3$s function for the action hook: %1$s.'."\n".
					'Error triggered inside: file name %2$s (line number %4$s)'
					,$textdomain
				)
				,$hook.$args['UID']
				,__FILE__
				,__FUNCTION__
				,__LINE__
			);

		// Trigger Errors if we got some
		# @todo replace with the new _doing_it_wrong() function from WP 3.1.
		if ( isset( $error_msg ) )
		{
			$error = new WP_Error( 'oxo_handle_data', $error_msg );
			if ( is_wp_error( $error ) ) 
			{
				$output = 
					'<div id="error-'.$error->get_error_code().'" class="error error-notice">'.
						'<strong>'.
							$error->get_error_message().
						'</strong>'.
					'</div>';
	
				// die & print error message
				wp_die( $output, $error->get_error_code() );
			}
		}

		// setup default arguments
		$defaults = ( 
			array(
				 'UID'		=> null		// DB/css: #id | used to identify the data inside your database - $name[$ID] - can be used as css #id too
				,'name'		=> $opt_name	// name of DB field, should be a constant when fn get's triggered - just here for completeness, not needed
				,'args' 	=> array(	// $arguments the function can handle - put default arguments in here as array data
					// 'classes'	=> null		// css: .class - example
				 )
				,'output'	=> ''
				,'echo' 	=> false	// if you want to echo the output or just save it in a var for later modifying
			) 
		);
		// filter defaults
		$defaults = apply_filters( $filter_defaults.$args['UID'], $defaults ); 

		// If we got a query string instead of an array
		if ( ! is_array( $args ) )
			$args = oxo_handle_query_string( $args );

		// merge defaults with input arguments
		$args = wp_parse_args( $args, $defaults );
		extract( $args, EXTR_SKIP );

		// in case you want to call the global function again, 
		// but for some reason need to modify the merged result of defaults & arguments
		$args = apply_filters( $filter_args.$args['UID'], $args );

		// if a name was set, retrieve the database option by it
		if ( isset( $args['name'] ) )
			$options = get_option( $args['name'] );


		# >>> start building $output

			// do stuff here - your argument is the initial array
			$args['output'] = apply_filters( $filter_output.$args['UID'], $args, $options );
	
			// if true, echo the $output
			if ( $args['echo'] === true )
			{
				// return print / echo output
				return print $args['output'];
			}
	
			// else just return the $output
			return $args['output'];

		# <<< end building $output
	}


	/**
	 * Converts a query string to an array.
	 * Runs the oxo_handle_query_string_cb() function to convert
	 * strings to (boolean) or (integer) in case.
	 * 
	 * @uses	oxo_handle_query_string_cb()
	 * @param	(string) $args
	 * @return	$args
	 */
	function oxo_handle_query_string( $args )
	{
		// Check if it's really a query string
		$check_query_string = strstr( $args, "=" );

		// we got here by accident
		if ( $check_query_string === false )
			return;

		parse_str( $args, $output );

		$args = $output;

		$args = array_map( 'oxo_handle_query_string_cb', $args );

		return $args;
	}


	/**
	 * Callback function for array_map() in oxo_handle_query_string()
	 * Converts '0' to (boolean) false, but leaves '1' as an (integer)
	 * 
	 * Pay attention that you don't pass in *real* query args.
	 * If so, make use of the filter and in case just return the value.
	 * 
	 * @param	(mixed) $arg
	 * @return	$arg
	 */
	function oxo_handle_query_string_cb( $arg )
	{
		// Convert string to lower so we can test strict for values
		$arg = strtolower( $arg );

		// Filter if there are values you want to preserve. Just return the value.
		$arg = apply_filters( 'handle_query_string_cb', $arg );

		// Care about 'false', '0' and 'null', which are now reserved as alias for FALSE
		if ( $arg === (string) 'false' || $arg === (string) '0' || $arg === (string) 'null' )
			return false;

		if ( $arg === (string) 'true' )
			return true;

		// Set up an array of numbers 1-100. Numbers are strings.
		$numbers = array();
		for ( $i = 1; $i <= 100; $i++ )
			$numbers[] = (string) $i;

		// If our number-string is in the array, we convert it to an (integer)
		if ( in_array( $arg, $numbers ) )
			return intval( $arg );

		return $arg;
	}
?>