Skip to content

Commit f8cb4f6

Browse files
seebeenseebeen
committed
chore: Update docs and CI workflow
1 parent a24130d commit f8cb4f6

3 files changed

Lines changed: 191 additions & 95 deletions

File tree

‎.github/workflows/tests.yml‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
name: Tests
2+
3+
on:
4+
pull_request:
5+
merge_group:
6+
types:
7+
- checks_requested
8+
push:
9+
10+
permissions:
11+
contents: read
12+
13+
concurrency:
14+
group: ${{ github.workflow }}-${{ github.ref }}
15+
cancel-in-progress: true
16+
17+
jobs:
18+
unit-tests:
19+
name: PHPUnit (PHP ${{ matrix.php }})
20+
runs-on: ubuntu-latest
21+
continue-on-error: ${{ matrix.php == '8.5' }}
22+
strategy:
23+
fail-fast: false
24+
matrix:
25+
php: ['8.1', '8.2', '8.3', '8.4', '8.5']
26+
27+
steps:
28+
- name: Checkout
29+
uses: actions/checkout@v4
30+
31+
- name: Setup PHP
32+
uses: shivammathur/setup-php@v2
33+
with:
34+
php-version: ${{ matrix.php }}
35+
coverage: pcov
36+
37+
- name: Cache Composer dependencies
38+
uses: actions/cache@v4
39+
with:
40+
path: ~/.composer/cache/files
41+
key: ${{ runner.os }}-php-${{ matrix.php }}-composer-${{ hashFiles('**/composer.lock') }}
42+
restore-keys: |
43+
${{ runner.os }}-php-${{ matrix.php }}-composer-
44+
45+
- name: Install dependencies
46+
run: composer install --prefer-dist --no-progress --no-interaction
47+
48+
- name: Run unit tests (coverage leg)
49+
if: matrix.php == '8.1'
50+
run: composer test:coverage:ci
51+
52+
- name: Run unit tests
53+
if: matrix.php != '8.1'
54+
run: composer test:unit
55+
56+
- name: Upload coverage to Codecov
57+
if: matrix.php == '8.1'
58+
uses: codecov/codecov-action@v5
59+
with:
60+
files: build/coverage.xml
61+
fail_ci_if_error: true
62+
token: ${{ secrets.CODECOV_TOKEN }}

‎CONTRIBUTING.md‎

Lines changed: 97 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,97 @@
1+
# Contributing
2+
3+
Thank you for contributing to `rnids/rsreg-epp-client`.
4+
5+
This project is a modern RNIDS/RSreg EPP client for PHP 8.1+, with strict typing, deterministic XML behavior, and fluent service APIs.
6+
7+
## Development setup
8+
9+
### Requirements
10+
11+
- PHP 8.1+
12+
- Composer
13+
- `ext-json`
14+
15+
### Install dependencies
16+
17+
```bash
18+
composer install
19+
```
20+
21+
## Project standards
22+
23+
- Keep RNIDS/RSreg behavior explicit and first-class.
24+
- Prefer typed DTOs and small single-purpose methods.
25+
- Keep XML composition/parsing deterministic and namespace-safe.
26+
- Preserve fluent API discoverability from `RNIDS\Client` entry points.
27+
28+
## Quality gates
29+
30+
Run these checks before opening a PR:
31+
32+
```bash
33+
composer test
34+
```
35+
36+
Useful individual commands:
37+
38+
```bash
39+
composer test:unit
40+
composer phpstan
41+
composer phpcs
42+
composer test:coverage
43+
composer test:coverage:ci
44+
```
45+
46+
### Live integration suite
47+
48+
Run live RNIDS integration tests explicitly:
49+
50+
```bash
51+
composer test:live
52+
```
53+
54+
These tests depend on external connectivity and credentials/certificates. If preflight conditions are not met, suites are skipped with explicit reasons.
55+
56+
## Coding conventions
57+
58+
- Use `declare(strict_types=1);` in PHP source files.
59+
- Use explicit parameter/return types on public methods.
60+
- Mark classes `final` by default unless extension is intentional.
61+
- Prefer immutable/readonly DTO-style structures where practical.
62+
- Keep public API names aligned with RNIDS usage terminology.
63+
64+
## Commit message format
65+
66+
This repository uses semantic-release and Conventional Commits.
67+
68+
Format:
69+
70+
```text
71+
type(scope): Description starting with a capital letter
72+
```
73+
74+
Examples:
75+
76+
- `feat(domain): Add transfer query response mapper`
77+
- `fix(xml): Correct namespace registration for host parser`
78+
- `test: Expand session poll integration coverage`
79+
80+
Rules:
81+
82+
- Capitalize the first word of the description.
83+
- Do not end the subject line with a period.
84+
- Keep the subject concise (preferably under 72 chars).
85+
86+
## Pull requests
87+
88+
Please include:
89+
90+
1. A clear summary of what changed and why.
91+
2. Any relevant protocol/behavior notes (especially RNIDS-specific behavior).
92+
3. Tests added/updated for behavior changes.
93+
4. Confirmation that local quality gates pass.
94+
95+
## Documentation updates
96+
97+
If you change public behavior, update relevant docs in `docs/` and cross-link from `README.md` when appropriate.

‎README.md‎

Lines changed: 32 additions & 95 deletions
Original file line numberDiff line numberDiff line change
@@ -1,23 +1,36 @@
1-
# RNIDS / RSreg EPP Client
1+
<div align="center">
22

3-
Modern PHP 8.1+ client library for RNIDS/RSreg EPP integration.
3+
<h1 align="center" style="border-bottom: none; margin-bottom: 0px">RNIDS / RSreg EPP Client</h1>
4+
<h3 align="center" style="margin-top: 0px">Modern Dependency-Safe PHP Client for RNIDS Registry EPP</h3>
45

5-
This package provides a fluent, RNIDS-first API with deterministic XML generation, typed DTOs internally, and predictable command execution over native stream transport.
6+
[![Packagist Version](https://img.shields.io/packagist/v/rnids/rsreg-epp-client?label=Release&style=flat-square)](https://packagist.org/packages/rnids/rsreg-epp-client)
7+
![Packagist PHP Version](https://img.shields.io/packagist/dependency-v/rnids/rsreg-epp-client/php?label=PHP&logo=php&logoColor=white&logoSize=auto&style=flat-square)
8+
![Static Badge](https://img.shields.io/badge/RNIDS-RSreg-3858e9?style=flat-square)
9+
[![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/oblakhost/rnids-rsreg-client-php/release.yml?label=Build&event=push&style=flat-square&logo=githubactions&logoColor=white&logoSize=auto)](https://github.com/oblakhost/rnids-rsreg-client-php/actions/workflows/release.yml)
10+
11+
</div>
12+
13+
This library provides a fluent, RNIDS-first implementation of the EPP protocol for PHP 8.1+ applications.
14+
It focuses on deterministic XML handling, typed request/response modeling, strict transport behavior, and predictable command execution for RNIDS/RSreg environments.
15+
16+
## Key Features
17+
18+
1. RNIDS-first API design with fluent entry points for session, domain, contact, and host operations.
19+
2. Deterministic EPP request lifecycle over native stream transport and frame codec boundaries.
20+
3. Typed service-layer DTOs and normalized response mapping for reliable integrations.
21+
4. Explicit protocol/transport exception strategy under `RNIDS\Exception\*`.
22+
5. Separate XML composition/parsing modules for easier testing and maintenance.
23+
6. Coverage-aware quality gate with static analysis and coding standards checks.
624

725
## Installation
826

27+
Install via Composer:
28+
929
```bash
1030
composer require rnids/rsreg-epp-client
1131
```
1232

13-
## Requirements
14-
15-
- PHP 8.1+
16-
- `ext-json`
17-
- Network access to RNIDS/RSreg EPP endpoint
18-
- TLS certificates configured in client config when required by your environment
19-
20-
## Quick Start
33+
## Usage
2134

2235
```php
2336
<?php
@@ -35,46 +48,22 @@ $client = Client::ready([
3548
]);
3649

3750
$domainInfo = $client->domain()->info('example.rs');
38-
39-
// Optional metadata from the latest EPP response:
4051
$meta = $client->responseMeta();
4152

4253
$client->close();
4354
```
4455

45-
Minimum config keys for first run:
46-
47-
- `host`
48-
- `username`
49-
- `password`
50-
51-
Common optional keys:
52-
53-
- `port` (default `700`)
54-
- `language` (default `en`)
55-
- `version` (default `1.0`)
56-
- `objectUris`, `extensionUris`
57-
- `tls` options (`localCertPath`, `localPkPath`, `passphrase`, `caFile`, `verifyPeer`, `verifyPeerName`, `allowSelfSigned`, `peerName`)
58-
59-
If you need explicit lifecycle control:
60-
61-
```php
62-
$client = new Client([...]);
63-
$client->init();
64-
```
65-
66-
## Fluent API
56+
Common fluent entry points:
6757

6858
- Session: `$client->session()->hello()`, `login()`, `logout()`, `poll()`
6959
- Domain: `$client->domain()->check()`, `info()`, `register()`, `renew()`, `update()`, `delete()`, `transfer()`
7060
- Contact: `$client->contact()->check()`, `create()`, `info()`, `update()`, `delete()`
7161
- Host: `$client->host()->check()`, `info()`, `create()`, `update()`, `delete()`
7262

73-
Contact runtime policy:
63+
Runtime contact policy:
7464

75-
- Contact IDs are normalized to `OBL-...` for create/update requests.
76-
- Contact `extension.identDescription` is enforced to:
77-
`Object Creation provided by Oblak Solutions.`
65+
- Contact IDs are normalized to `OBL-...` for create/update flows.
66+
- Contact `extension.identDescription` is enforced to `Object Creation provided by Oblak Solutions.`
7867

7968
## Documentation
8069

@@ -86,62 +75,10 @@ Contact runtime policy:
8675
- Host API: [`docs/api-host.md`](docs/api-host.md)
8776
- EPP Protocol Reference: [`docs/epp-protocol/epp-reference-index.md`](docs/epp-protocol/epp-reference-index.md)
8877

89-
## Error Handling
90-
91-
Protocol and transport issues are surfaced as exceptions from `RNIDS\Exception\*`.
92-
93-
Successful operations return typed/normalized data arrays from service methods, while low-level response context is available via:
94-
95-
```php
96-
<?php
97-
98-
$client->responseMeta();
99-
```
100-
101-
Shutdown behavior:
102-
103-
- Explicit `$client->close()` may throw on logout/disconnect failure.
104-
- Automatic destructor shutdown is non-throwing.
105-
- Inspect `$client->lastCloseError()` for the last shutdown failure, if any.
106-
107-
## Development
108-
109-
Default local test gate (offline-safe):
110-
111-
```bash
112-
composer test
113-
```
114-
115-
Expanded local quality gate (equivalent behavior):
116-
117-
```bash
118-
composer test:local
119-
```
78+
## Contributing
12079

121-
Live RNIDS integration suites only:
80+
For local setup, quality gates, commit conventions, and PR guidelines, see [`CONTRIBUTING.md`](CONTRIBUTING.md).
12281

123-
```bash
124-
composer test:live
125-
```
126-
127-
Live suites run preflight checks for required environment variables, certificate files,
128-
DNS, and TCP endpoint reachability. If prerequisites are missing, suites are skipped with
129-
an explicit reason instead of failing the default local workflow.
130-
131-
Local coverage gate (unit tests + threshold):
132-
133-
```bash
134-
composer test:coverage
135-
```
136-
137-
`test:coverage` enables `pcov` explicitly (`php -d pcov.enabled=1`) and enforces the
138-
line-coverage threshold using `build/coverage.xml`.
139-
140-
Codecov/CI coverage artifact command:
141-
142-
```bash
143-
composer test:coverage:ci
144-
```
82+
## License
14583

146-
`test:coverage:ci` writes Clover XML to `build/coverage.xml` (ready for upload) and
147-
applies the same strict threshold gate.
84+
Apache-2.0. See [`LICENSE`](LICENSE).

0 commit comments

Comments
 (0)