Phalcon\Helper\Str

Complexity

Total Complexity

47

Size/Duplication

Total Lines	480
Duplicated Lines	0 %

Test Coverage

Coverage

99.25%

Importance

Changes

0

22 Methods

Rating	Name	Duplication	Size	Complexity
A	dirSeparator()	0	3	1
A	concat()	0	26	5
A	endsWith()	0	15	2
A	dirFromFile()	0	10	2
A	decapitalize()	0	14	2
A	countVowels()	0	5	1
A	decrement()	0	14	3
A	firstBetween()	0	11	3
A	random()	0	32	4
A	isPalindrome()	0	3	1
A	isAnagram()	0	3	1
A	includes()	0	6	2
A	reduceSlashes()	0	5	2
A	upper()	0	3	1
A	increment()	0	10	2
A	startsWith()	0	15	2
A	humanize()	0	5	2
A	lower()	0	3	1
A	isLower()	0	3	1
A	underscore()	0	5	2
A	friendly()	0	35	6
A	isUpper()	0	3	1

<?php

/**
 * This file is part of the Phalcon Framework.
 *
 * For the full copyright and license information, please view the LICENSE.md
 * file that was distributed with this source code.
 */

declare(strict_types=1);

namespace Phalcon\Helper;

use function array_merge;
use function count_chars;
use function explode;
use function implode;
use function ltrim;
use function mt_rand;
use function pathinfo;
use function preg_match_all;
use function preg_replace;
use function range;
use function rtrim;
use function str_split;
use function strlen;
use function strrev;
use function substr;
use function substr_compare;
use function trim;

use const DIRECTORY_SEPARATOR;
use const PATHINFO_FILENAME;

/**
 * Phalcon\Helper\Str
 *
 * This class offers quick string functions throughout the framework
 */
class Str
{
    public const RANDOM_ALNUM    = 0;
    public const RANDOM_ALPHA    = 1;
    public const RANDOM_DISTINCT = 5;
    public const RANDOM_HEXDEC   = 2;
    public const RANDOM_NOZERO   = 4;
    public const RANDOM_NUMERIC  = 3;

    /**
     * Concatenates strings using the separator only once without duplication in
     * places concatenation
     *
     * @param string $separator
     * @param mixed  ...$arguments
     *
     * @return string
     * @throws Exception
     */
    final public static function concat(string $separator, ...$arguments): string
    {
        if (count($arguments) < 2) {
            throw new Exception('concat needs at least three parameters');
        }

        $first  = Arr::first($arguments);
        $last   = Arr::last($arguments);
        $prefix = '';
        $suffix = '';
        $data   = [];

        if (self::startsWith($first, $separator)) {
            $prefix = $separator;
        }

        if (self::endsWith($last, $separator)) {
            $suffix = $separator;
        }


        foreach ($arguments as $argument) {
            $data[] = rtrim(ltrim($argument, $separator), $separator);
        }

        return $prefix . implode($separator, $data) . $suffix;
    }

    /**
     * Returns number of vowels in provided string. Uses a regular expression
     * to count the number of vowels (A, E, I, O, U) in a string.
     *
     * @param string $text
     *
     * @return int
     */
    final public static function countVowels(string $text): int
    {
        preg_match_all('/[aeiou]/i', $text, $matches);

        return count($matches[0]);
    }

    /**
     * Decapitalizes the first letter of the string and then adds it with rest
     * of the string. Omit the upperRest parameter to keep the rest of the
     * string intact, or set it to true to convert to uppercase.
     *
     * @param string $text
     * @param bool   $upperRest
     * @param string $encoding
     *
     * @return string
     */
    final public static function decapitalize(
        string $text,
        bool $upperRest = false,
        string $encoding = 'UTF-8'
    ): string {
        $substr = mb_substr($text, 1);

        if ($upperRest) {
            $suffix = mb_strtoupper($substr, $encoding);
        } else {
            $suffix = $substr;
        }

        return mb_strtolower(mb_substr($text, 0, 1), $encoding) . $suffix;
    }

    /**
     * Removes a number from a string or decrements that number if it already
     * is defined. defined
     *
     * ```php
     * use Phalcon\Helper\Str;
     *
     * echo Str::decrement("a_1");    // "a"
     * echo Str::decrement("a_2");  // "a_1"
     * ```
     *
     * @param string $text
     * @param string $separator
     *
     * @return string
     */
    final public static function decrement(string $text, string $separator = "_"): string
    {
        $number = 0;
        $parts  = explode($separator, $text);

        if (isset($parts[1])) {
            $number = $parts[1];
            $number--;
            if ($number <= 0) {
                return $parts[0];
            }
        }

        return $parts[0] . $separator . $number;
    }

    /**
     * Accepts a file name (without extension) and returns a calculated
     * directory structure with the filename in the end
     *
     * @param string $file
     *
     * @return string
     */
    final public static function dirFromFile(string $file): string
    {
        $name  = pathinfo($file, PATHINFO_FILENAME);
        $start = substr($name, 0, -2);

        if (!$start) {
            $start = substr($name, 0, 1);
        }

        return implode('/', str_split($start, 2)) . '/';
    }

    /**
     * Accepts a directory name and ensures that it ends with
     * DIRECTORY_SEPARATOR
     *
     * @param string $directory
     *
     * @return string
     */
    final public static function dirSeparator(string $directory): string
    {
        return rtrim($directory, DIRECTORY_SEPARATOR) . DIRECTORY_SEPARATOR;
    }

    /**
     * Check if a string ends with a given string
     *
     * @param string $haystack
     * @param string $needle
     * @param bool   $ignoreCase
     *
     * @return bool
     */
    final public static function endsWith(
        string $haystack,
        string $needle,
        bool $ignoreCase = true
    ): bool {
        if ('' === $haystack) {
            return false;
        }

        return 0 === substr_compare(
            $haystack,
            $needle,
            -strlen($needle),
            strlen($needle),
            $ignoreCase
        );
    }

    /**
     * Returns the first string there is between the strings from the
     * parameter start and end.
     *
     * @param string $text
     * @param string $start
     * @param string $end
     *
     * @return string
     */
    final public static function firstBetween(
        string $text,
        string $start,
        string $end
    ): string {
        $result = mb_strstr($text, $start);
        $result = (false === $result) ? '' : $result;
        $result = mb_strstr($result, $end, true);
        $result = (false === $result) ? '' : $result;

        return trim($result, $start . $end);
    }

    /**
     * Changes a text to a URL friendly one
     *
     * @param string $text
     * @param string $separator
     * @param bool   $lowercase
     * @param null   $replace

Are you sure the doc-type for parameter $replace is correct as it would always require null to be passed?

     *
     * @return string
     * @throws Exception
     */
    public function friendly(
        string $text,
        string $separator = "-",
        bool $lowercase = true,
        $replace = null
    ): string {

        if (null !== $replace) {

The condition null !== $replace is always false.

            if (!is_array($replace) && !is_string($replace)) {
                throw new Exception(
                    "Parameter replace must be an array or a string"
                );
            }

            if (is_string($replace)) {
                $replace = [$replace];
            }

            $text = str_replace($replace, " ", $text);
        }

        $friendly = preg_replace(
            "/[^a-zA-Z0-9\\/_|+ -]/",
            "",
            $text
        );

        if ($lowercase) {
            $friendly = strtolower($friendly);
        }

        $friendly = preg_replace("/[\\/_|+ -]+/", $separator, $friendly);
        $friendly = trim($friendly, $separator);

        return $friendly;
    }

    /**
     * Makes an underscored or dashed phrase human-readable
     *
     * @param string $text
     *
     * @return string
     */
    final public static function humanize(string $text): string
    {
        $result = preg_replace('#[_-]+#', ' ', trim($text));

        return (null === $result) ? '' : $result;
    }

    /**
     * Lets you determine whether or not a string includes another string.
     *
     * @param string $haystack
     * @param string $needle
     *
     * @return bool
     */
    final public static function includes(string $haystack, string $needle): bool
    {
        if (function_exists("mb_strpos")) {
            return false !== mb_strpos($haystack, $needle);
        } else {
            return false !== strpos($haystack, $needle);
        }
    }

    /**
     * Adds a number to a string or increment that number if it already is
     * defined
     *
     * @param string $text
     * @param string $separator
     *
     * @return string
     */
    final public static function increment(string $text, string $separator = '_'): string
    {
        $parts  = explode($separator, $text);
        $number = 1;

        if (isset($parts[1])) {
            $number = ((int) $parts[1]) + 1;
        }

        return $parts[0] . $separator . $number;
    }

    /**
     * Compare two strings and returns true if both strings are anagram,
     * false otherwise.
     *
     * @param string $first
     * @param string $second
     *
     * @return bool
     */
    final public static function isAnagram(string $first, string $second): bool
    {
        return count_chars($first, 1) === count_chars($second, 1);
    }

    /**
     * Returns true if the given string is lower case, false otherwise.
     *
     * @param string $text
     * @param string $encoding
     *
     * @return bool
     */
    final public static function isLower(string $text, string $encoding = 'UTF-8'): bool
    {
        return $text === mb_strtolower($text, $encoding);
    }

    /**
     * Returns true if the given string is a palindrome, false otherwise.
     *
     * @param string $text
     *
     * @return bool
     */
    final public static function isPalindrome(string $text): bool
    {
        return strrev($text) === $text;
    }

    /**
     * Returns true if the given string is upper case, false otherwise.
     *
     * @param string $text
     * @param string $encoding
     *
     * @return bool
     */
    final public static function isUpper(string $text, string $encoding = 'UTF-8'): bool
    {
        return $text === mb_strtoupper($text, $encoding);
    }

    /**
     * Lowercases a string, this function makes use of the mbstring extension if
     * available
     *
     * @param string $text
     * @param string $encoding
     *
     * @return string
     */
    final public static function lower(string $text, string $encoding = 'UTF-8'): string
    {
        return mb_strtolower($text, $encoding);
    }

    /**
     * Generates a random string based on the given type. Type is one of the
     * RANDOM_* constants
     *
     * @param int $type
     * @param int $length
     *
     * @return string
     */
    final public static function random(
        int $type = self::RANDOM_ALNUM,
        int $length = 8
    ): string {
        $text  = '';
        $type  = ($type < 0 || $type > 5) ? self::RANDOM_ALNUM : $type;
        $pools = [
            self::RANDOM_ALPHA    => array_merge(
                range('a', 'z'),
                range('A', 'Z')
            ),
            self::RANDOM_HEXDEC   => array_merge(
                range(0, 9),
                range('a', 'f')
            ),
            self::RANDOM_NUMERIC  => range(0, 9),
            self::RANDOM_NOZERO   => range(1, 9),
            self::RANDOM_DISTINCT => str_split('2345679ACDEFHJKLMNPRSTUVWXYZ'),
            self::RANDOM_ALNUM    => array_merge(
                range(0, 9),
                range('a', 'z'),
                range('A', 'Z')
            ),
        ];

        $end = count($pools[$type]) - 1;

        while (strlen($text) < $length) {
            $text .= $pools[$type][mt_rand(0, $end)];
        }

        return $text;
    }

    /**
     * Reduces multiple slashes in a string to single slashes
     *
     * @param string $text
     *
     * @return string
     */
    final public static function reduceSlashes(string $text): string
    {
        $result = preg_replace('#(?<!:)//+#', '/', $text);

        return (null === $result) ? '' : $result;
    }

    /**
     * Check if a string starts with a given string
     *
     * @param string $haystack
     * @param string $needle
     * @param bool   $ignoreCase
     *
     * @return bool
     */
    final public static function startsWith(
        string $haystack,
        string $needle,
        bool $ignoreCase = true
    ): bool {
        if ('' === $haystack) {
            return false;
        }

        return 0 === substr_compare(
            $haystack,
            $needle,
            0,
            strlen($needle),
            $ignoreCase
        );
    }

    /**
     * Makes a phrase underscored instead of spaced
     *
     * @param string $text
     *
     * @return string
     */
    final public static function underscore(string $text): string
    {
        $result = preg_replace('#\s+#', '_', trim($text));

        return (null === $result) ? '' : $result;
    }

    /**
     * Uppercases a string, this function makes use of the mbstring extension if
     * available
     *
     * @param string $text
     * @param string $encoding
     *
     * @return string
     */
    final public static function upper(string $text, string $encoding = 'UTF-8'): string
    {
        return mb_strtoupper($text, $encoding);
    }
}