|
| 1 | +# AGENTS.md |
| 2 | + |
| 3 | +## Project Purpose |
| 4 | + |
| 5 | +Pure PHP interfaces library for [PHP/SAP](https://php-sap.github.io) — a contract-only package that consuming |
| 6 | +implementations must satisfy to call SAP RFC (Remote Function Call) functions. **No concrete classes exist here.** |
| 7 | + |
| 8 | +## Architecture |
| 9 | + |
| 10 | +``` |
| 11 | +src/ |
| 12 | +├── IFunction.php # Main entry point: create(), setParam(), invoke() |
| 13 | +├── Api/ # Describe RFC input/output schema |
| 14 | +│ ├── IApi.php # Container for IApiElement items (input/output/changing/table) |
| 15 | +│ ├── IApiElement.php # Base: name, type, direction, optional flag |
| 16 | +│ ├── IValue.php # Single scalar value; direction constants + type constants |
| 17 | +│ ├── IStruct.php # Struct with IMember columns |
| 18 | +│ ├── ITable.php # Table with IMember columns; rows cast from array-of-arrays |
| 19 | +│ └── IMember.php # Struct/table column: 8 type constants (BOOL, INT, FLOAT, STRING, DATE, TIME, HEX, NUM) |
| 20 | +├── Config/ |
| 21 | +│ ├── IConfiguration.php # Common SAP connection params + 4 trace levels |
| 22 | +│ ├── IConfigTypeA.php # Direct application server (ashost, sysnr, client, ...) |
| 23 | +│ └── IConfigTypeB.php # Load-balanced via message server (mshost, r3name, group, ...) |
| 24 | +├── exceptions/ |
| 25 | +│ ├── ISapException.php # Base; extends Throwable |
| 26 | +│ └── I*Exception.php # 6 specialisations (Connection, FunctionCall, InvalidArgument, ...) |
| 27 | +└── Util/ |
| 28 | + └── IJsonSerializable.php # Extends JsonSerializable; adds static jsonDecode(string): static |
| 29 | +``` |
| 30 | + |
| 31 | +**Cross-cutting pattern:** every top-level interface (`IFunction`, `IApi`, `IApiElement`, `IConfiguration`, |
| 32 | +`IMember`) extends `IJsonSerializable` — all objects must be round-trippable through JSON. |
| 33 | + |
| 34 | +## Namespace |
| 35 | + |
| 36 | +PSR-4 root `phpsap\interfaces` → `src/`. Subdirectory namespaces (`Api`, `Config`, `exceptions`, `Util`) |
| 37 | +map directly to directory names. Exception interfaces live in the lowercase `exceptions/` directory but use |
| 38 | +the mixed-case namespace `phpsap\interfaces\exceptions`. |
| 39 | + |
| 40 | +## Developer Workflows |
| 41 | + |
| 42 | +```bash |
| 43 | +# Full CI check (validate + lint + phpstan + phpcs) |
| 44 | +composer ci |
| 45 | + |
| 46 | +# Individual tools (phpcs.xml already configures PSR12 for src/) |
| 47 | +vendor/bin/phpstan analyse --configuration=phpstan.neon |
| 48 | +vendor/bin/phpcbf # auto-fix first, uses phpcs.xml |
| 49 | +vendor/bin/phpcs # inspect remaining issues, uses phpcs.xml |
| 50 | +php -l src/ # syntax check only |
| 51 | +``` |
| 52 | + |
| 53 | +PHPStan runs at **level 9** (strictest). All new code must pass without suppressions. |
| 54 | + |
| 55 | +## Key Conventions |
| 56 | + |
| 57 | +- **Interfaces only** — never add concrete classes or traits to `src/`. |
| 58 | +- All type constants are defined as `string` constants directly on the interface |
| 59 | + (e.g. `IValue::TYPE_BOOLEAN`, `IMember::TYPE_DATE`). |
| 60 | +- Direction constants on `IApiElement`: `DIRECTION_INPUT`, `DIRECTION_OUTPUT`, `DIRECTION_CHANGING`, `DIRECTION_TABLE`. |
| 61 | +- `cast(array $array): array` / `castToArray(mixed $value): array` are the standard conversion methods on |
| 62 | + `IStruct`, `ITable`, and `IMember` — always accept raw RFC output and return PHP-typed arrays. |
| 63 | +- Config constants follow the SAP NW RFC SDK parameter naming (e.g. `ASHOST`, `SYSNR`, `MSHOST`, `R3NAME`). |
| 64 | +- `.gitattributes` marks development-only files such as `phpcs.xml`, `phpstan.neon`, and `AGENTS.md` |
| 65 | + as `export-ignore`, so release archives are intentionally slimmer than the Git checkout. |
| 66 | + |
0 commit comments