Functions

Your PHP functions, wrapped and renamed, so they are safer, consistent and fully typed.

---

The functions package provides type-safe, well-designed wrappers for the most popular native PHP functions.

Installation

Add the Castor repository to your composer.json.

{
  "repositories": [{
    "type": "composer",
    "url": "https://castor-labs.github.io/php-packages"
  }]
}

And then install with composer.

composer require castor/functions

Motivation

PHP functions are known for their inconsistencies (in naming, parametrization and behaviour). This is more due to an issue on how the language naturally evolved from being a hacky personal project from Rasmus Lerdorf, to a language with a core team of maintainers, RFC processes and such a big user base and community that is hard to evolve the language without upsetting anyone.

I’ve always thought that PHP shouldn’t try to fix what’s already broken, and instead give up trying to maintain the old APIs and functions. If I were in the core team, I’d dump all the manpower it has into redesigning the current functions and APIs creating a powerful standard library. Then I would mark all the old stuff as deprecated (without providing really a date for removal) so we encourage users to switch to the new APIs.

Obviously, that will take a long time to happen (and might never will), and that’s why this library exists: it provides alternative PHP functions that coexist with the native ones, and that enhance them by making them more consistent and safe.

The function package implements functions using PHP namespaces. All array functions are under the Castor\Arr namespace. Similarly, all string functions are under Castor\Str. Here is a catalog of all current existing functions and their namespaces.

The Castor\Str functions

These functions operate on UTF-8 strings. They contain different operations to manipulate these strings easily.

Castor\Str\fmt

Returns a string formatted according to the rules of \sprinf template strings.

use Castor\Str;

Str\fmt('Hello %s', 'World'); // "Hello World"
Str\fmt('I am %d years old', 35); // "I am 35 years old"

Castor\Str\toUpper

Returns the given string in upper case.

use Castor\Str;

Str\toUpper('Castor Labs'); // 'CASTOR LABS'

Castor\Str\toLower

Returns the given string in lower case.

use Castor\Str;

Str\toLower('Castor Labs'); // 'castor labs'

Castor\Str\toTitle

Returns the given string in title case.

use Castor\Str;

Str\toTitle('castor labs'); // 'Castor Labs'

Castor\Str\replace

Returns a new string with the substring replaced by $replacement

use Castor\Str;

Str\replace('Hello World', 'World', 'Castor'); // 'Hello Castor'

Castor\Str\index

Returns the index where first occurrence of a substring starts in a given string. If the substring is not found in the given string, then this function returns -1.

use Castor\Str;

Str\index('Castor Labs', 'a'); // 1
Str\index('Castor Labs', 'X'); // -1

You can optionally pass an offset to where to start looking from.

use Castor\Str;

Str\index('Castor Labs', 'a', 3); // 8

Castor\Str\lastIndex

Returns the index where the last occurrence of a substring starts in a given string. If the substring is not found in the given string, then this function returns -1.

use Castor\Str;

Str\lastIndex('Castor Labs', 'a'); // 8
Str\lastIndex('Castor Labs', 'X'); // -1

Castor\Str\trim

Returns a string with the given characters trimmed from both ends of the given string.

use Castor\Str;

Str\trim(" Castor Labs \n"); // "Castor Labs"

Castor\Str\ltrim

Returns a string with the given characters trimmed from the left end of the given string.

use Castor\Str;

Str\ltrim(" Castor Labs \n"); // "Castor Labs \n"

Castor\Str\rtrim

Returns a string with the given characters trimmed from the right end of the given string.

use Castor\Str;

Str\rtrim(" Castor Labs \n"); // " Castor Labs"

Castor\Str\split

Splits the given string into an array of strings by the given separator.

use Castor\Str;

Str\split('app.events.user.created', '.'); // ['app', 'events', 'user', 'created']

You can optionally pass a limit to the number of elements to split

use Castor\Str;

Str\split('app.events.user.created', '.', 2); // ['app', 'events.user.created']

Castor\Str\join

Joins an array of strings into a single string by the given glue.

It’s technically the opposite operation to Castor\Str\split.

use Castor\Str;

Str\join(['app', 'events', 'user', 'created'], '.'); // 'app.events.user.created'

Castor\Str\slice

Returns a slice from the given string. There are multiple ways of slicing the string:

use Castor\Str;

// You can slice from a certain offset until the end of the string
Str\slice('app.events.user.created', 4); // 'events.user.created'

// You can slice from the start up to a particular length
Str\slice('app.events.user.created', 0, 3); // 'app'

// You can slice from the the n last characters to the end of the string
Str\slice('app.events.user.created', -7); // 'created'

Castor\Str\len

Returns the length of the given string. The length is always the number of UTF-8 code points (characters) on the string, and not the number of bytes in it.

use Castor\Str;

Str\len('Castor'); // 6
Str\len('ビーバー'); // 4

Castor\Str\cut

Cuts a string in two parts by the given substring. It returns an array of three elements that can be destructured. The substring is not included.

use Castor\Str;

[$left, $right, $ok] = Str\cut('foo=bar', '=');
$left; // 'foo'
$right; // 'bar'
$ok; // true

[$left, $right, $ok] = Str\cut('foobar', '=');
$left; // 'foobar'
$right; // ''
$ok; // false