inspirum/arrayable

PHP arrayable interface for handling casting to an array

v1.3.0 2024-09-05 11:29 UTC

This package is auto-updated.

Last update: 2024-11-21 14:18:55 UTC


README

Latest Stable Version Build Status Coverage Status Quality Score PHPStan Total Downloads Software License

Motivation

Unfortunately PHP does not have a nice way how to typecast objects to array.

There is the __toString() magic method for \Stringable interface (since PHP 8.0) and the jsonSerialize() method for \JsonSerializable interface (since PHP 5.4), but __toArray() method is not (and will not) be supported – there are just several rejected draft RFC (object_cast_to_types, to array, ...) that suggests some kind of object to scalar type casting.

But so far (at least) there is no way to implement some (not even magic) method to be called when cast to array.

Ideally, something like this would work:

class Person
{
    public function __construct(
        public string $name,
        protected string $username,
        private string $password,
    ) {}
 
    public function __toArray(): array
    {
        return [
            'name' => $this->name,
            'email' => $this->username,
        ];
    }
}

$person = new Person('John Doe', 'j.doe@example.com', 'secret_pwd');

$personArray = (array) $person; // casting triggers __toArray()

/**
var_dump($personArray);
[
  'name' => 'John Doe'
  'email' => 'j.doe@example.com'
]
*/

but actually it cast to array like this:

/**
var_dump($personArray);
[
  'name' => 'John Doe'
  '*username' => 'j.doe@example.com'
  'Person@password' => 'secret_pwd'
]
*/

Usage example

All the code snippets shown here are modified for clarity, so they may not be executable.

This package implements simple \Arrayable (or \Inspirum\Arrayable\Arrayable) interface.

/** @implements \Arrayable<string, string> */
class Person implements \Arrayable
{
    public function __construct(
        public string $name,
        protected string $username,
        protected string $password,
    ) {}
 
    /** @return array<string, string> */
    public function __toArray(): array
    {
        return [
            'name' => $this->name,
            'email' => $this->username,
        ];
    }
}

$person = new Person('John Doe', 'j.doe@example.com', 'secret_pwd');

There is \is_arrayable() function (or \Inspirum\Arrayable\Convertor::isArrayable() method) to check if given data are able to type cast itself to array.

var_dump(\is_arrayable([1, 2, 3])); // bool(true)
var_dump(\is_arrayable(new \ArrayIterator([1, 2, 3]))); // bool(true)
var_dump(\is_arrayable(new \ArrayObject([4, 5, 6]))); // bool(true)
var_dump(\is_arrayable((function () { yield 1; })())); // bool(true)
var_dump(\is_arrayable(1)); // bool(false)
var_dump(\is_arrayable(new \stdClass())); // bool(false)
var_dump(\is_arrayable(new class {})); // bool(false)
var_dump(\is_arrayable(new class implements \Arrayable {})); // bool(true)
var_dump(\is_arrayable($person); // bool(true)

Then there is \to_array() function (or \Inspirum\Arrayable\Convertor::toArray() method) to recursively cast data to array.

$data = \to_array(new \ArrayIterator([1, $person, (object) ['a' => true]]));

/**
var_dump($data);
[
  0 => 1
  1 => [ 
    'name' => 'John Doe'
    'email' => 'j.doe@example.com'
  ]
  2 => [
   'a' => true
  ]
*/

There is also helper abstract classes for common use for DAO (BaseModel) and collection (BaseCollection) objects.

System requirements

Installation

Run composer require command

$ composer require inspirum/arrayable

Testing

To run unit tests, run:

$ composer test:test

To show coverage, run:

$ composer test:coverage

Contributing

Please see CONTRIBUTING and CODE_OF_CONDUCT for details.

Security

If you discover any security related issues, please email tomas.novotny@inspirum.cz instead of using the issue tracker.

Credits

License

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