start with a project description

Author: gregor-j

index.md

@@ -1,44 +1,23 @@
-**ATTENTION: THIS IS WORK IN PROGRESS AND NOT TO BE USED UNTIL THIS MESSAGE DISAPPEARS!**
+**ATTENTION: THIS IS WORK IN PROGRESS AND NOT TO BE USED UNTIL THIS MESSAGE
+ DISAPPEARS!**
 
 ## What is this?
 
-PHP/SAP defines an layer of abstraction between actual SAP remote function calls and your PHP-Code. Therefore PHP/SAP provides three types of interfaces for abstraction:
-1. Configuring a connection to an SAP application server.
-2. Connecting to an SAP application server
-3. Calling a remote function on an SAP application server.
+PHP/SAP defines a layer of abstraction between actual SAP remote function calls
+ and your PHP-Code. As to why this project was created, you can read the
+ [motivation](motivation).
 
-## The motivation
+[![PHP/SAP](res/php-sap.png)](res/php-sap.svg)
 
-In case you have legacy code written for PHP <= 5.x using a PHP module to call SAP remote functions, and you need to update this code to a PHP version >= 7.x, this project is for you.
+The [interfaces][interfaces] define a common denominator on how to configure a
+ connection to SAP, prepare a SAP remote function call, and invoke a SAP remote
+ function call.
 
-There are currently several open source PHP modules available that are compiled using the SAP RFC SDK or SAP Netweaver RFC SDK. Each one of them handles the main tasks, connecting and calling a remote function, quite differently. To complicate things, none of them are available for old and new versions of PHP.
+The [common classes and exceptions][common] add logic that is not specific to
+ the underlying PHP module.
 
-In order to clean this up, you need to remove the dependency of your PHP code on one of these modules. After that you will be able to switch between modules and PHP versions without the need to touch your code calling SAP remote functions.
+The module specific implementations contain code that is specific to [the
+ underlying PHP-module](php-modules).
 
-```php
-<?php
-//stored configuration, JSON encoded
-$config = '{
-    "ashost": "sap.example.com",
-    "sysnr": "001",
-    "client": "01",
-    "user": "username",
-    "passwd": "password"
-}';
-//establish a connection using the stored configuration
-$connection = new SapRfcConnection(new SapRfcConfigA($config));
-//prepare a function call
-$function = $connection->prepareFunction('remoteFunctionName');
-//call the remote function
-$result = $function->invoke(['paramName' => 'value']);
-```
-
-## PHP SAP RFC modules
-
-I am aware of the following three PHP modules.
-
-author        | module Name | supported PHP versions | composer package
-------------- | ----------- | ---------------------- | ----------------------
-Eduard Koucky | `saprfc`    | PHP 4.x - 5.5.x        | `phpsap/saprfc-koucky`
-Piers Haring  | `sapnwrfc`  | PHP 5.x                | `phpsap/saprfc-harding`
-Gregor Kralik | `sapnwrfc`  | PHP 7.x                | `phpsap/saprfc-kralik`
+[interfaces]: https://github.com/php-sap/interfaces "Interfaces for implementing the PHP/SAP API."
+[common]: https://github.com/php-sap/common "Exceptions and abstract classes containing logic for PHP/SAP that is not specific to the underlying PHP module."

motivation.md

@@ -0,0 +1,44 @@
+## The motivation
+
+I inherited a project running on PHP 5.5.x containing undocumented code dealing
+ with SAP remote function calls. As a way to connect, [Eduard Kouckys SAPRFC
+ module][koucky] had been used. In order to switch to a more current PHP
+ version, I had to replace the PHP module too. The question was: How can I be
+ sure, that the code of this project dealing with SAP remote function calls
+ will not be the source of errors? That lead to the following requirements:
+
+1. Any code dealing with the actual PHP module has to be simple in order to
+   reduce the risk of errors.
+2. The code in my project dealing with SAP remote function calls has to work
+   for several [PHP modules](php-modules) and it still has to work, in case
+   of a switch to a different way of communicating with SAP.
+3. Any in- and output of a SAP remote function call has to be defined as
+   methods as a way of documentation.
+4. The configuration has to be as interchangeable as possible between the PHP
+   modules.
+
+Example:
+
+```php
+<?php
+
+use phpsap\saprfc\SapRfcConnection;
+use phpsap\saprfc\SapRfcConfigA;
+
+//stored configuration, JSON encoded
+$config = '{
+    "ashost": "sap.example.com",
+    "sysnr": "001",
+    "client": "01",
+    "user": "username",
+    "passwd": "password"
+}';
+//establish a connection using the stored configuration
+$connection = new SapRfcConnection(new SapRfcConfigA($config));
+//prepare a function call
+$function = $connection->prepareFunction('remoteFunctionName');
+//call the remote function
+$result = $function->invoke(['paramName' => 'value']);
+```
+
+[koucky]: http://saprfc.sourceforge.net/ "SAPRFC extension module for PHP"

php-modules.md

@@ -0,0 +1,13 @@
+## PHP SAP RFC modules
+
+The following PHP modules are currently supported by PHP/SAP.
+
+Author                  | Module      | supported PHP versions | PHP/SAP composer package
+----------------------- | ----------- | ---------------------- | ------------------------
+[Eduard Koucky][koucky] | `saprfc`    | PHP 4.x - 5.5.x        | `phpsap/saprfc-koucky`
+[Piers Haring][harding] | `sapnwrfc`  | PHP 5.x                | `phpsap/saprfc-harding`
+[Gregor Kralik][kralik] | `sapnwrfc`  | PHP 7.x                | `phpsap/saprfc-kralik`
+
+[koucky]: http://saprfc.sourceforge.net/ "SAPRFC extension module for PHP"
+[harding]: https://github.com/piersharding/php-sapnwrfc "SAP RFC Connector using the SAP NW RFC SDK for PHP"
+[kralik]: https://github.com/gkralik/php7-sapnwrfc "SAP NW RFC SDK extension for PHP7"