give / vendor / vendor-prefixed / stellarwp / admin-notices / src / AdminNotice.php

AdminNotice.php in GiveWP – Donation Plugin and Fundraising Platform 4.17.0, at vendor/vendor-prefixed/stellarwp/admin-notices/src/AdminNotice.php

603 lines 13.2 KB

Raw Download Zip

1	<?php
2
3	declare(strict_types=1);
4
5	namespace Give\Vendors\StellarWP\AdminNotices;
6
7	use DateTimeImmutable;
8	use DateTimeInterface;
9	use DateTimeZone;
10	use Exception;
11	use InvalidArgumentException;
12	use Give\Vendors\StellarWP\AdminNotices\ValueObjects\NoticeLocation;
13	use Give\Vendors\StellarWP\AdminNotices\ValueObjects\NoticeUrgency;
14	use Give\Vendors\StellarWP\AdminNotices\ValueObjects\ScreenCondition;
15	use Give\Vendors\StellarWP\AdminNotices\ValueObjects\Script;
16	use Give\Vendors\StellarWP\AdminNotices\ValueObjects\Style;
17	use Give\Vendors\StellarWP\AdminNotices\ValueObjects\UserCapability;
18
19	class AdminNotice
20	{
21	/**
22	* @var string
23	*/
24	protected $id;
25
26	/**
27	* @var string\|callable
28	*/
29	protected $renderTextOrCallback;
30
31	/**
32	* @var UserCapability[]
33	*/
34	protected $userCapabilities;
35
36	/**
37	* @var DateTimeInterface
38	*/
39	protected $afterDate;
40
41	/**
42	* @var DateTimeInterface
43	*/
44	protected $untilDate;
45
46	/**
47	* @var callable
48	*/
49	protected $whenCallback;
50
51	/**
52	* @var ScreenCondition[]
53	*/
54	protected $onConditions;
55
56	/**
57	* @var bool
58	*/
59	protected $autoParagraph = false;
60
61	/**
62	* @var NoticeUrgency
63	*/
64	protected $urgency;
65
66	/**
67	* @var bool
68	*/
69	protected $alternateStyles = false;
70
71	/**
72	* @var bool Indicates that the notice is customized and not the standard WordPress notice
73	*/
74	protected $custom = false;
75
76	/**
77	* @var bool
78	*/
79	protected $dismissible = false;
80
81	/**
82	* @var NoticeLocation\|null
83	*/
84	protected $location;
85
86	/**
87	* @var Script
88	*/
89	protected $scriptToEnqueue;
90
91	/**
92	* @var Style
93	*/
94	protected $styleToEnqueue;
95
96	/**
97	* @since 1.0.0
98	*
99	* @param string\|callable $renderTextOrCallback
100	*/
101	public function __construct(string $id, $renderTextOrCallback)
102	{
103	if (!is_string($renderTextOrCallback) && !is_callable($renderTextOrCallback)) {
104	throw new InvalidArgumentException('The renderTextOrCallback argument must be a string or a callable');
105	}
106
107	$this->id = $id;
108	$this->renderTextOrCallback = $renderTextOrCallback;
109	$this->urgency = NoticeUrgency::info();
110	$this->location = NoticeLocation::standard();
111	}
112
113	/**
114	* Limits the notice to display based on the capabilities of the current user
115	*
116	* @since 1.0.0
117	*
118	* @param string\|array ...$capabilities String or array of arguments compatible with current_user_can()
119	*
120	* @return $this
121	*/
122	public function ifUserCan(...$capabilities): self
123	{
124	$this->userCapabilities = [];
125
126	// Validate and store the capabilities
127	foreach ($capabilities as $capability) {
128	if (empty($capability)) {
129	throw new InvalidArgumentException('Capability must be a non-empty string or array');
130	} elseif (is_string($capability)) {
131	$this->userCapabilities[] = new UserCapability($capability);
132	} elseif (is_array($capability) && is_string($capability[0])) {
133	$this->userCapabilities[] = new UserCapability($capability[0], array_slice($capability, 1));
134	} elseif ($capability instanceof UserCapability) {
135	$this->userCapabilities[] = $capability;
136	} else {
137	throw new InvalidArgumentException(
138	'Invalid capability type. Must be string or array of arguments compatible with current_user_can()'
139	);
140	}
141	}
142
143	return $this;
144	}
145
146	/**
147	* Limits the notice to display after a specific date
148	*
149	* @since 1.0.0
150	*
151	* @param $date DateTimeInterface\|string\|int if a string then it will be considered UTC
152	*
153	* @return $this
154	* @throws Exception If the date is not a valid DateTimeInterface or string
155	*/
156	public function after($date): self
157	{
158	$this->afterDate = $this->parseDate($date);
159
160	return $this;
161	}
162
163	/**
164	* Limits the notice to display until a specific date
165	*
166	* @since 1.0.0
167	*
168	* @param $date DateTimeInterface\|string\|int if a string then it will be considered UTC
169	*
170	* @throws Exception If the date is not a valid DateTimeInterface or string
171	*/
172	public function until($date): self
173	{
174	$this->untilDate = $this->parseDate($date);
175
176	return $this;
177	}
178
179	/**
180	* Limits the notice to a specific date range
181	*
182	* @param $after DateTimeInterface\|string if a string then it will be considered UTC
183	* @param $until DateTimeInterface\|string if a string then it will be considered UTC
184	*
185	* @throws Exception If the date is not a valid DateTimeInterface or string
186	*/
187	public function between($after, $until): self
188	{
189	return $this->after($after)->until($until);
190	}
191
192	/**
193	* Provide a callback which returns a boolean to determine if the notice should be displayed
194	*
195	* @since 1.0.0
196	*/
197	public function when(callable $callback): self
198	{
199	$this->whenCallback = $callback;
200
201	return $this;
202	}
203
204	/**
205	* Limits the notice to display on specific screens
206	*
207	* @since 1.0.0
208	*
209	* @param array\|string\|ScreenCondition $on
210	*/
211	public function on(...$on): self
212	{
213	foreach ($on as $condition) {
214	$this->onConditions[] = $condition instanceof ScreenCondition ? $condition : new ScreenCondition(
215	$condition
216	);
217	}
218
219	return $this;
220	}
221
222	/**
223	* Automatically applies paragraph tags to the notice content
224	*
225	* @since 1.0.0
226	*/
227	public function autoParagraph(bool $auto = true): self
228	{
229	$this->autoParagraph = $auto;
230
231	return $this;
232	}
233
234	/**
235	* Disables automatic paragraph tagging
236	*
237	* @since 1.0.0
238	*/
239	public function withoutAutoParagraph(): self
240	{
241	$this->autoParagraph = false;
242
243	return $this;
244	}
245
246	/**
247	* Sets the urgency of the notice, used when the notice is displayed in the standard wrapper
248	*
249	* @since 1.0.0
250	*
251	* @param $urgency string\|NoticeUrgency
252	*/
253	public function urgency($urgency): self
254	{
255	$this->urgency = $urgency instanceof NoticeUrgency ? $urgency : new NoticeUrgency($urgency);
256
257	return $this;
258	}
259
260	/**
261	* Alias for setting the urgency to info
262	*
263	* @since 1.1.0
264	*/
265	public function asInfo(): self
266	{
267	return $this->urgency(NoticeUrgency::info());
268	}
269
270	/**
271	* Alias for setting the urgency to success
272	*
273	* @since 1.1.0
274	*/
275	public function asSuccess(): self
276	{
277	return $this->urgency(NoticeUrgency::success());
278	}
279
280	/**
281	* Alias for setting the urgency to warning
282	*
283	* @since 1.1.0
284	*/
285	public function asWarning(): self
286	{
287	return $this->urgency(NoticeUrgency::warning());
288	}
289
290	/**
291	* Alias for setting the urgency to error
292	*
293	* @since 1.1.0
294	*/
295	public function asError(): self
296	{
297	return $this->urgency(NoticeUrgency::error());
298	}
299
300	/**
301	* Uses the alternate WP notice styles
302	*
303	* @since 1.2.0
304	*/
305	public function alternateStyles(bool $altStyle = true): self
306	{
307	$this->alternateStyles = $altStyle;
308
309	return $this;
310	}
311
312	/**
313	* Uses the standard WP notice styles
314	*
315	* @since 1.2.0
316	*/
317	public function standardStyles(): self
318	{
319	$this->alternateStyles = false;
320
321	return $this;
322	}
323
324	/**
325	* Returns whether the notice uses the alternate WP notice styles
326	*
327	* @since 1.2.0
328	*/
329	public function usesAlternateStyles(): bool
330	{
331	return $this->alternateStyles;
332	}
333
334	public function custom(bool $custom = true): self
335	{
336	$this->custom = $custom;
337
338	return $this;
339	}
340
341	public function standard(): self
342	{
343	$this->custom = false;
344
345	return $this;
346	}
347
348	/**
349	* Sets the notice to be inline
350	*
351	* @since 2.0.0 removed parameter in favor of new location parameter
352	* @since 1.2.0
353	*/
354	public function inline(): self
355	{
356	$this->location = NoticeLocation::inline();
357
358	return $this;
359	}
360
361	/**
362	* Prevents the notice from being moved from the place it's rendered
363	*
364	* @since 2.0.0
365	*/
366	public function inPlace(): self
367	{
368	$this->location = null;
369
370	return $this;
371	}
372
373	public function location($location): self
374	{
375	$this->location = $location instanceof NoticeLocation ? $location : new NoticeLocation($location);
376
377	return $this;
378	}
379
380	public function getLocation(): ?NoticeLocation
381	{
382	return $this->location;
383	}
384
385	/**
386	* Sets the notice to be dismissible, usable when the notice is displayed in the standard wrapper
387	*
388	* @since 1.0.0
389	*/
390	public function dismissible(bool $dismissible = true): self
391	{
392	$this->dismissible = $dismissible;
393
394	return $this;
395	}
396
397	/**
398	* Sets the notice to be not dismissible, usable when the notice is displayed in the standard wrapper
399	*
400	* @since 1.0.0
401	*/
402	public function notDismissible(): self
403	{
404	$this->dismissible = false;
405
406	return $this;
407	}
408
409	/**
410	* Returns the notice ID
411	*
412	* @since 1.0.0
413	*/
414	public function getId(): string
415	{
416	return $this->id;
417	}
418
419	/**
420	* @since 2.0.0
421	*/
422	public function enqueueScript(
423	string $source,
424	array $dependencies = [],
425	string $version = null,
426	array $args = null
427	): self {
428	if ($args === null) {
429	$args = ['strategy' => 'defer'];
430	}
431
432	$this->scriptToEnqueue = new Script($source, $dependencies, $version, $args);
433
434	return $this;
435	}
436
437	/**
438	* @since 2.0.0
439	*/
440	public function getScriptToEnqueue(): ?Script
441	{
442	return $this->scriptToEnqueue;
443	}
444
445	/**
446	* @since 2.0.0
447	*/
448	public function enqueueStylesheet(
449	string $source,
450	array $dependencies = [],
451	string $version = null,
452	string $media = 'all'
453	): self {
454	$this->styleToEnqueue = new Style($source, $dependencies, $version, $media);
455
456	return $this;
457	}
458
459	/**
460	* @since 2.0.0
461	*/
462	public function getStyleToEnqueue(): ?Style
463	{
464	return $this->styleToEnqueue;
465	}
466
467	/**
468	* Returns the text or callback used to render the notice
469	*
470	* @since 1.0.0
471	*
472	* @return callable\|string
473	*/
474	public function getRenderTextOrCallback()
475	{
476	return $this->renderTextOrCallback;
477	}
478
479	/**
480	* Returns the rendered content of the notice, either by returning the string or executing the callback
481	*
482	* @since 1.0.0
483	*/
484	public function getRenderedContent(): string
485	{
486	$render = $this->renderTextOrCallback;
487
488	$content = is_callable($render) ? $render() : $render;
489
490	return $this->autoParagraph ? wpautop($content) : $content;
491	}
492
493	/**
494	* Returns the user capabilities
495	*
496	* @since 1.0.0
497	*
498	* @return UserCapability[]
499	*/
500	public function getUserCapabilities(): ?array
501	{
502	return $this->userCapabilities;
503	}
504
505	/**
506	* Returns the date after which the notice should be displayed
507	*
508	* @since 1.0.0
509	*/
510	public function getAfterDate(): ?DateTimeInterface
511	{
512	return $this->afterDate;
513	}
514
515	/**
516	* Returns the date until which the notice should be displayed
517	*
518	* @since 1.0.0
519	*/
520	public function getUntilDate(): ?DateTimeInterface
521	{
522	return $this->untilDate;
523	}
524
525	/**
526	* Returns the callback used to determine if the notice should be displayed
527	*
528	* @since 1.0.0
529	*/
530	public function getWhenCallback(): ?callable
531	{
532	return $this->whenCallback;
533	}
534
535	/**
536	* Returns the screen conditions used to determine if the notice should be displayed
537	*
538	* @since 1.0.0
539	*
540	* @return ScreenCondition[]
541	*/
542	public function getOnConditions(): ?array
543	{
544	return $this->onConditions;
545	}
546
547	/**
548	* Returns whether the notice content should be automatically wrapped in paragraph tags
549	*
550	* @since 1.0.0
551	*/
552	public function shouldAutoParagraph(): bool
553	{
554	return $this->autoParagraph;
555	}
556
557	/**
558	* Returns the urgency of the notice
559	*
560	* @since 1.0.0
561	*/
562	public function getUrgency(): NoticeUrgency
563	{
564	return $this->urgency;
565	}
566
567	public function isCustom(): bool
568	{
569	return $this->custom;
570	}
571
572	/**
573	* Returns whether the notice is dismissible
574	*
575	* @since 1.0.0
576	*/
577	public function isDismissible(): bool
578	{
579	return $this->dismissible;
580	}
581
582	/**
583	* Parses the date into a DateTimeInterface for the date methods
584	*
585	* @since 1.0.0
586	*
587	* @param $date DateTimeInterface\|string\|int if a string then it will be considered UTC
588	*
589	* @throws Exception
590	*/
591	private function parseDate($date): DateTimeInterface
592	{
593	if (is_int($date)) {
594	$date = '@' . $date;
595	}
596
597	return $date instanceof DateTimeInterface ? $date : new DateTimeImmutable(
598	$date,
599	new DateTimeZone('UTC')
600	);
601	}
602	}
603