Code Coverage
 
Lines
Functions and Methods
Classes and Traits
Total
100.00%
156 / 156
100.00%
12 / 12
 CRAP
100.00%
1 / 1
Str
100.00%
156 / 156
100.00%
12 / 12
 72
100.00%
1 / 1
 createSlug
100.00%
3 / 3
100.00%
1 / 1
 1
 createLinks
100.00%
9 / 9
100.00%
1 / 1
 4
 createRandom
100.00%
11 / 11
100.00%
1 / 1
 4
 createRandomAlphaNum
100.00%
12 / 12
100.00%
1 / 1
 4
 createRandomAlpha
100.00%
13 / 13
100.00%
1 / 1
 4
 createRandomNumeric
100.00%
1 / 1
100.00%
1 / 1
 1
 generateRandomString
100.00%
7 / 7
100.00%
1 / 1
 2
 stripSpecialCharacters
100.00%
4 / 4
100.00%
1 / 1
 4
 __callStatic
100.00%
77 / 77
100.00%
1 / 1
 36
 convertFromCamelCase
100.00%
6 / 6
100.00%
1 / 1
 5
 convertToCamelCase
100.00%
7 / 7
100.00%
1 / 1
 4
 detectSeparator
100.00%
6 / 6
100.00%
1 / 1
 3
1<?php
2/**
3 * Pop PHP Framework (https://www.popphp.org/)
4 *
5 * @link       https://github.com/popphp/popphp-framework
6 * @author     Nick Sagona, III <dev@noladev.com>
7 * @copyright  Copyright (c) 2009-2026 NOLA Interactive, LLC.
8 * @license    https://www.popphp.org/license     New BSD License
9 */
10
11/**
12 * @namespace
13 */
14namespace Pop\Utils;
15
16/**
17 * Pop utils string helper class
18 *
19 * @category   Pop
20 * @package    Pop\Utils
21 * @author     Nick Sagona, III <dev@noladev.com>
22 * @copyright  Copyright (c) 2009-2026 NOLA Interactive, LLC.
23 * @license    https://www.popphp.org/license     New BSD License
24 * @version    2.3.0
25 */
26class Str
27{
28
29    /**
30     * Constants case type for random string generation
31     */
32    const MIXEDCASE = 0;
33    const LOWERCASE = 1;
34    const UPPERCASE = 2;
35
36    /**
37     * Characters for random string generation (certain characters omitted to eliminate confusion)
38     * @var array
39     */
40    protected static array $randomChars = [
41        'abcdefghjkmnpqrstuvwxyz',
42        'ABCDEFGHJKLMNPQRSTUVWXYZ',
43        '0123456789',
44        '!?#$%&@-_+*=,.:;()[]{}',
45    ];
46
47    /**
48     * Regex patterns & replacements for links
49     * @var array
50     */
51    protected static array $linksRegex = [
52        [
53            'pattern'     => '/(http|https|ftp|ftps)\:\/\/[a-zA-Z0-9\-\.]+\.[a-zA-Z]{2,3}(\/\S*)?/m',
54            'replacement' => '<a href="$0">$0</a>'
55        ],
56        [
57            'pattern'     => '/[a-zA-Z0-9\.\-\_+%]+@[a-zA-Z0-9\-\_\.]+\.[a-zA-Z]{2,4}/m',
58            'replacement' => '<a href="mailto:$0">$0</a>'
59        ]
60    ];
61
62    /**
63     * Allowed keywords for converting cases
64     * @var array
65     */
66    protected static array $allowedCases = [
67        'titlecase', 'camelcase', 'kebabcase', 'dash', 'snakecase', 'underscore', 'namespace', 'path', 'url', 'uri'
68    ];
69
70    /**
71     * Convert the string into an SEO-friendly slug.
72     *
73     * @param  string $string
74     * @param  string $separator
75     * @return string
76     */
77    public static function createSlug(string $string, string $separator = '-'): string
78    {
79        $string = str_replace(' ', $separator, preg_replace('/([^a-zA-Z0-9 \-\/])/', '', strtolower($string)));
80        $regex  = '/' . $separator . '*' . $separator .'/';
81
82        return preg_replace($regex, $separator, $string);
83    }
84
85    /**
86     * Convert any links in the string to HTML links.
87     *
88     * @param  string $string
89     * @param  array  $attributes
90     * @return string
91     */
92    public static function createLinks(string $string, array $attributes = []): string
93    {
94        foreach (self::$linksRegex as $regex) {
95            $replacement = $regex['replacement'];
96
97            if (!empty($attributes)) {
98                $attribs = [];
99                foreach ($attributes as $attrib => $value) {
100                    $attribs[] = $attrib . '="' . $value . '"';
101                }
102                $replacement = str_replace('<a ', '<a ' . implode(' ', $attribs) . ' ', $replacement);
103            }
104
105            $string = preg_replace($regex['pattern'], $replacement, $string);
106        }
107
108        return $string;
109    }
110
111    /**
112     * Generate a random string of a predefined length.
113     *
114     * @param  int $length
115     * @param  int $case
116     * @return string
117     */
118    public static function createRandom(int $length, int $case = self::MIXEDCASE): string
119    {
120        $chars    = self::$randomChars;
121        $charsets = [];
122
123        switch ($case) {
124            case 1:
125                unset($chars[1]);
126                break;
127            case 2:
128                unset($chars[0]);
129                break;
130        }
131
132        foreach ($chars as $key => $value) {
133            $charsets[] = str_split($value);
134        }
135
136        return self::generateRandomString($length, $charsets);
137    }
138
139    /**
140     * Generate a random alphanumeric string of a predefined length.
141     *
142     * @param  int $length
143     * @param  int $case
144     * @return string
145     */
146    public static function createRandomAlphaNum(int $length, int $case = self::MIXEDCASE): string
147    {
148        $chars    = self::$randomChars;
149        $charsets = [];
150
151        switch ($case) {
152            case 1:
153                unset($chars[1]);
154                break;
155            case 2:
156                unset($chars[0]);
157                break;
158        }
159        unset($chars[3]);
160
161        foreach ($chars as $key => $value) {
162            $charsets[] = str_split($value);
163        }
164
165        return self::generateRandomString($length, $charsets);
166    }
167
168    /**
169     * Generate a random alphabetical string of a predefined length.
170     *
171     * @param  int $length
172     * @param  int $case
173     * @return string
174     */
175    public static function createRandomAlpha(int $length, int $case = self::MIXEDCASE): string
176    {
177        $chars    = self::$randomChars;
178        $charsets = [];
179
180        switch ($case) {
181            case 1:
182                unset($chars[1]);
183                break;
184            case 2:
185                unset($chars[0]);
186                break;
187        }
188        unset($chars[2]);
189        unset($chars[3]);
190
191        foreach ($chars as $key => $value) {
192            $charsets[] = str_split($value);
193        }
194
195        return self::generateRandomString($length, $charsets);
196    }
197
198    /**
199     * Generate a random numeric string of a predefined length.
200     *
201     * @param  int $length
202     * @return string
203     */
204    public static function createRandomNumeric(int $length): string
205    {
206        return self::generateRandomString($length, [str_split(self::$randomChars[2])]);
207    }
208
209    /**
210     * Generate characters based on length and character sets provided
211     *
212     * @param  int   $length
213     * @param  array $charsets
214     * @return string
215     */
216    public static function generateRandomString(int $length, array $charsets): string
217    {
218        $string  = '';
219        $indices = array_keys($charsets);
220
221        for ($i = 0; $i < $length; $i++) {
222            $index    = $indices[rand(0, (count($indices) - 1))];
223            $subIndex = rand(0, (count($charsets[$index]) - 1));
224            $string  .= $charsets[$index][$subIndex];
225        }
226
227        return $string;
228    }
229
230    /**
231     * Strip special characters
232     *
233     * @param  string $string
234     * @param  bool   $alphaNumOnly    No dashes or underscores
235     * @param  bool   $spaces          Allow spaces
236     * @return string
237     */
238    public static function stripSpecialCharacters(string $string, bool $alphaNumOnly = false, bool $spaces = true): string
239    {
240        if ($alphaNumOnly) {
241            $regex = ($spaces) ? "/[^A-Za-z0-9 ]/" : "/[^A-Za-z0-9]/";
242        } else {
243            $regex = ($spaces) ? "/[^A-Za-z0-9_\- ]/" : "/[^A-Za-z0-9_\-]/";
244        }
245        return preg_replace($regex, '', $string);
246    }
247
248    /**
249     * Convert a string from one case to another
250     *
251     * @param string $name
252     * @param array  $arguments
253     * @return string
254     */
255    public static function __callStatic(string $name, array $arguments): string
256    {
257        [$from, $to]   = explode('to', strtolower($name));
258        $string        = $arguments[0] ?? null;
259        $preserveCase  = (array_key_exists(1, $arguments) && is_bool($arguments[1])) ? $arguments[1] : null;
260        $separator     = null;
261        $prevSeparator = null;
262        $result        = null;
263
264        switch ($to) {
265            case 'titlecase':
266            case 'camelcase':
267                $preserveCase = true;
268                break;
269            case 'kebabcase':
270            case 'dash':
271                $separator = '-';
272                if ($preserveCase === null) {
273                    $preserveCase = false;
274                }
275                break;
276            case 'snakecase':
277            case 'underscore':
278                $separator = '_';
279                if ($preserveCase === null) {
280                    $preserveCase = false;
281                }
282                break;
283            case 'namespace':
284                $separator = '\\';
285                if ($preserveCase === null) {
286                    $preserveCase = true;
287                }
288                break;
289            case 'path':
290                $separator = DIRECTORY_SEPARATOR;
291                if ($preserveCase === null) {
292                    $preserveCase = true;
293                }
294                break;
295            case 'uri':
296            case 'url':
297                $separator = '/';
298                if ($preserveCase === null) {
299                    $preserveCase = true;
300                }
301                break;
302        }
303
304        switch ($from) {
305            case 'titlecase':
306            case 'camelcase':
307                $result = self::convertFromCamelCase($string, $separator, $preserveCase);
308                if ($to == 'titlecase') {
309                    $result = ucfirst($result);
310                }
311                if ($to == 'camelcase') {
312                    $result = lcfirst($result);
313                }
314                break;
315            case 'kebabcase':
316            case 'dash':
317                $prevSeparator = '-';
318                break;
319            case 'snakecase':
320            case 'underscore':
321                $prevSeparator = '_';
322                break;
323            case 'namespace':
324                $prevSeparator = '\\';
325                break;
326            case 'path':
327                $prevSeparator = DIRECTORY_SEPARATOR;
328                break;
329            case 'url':
330            case 'uri':
331                $prevSeparator = '/';
332                break;
333        }
334
335        if ($result === null) {
336            switch ($to) {
337                case 'titlecase':
338                    $result = ucfirst(self::convertToCamelCase($string, $prevSeparator));
339                    break;
340                case 'camelcase':
341                    $result = lcfirst(self::convertToCamelCase($string, $prevSeparator));
342                    break;
343                default:
344                    if ($preserveCase) {
345                        $string = implode($prevSeparator, array_map('ucfirst', explode($prevSeparator, $string)));
346                    }
347                    $result = str_replace($prevSeparator, $separator, $string);
348                    if ($preserveCase === false) {
349                        $result = strtolower($result);
350                    }
351            }
352        }
353
354        return $result;
355    }
356
357    /**
358     * Convert a camelCase string using the $separator value passed
359     *
360     * @param string  $string
361     * @param ?string $separator
362     * @param bool    $preserveCase
363     * @return string
364     */
365    public static function convertFromCamelCase(string $string, ?string $separator = null, bool $preserveCase = false): string
366    {
367        $stringAry = str_split($string);
368        $converted = null;
369
370        foreach ($stringAry as $i => $char) {
371            $converted .= ($i == 0) ?
372                $char : ((ctype_upper($char)) ? ($separator . $char) : $char);
373        }
374
375        return ($preserveCase) ? $converted : strtolower($converted);
376    }
377
378    /**
379     * Convert a camelCase string using the $separator value passed
380     *
381     * @param  string  $string
382     * @param  ?string $separator
383     * @return string
384     */
385    public static function convertToCamelCase(string $string, ?string $separator = null): string
386    {
387        if ($separator === null) {
388            $separator = self::detectSeparator($string);
389        }
390        $stringAry = explode($separator, $string);
391        $converted = null;
392
393        foreach ($stringAry as $i => $word) {
394            $converted .= ($i == 0) ? $word : ucfirst($word);
395        }
396
397        return $converted;
398    }
399
400    /**
401     * Attempt to detect separator
402     *
403     * @param  string  $string
404     * @return string
405     */
406    public static function detectSeparator(string $string): string
407    {
408        $separator  = '';
409        $separators = ['-', '_', '\\', '/', DIRECTORY_SEPARATOR];
410
411        foreach ($separators as $s) {
412            if (str_contains($string, $s)) {
413                return $s;
414            }
415        }
416
417        return $separator;
418    }
419
420}
421