arraypress/wp-cast-utils

A lightweight WordPress library for type casting and data conversion

dev-main 2025-10-03 18:10 UTC

Requires

• php: >=7.4

GPL-2.0-or-later

• David Sherlock

• wordpress
• wp
• sanitization
• casting
• form-data
• type-conversion
• arraypress
• data-conversion
• meta-values

README

A lightweight WordPress library for smart type casting and data conversion. Focuses on genuinely useful conversions with special handling for WordPress-specific formats.

Features

• 🎯 Focused API: Only the conversions that add real value
• 🔧 WordPress-Ready: Handles serialized data, JSON, and CSV
• ⚡ Smart Conversions: Intelligent array and number detection
• 🛡️ Type Safety: Predictable return types
• 📊 Meta Support: Direct casting of WordPress meta values

Requirements

• PHP 7.4 or later
• WordPress 5.0 or later

Installation

composer require arraypress/wp-cast-utils

Basic Usage

Type Casting

use ArrayPress\CastUtils\Cast;

Boolean conversion (handles 'yes'/'no', 'true'/'false', etc.)
Cast::to_bool( 'yes' ); true
Cast::to_bool( 'false' ); false
Cast::to_bool( 1 ); true

Smart number conversion (preserves int vs float)
Cast::to_number( '123' ); 123 (int)
Cast::to_number( '123.45' ); 123.45 (float)
Cast::to_number( '-67', true ); 67 (absolute)

Array Conversions

Smart array conversion - tries multiple formats
Cast::to_array( 'a,b,c' ); ['a', 'b', 'c'] (CSV)
Cast::to_array( '{"x":1,"y":2}' ); ['x' => 1, 'y' => 2] (JSON)
Cast::to_array( 'a:2:{i:0;s:1:"a";i:1;s:1:"b";}' ); ['a', 'b'] (serialized)

Array to CSV
Cast::to_csv( ['apple', 'banana', 'cherry'] ); 'apple,banana,cherry'
Cast::to_csv( ['red', 'green', 'blue'], '|' ); 'red|green|blue'

JSON Conversion

JSON encoding with WordPress functions
Cast::to_json( ['name' => 'John', 'age' => 30] );
'{"name":"John","age":30}'

Pretty JSON for debugging
Cast::to_json( ['name' => 'John'], true );
{
    "name": "John"
}

WordPress Meta Casting

Cast meta values directly to the type you need
$featured = Cast::meta( 'post', $post_id, 'featured', 'bool' );
$tags = Cast::meta( 'post', $post_id, 'tags', 'array' );
$views = Cast::meta( 'post', $post_id, 'view_count', 'number' );

Works with options too
$settings = Cast::meta( 'option', 'my_plugin_settings', '', 'array' );

API Reference

Core Methods

Method	Description	Returns
to_bool($value)	Convert to boolean with smart string handling	bool
to_number($value, $absolute = false)	Smart int/float detection	int|float
to_array($value)	Smart array conversion (JSON, CSV, serialized)	array
to_json($value, $pretty = false)	Convert to JSON string	string|null
to_csv($array, $separator = ',')	Convert array to CSV string	string

Meta Method

Method	Description	Returns
meta($type, $id, $key, $cast_type, $default = null)	Cast WordPress meta to type	mixed

Meta Types Supported:

• 'post' - Post meta
• 'user' - User meta
• 'term' - Term meta
• 'option' - WordPress options

Cast Types:

• 'array' - Smart array conversion
• 'bool' - Boolean
• 'number' - Smart int/float
• 'int' - Integer
• 'float' - Float
• 'string' - String

Common Use Cases

Form Data Processing

Handle various input formats intelligently
$age = Cast::to_number( $_POST['age'] ?? 0 );
$interests = Cast::to_array( $_POST['interests'] ?? '' ); Handles CSV or array
$newsletter = Cast::to_bool( $_POST['newsletter'] ?? false );

API Responses

Prepare clean data for JSON APIs
$response = [
    'user_id' => Cast::to_number( $user->ID ),
    'is_active' => Cast::to_bool( $user_meta['active'] ),
    'tags' => Cast::to_array( $user_meta['tags'] )
];

return wp_send_json( $response );

Plugin Settings

Handle plugin options reliably
$enabled = Cast::meta( 'option', 'my_plugin_enabled', '', 'bool', false );
$max_items = Cast::meta( 'option', 'my_plugin_max', '', 'number', 10 );
$allowed_types = Cast::meta( 'option', 'my_plugin_types', '', 'array', [] );

Why This Library?

Unlike generic PHP casting, this library:

• Handles WordPress formats: Serialized data, meta values
• Smart detection: Preserves int vs float types
• Multiple format support: JSON, CSV, serialized in one method
• Clean API: Predictable, easy-to-remember method names
• No exceptions: Safe conversions that won't break your site

Requirements

• PHP 7.4+
• WordPress 5.0+

License

GPL-2.0-or-later

Support

• Documentation
• Issue Tracker