insert-php / admin / includes / dto / class-dto-base.php

class-dto-base.php in Woody Code Snippets – Insert PHP, CSS, JS, and Header/Footer Scripts 2.7.1, at admin/includes/dto/class-dto-base.php

96 lines 2.7 KB

Raw Download Zip

1	<?php
2	/**
3	* Base DTO class
4	*
5	* Base Data Transfer Object with common factory methods.
6	* Replaces the non-GPL-compatible JsonMapper implementation.
7	*
8	* @package Woody_Code_Snippets
9	* @copyright Copyright (c) 2025, Themeisle
10	* @license GPL-2.0+
11	*/
12
13	// Exit if accessed directly.
14	if ( ! defined( 'ABSPATH' ) ) {
15	exit;
16	}
17
18	/**
19	* Abstract base class for Data Transfer Objects.
20	*/
21	abstract class WINP_DTO_Base {
22
23	/**
24	* Create instance from associative array.
25	*
26	* Must be implemented by child classes.
27	*
28	* @param array<string, mixed> $data Associative array of data.
29	*
30	* @return static
31	* @throws Exception If required fields are missing.
32	*/
33	abstract public static function from_array( array $data );
34
35	/**
36	* Create instance from JSON object.
37	*
38	* @param mixed $json JSON object from json_decode().
39	*
40	* @return static
41	* @throws Exception If required fields are missing or invalid type.
42	*/
43	public static function from_json( $json ) {
44	if ( ! is_object( $json ) ) {
45	$class = static::class;
46	// phpcs:ignore WordPress.Security.EscapeOutput.ExceptionNotEscaped -- Error message for developers only.
47	throw new Exception( "{$class}::from_json() requires an object, " . gettype( $json ) . ' given' );
48	}
49
50	return static::from_array( (array) $json );
51	}
52
53	/**
54	* Create array of instances from JSON array.
55	*
56	* @param array<mixed> $json_array Array of JSON objects or arrays.
57	*
58	* @return static[]
59	* @throws Exception If data is invalid.
60	*/
61	public static function array_from_json( array $json_array ) {
62	$result = [];
63
64	foreach ( $json_array as $item ) {
65	if ( is_object( $item ) ) {
66	$result[] = static::from_json( $item );
67	} elseif ( is_array( $item ) ) {
68	$result[] = static::from_array( $item );
69	} else {
70	$class = static::class;
71	// phpcs:ignore WordPress.Security.EscapeOutput.ExceptionNotEscaped -- Error message for developers only.
72	throw new Exception( "Invalid item type in {$class} array: " . gettype( $item ) );
73	}
74	}
75
76	return $result;
77	}
78
79	/**
80	* Validate required field exists in data array.
81	*
82	* @param array<string, mixed> $data Data array to check.
83	* @param string $field_name Required field name.
84	* @param string $class_name Class name for error message.
85	*
86	* @return void
87	* @throws Exception If required field is missing.
88	*/
89	protected static function require_field( array $data, $field_name, $class_name ) {
90	if ( ! isset( $data[ $field_name ] ) ) {
91	// phpcs:ignore WordPress.Security.EscapeOutput.ExceptionNotEscaped -- Error message for developers only.
92	throw new Exception( "Required field \"{$field_name}\" is missing in {$class_name} data" );
93	}
94	}
95	}
96