templately / modules / utilities / Cleanup / TaskDescriptor.php

TaskDescriptor.php in Templately – Elementor & Gutenberg Template Library: 6500+ Free & Pro Ready Templates And Cloud! 3.8.0, at modules/utilities/Cleanup/TaskDescriptor.php

120 lines 3.8 KB

Raw Download Zip

1	<?php
2	/**
3	* What a contributed cleanup task declares about itself.
4	*
5	* @package Templately
6	*/
7
8	namespace Templately\Modules\Utilities\Cleanup;
9
10	use InvalidArgumentException;
11
12	/**
13	* Normalized descriptor. Built by the registry from each task's `descriptor()`
14	* array so the engine, the REST layer and the UI all read one validated shape
15	* rather than trusting whatever a contributor returned.
16	*
17	* Validation is strict and throws: a malformed descriptor is a programming
18	* error in the contributing module, and failing loudly at registration beats
19	* discovering it when a scheduled sweep silently skips a task at 3am.
20	*/
21	final class TaskDescriptor {
22
23	/** @var string Unique, kebab-case. The address the REST run route takes. */
24	public $id;
25
26	/** @var string Translated label. Resolved lazily — never at registration. */
27	public $label;
28
29	/** @var string UI grouping, e.g. `imports`, `cache`. */
30	public $group;
31
32	/** @var string `files` \| `records` \| `both`. */
33	public $scope;
34
35	/** @var string One of RetentionKind. */
36	public $retention_kind;
37
38	/** @var bool Destructive tasks require explicit confirmation. */
39	public $destructive;
40
41	/** @var bool False = manual-only; excluded from scheduled and batch runs. */
42	public $schedulable;
43
44	const SCOPE_FILES = 'files';
45	const SCOPE_RECORDS = 'records';
46	const SCOPE_BOTH = 'both';
47
48	private function __construct() {}
49
50	/**
51	* @param array $fields Raw descriptor from a task.
52	* @param string $source Class name, for a diagnosable error message.
53	* @throws InvalidArgumentException When the descriptor is malformed.
54	*/
55	public static function from_array( array $fields, string $source = '' ): self {
56	$where = $source ? sprintf( ' (declared by %s)', $source ) : '';
57
58	$id = isset( $fields['id'] ) ? (string) $fields['id'] : '';
59	if ( '' === $id \|\| sanitize_key( $id ) !== $id ) {
60	throw new InvalidArgumentException(
61	sprintf( 'Cleanup task id must be a non-empty kebab-case key, got "%s"%s.', $id, $where )
62	);
63	}
64
65	$scope = isset( $fields['scope'] ) ? (string) $fields['scope'] : self::SCOPE_BOTH;
66	if ( ! in_array( $scope, [ self::SCOPE_FILES, self::SCOPE_RECORDS, self::SCOPE_BOTH ], true ) ) {
67	throw new InvalidArgumentException(
68	sprintf( 'Cleanup task "%s" declared an unknown scope "%s"%s.', $id, $scope, $where )
69	);
70	}
71
72	$kind = isset( $fields['retention_kind'] ) ? (string) $fields['retention_kind'] : '';
73	if ( ! RetentionKind::is_valid( $kind ) ) {
74	throw new InvalidArgumentException(
75	sprintf(
76	'Cleanup task "%s" must declare a retention kind (%s), got "%s"%s.',
77	$id,
78	implode( ', ', RetentionKind::all() ),
79	$kind,
80	$where
81	)
82	);
83	}
84
85	$descriptor = new self();
86	$descriptor->id = $id;
87	$descriptor->label = isset( $fields['label'] ) ? (string) $fields['label'] : $id;
88	$descriptor->group = isset( $fields['group'] ) ? (string) $fields['group'] : 'general';
89	$descriptor->scope = $scope;
90	$descriptor->retention_kind = $kind;
91	$descriptor->destructive = isset( $fields['destructive'] ) ? (bool) $fields['destructive'] : true;
92	$descriptor->schedulable = isset( $fields['schedulable'] ) ? (bool) $fields['schedulable'] : true;
93
94	return $descriptor;
95	}
96
97	/**
98	* Whether this task touches the filesystem, and therefore whether an
99	* unwritable uploads directory makes it unavailable.
100	*/
101	public function touches_files(): bool {
102	return self::SCOPE_RECORDS !== $this->scope;
103	}
104
105	/**
106	* @return array Wire shape consumed by the REST layer and the UI.
107	*/
108	public function to_array(): array {
109	return [
110	'id' => $this->id,
111	'label' => $this->label,
112	'group' => $this->group,
113	'scope' => $this->scope,
114	'retention_kind' => $this->retention_kind,
115	'destructive' => $this->destructive,
116	'schedulable' => $this->schedulable,
117	];
118	}
119	}
120