Traits¶

Overview¶

The Phalcon\Traits namespace is a collection of small, focused traits used throughout the framework. Each trait bundles a single reusable piece of behavior - for example reading a value from an array with a fallback - so that any class needing it can use the trait instead of carrying its own copy of the same method.

Consolidating shared behavior in traits keeps the implementation in one place: a fix or improvement to a trait is immediately picked up by every class that uses it.

The traits follow the layout of the components they support, so a trait lives under a namespace that mirrors its area of responsibility. For instance, array helper traits live under Phalcon\Traits\Support\Helper\Arr, while wrappers for native PHP functions live under Phalcon\Traits\Php.

Available Traits¶

Support¶

Traits that back the Phalcon\Support helper components.

Arr\GetTrait¶

Phalcon\Traits\Support\Helper\Arr\GetTrait

Reads an element from an array by key. When the key is not present, the supplied default value is returned instead. The result can optionally be cast to a specific type using PHP's settype().

Method

protected function getArrVal(
    array $collection,
    mixed $index,
    mixed $defaultValue = null,
    ?string $cast = null
): mixed

Parameters

Returns the value stored at $index, or $defaultValue when the key is absent - cast to $cast when one is supplied.

Example

<?php

use Phalcon\Traits\Support\Helper\Arr\GetTrait;

class MyAdapter
{
    use GetTrait;

    public function __construct(array $options = [])
    {
        // 'sess-' is returned when 'prefix' is not supplied
        $prefix = $this->getArrVal($options, 'prefix', 'sess-');

        // the looked up value is cast to an int
        $lifetime = $this->getArrVal($options, 'lifetime', 3600, 'int');

        // cast to bool
        $persistent = $this->getArrVal($options, 'persistent', false, 'bool');
    }
}

Arr\FilterTrait¶

Phalcon\Traits\Support\Helper\Arr\FilterTrait

Filters a collection using PHP's array_filter() with an optional callable. When no callable is supplied - or the supplied value is not callable - the collection is returned unchanged.

Method

protected function toFilter(
    array $collection,
    callable|null $method = null
): array

Parameters

Returns the filtered array, or the original $collection when no valid callable is provided.

Example

<?php

use Phalcon\Traits\Support\Helper\Arr\FilterTrait;

class MyCollection
{
    use FilterTrait;

    public function positives(array $numbers): array
    {
        return $this->toFilter(
            $numbers,
            function ($value) {
                return $value > 0;
            }
        );
    }
}

Json\EncodeTrait¶

Phalcon\Traits\Support\Helper\Json\EncodeTrait

Encodes data using PHP's json_encode(). On failure it throws the native \JsonException - a leaf dependency, so the trait carries no framework coupling. The framework-flavored exception (JsonEncodeError) is added by the Support helper class that wraps the trait.

Method

protected static function toEncode(
    mixed $data,
    int $options = 79,
    int $depth = 512
): string

Parameters

Returns the JSON-encoded string. Throws \JsonException when the data cannot be encoded.

Example

<?php

use Phalcon\Traits\Support\Helper\Json\EncodeTrait;

class MyEncoder
{
    use EncodeTrait;

    public function toJson(array $data): string
    {
        return $this->toEncode($data);
    }
}

Json\DecodeTrait¶

Phalcon\Traits\Support\Helper\Json\DecodeTrait

Decodes a string using PHP's json_decode(). On failure it throws the native \JsonException - a leaf dependency, so the trait carries no framework coupling. The framework-flavored exception (JsonDecodeError) is added by the Support helper class that wraps the trait.

Method

protected static function toDecode(
    string $data,
    bool $associative = false,
    int $depth = 512,
    int $options = 79
): mixed

Parameters

Returns the decoded value (its type depends on the JSON and $associative). Throws \JsonException when the data cannot be decoded.

Example

<?php

use Phalcon\Traits\Support\Helper\Json\DecodeTrait;

class MyDecoder
{
    use DecodeTrait;

    public function fromJson(string $json): array
    {
        return $this->toDecode($json, true);
    }
}

Str\DirFromFileTrait¶

Phalcon\Traits\Support\Helper\Str\DirFromFileTrait

Turns a file name into a calculated nested directory path, so a large number of files can be spread across sub-directories rather than living in a single folder. The name is taken without its extension, its leading characters are split into two-character segments, and those segments are joined with /.

Method

protected function toDirFromFile(
    string $file,
    bool $filesystemSafe = false
): string

Parameters

Returns the calculated directory path with a trailing / (for example te/st/fi/ for testfile). The method is multibyte-aware - it uses mb_* functions - so names containing multibyte characters are split by character rather than by byte.

Example

<?php

use Phalcon\Traits\Support\Helper\Str\DirFromFileTrait;

class MyCache
{
    use DirFromFileTrait;

    public function pathFor(string $key): string
    {
        // nested two-character segments; $filesystemSafe blocks "../" traversal
        return $this->toDirFromFile($key, true);
    }
}

Str\DirSeparatorTrait¶

Phalcon\Traits\Support\Helper\Str\DirSeparatorTrait

Normalizes a directory string so it ends with exactly one DIRECTORY_SEPARATOR. Any trailing separators are trimmed and a single one is appended, so the result is safe to concatenate with a file name or a sub-directory.

Method

protected function toDirSeparator(string $directory): string

Parameters

Returns the directory with exactly one trailing DIRECTORY_SEPARATOR (for example /var/www/ for both /var/www and /var/www///).

Example

<?php

use Phalcon\Traits\Support\Helper\Str\DirSeparatorTrait;

class MyLoader
{
    use DirSeparatorTrait;

    public function pathFor(string $dir, string $file): string
    {
        // "/base/" + "view.phtml" regardless of trailing slashes on $dir
        return $this->toDirSeparator($dir) . $file;
    }
}

Str\EndsWithTrait¶

Phalcon\Traits\Support\Helper\Str\EndsWithTrait

Reports whether a string ends with a given substring. The comparison is case-insensitive by default and multibyte-aware - both sides are lowercased with mb_strtolower() before the suffix is checked (via the native ends_with()) - and an empty haystack always returns false.

Method

protected function toEndsWith(
    string $haystack,
    string $needle,
    bool $ignoreCase = true
): bool

Parameters

Returns true when $haystack ends with $needle, false otherwise (including when $haystack is empty).

Example

<?php

use Phalcon\Traits\Support\Helper\Str\EndsWithTrait;

class MyValidator
{
    use EndsWithTrait;

    public function isImage(string $file): bool
    {
        return $this->toEndsWith($file, ".png")
            || $this->toEndsWith($file, ".jpg");
    }
}

Str\StartsWithTrait¶

Phalcon\Traits\Support\Helper\Str\StartsWithTrait

Reports whether a string starts with a given substring. The comparison is case-insensitive by default and multibyte-aware - both sides are lowercased with mb_strtolower() before the prefix is checked (via the native starts_with()) - and an empty haystack always returns false.

Method

protected function toStartsWith(
    string $haystack,
    string $needle,
    bool $ignoreCase = true
): bool

Parameters

Returns true when $haystack starts with $needle, false otherwise (including when $haystack is empty).

Example

<?php

use Phalcon\Traits\Support\Helper\Str\StartsWithTrait;

class MyRequest
{
    use StartsWithTrait;

    public function isBearer(string $header): bool
    {
        return $this->toStartsWith($header, "Bearer ", false);
    }
}

Str\InterpolateTrait¶

Phalcon\Traits\Support\Helper\Str\InterpolateTrait

Substitutes values from a context array into placeholder tokens in a string - the PSR-3 message-interpolation convention. Each context key is wrapped in the left/right delimiters (both % by default) and replaced with its value using strtr(). An empty context, or a subject that contains no opening delimiter, is returned unchanged.

Method

protected function toInterpolate(
    string $input,
    array $context = [],
    string $left = "%",
    string $right = "%"
): string

Parameters

Returns the interpolated string, or $input unchanged when $context is empty or the subject has no opening delimiter.

Example

<?php

use Phalcon\Traits\Support\Helper\Str\InterpolateTrait;

class MyLogger
{
    use InterpolateTrait;

    public function render(string $message, array $context): string
    {
        // "User 42 logged in" from "User %id% logged in" + ["id" => 42]
        return $this->toInterpolate($message, $context);
    }
}

Str\CamelizeTrait¶

Phalcon\Traits\Support\Helper\Str\CamelizeTrait

Converts a delimited string into camel case - for example camel_case → CamelCase, or camelCase when $lowerFirst is true. It wraps the native Zephir camelize() builtin and, when a lower first letter is requested, applies lcfirst() to the result.

Method

public function toCamelize(
    string $text,
    string $delimiters = "-_",
    bool $lowerFirst = false
): string

Parameters

Returns the camel-cased string - e.g. coco_bongo → CocoBongo, or cocoBongo when $lowerFirst is true.

Example

<?php

use Phalcon\Traits\Support\Helper\Str\CamelizeTrait;

class MyResolver
{
    use CamelizeTrait;

    public function toClassName(string $name): string
    {
        // "gilmore_girls" -> "GilmoreGirls"
        return $this->toCamelize($name);
    }
}

Str\UncamelizeTrait¶

Phalcon\Traits\Support\Helper\Str\UncamelizeTrait

Converts a camel-cased string into a lower-cased, delimited one - for example CamelCase → camel_case. It wraps the native Zephir uncamelize() builtin: every uppercase ASCII letter is lower-cased and preceded by the delimiter (except a leading one, which is only lower-cased).

Method

protected function toUncamelize(
    string $text,
    string $delimiter = "_"
): string

Parameters

Returns the de-camelized string - e.g. myProperty → my_property, or myAction → my-action when called with "-".

Example

<?php

use Phalcon\Traits\Support\Helper\Str\UncamelizeTrait;

class MyResolver
{
    use UncamelizeTrait;

    public function toColumn(string $property): string
    {
        // "firstName" -> "first_name"
        return $this->toUncamelize($property);
    }
}

Str\LowerTrait¶

Phalcon\Traits\Support\Helper\Str\LowerTrait

Lowercases a string in a multibyte-safe way using mb_convert_case() with MB_CASE_LOWER, so accented and other non-ASCII letters are folded correctly.

Method

protected function toLower(
    string $text,
    string $encoding = "UTF-8"
): string

Parameters

Returns the lowercased string.

Example

<?php

use Phalcon\Traits\Support\Helper\Str\LowerTrait;

class MyNormalizer
{
    use LowerTrait;

    public function key(string $value): string
    {
        // "CAFÉ" -> "café"
        return $this->toLower($value);
    }
}

Str\UpperTrait¶

Phalcon\Traits\Support\Helper\Str\UpperTrait

Uppercases a string in a multibyte-safe way using mb_convert_case() with MB_CASE_UPPER, so accented and other non-ASCII letters are folded correctly.

Method

protected function toUpper(
    string $text,
    string $encoding = "UTF-8"
): string

Parameters

Returns the uppercased string.

Example

<?php

use Phalcon\Traits\Support\Helper\Str\UpperTrait;

class MyNormalizer
{
    use UpperTrait;

    public function code(string $value): string
    {
        // "café" -> "CAFÉ"
        return $this->toUpper($value);
    }
}

Php¶

Traits that wrap native PHP functions behind protected methods. Isolating these calls in a method makes them straightforward to override in a test double, so behavior such as filesystem access can be simulated without touching the real environment.

ApcuTrait¶

Phalcon\Traits\Php\ApcuTrait

Provides overridable wrappers around PHP's APCu functions. Each method forwards to the matching apcu_* function; phpApcuIterator() constructs an APCUIterator.

All methods are protected; call them from inside the class with $this->methodName().

Example

<?php

use Phalcon\Traits\Php\ApcuTrait;

class MyStore
{
    use ApcuTrait;

    public function remember(string $key, mixed $value): void
    {
        if (false === $this->phpApcuExists($key)) {
            $this->phpApcuStore($key, $value, 3600);
        }
    }
}

FileTrait¶

Phalcon\Traits\Php\FileTrait

Provides overridable wrappers around PHP's filesystem functions. Each method forwards its arguments to the matching PHP function and returns its result unchanged.

All methods are protected; call them from inside the class with $this->methodName().

Example

<?php

use Phalcon\Traits\Php\FileTrait;

class MyStore
{
    use FileTrait;

    public function save(string $file, string $data): bool
    {
        return false !== $this->phpFilePutContents($file, $data);
    }

    public function load(string $file): string
    {
        if (false === $this->phpFileExists($file)) {
            return "";
        }

        $contents = $this->phpFileGetContents($file);

        return false === $contents ? "" : $contents;
    }
}

HeaderTrait¶

Phalcon\Traits\Php\HeaderTrait

Provides an overridable wrapper around PHP's headers_sent(), so whether the HTTP headers have already been sent can be simulated in a test double.

The method is protected; call it from inside the class with $this->methodName().

Example

<?php

use Phalcon\Traits\Php\HeaderTrait;

class MySession
{
    use HeaderTrait;

    public function start(): bool
    {
        if (true === $this->phpHeadersSent()) {
            return false;
        }

        // ... start the session ...
        return true;
    }
}

IniTrait¶

Phalcon\Traits\Php\IniTrait

Provides overridable wrappers around PHP's ini functions. ini_get() is exposed as three typed getters (string, bool, int), each returning a default when the option is not set; parse_ini_file() is wrapped as-is. Every method has a static counterpart (prefixed static) for callers that have no instance - for example a static factory or a static settings reader.

Both the instance and static methods are protected. Because Zephir cannot call a static method through $this, the pair lets a class read ini values from either an instance context ($this->phpIniGet(...)) or a static one (self::staticPhpIniGet(...)).

Example

<?php

use Phalcon\Traits\Php\IniTrait;

class MyComponent
{
    use IniTrait;

    public function __construct()
    {
        // instance context
        $path = $this->phpIniGet('session.save_path', '/tmp');
    }

    public static function isEnabled(): bool
    {
        // static context - no $this available
        return self::staticPhpIniGetBool('my.feature.enabled');
    }
}

InfoTrait¶

Phalcon\Traits\Php\InfoTrait

Provides overridable wrappers around PHP's runtime-inspection functions. Isolating these checks behind a method lets a test double report an extension or function as present or absent without changing the real environment.

Both methods are protected; call them from inside the class with $this->methodName().

Example

<?php

use Phalcon\Traits\Php\InfoTrait;

class MyComponent
{
    use InfoTrait;

    public function encode(string $value): string
    {
        if (false === $this->phpFunctionExists('mb_convert_case')) {
            return strtoupper($value);
        }

        return mb_convert_case($value, MB_CASE_UPPER);
    }
}

OpensslTrait¶

Phalcon\Traits\Php\OpensslTrait

Provides overridable wrappers around two of PHP's OpenSSL functions, so their results can be substituted in a test double (for example to simulate a failure).

All methods are protected; call them from inside the class with $this->methodName().

Example

<?php

use Phalcon\Traits\Php\OpensslTrait;

class MyCipher
{
    use OpensslTrait;

    public function newIv(string $cipher): string
    {
        $length = (int) $this->phpOpensslCipherIvLength($cipher);

        return $this->phpOpensslRandomPseudoBytes($length);
    }
}

YamlTrait¶

Phalcon\Traits\Php\YamlTrait

Provides an overridable wrapper around PHP's yaml_parse_file(), so YAML file parsing can be substituted in a test double. The function's by-reference $ndocs output is handled by an internal throwaway variable (Zephir cannot declare a by-reference parameter), so it is not part of the method signature.

Method

protected function phpYamlParseFile(
    string $filename,
    int $pos = 0,
    array $callbacks = []
): mixed

Parameters

Returns the parsed value, or false on failure.

Example

<?php

use Phalcon\Traits\Php\YamlTrait;

class MyConfig
{
    use YamlTrait;

    public function load(string $file): array
    {
        $data = $this->phpYamlParseFile($file);

        return is_array($data) ? $data : [];
    }
}

Base64Trait¶

Phalcon\Traits\Php\Base64Trait

Wrappers around PHP's base64 functions, plus helpers for the URL-safe "base64url" variant (used by JWT and similar).

Example

<?php

use Phalcon\Traits\Php\Base64Trait;

class MyToken
{
    use Base64Trait;

    public function segment(string $json): string
    {
        return $this->doEncodeUrl($json); // URL-safe, unpadded
    }
}

IgbinaryTrait¶

Phalcon\Traits\Php\IgbinaryTrait

Overridable wrappers around the igbinary extension's functions, so igbinary (de)serialization can be substituted in tests.

MsgpackTrait¶

Phalcon\Traits\Php\MsgpackTrait

Overridable wrappers around the msgpack extension's functions.

SerializeTrait¶

Phalcon\Traits\Php\SerializeTrait

Overridable wrappers around PHP's native serialize()/unserialize().