<?php
/**
 * Copyright 2018 Google Inc.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

namespace Google\Cloud\Spanner;

/**
 * Represents a Struct Query Parameter type declaration.
 *
 * Example:
 * ```
 * use Google\Cloud\Spanner\StructType;
 * use Google\Cloud\Spanner\Database;
 * use Google\Cloud\Spanner\SpannerClient;
 *
 * $spanner = new SpannerClient();
 * $database = $spanner->connect('my-instance', 'my-database');
 *
 * $res = $database->execute('SELECT @userStruct.firstName, @userStruct.lastName', [
 *     'parameters' => [
 *         'userStruct' => [
 *             'firstName' => 'John',
 *             'lastName' => 'Testuser'
 *         ]
 *     ],
 *     'types' => [
 *         'userStruct' => (new StructType())
 *             ->add('firstName', Database::TYPE_STRING)
 *             ->add('lastName', Database::TYPE_STRING)
 *     ]
 * ])->rows()->current();
 *
 * $fullName = $res['firstName'] . ' ' . $res['lastName']; // `John Testuser`
 * ```
 */
class StructType
{
    /**
     * @var array
     */
    private $fields = [];

    /**
     * Example:
     * ```
     * use Google\Cloud\Spanner\ArrayType;
     * use Google\Cloud\Spanner\Database;
     * use Google\Cloud\Spanner\StructType;
     *
     * $structType = new StructType([
     *     [
     *         'name' => 'stringField',
     *         'type' => Database::TYPE_STRING
     *     ],
     *     [
     *         'name' => 'arrayField',
     *         'type' => Database::TYPE_ARRAY,
     *         'child' => new ArrayType(Database::TYPE_STRING)
     *     ]
     * ]);
     * ```
     *
     * @param array[] $fields An array containing a field definition. Each field
     *        must be of form `[(string|null) $name, (int) $type, (ArrayType|StructType|null) $child]`.
     */
    public function __construct(array $fields = [])
    {
        foreach ($fields as $field) {
            $field += [
                'name' => null,
                'type' => null,
                'child' => null
            ];

            $type = $field['child'] === null
                ? $field['type']
                : $field['child'];

            $this->add($field['name'], $type);
        }
    }

    /**
     * Add a struct field definition.
     *
     * Unnamed struct fields may be defined by providing `null` as the first
     * argument value, however you may find it more convenient to use the provided
     * {@see Google\Cloud\Spanner\StructType::addUnnamed()} method.
     *
     * Example:
     * ```
     * $structType->add('firstName', Database::TYPE_STRING);
     * ```
     *
     * ```
     * // If a field is a struct or array, it must be explicitly defined.
     * use Google\Cloud\Spanner\ArrayType;
     * use Google\Cloud\Spanner\Database;
     * use Google\Cloud\Spanner\StructType;
     *
     * // Create a struct which will be nested later.
     * $customer = (new StructType)
     *     ->add('name', Database::TYPE_STRING)
     *     ->add('phone', Database::TYPE_STRING)
     *     ->add('email', Database::TYPE_STRING)
     *     ->add('lastOrderDate', Database::TYPE_DATE);
     *
     * // Create an array to nest within the customer type definition.
     * $orderIds = new ArrayType(Database::TYPE_INT64);
     * $customer->add('orderIds', $orderIds);
     *
     * // Add the customer definition to the parameter definition.
     * $structType->add('customer', $customer);
     * ```
     *
     * @param string|null $name The field name.
     * @param int|ArrayType|StructType $type $type A value type code or nested
     *        struct or array definition. Accepted integer values are defined as
     *        constants on {@see Google\Cloud\Spanner\Database}, and are as
     *        follows: `Database::TYPE_BOOL`, `Database::TYPE_INT64`,
     *        `Database::TYPE_FLOAT64`, `Database::TYPE_TIMESTAMP`,
     *        `Database::TYPE_DATE`, `Database::TYPE_STRING` and
     *        `Database::TYPE_BYTES`
     * @return StructType The current instance, for chaining additional field
     *        definitions.
     * @throws \InvalidArgumentException If an invalid type is provided.
     */
    public function add($name, $type)
    {
        $invalidIntTypes = [
            Database::TYPE_STRUCT,
            Database::TYPE_ARRAY
        ];

        if (is_int($type) && in_array($type, $invalidIntTypes)) {
            throw new \InvalidArgumentException(
                '`Database::TYPE_ARRAY` and `Database::TYPE_STRUCT` are not valid as struct types. ' .
                'Instead provide `Google\Cloud\Spanner\ArrayType` or `Google\Cloud\Spanner\StructType`.'
            );
        }

        $child = null;
        if ($type instanceof StructType) {
            $child = $type;
            $type = Database::TYPE_STRUCT;
        } elseif ($type instanceof ArrayType) {
            $child = $type;
            $type = Database::TYPE_ARRAY;
        }

        if (!in_array($type, ValueMapper::$allowedTypes)) {
            throw new \InvalidArgumentException(sprintf(
                'Field type `%s` is not valid.',
                $type
            ));
        }

        $this->fields[] = [
            'name' => $name,
            'type' => $type,
            'child' => $child
        ];

        return $this;
    }

    /**
     * Add a struct field with no name.
     *
     * Example:
     * ```
     * $structType->addUnnamed(Database::TYPE_STRING);
     * ```
     *
     * @param int|ArrayType|StructType $type $type A value type code or nested
     *        struct or array definition. Accepted integer values are defined as
     *        constants on {@see Google\Cloud\Spanner\Database}, and are as
     *        follows: `Database::TYPE_BOOL`, `Database::TYPE_INT64`,
     *        `Database::TYPE_FLOAT64`, `Database::TYPE_TIMESTAMP`,
     *        `Database::TYPE_DATE`, `Database::TYPE_STRING` and
     *        `Database::TYPE_BYTES`
     * @return StructType The current instance, for chaining additional field
     *        definitions.
     * @throws \InvalidArgumentException If an invalid type is provided.
     */
    public function addUnnamed($type)
    {
        return $this->add(null, $type);
    }

    /**
     * Fetch the defined fields list.
     *
     * @access private
     * @return array[] An array containing a field definition. Each field
     *        is of form `[(string|null) $name, (int) $type, (ArrayType|StructType|null) $child]`.
     */
    public function fields()
    {
        return $this->fields;
    }
}