VArray.php

<?php

declare(strict_types=1);

namespace Vection\Component\Common;

use ArrayAccess;
use Countable;
use Iterator;
use JsonSerializable;
use LogicException;
use Vection\Component\Common\Exception\IOException;
use Vection\Component\Common\Exception\RuntimeException;
use Vection\Contracts\Validator\Schema\PropertyExceptionInterface;
use Vection\Contracts\Validator\Schema\SchemaExceptionInterface;
use Vection\Contracts\Validator\Schema\SchemaValidatorInterface;

/**
 * Class VArray
 *
 * @package Vection\Component\Common
 * @author  David Lung <david.lung@appsdock.de>
 */
class VArray implements Countable, ArrayAccess, Iterator, JsonSerializable
{
    /** @var mixed[] */
    protected array $data;
    protected bool  $immutable;

    # region Parsing

    /**
     * Reads the structured content of a file and returns a
     * VArray instance which contains the data from the file.
     *
     * @param string $filePath A JSON or Yaml formatted file.
     * @param bool   $immutable
     *
     * @return VArray
     */
    public static function parseFile(string $filePath, bool $immutable = false): VArray
    {
        if (!is_file($filePath)) {
            throw new RuntimeException("VArray::fromFile(): File does not exist ($filePath).");
        }

        if (!in_array($ext = pathinfo($filePath, PATHINFO_EXTENSION), ['json', 'yaml', 'yml'])) {
            throw new RuntimeException('Unsupported file format. Supported formats are json, yaml.');
        }

        $content = file_get_contents($filePath);

        if ($content === false) {
            throw new IOException("VArray::fromFile: Unable to read file ($filePath).");
        }

        if (in_array($ext, ['yaml', 'yml'])) {
            return self::parseYAML($content, $immutable);
        }

        if ($ext === 'json') {
            return self::parseJSON($content, $immutable);
        }

        return new VArray();
    }

    /**
     * @param string $yaml
     * @param bool   $immutable
     *
     * @return VArray
     */
    public static function parseYAML(string $yaml, bool $immutable = false): VArray
    {
        return Yaml::parse($yaml, $immutable);
    }

    /**
     * @param string $json
     * @param bool   $immutable
     *
     * @return VArray
     */
    public static function parseJSON(string $json, bool $immutable = false): VArray
    {
        return Json::parse($json, $immutable);
    }

    # endregion

    /**
     * @param mixed[] $data
     * @param bool    $immutable
     */
    public function __construct(array $data = [], bool $immutable = false)
    {
        $this->data = $data;
        $this->immutable = $immutable;
    }

    # region VArray Methods

    /**
     * @param mixed[] $value
     *
     * @return VArray
     */
    public function add(mixed $value): VArray
    {
        $this->assertMutable();
        $this->data[] = $value;

        return $this;
    }

    /**
     * @param string $key
     * @param mixed  $value
     *
     * @return VArray
     */
    public function set(string $key, mixed $value): VArray
    {
        $this->assertMutable();
        $this->data[$key] = $value;

        return $this;
    }

    /**
     * @param string $key
     * @param bool   $usePathNotation
     *
     * @return mixed
     */
    public function get(string $key, bool $usePathNotation = true): mixed
    {
        return strpos($key, '.') > -1 && $usePathNotation ? $this->pathGet($this->data, $key) : ($this->data[$key] ?? null);
    }

    /**
     * @param mixed[] $data
     * @param string  $name
     *
     * @return mixed|null
     */
    private function pathGet(array $data, string $name): mixed
    {
        $parts = explode('.', $name);

        if (!array_key_exists($key = array_shift($parts), $data)) {
            return null;
        }

        $data = $data[$key];
        $name = implode('.', $parts);

        if ($name && is_array($data)) {
            return $this->pathGet($data, $name);
        }

        return $data;
    }

    /**
     * @param string $key
     *
     * @return bool
     */
    public function hasKey(string $key): bool
    {
        return array_key_exists($key, $this->data);
    }

    /**
     * @return mixed
     */
    public function first(): mixed
    {
        $index = array_keys($this->data)[0] ?? null;
        return $index ? $this->data[$index] : null;
    }

    /**
     * @return mixed
     */
    public function last(): mixed
    {
        if ($keys = array_keys($this->data)) {
            $index = $keys[count($keys) - 1];
            return $this->data[$index];
        }

        return null;
    }

    /**
     * @return mixed
     */
    public function shift(): mixed
    {
        return array_shift($this->data);
    }

    /**
     * @return mixed
     */
    public function pop(): mixed
    {
        return array_pop($this->data);
    }

    /**
     *
     */
    public function map(callable $function): VArray
    {
        $result = [];

        foreach ($this->data as $key => $element) {
            $result[$key] = $function($element, $key, $this);
        }

        return new self($result, $this->immutable);
    }

    private function assertMutable(): void
    {
        if ($this->immutable === true){
            throw new LogicException('An immutable collection cannot be changed.');
        }
    }

    public function toArray(): array
    {
        return $this->data;
    }

    # endregion

    # region Advanced Methods

    /**
     * @throws SchemaExceptionInterface
     * @throws PropertyExceptionInterface
     */
    public function validate(SchemaValidatorInterface $schemaValidator): void
    {
        $schemaValidator->validateArray($this->data);
    }

    # endregion

    # region ArrayAccess

    /**
     * @inheritDoc
     */
    public function offsetExists($offset): bool
    {
        return isset($this->data[$offset]);
    }

    /**
     * @inheritDoc
     */
    public function &offsetGet($offset): mixed
    {
        return $this->data[$offset];
    }

    /**
     * @inheritDoc
     */
    public function offsetSet($offset, $value): void
    {
        $this->assertMutable();
        $this->data[$offset] = $value;
    }

    /**
     * @inheritDoc
     */
    public function offsetUnset($offset): void
    {
        $this->assertMutable();
        unset($this->data[$offset]);
    }

    # endregion

    # region Iterator

    /**
     * @inheritDoc
     */
    public function key(): mixed
    {
        return key($this->data);
    }

    /**
     * @inheritDoc
     */
    public function current(): mixed
    {
        return current($this->data);
    }

    /**
     * @inheritDoc
     */
    public function valid(): bool
    {
        return array_key_exists(key($this->data), $this->data);
    }

    /**
     * @inheritDoc
     */
    public function rewind(): void
    {
        reset($this->data);
    }

    /**
     * @inheritDoc
     */
    public function next(): void
    {
        next($this->data);
    }

    # endregion

    # region Interfaces

    /**
     * @inheritDoc
     */
    public function count(): int
    {
        return count($this->data);
    }

    /**
     * @inheritDoc
     */
    public function jsonSerialize(): mixed
    {
        return $this->data;
    }

    # endregion

    # region Magic Methods

    public function &__get(string $name): mixed
    {
        return $this->data[$name];
    }

    public function __set(string $name, mixed $value): void
    {
        $this->assertMutable();
        $this->set($name, $value);
    }

    public function __isset(string $name): bool
    {
        return isset($this->data[$name]);
    }

    public function __toString()
    {
        return "VArray({$this->count()})";
    }

    # endregion
}