1<?php
2
3namespace Illuminate\Support;
4
5use Illuminate\Support\Traits\Macroable;
6use Ramsey\Uuid\Codec\TimestampFirstCombCodec;
7use Ramsey\Uuid\Generator\CombGenerator;
8use Ramsey\Uuid\Uuid;
9use Ramsey\Uuid\UuidFactory;
10use voku\helper\ASCII;
11
12class Str
13{
14 use Macroable;
15
16 /**
17 * The cache of snake-cased words.
18 *
19 * @var array
20 */
21 protected static $snakeCache = [];
22
23 /**
24 * The cache of camel-cased words.
25 *
26 * @var array
27 */
28 protected static $camelCache = [];
29
30 /**
31 * The cache of studly-cased words.
32 *
33 * @var array
34 */
35 protected static $studlyCache = [];
36
37 /**
38 * The callback that should be used to generate UUIDs.
39 *
40 * @var callable
41 */
42 protected static $uuidFactory;
43
44 /**
45 * Get a new stringable object from the given string.
46 *
47 * @param string $string
48 * @return \Illuminate\Support\Stringable
49 */
50 public static function of($string)
51 {
52 return new Stringable($string);
53 }
54
55 /**
56 * Return the remainder of a string after the first occurrence of a given value.
57 *
58 * @param string $subject
59 * @param string $search
60 * @return string
61 */
62 public static function after($subject, $search)
63 {
64 return $search === '' ? $subject : array_reverse(explode($search, $subject, 2))[0];
65 }
66
67 /**
68 * Return the remainder of a string after the last occurrence of a given value.
69 *
70 * @param string $subject
71 * @param string $search
72 * @return string
73 */
74 public static function afterLast($subject, $search)
75 {
76 if ($search === '') {
77 return $subject;
78 }
79
80 $position = strrpos($subject, (string) $search);
81
82 if ($position === false) {
83 return $subject;
84 }
85
86 return substr($subject, $position + strlen($search));
87 }
88
89 /**
90 * Transliterate a UTF-8 value to ASCII.
91 *
92 * @param string $value
93 * @param string $language
94 * @return string
95 */
96 public static function ascii($value, $language = 'en')
97 {
98 return ASCII::to_ascii((string) $value, $language);
99 }
100
101 /**
102 * Get the portion of a string before the first occurrence of a given value.
103 *
104 * @param string $subject
105 * @param string $search
106 * @return string
107 */
108 public static function before($subject, $search)
109 {
110 return $search === '' ? $subject : explode($search, $subject)[0];
111 }
112
113 /**
114 * Get the portion of a string before the last occurrence of a given value.
115 *
116 * @param string $subject
117 * @param string $search
118 * @return string
119 */
120 public static function beforeLast($subject, $search)
121 {
122 if ($search === '') {
123 return $subject;
124 }
125
126 $pos = mb_strrpos($subject, $search);
127
128 if ($pos === false) {
129 return $subject;
130 }
131
132 return static::substr($subject, 0, $pos);
133 }
134
135 /**
136 * Get the portion of a string between two given values.
137 *
138 * @param string $subject
139 * @param string $from
140 * @param string $to
141 * @return string
142 */
143 public static function between($subject, $from, $to)
144 {
145 if ($from === '' || $to === '') {
146 return $subject;
147 }
148
149 return static::beforeLast(static::after($subject, $from), $to);
150 }
151
152 /**
153 * Convert a value to camel case.
154 *
155 * @param string $value
156 * @return string
157 */
158 public static function camel($value)
159 {
160 if (isset(static::$camelCache[$value])) {
161 return static::$camelCache[$value];
162 }
163
164 return static::$camelCache[$value] = lcfirst(static::studly($value));
165 }
166
167 /**
168 * Determine if a given string contains a given substring.
169 *
170 * @param string $haystack
171 * @param string|string[] $needles
172 * @return bool
173 */
174 public static function contains($haystack, $needles)
175 {
176 foreach ((array) $needles as $needle) {
177 if ($needle !== '' && mb_strpos($haystack, $needle) !== false) {
178 return true;
179 }
180 }
181
182 return false;
183 }
184
185 /**
186 * Determine if a given string contains all array values.
187 *
188 * @param string $haystack
189 * @param string[] $needles
190 * @return bool
191 */
192 public static function containsAll($haystack, array $needles)
193 {
194 foreach ($needles as $needle) {
195 if (! static::contains($haystack, $needle)) {
196 return false;
197 }
198 }
199
200 return true;
201 }
202
203 /**
204 * Determine if a given string ends with a given substring.
205 *
206 * @param string $haystack
207 * @param string|string[] $needles
208 * @return bool
209 */
210 public static function endsWith($haystack, $needles)
211 {
212 foreach ((array) $needles as $needle) {
213 if (substr($haystack, -strlen($needle)) === (string) $needle) {
214 return true;
215 }
216 }
217
218 return false;
219 }
220
221 /**
222 * Cap a string with a single instance of a given value.
223 *
224 * @param string $value
225 * @param string $cap
226 * @return string
227 */
228 public static function finish($value, $cap)
229 {
230 $quoted = preg_quote($cap, '/');
231
232 return preg_replace('/(?:'.$quoted.')+$/u', '', $value).$cap;
233 }
234
235 /**
236 * Determine if a given string matches a given pattern.
237 *
238 * @param string|array $pattern
239 * @param string $value
240 * @return bool
241 */
242 public static function is($pattern, $value)
243 {
244 $patterns = Arr::wrap($pattern);
245
246 if (empty($patterns)) {
247 return false;
248 }
249
250 foreach ($patterns as $pattern) {
251 // If the given value is an exact match we can of course return true right
252 // from the beginning. Otherwise, we will translate asterisks and do an
253 // actual pattern match against the two strings to see if they match.
254 if ($pattern == $value) {
255 return true;
256 }
257
258 $pattern = preg_quote($pattern, '#');
259
260 // Asterisks are translated into zero-or-more regular expression wildcards
261 // to make it convenient to check if the strings starts with the given
262 // pattern such as "library/*", making any string check convenient.
263 $pattern = str_replace('\*', '.*', $pattern);
264
265 if (preg_match('#^'.$pattern.'\z#u', $value) === 1) {
266 return true;
267 }
268 }
269
270 return false;
271 }
272
273 /**
274 * Determine if a given string is 7 bit ASCII.
275 *
276 * @param string $value
277 * @return bool
278 */
279 public static function isAscii($value)
280 {
281 return ASCII::is_ascii((string) $value);
282 }
283
284 /**
285 * Determine if a given string is a valid UUID.
286 *
287 * @param string $value
288 * @return bool
289 */
290 public static function isUuid($value)
291 {
292 if (! is_string($value)) {
293 return false;
294 }
295
296 return preg_match('/^[\da-f]{8}-[\da-f]{4}-[\da-f]{4}-[\da-f]{4}-[\da-f]{12}$/iD', $value) > 0;
297 }
298
299 /**
300 * Convert a string to kebab case.
301 *
302 * @param string $value
303 * @return string
304 */
305 public static function kebab($value)
306 {
307 return static::snake($value, '-');
308 }
309
310 /**
311 * Return the length of the given string.
312 *
313 * @param string $value
314 * @param string|null $encoding
315 * @return int
316 */
317 public static function length($value, $encoding = null)
318 {
319 if ($encoding) {
320 return mb_strlen($value, $encoding);
321 }
322
323 return mb_strlen($value);
324 }
325
326 /**
327 * Limit the number of characters in a string.
328 *
329 * @param string $value
330 * @param int $limit
331 * @param string $end
332 * @return string
333 */
334 public static function limit($value, $limit = 100, $end = '...')
335 {
336 if (mb_strwidth($value, 'UTF-8') <= $limit) {
337 return $value;
338 }
339
340 return rtrim(mb_strimwidth($value, 0, $limit, '', 'UTF-8')).$end;
341 }
342
343 /**
344 * Convert the given string to lower-case.
345 *
346 * @param string $value
347 * @return string
348 */
349 public static function lower($value)
350 {
351 return mb_strtolower($value, 'UTF-8');
352 }
353
354 /**
355 * Limit the number of words in a string.
356 *
357 * @param string $value
358 * @param int $words
359 * @param string $end
360 * @return string
361 */
362 public static function words($value, $words = 100, $end = '...')
363 {
364 preg_match('/^\s*+(?:\S++\s*+){1,'.$words.'}/u', $value, $matches);
365
366 if (! isset($matches[0]) || static::length($value) === static::length($matches[0])) {
367 return $value;
368 }
369
370 return rtrim($matches[0]).$end;
371 }
372
373 /**
374 * Parse a Class[@]method style callback into class and method.
375 *
376 * @param string $callback
377 * @param string|null $default
378 * @return array<int, string|null>
379 */
380 public static function parseCallback($callback, $default = null)
381 {
382 return static::contains($callback, '@') ? explode('@', $callback, 2) : [$callback, $default];
383 }
384
385 /**
386 * Get the plural form of an English word.
387 *
388 * @param string $value
389 * @param int $count
390 * @return string
391 */
392 public static function plural($value, $count = 2)
393 {
394 return Pluralizer::plural($value, $count);
395 }
396
397 /**
398 * Pluralize the last word of an English, studly caps case string.
399 *
400 * @param string $value
401 * @param int $count
402 * @return string
403 */
404 public static function pluralStudly($value, $count = 2)
405 {
406 $parts = preg_split('/(.)(?=[A-Z])/u', $value, -1, PREG_SPLIT_DELIM_CAPTURE);
407
408 $lastWord = array_pop($parts);
409
410 return implode('', $parts).self::plural($lastWord, $count);
411 }
412
413 /**
414 * Generate a more truly "random" alpha-numeric string.
415 *
416 * @param int $length
417 * @return string
418 */
419 public static function random($length = 16)
420 {
421 $string = '';
422
423 while (($len = strlen($string)) < $length) {
424 $size = $length - $len;
425
426 $bytes = random_bytes($size);
427
428 $string .= substr(str_replace(['/', '+', '='], '', base64_encode($bytes)), 0, $size);
429 }
430
431 return $string;
432 }
433
434 /**
435 * Replace a given value in the string sequentially with an array.
436 *
437 * @param string $search
438 * @param array<int|string, string> $replace
439 * @param string $subject
440 * @return string
441 */
442 public static function replaceArray($search, array $replace, $subject)
443 {
444 $segments = explode($search, $subject);
445
446 $result = array_shift($segments);
447
448 foreach ($segments as $segment) {
449 $result .= (array_shift($replace) ?? $search).$segment;
450 }
451
452 return $result;
453 }
454
455 /**
456 * Replace the first occurrence of a given value in the string.
457 *
458 * @param string $search
459 * @param string $replace
460 * @param string $subject
461 * @return string
462 */
463 public static function replaceFirst($search, $replace, $subject)
464 {
465 if ($search == '') {
466 return $subject;
467 }
468
469 $position = strpos($subject, $search);
470
471 if ($position !== false) {
472 return substr_replace($subject, $replace, $position, strlen($search));
473 }
474
475 return $subject;
476 }
477
478 /**
479 * Replace the last occurrence of a given value in the string.
480 *
481 * @param string $search
482 * @param string $replace
483 * @param string $subject
484 * @return string
485 */
486 public static function replaceLast($search, $replace, $subject)
487 {
488 $position = strrpos($subject, $search);
489
490 if ($position !== false) {
491 return substr_replace($subject, $replace, $position, strlen($search));
492 }
493
494 return $subject;
495 }
496
497 /**
498 * Begin a string with a single instance of a given value.
499 *
500 * @param string $value
501 * @param string $prefix
502 * @return string
503 */
504 public static function start($value, $prefix)
505 {
506 $quoted = preg_quote($prefix, '/');
507
508 return $prefix.preg_replace('/^(?:'.$quoted.')+/u', '', $value);
509 }
510
511 /**
512 * Convert the given string to upper-case.
513 *
514 * @param string $value
515 * @return string
516 */
517 public static function upper($value)
518 {
519 return mb_strtoupper($value, 'UTF-8');
520 }
521
522 /**
523 * Convert the given string to title case.
524 *
525 * @param string $value
526 * @return string
527 */
528 public static function title($value)
529 {
530 return mb_convert_case($value, MB_CASE_TITLE, 'UTF-8');
531 }
532
533 /**
534 * Get the singular form of an English word.
535 *
536 * @param string $value
537 * @return string
538 */
539 public static function singular($value)
540 {
541 return Pluralizer::singular($value);
542 }
543
544 /**
545 * Generate a URL friendly "slug" from a given string.
546 *
547 * @param string $title
548 * @param string $separator
549 * @param string|null $language
550 * @return string
551 */
552 public static function slug($title, $separator = '-', $language = 'en')
553 {
554 $title = $language ? static::ascii($title, $language) : $title;
555
556 // Convert all dashes/underscores into separator
557 $flip = $separator === '-' ? '_' : '-';
558
559 $title = preg_replace('!['.preg_quote($flip).']+!u', $separator, $title);
560
561 // Replace @ with the word 'at'
562 $title = str_replace('@', $separator.'at'.$separator, $title);
563
564 // Remove all characters that are not the separator, letters, numbers, or whitespace.
565 $title = preg_replace('![^'.preg_quote($separator).'\pL\pN\s]+!u', '', static::lower($title));
566
567 // Replace all separator characters and whitespace by a single separator
568 $title = preg_replace('!['.preg_quote($separator).'\s]+!u', $separator, $title);
569
570 return trim($title, $separator);
571 }
572
573 /**
574 * Convert a string to snake case.
575 *
576 * @param string $value
577 * @param string $delimiter
578 * @return string
579 */
580 public static function snake($value, $delimiter = '_')
581 {
582 $key = $value;
583
584 if (isset(static::$snakeCache[$key][$delimiter])) {
585 return static::$snakeCache[$key][$delimiter];
586 }
587
588 if (! ctype_lower($value)) {
589 $value = preg_replace('/\s+/u', '', ucwords($value));
590
591 $value = static::lower(preg_replace('/(.)(?=[A-Z])/u', '$1'.$delimiter, $value));
592 }
593
594 return static::$snakeCache[$key][$delimiter] = $value;
595 }
596
597 /**
598 * Determine if a given string starts with a given substring.
599 *
600 * @param string $haystack
601 * @param string|string[] $needles
602 * @return bool
603 */
604 public static function startsWith($haystack, $needles)
605 {
606 foreach ((array) $needles as $needle) {
607 if ((string) $needle !== '' && strncmp($haystack, $needle, strlen($needle)) === 0) {
608 return true;
609 }
610 }
611
612 return false;
613 }
614
615 /**
616 * Convert a value to studly caps case.
617 *
618 * @param string $value
619 * @return string
620 */
621 public static function studly($value)
622 {
623 $key = $value;
624
625 if (isset(static::$studlyCache[$key])) {
626 return static::$studlyCache[$key];
627 }
628
629 $value = ucwords(str_replace(['-', '_'], ' ', $value));
630
631 return static::$studlyCache[$key] = str_replace(' ', '', $value);
632 }
633
634 /**
635 * Returns the portion of string specified by the start and length parameters.
636 *
637 * @param string $string
638 * @param int $start
639 * @param int|null $length
640 * @return string
641 */
642 public static function substr($string, $start, $length = null)
643 {
644 return mb_substr($string, $start, $length, 'UTF-8');
645 }
646
647 /**
648 * Returns the number of substring occurrences.
649 *
650 * @param string $haystack
651 * @param string $needle
652 * @param int $offset
653 * @param int|null $length
654 * @return int
655 */
656 public static function substrCount($haystack, $needle, $offset = 0, $length = null)
657 {
658 if (! is_null($length)) {
659 return substr_count($haystack, $needle, $offset, $length);
660 } else {
661 return substr_count($haystack, $needle, $offset);
662 }
663 }
664
665 /**
666 * Make a string's first character uppercase.
667 *
668 * @param string $string
669 * @return string
670 */
671 public static function ucfirst($string)
672 {
673 return static::upper(static::substr($string, 0, 1)).static::substr($string, 1);
674 }
675
676 /**
677 * Generate a UUID (version 4).
678 *
679 * @return \Ramsey\Uuid\UuidInterface
680 */
681 public static function uuid()
682 {
683 return static::$uuidFactory
684 ? call_user_func(static::$uuidFactory)
685 : Uuid::uuid4();
686 }
687
688 /**
689 * Generate a time-ordered UUID (version 4).
690 *
691 * @return \Ramsey\Uuid\UuidInterface
692 */
693 public static function orderedUuid()
694 {
695 if (static::$uuidFactory) {
696 return call_user_func(static::$uuidFactory);
697 }
698
699 $factory = new UuidFactory();
700
701 $factory->setRandomGenerator(new CombGenerator(
702 $factory->getRandomGenerator(),
703 $factory->getNumberConverter()
704 ));
705
706 $factory->setCodec(new TimestampFirstCombCodec(
707 $factory->getUuidBuilder()
708 ));
709
710 return $factory->uuid4();
711 }
712
713 /**
714 * Set the callable that will be used to generate UUIDs.
715 *
716 * @param callable|null $factory
717 * @return void
718 */
719 public static function createUuidsUsing(callable $factory = null)
720 {
721 static::$uuidFactory = $factory;
722 }
723
724 /**
725 * Indicate that UUIDs should be created normally and not using a custom factory.
726 *
727 * @return void
728 */
729 public static function createUuidsNormally()
730 {
731 static::$uuidFactory = null;
732 }
733}
734