README

Cast for Laravel

This package provide cast for Laravel.

Version Compatibility

Installation

You can install the package via composer:

composer require jn-jairo/laravel-cast

The CastServiceProvider will be automatically registered for you.

Usage

Both contract \JnJairo\Laravel\Cast\Contracts\Cast and facade \JnJairo\Laravel\Cast\Facades\Cast are available.

There are three methods Cast::cast(), Cast::castDb() and Cast::castJson().

Cast::cast() casts to PHP types
Cast::castDb() casts to database types
Cast::castJson() casts to json types

All methods accept three parameters mixed $value, string $type and optionally string $format.

Examples

print_r(Cast::cast('{"foo":"bar"}', 'array'));
/*
Array
(
    [foo] => bar
)
*/

print_r(Cast::castDb(1234.555, 'decimal', '10:2'));
// 1234.56

print_r(Cast::castDb(['foo' => 'bar'], 'json'));
// {"foo":"bar"}

print_r(Cast::castJson(new DateTime('01 jan 2000'), 'date'));
// 2000-01-01

Types available

int, integer
float, real, double
decimal
bool, boolean
date
datetime
timestamp
json
array
object
collection
string, text
uuid
encrypted
compressed
base64
pipe
enum

Format parameter

decimal - precision:places,(up|down|ceiling|floor|half_up|half_down|half_even|half_odd|truncate). Example: 10:2,half_up, 10:2, 2, half_up. Default: 28:2,half_up. The decimal type uses the https://php-decimal.io extension, to use this type run composer require php-decimal/php-decimal:^1.1 and install the decimal extension.
date - Example: Y-m-d. Default: Y-m-d.
datetime, timestamp - Example: Y-m-d H:i:s. Default: Y-m-d H:i:s.
uuid - (uuid1|uuid4|ordered). Example: uuid1. Default: uuid4. Empty string value will return a new UUID. To use ordered UUID format run composer require moontoast/math:^1.1.
encrypted - (one|all),base64:key,cipher. Empty key and cipher uses the laravel configuration app.key and app.cipher. Example: base64:N38XBrdzg505959nDEqefo6fNpeTmGy0wTBHRSxrpcQ=,aes-256-cbc. Default: one.
- one - allow double encryption, decrypts only one time.
- all - prevents double encryption, decrypts recursively all encryptions.

$decrypted = Cast::cast($encrypted, 'encrypted');
$encrypted = Cast::castDb($decrypted, 'encrypted');
$decrypted = Cast::castJson($encrypted, 'encrypted');

compressed - (always|smaller),(one|all),level,(raw|deflate|gzip). Example: smaller,all,9,gzip. Default: always,one,-1,raw.
- always - always uses the result of compression even if the result is bigger than the original value.
- smaller - only uses the result of compression if the result is smaller than the original value.
- one - allow double compression, decompresses only one time.
- all - prevents double compression, decompresses recursively all compressions.
- level - level of compression, from 0 (no compression) to 9 (maximum compression). If -1 is used, the default compression of the zlib library is used.
- raw - uses the encoding ZLIB_ENCODING_RAW with gzdeflate and gzinflate.
- deflate - uses the encoding ZLIB_ENCODING_DEFLATE with gzcompress and gzuncompress.
- gzip - uses the encoding ZLIB_ENCODING_GZIP with gzencode and gzdecode.

$decompressed = Cast::cast($compressed, 'compressed');
$compressed = Cast::castDb($decompressed, 'compressed');
$decompressed = Cast::castJson($compressed, 'compressed');

base64 - (one|all),prefix. Example: base64:. Default: one.
- one - allow double encoding, decodes only one time.
- all - prevents double encoding, decodes recursively all encodings (requires prefix).

$decoded = Cast::cast('base64:Rm9vQmFy', 'base64', 'base64:'); // FooBar
$encoded = Cast::castDb('FooBar', 'base64', 'base64:'); // base64:Rm9vQmFy
$decoded = Cast::castJson('base64:Rm9vQmFy', 'base64', 'base64:'); // FooBar

pipe - |type:format|type:format|...|direction. Example: |encrypted|compressed|array|. Default: ||php:>,db:<,json:>.
- The direction format is >|<|php:(>|<),db:(>|<),json:(>|<), > follows from left to right and < follows from right to left.
- The first character is used as the type separator, for the other separators in case of conflict with the type separator the | separator is used.
- Examples of valid parameters:
  |encrypted|array|
  |encrypted|array|<
  |encrypted|array|>,db:<
  |encrypted|decimal:2|php:>,db:<,json:>
  ,encrypted,decimal:2,php:>|db:<|json:>
  :encrypted:decimal|2:php|>,db|<,json|>

$array = Cast::cast('q1ZKy89XslJKSixSqgUA', 'pipe', '|base64|compressed|array|'); // ['foo' => 'bar']
$base64Compressed = Cast::castDb(['foo' => 'bar'], 'pipe', '|base64|compressed|array|'); // q1ZKy89XslJKSixSqgUA
$array = Cast::castJson('q1ZKy89XslJKSixSqgUA', 'pipe', '|base64|compressed|array|'); // ['foo' => 'bar']

enum - Example: MyEnum::class. Default: .

enum MyEnum : int
{
    case foo = 1;
    case bar = 2;
}

Cast::cast(1, 'enum', MyEnum::class); // MyEnum::foo
Cast::castDb(MyEnum::foo, 'enum', MyEnum::class); // 1
Cast::castJson(MyEnum::foo, 'enum', MyEnum::class); // 1

It can be a instance of \Illuminate\Contracts\Support\Arrayable or \Illuminate\Contracts\Support\Jsonable.

use Illuminate\Contracts\Support\Arrayable;

enum MyEnum : string implements Arrayable
{
    case foo = 1;
    case bar = 2;

    public function description() : string
    {
        return match ($this) {
            self::foo => 'foo description',
            self::bar => 'bar description',
        };
    }

    public function toArray()
    {
        return [
            'name' => $this->name,
            'value' => $this->value,
            'description' => $this->description(),
        ];
    }
}

Cast::cast(1, 'enum', MyEnum::class); // MyEnum::foo
Cast::castDb(MyEnum::foo, 'enum', MyEnum::class); // 1
Cast::castJson(MyEnum::foo, 'enum', MyEnum::class);
// [
//      'name' => 'foo',
//      'value' => 1,
//      'description' => 'foo description'
// ]

Custom types

To create a custom type just implements the contract \JnJairo\Laravel\Cast\Contracts\Type.

class CustomType implements \JnJairo\Laravel\Cast\Contracts\Type
{
    // ...
}

Or extends the \JnJairo\Laravel\Cast\Types\Type abstract class.

class CustomType extends \JnJairo\Laravel\Cast\Types\Type
{
    // ...
}

Publish the configuration to config/cast.php.

php artisan vendor:publish --provider=JnJairo\\Laravel\\Cast\\CastServiceProvider

Set the new type in the configuration.

// config/cast.php

return [
    'types' => [
        'custom_type' => CustomType::class,
    ],
];

And the custom type will be available.

Cast::cast('foo', 'custom_type');

License

The MIT License (MIT). Please see License File for more information.

jn-jairo / laravel-cast

Maintainers

Details