give / src / Framework / Support / Facades / Str.php

Str.php in GiveWP – Donation Plugin and Fundraising Platform 4.16.9, at src/Framework/Support/Facades/Str.php

820 lines 19.9 KB

Raw Download Zip

1	<?php
2
3	namespace Give\Framework\Support\Facades;
4
5	use function sanitize_title;
6
7	class Str
8	{
9	/**
10	* The cache of snake-cased words.
11	*
12	* @var array
13	*/
14	protected static $snakeCache = [];
15
16	/**
17	* The cache of camel-cased words.
18	*
19	* @var array
20	*/
21	protected static $camelCache = [];
22
23	/**
24	* The cache of studly-cased words.
25	*
26	* @var array
27	*/
28	protected static $studlyCache = [];
29
30	/**
31	* Return the remainder of a string after the first occurrence of a given value.
32	*
33	* @param string $subject
34	* @param string $search
35	* @return string
36	*/
37	public static function after($subject, $search)
38	{
39	return $search === '' ? $subject : array_reverse(explode($search, $subject, 2))[0];
40	}
41
42	/**
43	* Return the remainder of a string after the last occurrence of a given value.
44	*
45	* @param string $subject
46	* @param string $search
47	* @return string
48	*/
49	public static function afterLast($subject, $search)
50	{
51	if ($search === '') {
52	return $subject;
53	}
54
55	$position = strrpos($subject, (string) $search);
56
57	if ($position === false) {
58	return $subject;
59	}
60
61	return substr($subject, $position + strlen($search));
62	}
63
64	/**
65	* Get the portion of a string before the first occurrence of a given value.
66	*
67	* @param string $subject
68	* @param string $search
69	* @return string
70	*/
71	public static function before($subject, $search)
72	{
73	if ($search === '') {
74	return $subject;
75	}
76
77	$result = strstr($subject, (string) $search, true);
78
79	return $result === false ? $subject : $result;
80	}
81
82	/**
83	* Get the portion of a string before the last occurrence of a given value.
84	*
85	* @param string $subject
86	* @param string $search
87	* @return string
88	*/
89	public static function beforeLast($subject, $search)
90	{
91	if ($search === '') {
92	return $subject;
93	}
94
95	$pos = mb_strrpos($subject, $search);
96
97	if ($pos === false) {
98	return $subject;
99	}
100
101	return static::substr($subject, 0, $pos);
102	}
103
104	/**
105	* Get the portion of a string between two given values.
106	*
107	* @param string $subject
108	* @param string $from
109	* @param string $to
110	* @return string
111	*/
112	public static function between($subject, $from, $to)
113	{
114	if ($from === '' \|\| $to === '') {
115	return $subject;
116	}
117
118	return static::beforeLast(static::after($subject, $from), $to);
119	}
120
121	/**
122	* Get the smallest possible portion of a string between two given values.
123	*
124	* @param string $subject
125	* @param string $from
126	* @param string $to
127	* @return string
128	*/
129	public static function betweenFirst($subject, $from, $to)
130	{
131	if ($from === '' \|\| $to === '') {
132	return $subject;
133	}
134
135	return static::before(static::after($subject, $from), $to);
136	}
137
138	/**
139	* Convert a value to camel case.
140	*
141	* @param string $value
142	* @return string
143	*/
144	public static function camel($value)
145	{
146	if (isset(static::$camelCache[$value])) {
147	return static::$camelCache[$value];
148	}
149
150	return static::$camelCache[$value] = lcfirst(static::studly(static::lower($value)));
151	}
152
153	/**
154	* Determine if a given string contains a given substring.
155	*
156	* @param string $haystack
157	* @param string\|string[] $needles
158	* @param bool $ignoreCase
159	* @return bool
160	*/
161	public static function contains($haystack, $needles, $ignoreCase = false)
162	{
163	if ($ignoreCase) {
164	$haystack = mb_strtolower($haystack);
165	$needles = array_map('mb_strtolower', (array) $needles);
166	}
167
168	foreach ((array) $needles as $needle) {
169	if ($needle !== '' && str_contains($haystack, $needle)) {
170	return true;
171	}
172	}
173
174	return false;
175	}
176
177	/**
178	* Determine if a given string contains all array values.
179	*
180	* @param string $haystack
181	* @param string[] $needles
182	* @param bool $ignoreCase
183	* @return bool
184	*/
185	public static function containsAll($haystack, array $needles, $ignoreCase = false)
186	{
187	if ($ignoreCase) {
188	$haystack = mb_strtolower($haystack);
189	$needles = array_map('mb_strtolower', $needles);
190	}
191
192	foreach ($needles as $needle) {
193	if (! static::contains($haystack, $needle)) {
194	return false;
195	}
196	}
197
198	return true;
199	}
200
201	/**
202	* Determine if a given string ends with a given substring.
203	*
204	* @param string $haystack
205	* @param string\|string[] $needles
206	* @return bool
207	*/
208	public static function endsWith($haystack, $needles)
209	{
210	foreach ((array) $needles as $needle) {
211	if (
212	$needle !== '' && $needle !== null
213	&& str_ends_with($haystack, $needle)
214	) {
215	return true;
216	}
217	}
218
219	return false;
220	}
221
222	/**
223	* Cap a string with a single instance of a given value.
224	*
225	* @param string $value
226	* @param string $cap
227	* @return string
228	*/
229	public static function finish($value, $cap)
230	{
231	$quoted = preg_quote($cap, '/');
232
233	return preg_replace('/(?:'.$quoted.')+$/u', '', $value).$cap;
234	}
235
236	/**
237	* Determine if a given string is a valid UUID.
238	*
239	* @param string $value
240	* @return bool
241	*/
242	public static function isUuid($value)
243	{
244	if (! is_string($value)) {
245	return false;
246	}
247
248	return preg_match('/^[\da-f]{8}-[\da-f]{4}-[\da-f]{4}-[\da-f]{4}-[\da-f]{12}$/iD', $value) > 0;
249	}
250
251	/**
252	* Convert a string to kebab case.
253	*
254	* @param string $value
255	* @return string
256	*/
257	public static function kebab($value)
258	{
259	return static::snake($value, '-');
260	}
261
262	/**
263	* Return the length of the given string.
264	*
265	* @param string $value
266	* @param string\|null $encoding
267	* @return int
268	*/
269	public static function length($value, $encoding = null)
270	{
271	if ($encoding) {
272	return mb_strlen($value, $encoding);
273	}
274
275	return mb_strlen($value);
276	}
277
278	/**
279	* Limit the number of characters in a string.
280	*
281	* @param string $value
282	* @param int $limit
283	* @param string $end
284	* @return string
285	*/
286	public static function limit($value, $limit = 100, $end = '...')
287	{
288	if (mb_strwidth($value, 'UTF-8') <= $limit) {
289	return $value;
290	}
291
292	return rtrim(mb_strimwidth($value, 0, $limit, '', 'UTF-8')).$end;
293	}
294
295	/**
296	* Convert the given string to lower-case.
297	*
298	* @param string $value
299	* @return string
300	*/
301	public static function lower($value)
302	{
303	return mb_strtolower($value, 'UTF-8');
304	}
305
306	/**
307	* Limit the number of words in a string.
308	*
309	* @param string $value
310	* @param int $words
311	* @param string $end
312	* @return string
313	*/
314	public static function words($value, $words = 100, $end = '...')
315	{
316	preg_match('/^\s+(?:\S++\s+){1,'.$words.'}/u', $value, $matches);
317
318	if (! isset($matches[0]) \|\| static::length($value) === static::length($matches[0])) {
319	return $value;
320	}
321
322	return rtrim($matches[0]).$end;
323	}
324
325	/**
326	* Masks a portion of a string with a repeated character.
327	*
328	* @param string $string
329	* @param string $character
330	* @param int $index
331	* @param int\|null $length
332	* @param string $encoding
333	* @return string
334	*/
335	public static function mask($string, $character, $index, $length = null, $encoding = 'UTF-8')
336	{
337	if ($character === '') {
338	return $string;
339	}
340
341	if (is_null($length) && PHP_MAJOR_VERSION < 8) {
342	$length = mb_strlen($string, $encoding);
343	}
344
345	$segment = mb_substr($string, $index, $length, $encoding);
346
347	if ($segment === '') {
348	return $string;
349	}
350
351	$start = mb_substr($string, 0, mb_strpos($string, $segment, 0, $encoding), $encoding);
352	$end = mb_substr($string, mb_strpos($string, $segment, 0, $encoding) + mb_strlen($segment, $encoding));
353
354	return $start.str_repeat(mb_substr($character, 0, 1, $encoding), mb_strlen($segment, $encoding)).$end;
355	}
356
357	/**
358	* Get the string matching the given pattern.
359	*
360	* @param string $pattern
361	* @param string $subject
362	* @return string
363	*/
364	public static function match($pattern, $subject)
365	{
366	preg_match($pattern, $subject, $matches);
367
368	if (! $matches) {
369	return '';
370	}
371
372	return isset($matches[1]) ? $matches[1] : $matches[0];
373	}
374
375	/**
376	* Pad both sides of a string with another.
377	*
378	* @param string $value
379	* @param int $length
380	* @param string $pad
381	* @return string
382	*/
383	public static function padBoth($value, $length, $pad = ' ')
384	{
385	return str_pad($value, $length, $pad, STR_PAD_BOTH);
386	}
387
388	/**
389	* Pad the left side of a string with another.
390	*
391	* @param string $value
392	* @param int $length
393	* @param string $pad
394	* @return string
395	*/
396	public static function padLeft($value, $length, $pad = ' ')
397	{
398	return str_pad($value, $length, $pad, STR_PAD_LEFT);
399	}
400
401	/**
402	* Pad the right side of a string with another.
403	*
404	* @param string $value
405	* @param int $length
406	* @param string $pad
407	* @return string
408	*/
409	public static function padRight($value, $length, $pad = ' ')
410	{
411	return str_pad($value, $length, $pad, STR_PAD_RIGHT);
412	}
413
414	/**
415	* Parse a Class[@]method style callback into class and method.
416	*
417	* @param string $callback
418	* @param string\|null $default
419	* @return array<int, string\|null>
420	*/
421	public static function parseCallback($callback, $default = null)
422	{
423	return static::contains($callback, '@') ? explode('@', $callback, 2) : [$callback, $default];
424	}
425
426	/**
427	* Generate a more truly "random" alpha-numeric string.
428	*
429	* @param int $length
430	* @return string
431	*/
432	public static function random($length = 16)
433	{
434	$string = '';
435
436	while (($len = strlen($string)) < $length) {
437	$size = $length - $len;
438
439	$bytes = random_bytes($size);
440
441	$string .= substr(str_replace(['/', '+', '='], '', base64_encode($bytes)), 0, $size);
442	}
443
444	return $string;
445	}
446
447	/**
448	* Repeat the given string.
449	*
450	* @param string $string
451	* @param int $times
452	* @return string
453	*/
454	public static function repeat($string, $times)
455	{
456	return str_repeat($string, $times);
457	}
458
459	/**
460	* Replace a given value in the string sequentially with an array.
461	*
462	* @param string $search
463	* @param array<int\|string, string> $replace
464	* @param string $subject
465	* @return string
466	*/
467	public static function replaceArray($search, array $replace, $subject)
468	{
469	$segments = explode($search, $subject);
470
471	$result = array_shift($segments);
472
473	foreach ($segments as $segment) {
474	$value = array_shift($replace);
475	$result .= ($value !== null ? $value : $search) . $segment;
476	}
477
478	return $result;
479	}
480
481	/**
482	* Replace the given value in the given string.
483	*
484	* @param string\|string[] $search
485	* @param string\|string[] $replace
486	* @param string\|string[] $subject
487	* @return string
488	*/
489	public static function replace($search, $replace, $subject)
490	{
491	return str_replace($search, $replace, $subject);
492	}
493
494	/**
495	* Replace the first occurrence of a given value in the string.
496	*
497	* @param string $search
498	* @param string $replace
499	* @param string $subject
500	* @return string
501	*/
502	public static function replaceFirst($search, $replace, $subject)
503	{
504	$search = (string) $search;
505
506	if ($search === '') {
507	return $subject;
508	}
509
510	$position = strpos($subject, $search);
511
512	if ($position !== false) {
513	return substr_replace($subject, $replace, $position, strlen($search));
514	}
515
516	return $subject;
517	}
518
519	/**
520	* Replace the last occurrence of a given value in the string.
521	*
522	* @param string $search
523	* @param string $replace
524	* @param string $subject
525	* @return string
526	*/
527	public static function replaceLast($search, $replace, $subject)
528	{
529	if ($search === '') {
530	return $subject;
531	}
532
533	$position = strrpos($subject, $search);
534
535	if ($position !== false) {
536	return substr_replace($subject, $replace, $position, strlen($search));
537	}
538
539	return $subject;
540	}
541
542	/**
543	* Remove any occurrence of the given string in the subject.
544	*
545	* @param string\|array<string> $search
546	* @param string $subject
547	* @param bool $caseSensitive
548	* @return string
549	*/
550	public static function remove($search, $subject, $caseSensitive = true)
551	{
552	return $caseSensitive
553	? str_replace($search, '', $subject)
554	: str_ireplace($search, '', $subject);
555	}
556
557	/**
558	* Reverse the given string.
559	*
560	* @param string $value
561	* @return string
562	*/
563	public static function reverse($value)
564	{
565	// phpcs:ignore PHPCompatibility.FunctionUse.NewFunctions.mb_str_splitFound
566	return implode(array_reverse(mb_str_split($value)));
567	}
568
569	/**
570	* Begin a string with a single instance of a given value.
571	*
572	* @param string $value
573	* @param string $prefix
574	* @return string
575	*/
576	public static function start($value, $prefix)
577	{
578	$quoted = preg_quote($prefix, '/');
579
580	return $prefix.preg_replace('/^(?:'.$quoted.')+/u', '', $value);
581	}
582
583	/**
584	* Convert the given string to upper-case.
585	*
586	* @param string $value
587	* @return string
588	*/
589	public static function upper($value)
590	{
591	return mb_strtoupper($value, 'UTF-8');
592	}
593
594	/**
595	* Convert the given string to title case.
596	*
597	* @param string $value
598	* @return string
599	*/
600	public static function title($value)
601	{
602	return mb_convert_case($value, MB_CASE_TITLE, 'UTF-8');
603	}
604
605	/**
606	* Convert the given string to title case for each word.
607	*
608	* @param string $value
609	* @return string
610	*/
611	public static function headline($value)
612	{
613	$parts = explode(' ', $value);
614
615	$parts = count($parts) > 1
616	? array_map([static::class, 'title'], $parts)
617	: array_map([static::class, 'title'], static::ucsplit(implode('_', $parts)));
618
619	$collapsed = static::replace(['-', '_', ' '], '_', implode('_', $parts));
620
621	return implode(' ', array_filter(explode('_', $collapsed)));
622	}
623
624	/**
625	* Generate a URL friendly "slug" from a given string.
626	*
627	* @param string $title
628	* @param string $fallback_title
629	* @param string $context
630	*
631	* @return string
632	*/
633	public static function slug($title, $fallback_title = '', $context = 'save')
634	{
635	return sanitize_title($title, $fallback_title, $context);
636	}
637
638	/**
639	* Convert a string to snake case.
640	*
641	* @param string $value
642	* @param string $delimiter
643	* @return string
644	*/
645	public static function snake($value, $delimiter = '_')
646	{
647	$key = $value;
648
649	if (isset(static::$snakeCache[$key][$delimiter])) {
650	return static::$snakeCache[$key][$delimiter];
651	}
652
653	if (! ctype_lower($value)) {
654	$value = preg_replace('/\s+/u', '', ucwords($value));
655
656	$value = static::lower(preg_replace('/(.)(?=[A-Z])/u', '$1'.$delimiter, $value));
657	}
658
659	return static::$snakeCache[$key][$delimiter] = $value;
660	}
661
662	/**
663	* Determine if a given string starts with a given substring.
664	*
665	* @param string $haystack
666	* @param string\|string[] $needles
667	* @return bool
668	*/
669	public static function startsWith($haystack, $needles)
670	{
671	foreach ((array) $needles as $needle) {
672	if ((string) $needle !== '' && str_starts_with($haystack, $needle)) {
673	return true;
674	}
675	}
676
677	return false;
678	}
679
680	/**
681	* Convert a value to studly caps case.
682	*
683	* @param string $value
684	* @return string
685	*/
686	public static function studly($value)
687	{
688	$key = $value;
689
690	if (isset(static::$studlyCache[$key])) {
691	return static::$studlyCache[$key];
692	}
693
694	$words = explode(' ', static::replace(['-', '_'], ' ', $value));
695
696	$studlyWords = array_map(static function ($word) {
697	return static::ucfirst($word);
698	}, $words);
699
700	return static::$studlyCache[$key] = implode($studlyWords);
701	}
702
703	/**
704	* Returns the portion of the string specified by the start and length parameters.
705	*
706	* @param string $string
707	* @param int $start
708	* @param int\|null $length
709	* @return string
710	*/
711	public static function substr($string, $start, $length = null)
712	{
713	return mb_substr($string, $start, $length, 'UTF-8');
714	}
715
716	/**
717	* Returns the number of substring occurrences.
718	*
719	* @param string $haystack
720	* @param string $needle
721	* @param int $offset
722	* @param int\|null $length
723	* @return int
724	*/
725	public static function substrCount($haystack, $needle, $offset = 0, $length = null)
726	{
727	if (! is_null($length)) {
728	return substr_count($haystack, $needle, $offset, $length);
729	}
730
731	return substr_count($haystack, $needle, $offset);
732	}
733
734	/**
735	* Replace text within a portion of a string.
736	*
737	* @param string\|array $string
738	* @param string\|array $replace
739	* @param array\|int $offset
740	* @param array\|int\|null $length
741	* @return string\|array
742	*/
743	public static function substrReplace($string, $replace, $offset = 0, $length = null)
744	{
745	if ($length === null) {
746	$length = strlen($string);
747	}
748
749	return substr_replace($string, $replace, $offset, $length);
750	}
751
752	/**
753	* Swap multiple keywords in a string with other keywords.
754	*
755	* @param array $map
756	* @param string $subject
757	* @return string
758	*/
759	public static function swap(array $map, $subject)
760	{
761	return strtr($subject, $map);
762	}
763
764	/**
765	* Make a string's first character lowercase.
766	*
767	* @param string $string
768	* @return string
769	*/
770	public static function lcfirst($string)
771	{
772	return static::lower(static::substr($string, 0, 1)).static::substr($string, 1);
773	}
774
775	/**
776	* Make a string's first character uppercase.
777	*
778	* @param string $string
779	* @return string
780	*/
781	public static function ucfirst($string)
782	{
783	return static::upper(static::substr($string, 0, 1)).static::substr($string, 1);
784	}
785
786	/**
787	* Split a string into pieces by uppercase characters.
788	*
789	* @param string $string
790	* @return array
791	*/
792	public static function ucsplit($string)
793	{
794	return preg_split('/(?=\p{Lu})/u', $string, -1, PREG_SPLIT_NO_EMPTY);
795	}
796
797	/**
798	* Get the number of words a string contains.
799	*
800	* @param string $string
801	* @return int
802	*/
803	public static function wordCount($string)
804	{
805	return str_word_count($string);
806	}
807
808	/**
809	* Remove all strings from the casing caches.
810	*
811	* @return void
812	*/
813	public static function flushCache()
814	{
815	static::$snakeCache = [];
816	static::$camelCache = [];
817	static::$studlyCache = [];
818	}
819	}
820