fluent-cart / vendor / wpfluent / framework / src / WPFluent / Support / Stringable.php

Stringable.php in FluentCart A New Era of eCommerce – Faster, Lighter, and Simpler 1.6.4, at vendor/wpfluent/framework/src/WPFluent/Support/Stringable.php

1,352 lines 31.0 KB

Raw Download Zip

1	<?php
2
3	namespace FluentCart\Framework\Support;
4
5	use Closure;
6	use ArrayAccess;
7	use JsonSerializable;
8	use FluentCart\Framework\Support\DateTime;
9	use FluentCart\Framework\Support\Tappable;
10	use FluentCart\Framework\Support\Conditionable;
11	use FluentCart\Framework\Support\MacroableTrait;
12	use FluentCart\Framework\Support\HelperFunctionsTrait;
13
14	class Stringable implements JsonSerializable
15	{
16	use Tappable, Conditionable, MacroableTrait, HelperFunctionsTrait;
17
18	/**
19	* The underlying string value.
20	*
21	* @var string
22	*/
23	protected $value;
24
25	/**
26	* Create a new instance of the class.
27	*
28	* @param string $value
29	* @return void
30	*/
31	public function __construct($value = '')
32	{
33	$this->value = (string) $value;
34	}
35
36	/**
37	* Makes an acronym from a string of words
38	*
39	* @param string $delimiter
40	* @return self
41	*/
42	public function acronym(string $delimiter = '')
43	{
44	return new static(Str::acronym($this->value, $delimiter));
45	}
46
47	/**
48	* Return the remainder of a string after the first occurrence of a given value.
49	*
50	* @param string $search
51	* @return static
52	*/
53	public function after($search)
54	{
55	return new static(Str::after($this->value, $search));
56	}
57
58	/**
59	* Return the remainder of a string after the last occurrence of a given value.
60	*
61	* @param string $search
62	* @return static
63	*/
64	public function afterLast($search)
65	{
66	return new static(Str::afterLast($this->value, $search));
67	}
68
69	/**
70	* Append the given values to the string.
71	*
72	* @param array\|string ...$values
73	* @return static
74	*/
75	public function append(...$values)
76	{
77	return new static($this->value.implode('', $values));
78	}
79
80	/**
81	* Append a new line to the string.
82	*
83	* @param int $count
84	* @return $this
85	*/
86	public function newLine($count = 1)
87	{
88	return $this->append(str_repeat(PHP_EOL, $count));
89	}
90
91	/**
92	* Transliterate a UTF-8 value to ASCII.
93	*
94	* @return static
95	*/
96	public function ascii()
97	{
98	return new static(Str::ascii($this->value));
99	}
100
101	/**
102	* Checks if the word(s) are in capitalized form.
103	*
104	* @param boolean $onlyFirst if true, checks only the first charatcer
105	* @return boolean
106	*/
107	public function isCapitalized($onlyFirst = false)
108	{
109	return Str::isCapitalized($this->value, $onlyFirst);
110	}
111
112	/**
113	* Checks if the first character is in capital form.
114	*
115	* @return boolean
116	*/
117	public function isCapital()
118	{
119	return $this->isCapitalized(true);
120	}
121
122	/**
123	* Checks if the chracters are in upper case
124	*
125	* @return boolean
126	*/
127	public function isUpper()
128	{
129	return Str::isUpper($this->value);
130	}
131
132	/**
133	* Checks if the chracters are in lower case
134	*
135	* @return boolean
136	*/
137	public function isLower()
138	{
139	return Str::isLower($this->value);
140	}
141
142	/**
143	* Checks if two words sounds alike
144	*
145	* @param string $str
146	*
147	* @return bool
148	*/
149	public function soundsAlike($str)
150	{
151	return Str::soundsAlike($this->value, $str);
152	}
153
154	/**
155	* Checks if two words are similar
156	*
157	* @param string $str
158	* @param int $accuracy
159	*
160	* @return bool
161	*/
162	public function isSimilar($str, $accuracy = 60)
163	{
164	return Str::isSimilar($this->value, $str, $accuracy);
165	}
166
167	/**
168	* Gets the similarity of two words as a percentage.
169	*
170	* @param string $str
171	*
172	* @return float
173	*/
174	public function similarityOf($str)
175	{
176	return Str::similarityOf($this->value, $str);
177	}
178
179	/**
180	* Get the trailing name component of the path.
181	*
182	* @param string $suffix
183	* @return static
184	*/
185	public function basename($suffix = '')
186	{
187	return new static(basename($this->value, $suffix));
188	}
189
190	/**
191	* Get the character at the specified index.
192	*
193	* @param int $index
194	* @return string\|false
195	*/
196	public function charAt($index)
197	{
198	return Str::charAt($this->value, $index);
199	}
200
201	/**
202	* Get the basename of the class path.
203	*
204	* @return static
205	*/
206	public function classBasename()
207	{
208	$class = $this->value;
209	$class = is_object($class) ? get_class($class) : $class;
210	return new static(basename(str_replace('\\', '/', $class)));
211	}
212
213	/**
214	* Get the portion of a string before the first occurrence of a given value.
215	*
216	* @param string $search
217	* @return static
218	*/
219	public function before($search)
220	{
221	return new static(Str::before($this->value, $search));
222	}
223
224	/**
225	* Get the portion of a string before the last occurrence of a given value.
226	*
227	* @param string $search
228	* @return static
229	*/
230	public function beforeLast($search)
231	{
232	return new static(Str::beforeLast($this->value, $search));
233	}
234
235	/**
236	* Get the portion of a string between two given values.
237	*
238	* @param string $from
239	* @param string $to
240	* @return static
241	*/
242	public function between($from, $to)
243	{
244	return new static(Str::between($this->value, $from, $to));
245	}
246
247	/**
248	* Get the smallest possible portion of a string between two given values.
249	*
250	* @param string $from
251	* @param string $to
252	* @return static
253	*/
254	public function betweenFirst($from, $to)
255	{
256	return new static(Str::betweenFirst($this->value, $from, $to));
257	}
258
259	/**
260	* Convert a value to camel case.
261	*
262	* @return static
263	*/
264	public function camel()
265	{
266	return new static(Str::camel($this->value));
267	}
268
269	/**
270	* Determine if a given string contains a given substring.
271	*
272	* @param string\|iterable<string> $needles
273	* @param bool $ignoreCase
274	* @return bool
275	*/
276	public function contains($needles, $ignoreCase = false)
277	{
278	return Str::contains($this->value, $needles, $ignoreCase);
279	}
280
281	/**
282	* Determine if a given string contains all array values.
283	*
284	* @param iterable<string> $needles
285	* @param bool $ignoreCase
286	* @return bool
287	*/
288	public function containsAll($needles, $ignoreCase = false)
289	{
290	return Str::containsAll($this->value, $needles, $ignoreCase);
291	}
292
293	/**
294	* Replace consecutive instances of a given character with a single character.
295	*
296	* @param string $character
297	* @return static
298	*/
299	public function deduplicate(string $character = ' ')
300	{
301	return new static(Str::deduplicate($this->value, $character));
302	}
303
304	/**
305	* Get the parent directory's path.
306	*
307	* @param int $levels
308	* @return static
309	*/
310	public function dirname($levels = 1)
311	{
312	return new static(dirname($this->value, $levels));
313	}
314
315	/**
316	* Determine if a given string ends with a given substring.
317	*
318	* @param string\|iterable<string> $needles
319	* @return bool
320	*/
321	public function endsWith($needles)
322	{
323	return Str::endsWith($this->value, $needles);
324	}
325
326	/**
327	* Determine if the string is an exact match with the given value.
328	*
329	* @param \FluentCart\Framework\Support\Stringable\|string $value
330	* @return bool
331	*/
332	public function exactly($value)
333	{
334	if ($value instanceof Stringable) {
335	$value = $value->toString();
336	}
337
338	return $this->value === $value;
339	}
340
341	/**
342	* Explode the string into an array.
343	*
344	* @param string $delimiter
345	* @param int $limit
346	* @return \FluentCart\Framework\Support\Collection<int, string>
347	*/
348	public function explode($delimiter, $limit = PHP_INT_MAX)
349	{
350	return Helper::collect(explode($delimiter, $this->value, $limit));
351	}
352
353	/**
354	* Split a string using a regular expression or by length.
355	*
356	* @param string\|int $pattern
357	* @param int $limit
358	* @param int $flags
359	* @return \FluentCart\Framework\Support\Collection<int, string>
360	*/
361	public function split($pattern, $limit = -1, $flags = 0)
362	{
363	if (filter_var($pattern, FILTER_VALIDATE_INT) !== false) {
364	return Helper::collect(mb_str_split($this->value, $pattern));
365	}
366
367	$segments = preg_split($pattern, $this->value, $limit, $flags);
368
369	return ! empty($segments) ? Helper::collect($segments) : Helper::collect();
370	}
371
372	/**
373	* Cap a string with a single instance of a given value.
374	*
375	* @param string $cap
376	* @return static
377	*/
378	public function finish($cap)
379	{
380	return new static(Str::finish($this->value, $cap));
381	}
382
383	/**
384	* Determine if a given string matches a given pattern.
385	*
386	* @param string\|iterable<string> $pattern
387	* @return bool
388	*/
389	public function is($pattern)
390	{
391	return Str::is($pattern, $this->value);
392	}
393
394	/**
395	* Determine if a given string is 7 bit ASCII.
396	*
397	* @return bool
398	*/
399	public function isAscii()
400	{
401	return Str::isAscii($this->value);
402	}
403
404	/**
405	* Determine if a given string is valid JSON.
406	*
407	* @return bool
408	*/
409	public function isJson()
410	{
411	return Str::isJson($this->value);
412	}
413
414	/**
415	* Determine if a given value is a valid URL.
416	*
417	* @return bool
418	*/
419	public function isUrl()
420	{
421	return Str::isUrl($this->value);
422	}
423
424	/**
425	* Determine if a given string is a valid UUID.
426	*
427	* @param int\|null $version Optional UUID version (e.g. 4 or 7) to
428	* require; null accepts any version.
429	* @return bool
430	*/
431	public function isUuid($version = null)
432	{
433	return Str::isUuid($this->value, $version);
434	}
435
436	/**
437	* Determine if the given string is empty.
438	*
439	* @return bool
440	*/
441	public function isEmpty()
442	{
443	return $this->value === '';
444	}
445
446	/**
447	* Determine if the given string is not empty.
448	*
449	* @return bool
450	*/
451	public function isNotEmpty()
452	{
453	return ! $this->isEmpty();
454	}
455
456	/**
457	* Convert a string to kebab case.
458	*
459	* @return static
460	*/
461	public function kebab()
462	{
463	return new static(Str::kebab($this->value));
464	}
465
466	/**
467	* Return the length of the given string.
468	*
469	* @param string\|null $encoding
470	* @return int
471	*/
472	public function length($encoding = null)
473	{
474	return Str::length($this->value, $encoding);
475	}
476
477	/**
478	* Limit the number of characters in a string.
479	*
480	* @param int $limit
481	* @param string $end
482	* @return static
483	*/
484	public function limit($limit = 100, $end = '...')
485	{
486	return new static(Str::limit($this->value, $limit, $end));
487	}
488
489	/**
490	* Convert the given string to lower-case.
491	*
492	* @return static
493	*/
494	public function lower()
495	{
496	return new static(Str::lower($this->value));
497	}
498
499	/**
500	* Masks a portion of a string with a repeated character.
501	*
502	* @param string $character
503	* @param int $index
504	* @param int\|null $length
505	* @param string $encoding
506	* @return static
507	*/
508	public function mask($character, $index, $length = null, $encoding = 'UTF-8')
509	{
510	return new static(Str::mask($this->value, $character, $index, $length, $encoding));
511	}
512
513	/**
514	* Get the string matching the given pattern.
515	*
516	* @param string $pattern
517	* @return static
518	*/
519	public function match($pattern)
520	{
521	return new static(Str::match($pattern, $this->value));
522	}
523
524	/**
525	* Determine if a given string matches a given pattern.
526	*
527	* @param string\|iterable<string> $pattern
528	* @return bool
529	*/
530	public function isMatch($pattern)
531	{
532	return Str::isMatch($pattern, $this->value);
533	}
534
535	/**
536	* Get the string matching the given pattern.
537	*
538	* @param string $pattern
539	* @return \FluentCart\Framework\Support\Collection
540	*/
541	public function matchAll($pattern)
542	{
543	return Str::matchAll($pattern, $this->value);
544	}
545
546	/**
547	* Determine if the string matches the given pattern.
548	*
549	* @param string $pattern
550	* @return bool
551	*/
552	public function test($pattern)
553	{
554	return $this->isMatch($pattern);
555	}
556
557	/**
558	* Pad both sides of the string with another.
559	*
560	* @param int $length
561	* @param string $pad
562	* @return static
563	*/
564	public function padBoth($length, $pad = ' ')
565	{
566	return new static(Str::padBoth($this->value, $length, $pad));
567	}
568
569	/**
570	* Pad the left side of the string with another.
571	*
572	* @param int $length
573	* @param string $pad
574	* @return static
575	*/
576	public function padLeft($length, $pad = ' ')
577	{
578	return new static(Str::padLeft($this->value, $length, $pad));
579	}
580
581	/**
582	* Pad the right side of the string with another.
583	*
584	* @param int $length
585	* @param string $pad
586	* @return static
587	*/
588	public function padRight($length, $pad = ' ')
589	{
590	return new static(Str::padRight($this->value, $length, $pad));
591	}
592
593	/**
594	* Parse a Class@method style callback into class and method.
595	*
596	* @param string\|null $default
597	* @return array<int, string\|null>
598	*/
599	public function parseCallback($default = null)
600	{
601	return Str::parseCallback($this->value, $default);
602	}
603
604	/**
605	* Parse an integer from a string.
606	*
607	* @param string $value
608	* @return int\|null
609	*/
610	public function parseInt($value)
611	{
612	return Str::parseInt($value);
613	}
614
615	/**
616	* Parse a floasting point number from a string.
617	*
618	* @param string $value
619	* @return float\|null
620	*/
621	public function parseFloat($value)
622	{
623	return Str::parseFloat($value);
624	}
625
626	/**
627	* Remove all non-numeric characters from a string.
628	*
629	* @param string $value
630	* @return string
631	*/
632	public function parseNumber($value)
633	{
634	return Str::parseNumber($value);
635	}
636
637	/**
638	* Call the given callback and return a new string.
639	*
640	* @param callable $callback
641	* @return static
642	*/
643	public function pipe(callable $callback)
644	{
645	return new static($callback($this));
646	}
647
648	/**
649	* Get the plural form of an English word.
650	*
651	* @param int\|array\|\Countable $count
652	* @return static
653	*/
654	public function plural($count = 2)
655	{
656	return new static(Str::plural($this->value, $count));
657	}
658
659	/**
660	* Pluralize the last word of an English, studly caps case string.
661	*
662	* @param int\|array\|\Countable $count
663	* @return static
664	*/
665	public function pluralStudly($count = 2)
666	{
667	return new static(Str::pluralStudly($this->value, $count));
668	}
669
670	/**
671	* Prepend the given values to the string.
672	*
673	* @param string ...$values
674	* @return static
675	*/
676	public function prepend(...$values)
677	{
678	return new static(implode('', $values).$this->value);
679	}
680
681	/**
682	* Remove any occurrence of the given string in the subject.
683	*
684	* @param string\|iterable<string> $search
685	* @param bool $caseSensitive
686	* @return static
687	*/
688	public function remove($search, $caseSensitive = true)
689	{
690	return new static(Str::remove($search, $this->value, $caseSensitive));
691	}
692
693	/**
694	* Reverse the string.
695	*
696	* @return static
697	*/
698	public function reverse()
699	{
700	return new static(Str::reverse($this->value));
701	}
702
703	/**
704	* Repeat the string.
705	*
706	* @param int $times
707	* @return static
708	*/
709	public function repeat(int $times)
710	{
711	return new static(str_repeat($this->value, $times));
712	}
713
714	/**
715	* Replace the given value in the given string.
716	*
717	* @param string\|iterable<string> $search
718	* @param string\|iterable<string> $replace
719	* @param bool $caseSensitive
720	* @return static
721	*/
722	public function replace($search, $replace, $caseSensitive = true)
723	{
724	return new static(Str::replace($search, $replace, $this->value, $caseSensitive));
725	}
726
727	/**
728	* Replace a given value in the string sequentially with an array.
729	*
730	* @param string $search
731	* @param iterable<string> $replace
732	* @return static
733	*/
734	public function replaceArray($search, $replace)
735	{
736	return new static(Str::replaceArray($search, $replace, $this->value));
737	}
738
739	/**
740	* Replace the first occurrence of a given value in the string.
741	*
742	* @param string $search
743	* @param string $replace
744	* @return static
745	*/
746	public function replaceFirst($search, $replace)
747	{
748	return new static(Str::replaceFirst($search, $replace, $this->value));
749	}
750
751	/**
752	* Replace the last occurrence of a given value in the string.
753	*
754	* @param string $search
755	* @param string $replace
756	* @return static
757	*/
758	public function replaceLast($search, $replace)
759	{
760	return new static(Str::replaceLast($search, $replace, $this->value));
761	}
762
763	/**
764	* Replace the patterns matching the given regular expression.
765	*
766	* @param string $pattern
767	* @param \Closure\|string $replace
768	* @param int $limit
769	* @return static
770	*/
771	public function replaceMatches($pattern, $replace, $limit = -1)
772	{
773	if ($replace instanceof Closure) {
774	return new static(preg_replace_callback($pattern, $replace, $this->value, $limit));
775	}
776
777	return new static(preg_replace($pattern, $replace, $this->value, $limit));
778	}
779
780	/**
781	* Parse input from a string to a collection, according to a format.
782	*
783	* @param string $format
784	* @return \FluentCart\Framework\Support\Collection
785	*/
786	public function scan($format)
787	{
788	return Helper::collect(sscanf($this->value, $format));
789	}
790
791	/**
792	* Remove all "extra" blank space from the given string.
793	*
794	* @return static
795	*/
796	public function squish()
797	{
798	return new static(Str::squish($this->value));
799	}
800
801	/**
802	* Begin a string with a single instance of a given value.
803	*
804	* @param string $prefix
805	* @return static
806	*/
807	public function start($prefix)
808	{
809	return new static(Str::start($this->value, $prefix));
810	}
811
812	/**
813	* Strip HTML and PHP tags from the given string.
814	*
815	* @param string $allowedTags
816	* @return static
817	*/
818	public function stripTags($allowedTags = null)
819	{
820	return new static(strip_tags($this->value, $allowedTags));
821	}
822
823	/**
824	* Convert the given string to upper-case.
825	*
826	* @return static
827	*/
828	public function upper()
829	{
830	return new static(Str::upper($this->value));
831	}
832
833	/**
834	* Convert the given string to title case.
835	*
836	* @return static
837	*/
838	public function title()
839	{
840	return new static(Str::title($this->value));
841	}
842
843	/**
844	* Convert the given string to title case for each word.
845	*
846	* @return static
847	*/
848	public function headline()
849	{
850	return new static(Str::headline($this->value));
851	}
852
853	/**
854	* Get the singular form of an English word.
855	*
856	* @return static
857	*/
858	public function singular()
859	{
860	return new static(Str::singular($this->value));
861	}
862
863	/**
864	* Generate a URL friendly "slug" from a given string.
865	*
866	* @param string $fallbackTitle
867	* @param string $context
868	* @return static
869	*/
870	public function slug($fallbackTitle = '', $context = 'save')
871	{
872	return new static(
873	Str::slug($this->value, $fallbackTitle, $context)
874	);
875	}
876
877	/**
878	* Convert a string to snake case.
879	*
880	* @param string $delimiter
881	* @return static
882	*/
883	public function snake($delimiter = '_')
884	{
885	return new static(Str::snake($this->value, $delimiter));
886	}
887
888	/**
889	* Determine if a given string starts with a given substring.
890	*
891	* @param string\|iterable<string> $needles
892	* @return bool
893	*/
894	public function startsWith($needles)
895	{
896	return Str::startsWith($this->value, $needles);
897	}
898
899	/**
900	* Convert a value to studly caps case.
901	*
902	* @return static
903	*/
904	public function studly()
905	{
906	return new static(Str::studly($this->value));
907	}
908
909	/**
910	* Returns the portion of the string specified by the start and length parameters.
911	*
912	* @param int $start
913	* @param int\|null $length
914	* @return static
915	*/
916	public function substr(int $start, ?int $length = null)
917	{
918	return new static(Str::substr($this->value, $start, $length));
919	}
920
921	/**
922	* Returns the number of substring occurrences.
923	*
924	* @param string $needle
925	* @param int $offset
926	* @param int\|null $length
927	* @return int
928	*/
929	public function substrCount($needle, $offset = 0, $length = null)
930	{
931	return Str::substrCount($this->value, $needle, $offset, $length);
932	}
933
934	/**
935	* Replace text within a portion of a string.
936	*
937	* @param string\|string[] $replace
938	* @param int\|int[] $offset
939	* @param int\|int[]\|null $length
940	* @return static
941	*/
942	public function substrReplace($replace, $offset = 0, $length = null)
943	{
944	return new static(Str::substrReplace($this->value, $replace, $offset, $length));
945	}
946
947	/**
948	* Swap multiple keywords in a string with other keywords.
949	*
950	* @param array $map
951	* @return static
952	*/
953	public function swap(array $map)
954	{
955	return new static(strtr($this->value, $map));
956	}
957
958	/**
959	* Trim the string of the given characters.
960	*
961	* @param string $characters
962	* @return static
963	*/
964	public function trim($characters = null)
965	{
966	return new static(trim(...array_merge([$this->value], func_get_args())));
967	}
968
969	/**
970	* Left trim the string of the given characters.
971	*
972	* @param string $characters
973	* @return static
974	*/
975	public function ltrim($characters = null)
976	{
977	return new static(ltrim(...array_merge([$this->value], func_get_args())));
978	}
979
980	/**
981	* Right trim the string of the given characters.
982	*
983	* @param string $characters
984	* @return static
985	*/
986	public function rtrim($characters = null)
987	{
988	return new static(rtrim(...array_merge([$this->value], func_get_args())));
989	}
990
991	/**
992	* Make a string's first character lowercase.
993	*
994	* @return static
995	*/
996	public function lcfirst()
997	{
998	return new static(Str::lcfirst($this->value));
999	}
1000
1001	/**
1002	* Make a string's first character uppercase.
1003	*
1004	* @return static
1005	*/
1006	public function ucfirst()
1007	{
1008	return new static(Str::ucfirst($this->value));
1009	}
1010
1011	/**
1012	* Split a string by uppercase characters.
1013	*
1014	* @return \FluentCart\Framework\Support\Collection<int, string>
1015	*/
1016	public function ucsplit()
1017	{
1018	return Helper::collect(Str::ucsplit($this->value));
1019	}
1020
1021	/**
1022	* Execute the given callback if the string contains a given substring.
1023	*
1024	* @param string\|iterable<string> $needles
1025	* @param callable $callback
1026	* @param callable\|null $default
1027	* @return static
1028	*/
1029	public function whenContains($needles, $callback, $default = null)
1030	{
1031	return $this->when($this->contains($needles), $callback, $default);
1032	}
1033
1034	/**
1035	* Execute the given callback if the string contains all array values.
1036	*
1037	* @param array $needles
1038	* @param callable $callback
1039	* @param callable\|null $default
1040	* @return static
1041	*/
1042	public function whenContainsAll(array $needles, $callback, $default = null)
1043	{
1044	return $this->when($this->containsAll($needles), $callback, $default);
1045	}
1046
1047	/**
1048	* Execute the given callback if the string is empty.
1049	*
1050	* @param callable $callback
1051	* @param callable\|null $default
1052	* @return static
1053	*/
1054	public function whenEmpty($callback, $default = null)
1055	{
1056	return $this->when($this->isEmpty(), $callback, $default);
1057	}
1058
1059	/**
1060	* Execute the given callback if the string is not empty.
1061	*
1062	* @param callable $callback
1063	* @param callable\|null $default
1064	* @return static
1065	*/
1066	public function whenNotEmpty($callback, $default = null)
1067	{
1068	return $this->when($this->isNotEmpty(), $callback, $default);
1069	}
1070
1071	/**
1072	* Execute the given callback if the string ends with a given substring.
1073	*
1074	* @param string\|iterable<string> $needles
1075	* @param callable $callback
1076	* @param callable\|null $default
1077	* @return static
1078	*/
1079	public function whenEndsWith($needles, $callback, $default = null)
1080	{
1081	return $this->when(
1082	$this->endsWith($needles), $callback, $default
1083	);
1084	}
1085
1086	/**
1087	* Execute the given callback if the string is an exact match with the given value.
1088	*
1089	* @param string $value
1090	* @param callable $callback
1091	* @param callable\|null $default
1092	* @return static
1093	*/
1094	public function whenExactly($value, $callback, $default = null)
1095	{
1096	return $this->when($this->exactly($value), $callback, $default);
1097	}
1098
1099	/**
1100	* Execute the given callback if the string is not an exact match with the given value.
1101	*
1102	* @param string $value
1103	* @param callable $callback
1104	* @param callable\|null $default
1105	* @return static
1106	*/
1107	public function whenNotExactly($value, $callback, $default = null)
1108	{
1109	return $this->when(! $this->exactly($value), $callback, $default);
1110	}
1111
1112	/**
1113	* Execute the given callback if the string matches a given pattern.
1114	*
1115	* @param string\|iterable<string> $pattern
1116	* @param callable $callback
1117	* @param callable\|null $default
1118	* @return static
1119	*/
1120	public function whenIs($pattern, $callback, $default = null)
1121	{
1122	return $this->when($this->is($pattern), $callback, $default);
1123	}
1124
1125	/**
1126	* Execute the given callback if the string is 7 bit ASCII.
1127	*
1128	* @param callable $callback
1129	* @param callable\|null $default
1130	* @return static
1131	*/
1132	public function whenIsAscii($callback, $default = null)
1133	{
1134	return $this->when($this->isAscii(), $callback, $default);
1135	}
1136
1137	/**
1138	* Execute the given callback if the string is a valid UUID.
1139	*
1140	* @param callable $callback
1141	* @param callable\|null $default
1142	* @return static
1143	*/
1144	public function whenIsUuid($callback, $default = null)
1145	{
1146	return $this->when($this->isUuid(), $callback, $default);
1147	}
1148
1149	/**
1150	* Execute the given callback if the string starts with a given substring.
1151	*
1152	* @param string\|string[] $needles
1153	* @param callable $callback
1154	* @param callable\|null $default
1155	* @return static
1156	*/
1157	public function whenStartsWith($needles, $callback, $default = null)
1158	{
1159	return $this->when(
1160	$this->startsWith($needles), $callback, $default
1161	);
1162	}
1163
1164	/**
1165	* Execute the given callback if the string matches the given pattern.
1166	*
1167	* @param string $pattern
1168	* @param callable $callback
1169	* @param callable\|null $default
1170	* @return static
1171	*/
1172	public function whenTest($pattern, $callback, $default = null)
1173	{
1174	return $this->when($this->test($pattern), $callback, $default);
1175	}
1176
1177	/**
1178	* Limit the number of words in a string.
1179	*
1180	* @param int $words
1181	* @param string $end
1182	* @return static
1183	*/
1184	public function words($words = 100, $end = '...')
1185	{
1186	return new static(Str::words($this->value, $words, $end));
1187	}
1188
1189	/**
1190	* Get the number of words a string contains.
1191	*
1192	* @return int
1193	*/
1194	public function wordCount()
1195	{
1196	return Str::wordCount($this->value);
1197	}
1198
1199	/**
1200	* Wrap a string to a given number of characters.
1201	*
1202	* @param int $characters
1203	* @param string $break
1204	* @param bool $cutLongWords
1205	* @return static
1206	*/
1207	public function wordWrap($characters = 75, $break = "\n", $cutLongWords = false)
1208	{
1209	return new static(Str::wordWrap($this->value, $characters, $break, $cutLongWords));
1210	}
1211
1212	/**
1213	* Wrap the string with the given strings.
1214	*
1215	* @param string $before
1216	* @param string\|null $after
1217	* @return static
1218	*/
1219	public function wrap($before, $after = null)
1220	{
1221	return new static(Str::wrap($this->value, $before, $after));
1222	}
1223
1224	/**
1225	* Dump the string.
1226	*
1227	* @return $this
1228	*/
1229	public function dump()
1230	{
1231	echo "<pre>";
1232	print_r($this->value);
1233	echo "</pre>";
1234
1235	return $this;
1236	}
1237
1238	/**
1239	* Dump the string and end the script.
1240	*
1241	* @return never
1242	*/
1243	public function dd()
1244	{
1245	$this->dump();
1246
1247	exit(1);
1248	}
1249
1250	/**
1251	* Get the underlying string value.
1252	*
1253	* @return string
1254	*/
1255	public function value()
1256	{
1257	return $this->toString();
1258	}
1259
1260	/**
1261	* Get the underlying string value.
1262	*
1263	* @return string
1264	*/
1265	public function toString()
1266	{
1267	return $this->value;
1268	}
1269
1270	/**
1271	* Get the underlying string value as an integer.
1272	*
1273	* @return int
1274	*/
1275	public function toInteger()
1276	{
1277	return intval($this->value);
1278	}
1279
1280	/**
1281	* Get the underlying string value as a float.
1282	*
1283	* @return float
1284	*/
1285	public function toFloat()
1286	{
1287	return floatval($this->value);
1288	}
1289
1290	/**
1291	* Get the underlying string value as a boolean.
1292	*
1293	* Returns true when value is "1", "true", "on", and "yes". Otherwise, returns false.
1294	*
1295	* @return bool
1296	*/
1297	public function toBoolean()
1298	{
1299	return filter_var($this->value, FILTER_VALIDATE_BOOLEAN);
1300	}
1301
1302	/**
1303	* Get the underlying string value as a Carbon instance.
1304	*
1305	* @param string\|null $format
1306	* @param string\|null $tz
1307	* @return \FluentCart\Framework\Support\DateTime
1308	*
1309	* @throws \InvalidArgumentException
1310	*/
1311	public function toDate($format = null, $tz = null)
1312	{
1313	if (is_null($format)) {
1314	return DateTime::parse($this->value, $tz);
1315	}
1316
1317	return DateTime::createFromFormat($format, $this->value, $tz);
1318	}
1319
1320	/**
1321	* Convert the object to a string when JSON encoded.
1322	*
1323	* @return string
1324	*/
1325	#[\ReturnTypeWillChange]
1326	public function jsonSerialize()
1327	{
1328	return $this->__toString();
1329	}
1330
1331	/**
1332	* Proxy dynamic properties onto methods.
1333	*
1334	* @param string $key
1335	* @return mixed
1336	*/
1337	public function __get($key)
1338	{
1339	return $this->{$key}();
1340	}
1341
1342	/**
1343	* Get the raw string value.
1344	*
1345	* @return string
1346	*/
1347	public function __toString()
1348	{
1349	return (string) $this->value;
1350	}
1351	}
1352