Primitive utilities

Overview

Tempest provides a set of utilities that make working with primitive values easier. It provides an object-oriented API for handling strings and arrays, along with many namespaced functions to work with arithmetic operations, regular expressions, random values, pluralization, filesystem paths and more.

Namespaced functions

Most utilities provided by Tempest have a function-based implementation under the Tempest\Support namespace. You may look at what is available on GitHub:

• Regular expressions
• Arithmetic operations
• Filesystem operations
• Filesystem paths
• Json manipulation
• Random values
• Pluralization
• PHP namespaces

Tempest also provids the Tempest\Support\IsEnumHelper trait to work with enumerations, since a functional API is not useful in this case.

String utilities

Tempest provides string utilities through namespaced functions or a fluent, object-oriented API, which comes in an immutable and a mutable flavor.

Providing a string value, you may create an instance of Tempest\Support\Str\ImmutableString or Tempest\Support\Str\MutableString:

use Tempest\Support\Str;
use Tempest\Support\Str\ImmutableString;

// Functional API
$title = Str\to_sentence_case($title);

// Object-oriented API
$slug = new ImmutableString('/blog/01-chasing-bugs-down-the-rabbit-hole/')
    ->stripEnd('/')
    ->afterLast('/')
    ->replaceRegex('/\d+-/', '')
    ->slug()
    ->toString();

Note that you may use the str() function as a shorthand to create an ImmutableString instance.

Array utilities

Tempest provides array utilities through namespaced functions or a fluent, object-oriented API, which comes in an immutable and a mutable flavor.

Providing an iterable value, you may create an instance of Tempest\Support\Arr\ImmutableArray or Tempest\Support\Arr\MutableArray:

use Tempest\Support\Arr;
use Tempest\Support\Arr\ImmutableArray;

// Functional API
$first = Arr\first($collection);

// Object-oriented API
$items = new ImmutableArray(glob(__DIR__ . '/content/*.md'))
    ->reverse()
    ->map(function (string $path) {
        // …
    })
    ->mapTo(BlogPost::class);

Note that you may use the arr() function as a shorthand to create an ImmutableArray instance.

Recommendations

We recommend working with primitive utilities when possible instead of using PHP's built-in methods. For instance, you may read a file by using Filesystem\read_file:

use Tempest\Support\Filesystem;

$contents = Filesystem\read_file(__DIR__ . '/content.md');

Using this function covers more edge cases and throws clear exceptions that are easier to catch. Similarly, it may not be useful to always reach for the object-oriented array and string helpers. Sometimes, you may simply use a single function:

use Tempest\Support\Str;
use function Tempest\Support\str;

 $title = str('My title')->title()->toString(); 
 $title = Str\to_title_case('My title');