V2 (#1)

* introduce new functions to retrieve formerly set parameters and remove parameters from invoke()

* introduce possibility to descript the remote function API

* add constants and move value interface to common element interface

* new API element hierarchy: value-element-array

* Rename Interfaces and add comments for better understanding

* Add exception for missing table elements

* rename table element missing exception to array

* add API interface and make API JSON serializeable

Use API interface as return value and parameter for the API methods of
the function interface. Make element interface JSON serializable and
thus all children too.

* add methods for adding API elements, values and arrays.

* move IArray specific constants from IElement and IValue

* combine all add() methods of the api interface

* add json decode static functions

* add json configuration keys

* update comments of API specific methods.

* add data types hex-bin and DateTime

* split DateTime data type into date and time.

* split hexbin to hex2bin and bin2hex for input and output directions

The type would depend on the master type being either an input- or
output- value. Tables are considered output values.

* add virtual timestamp and week data types

* update comments

* rename const hex2bin to hexbin

* fix typo

* refactor configuration interfaces

* Add JSON_* variables to be used for JSON encoded configurations.
* Move methods handling the configuration to a separate interface.
* Move configuration interfaces to a subdirectory.
* Remove const TYPE from interfaces (the class names should do fine).
* Remove incomplete configuration exception from configuration
interfaces. This validation is expected to be job of the actual
implementation.
* Introduce jsonDecode() method as pendant to \JsonSerializeable
interface.

* refactor connection interface

* Make connection JSON serializeable.
* Add methods to retrieve the configuration class.
* Remove getId() method.
* Remove connect() isConnected() and close() methods because this should
be handled by the actual implementation internally.
* Remove ping() methods, because this is essentially a function call.

* add JSON serialization of functions

* add missing exceptions, reduce jsonDecode to string, update comments

* unify comments

* fix error in comment

* overwrite cast() method for arrays

* remove IConfiguration::getValidConfigKeys()

* add JsonSerializable interface

* Make all classes children of IJsonSerializable

* make IFunction \JsonSerializable

IJsonSerializable doesn't work because jsonDecode() requires a
connection configuration as mandatory parameter to correctly decode a
function.

* remove addMember() from Api\IArray

* remove connection class and adapt function class for configuration

* rename retrieveApi() to extractApi()

* fix line length

* rename reset() to resetParams() and add missing exceptions

* update comments

* remove typecasting from IApi

* Change default return of get*() in config class to null except for mandatory fields.

* change order of methods and constants to reflect mandatory and optional properties

* unify PHPdoc of methods

* unify PHPdoc of methods

* remove setParam() method and add the missing exceptions

* fix typos and comments

* fix typos and comments

* fix typos and comments

* update readme to v2

* set PHP versions

README.md

@@ -4,8 +4,5 @@
 
 This repository defines interfaces for implementing the [PHP/SAP][phpsap] API.
 
-[See PHP/SAP Interfaces for documentation][doc]
-
 [phpsap]: https://php-sap.github.io
 [license-mit]: https://img.shields.io/badge/license-MIT-blue.svg
-[doc]: https://php-sap.github.io/interfaces "Interfaces | PHP/SAP"

composer.json

@@ -11,9 +11,6 @@
     }
   ],
   "homepage": "https://php-sap.github.io",
-  "support": {
-    "docs": "https://php-sap.github.io/interfaces"
-  },
   "keywords": [
     "phpsap",
     "php-sap",
@@ -24,7 +21,8 @@
   },
   "minimum-stability": "stable",
   "require": {
-    "php": ">=5.5.0"
+    "php": "^5.5|^7.0",
+    "ext-json": "*"
   },
   "autoload": {
     "psr-4": {

src/Api/IApi.php

@@ -0,0 +1,44 @@
+<?php
+
+namespace phpsap\interfaces\Api;
+
+use phpsap\interfaces\Util\IJsonSerializable;
+
+/**
+ * Interface IApi
+ *
+ * Describes the SAP remote function API. To be precise it describes the SAP remote
+ * function call parameters (input), the returns (output) and the tables (input/
+ * output).
+ *
+ * @package phpsap\interfaces
+ * @author  Gregor J.
+ * @license MIT
+ */
+interface IApi extends IJsonSerializable
+{
+    /**
+     * Add a value, struct or table of the remote function.
+     * @param \phpsap\interfaces\Api\IValue $value
+     * @return $this
+     */
+    public function add(IValue $value);
+
+    /**
+     * Get all input values of the remote function.
+     * @return \phpsap\interfaces\Api\IValue[]
+     */
+    public function getInputValues();
+
+    /**
+     * Get all output values of the remote function.
+     * @return \phpsap\interfaces\Api\IValue[]
+     */
+    public function getOutputValues();
+
+    /**
+     * Get all tables of the remote function.
+     * @return \phpsap\interfaces\Api\IArray[]
+     */
+    public function getTables();
+}

src/Api/IArray.php

@@ -0,0 +1,45 @@
+<?php
+
+namespace phpsap\interfaces\Api;
+
+/**
+ * Interface IArray
+ *
+ * API extend the logic of values but contain member elements.
+ *
+ * @package phpsap\interfaces\Api
+ * @author  Gregor J.
+ * @license MIT
+ */
+interface IArray extends IValue
+{
+    /**
+     * API table element.
+     */
+    const DIRECTION_TABLE = 'table';
+
+    /**
+     * API element that casts to PHP array.
+     */
+    const TYPE_ARRAY = 'array';
+
+    /**
+     * JSON configuration key for members array.
+     */
+    const JSON_MEMBERS = 'members';
+
+    /**
+     * Cast a given output value to the implemented value.
+     * @param array $struct The output array to typecast.
+     * @return array
+     * @throws \phpsap\interfaces\exceptions\IArrayElementMissingException
+     * @throws \phpsap\interfaces\exceptions\IInvalidArgumentException
+     */
+    public function cast($struct);
+
+    /**
+     * Return an array of member elements.
+     * @return \phpsap\interfaces\Api\IElement[]
+     */
+    public function getMembers();
+}

src/Api/IElement.php

@@ -0,0 +1,94 @@
+<?php
+
+namespace phpsap\interfaces\Api;
+
+use phpsap\interfaces\Util\IJsonSerializable;
+
+/**
+ * Interface IElement
+ *
+ * API elements are struct or table members and have no direction or optional flag
+ * of their own.
+ *
+ * @package phpsap\interfaces\Api
+ * @author  Gregor J.
+ * @license MIT
+ */
+interface IElement extends IJsonSerializable
+{
+    /**
+     * API element that casts to PHP string.
+     */
+    const TYPE_STRING = 'string';
+
+    /**
+     * API element that casts to PHP int.
+     */
+    const TYPE_INTEGER = 'int';
+
+    /**
+     * API element that casts to PHP bool.
+     */
+    const TYPE_BOOLEAN = 'bool';
+
+    /**
+     * API element that casts to PHP float.
+     */
+    const TYPE_FLOAT = 'float';
+
+    /**
+     * API element that casts to a hexadecimal encoded binary to a binary.
+     * (direction: output)
+     */
+    const TYPE_HEXBIN = 'hexbin';
+
+    /**
+     * API date element that casts to a DateTime object.
+     */
+    const TYPE_DATE = 'date';
+
+    /**
+     * API time element that casts to a DateTime object.
+     */
+    const TYPE_TIME = 'time';
+
+    /**
+     * API virtual timestamp element (e.g. string) that casts to a DateTime object.
+     */
+    const TYPE_TIMESTAMP = 'timestamp';
+
+    /**
+     * API virtual calendar week element (e.g. string) that casts to a DateTime object.
+     */
+    const TYPE_WEEK = 'week';
+
+    /**
+     * JSON configuration key for type value.
+     */
+    const JSON_TYPE = 'type';
+
+    /**
+     * JSON configuration key for name value.
+     */
+    const JSON_NAME = 'name';
+
+    /**
+     * The PHP type of the element.
+     * @return string
+     */
+    public function getType();
+
+    /**
+     * The name of the element.
+     * @return string
+     */
+    public function getName();
+
+    /**
+     * Cast a given output value to the implemented value.
+     * @param bool|int|float|string $value The output to typecast.
+     * @return bool|int|float|string|\phpsap\DateTime\SapDateTime
+     * @throws \phpsap\interfaces\exceptions\IInvalidArgumentException
+     */
+    public function cast($value);
+}

src/Api/IValue.php

@@ -0,0 +1,49 @@
+<?php
+
+namespace phpsap\interfaces\Api;
+
+/**
+ * Interface IValue
+ *
+ * API values extend the logic of an element but have a direction (input or output)
+ * and an optional flag, unlike elements.
+ *
+ * @package phpsap\interfaces\Api
+ * @author  Gregor J.
+ * @license MIT
+ */
+interface IValue extends IElement
+{
+    /**
+     * API input element.
+     */
+    const DIRECTION_INPUT = 'input';
+
+    /**
+     * API output element.
+     */
+    const DIRECTION_OUTPUT = 'output';
+
+    /**
+     * JSON configuration key for direction value.
+     */
+    const JSON_DIRECTION = 'direction';
+
+    /**
+     * JSON configuration key for is optional flag.
+     */
+    const JSON_OPTIONAL = 'optional';
+
+    /**
+     * Get the direction of the parameter.
+     * interface.
+     * @return string
+     */
+    public function getDirection();
+
+    /**
+     * Is the element optional?
+     * @return bool
+     */
+    public function isOptional();
+}