Merge branch 'main' into phpdoc

.gitignore

@@ -5,3 +5,9 @@
 composer.lock
 test*.php
 vendor/
+
+/.phpdoc/cache/
+
+/website/content/.vitepress/dist/
+/website/content/.vitepress/cache/
+/website/node_modules/

README.md

@@ -1,17 +1,17 @@
 # nostr-php
 
-![CI](https://github.com/swentel/nostr-php/actions/workflows/ci.yml/badge.svg)
+![CI](https://github.com/nostrver-se/nostr-php/actions/workflows/ci.yml/badge.svg)
 ![Packagist PHP Version](https://img.shields.io/packagist/dependency-v/swentel/nostr-php/php)
-![GitHub contributors](https://img.shields.io/github/contributors/swentel/nostr-php)
-![GitHub issues](https://img.shields.io/github/issues/swentel/nostr-php)
-![GitHub last commit (branch)](https://img.shields.io/github/last-commit/swentel/nostr-php/main)
+![GitHub contributors](https://img.shields.io/github/contributors/nostrver-se/nostr-php)
+![GitHub issues](https://img.shields.io/github/issues/nostrver-se/nostr-php)
+![GitHub last commit (branch)](https://img.shields.io/github/last-commit/nostrver-se/nostr-php/main)
 
 This is a PHP Helper library for Nostr.
 More info about Nostr: https://github.com/nostr-protocol/nostr.
 
 ## Installation
 
-To use in your project with Composer:
+To use the package in your PHP project with Composer:
 
 ```console
 $ composer require swentel/nostr-php
@@ -74,7 +74,7 @@ $eventMessage = new EventMessage($note);
 $message_string = $eventMessage->generate();
 ```
 
-## Interacting with a relay
+## Publish an event to a relay
 
 Publish an event with a note that has been prepared for sending to a relay.
 
@@ -93,10 +93,115 @@ $signer->signEvent($note, $private_key);
 $eventMessage = new EventMessage($note);
 
 $relayUrl = 'wss://nostr-websocket.tld';
-$relay = new Relay($relayUrl, $eventMessage);
+$relay = new Relay($relayUrl);
+$relay->setMessage($eventMessage);
 $result = $relay->send();
 ```
 
+If you would like to publish the event to multiple relays, you can use the `RelaySet` class.
+
+```php
+$relay1 = new Relay(''wss://nostr-websocket1.tld'');
+$relay2 = new Relay(''wss://nostr-websocket2.tld'');
+$relay3 = new Relay(''wss://nostr-websocket3.tld'');
+$relay4 = new Relay(''wss://nostr-websocket4.tld'');
+$relaySet = new RelaySet();
+$relaySet->setRelays([$relay1, $relay2, $relay3, $relay4]);
+$relaySet->setMessage($eventMessage);
+$result = $relay->send();
+```
+
+## Read events from a relay
+
+Fetch events from a relay. 
+
+```php
+$subscription = new Subscription();
+$subscriptionId = $subscription->setId();
+
+$filter1 = new Filter();
+$filter1->setKinds([1, 3]); // You can add multiple kind numbers
+$filter1->setLimit(25); // Limit to fetch only a maximum of 25 events
+$filters = [$filter1]; // You can add multiple filters.
+
+$requestMessage = new RequestMessage($subscriptionId, $filters);
+
+$relayUrl = 'wss://nostr-websocket.tld';
+$relay = new Relay($relayUrl);
+$relay->setMessage($requestMessage);
+
+$request = new Request($relay, $requestMessage);
+$response = $request->send();
+```
+
+`$response` is a multidimensional array with elements containing each a response message (JSON string) decoded to an array from the relay and sorted by the relay.
+Output example:
+```php
+[
+  'wss://nostr-websocket.tld' => [
+    0 => [
+      "EVENT",
+      "A8kWzjCVUHSD1rmuwGqyK2PxsolZMO9YXditbg05fch6p3Q4eT7vRFLEJINBna",
+      [
+        'id' => '1e8534623845629d40f7761c0577edf10f778c490e7b95a524845d9280c7c25a',
+        'kind' => 1,
+        'pubkey' => '06639a386c9c1014217622ccbcf40908c4f1a0c33e23f8d6d68f4abf655f8f71',
+        'created_at' => 1718723787,
+        'content' => 'Losing your social graph can feel the same for some I think 😮 ',
+        'tags' => [
+          ['e', 'f754a238947b7f32168f872650a8dd0b9376493e58005d7e0b8be52f6f229364', 'wss://nos.lol/', 'root'],
+          ['e', 'fe7dd6ba22fa0aa39370aa160226b8bc2413460621c8d67ce862205ad5a02c24', 'wss://nos.lol/', 'reply'],
+          ['p', 'fb1366abd5e4c92a8a950791bc72d51bde291a83555cb2c629a92fedd78068ac', '', 'mention']
+        ],
+        'sig' => '888c9b5d9e0b69eba3510dd2b5d03eddcf0a680ab0e7673820fb36a56448ad80701042a669c7ef9918593c5a41c8b3ccc1d82ade50f32b62dd843144f32df403'
+    ],
+    1 => [
+      "EVENT",
+      "A8kWzjCVUHSD1rmuwGqyK2PxsolZMO9YXditbg05fch6p3Q4eT7vRFLEJINBna",
+      [
+        ...Nostr event
+      ]
+    ],
+    2 => [
+      ...
+    ],
+    3 => [
+      ...
+    ],
+    4 => [
+      ...
+    ]
+  ]
+]
+
+```
+
+## Read events from a set of relays
+
+Read events from a set of relays with the `RelaySet` class.
+It's basically the same snippet as above with the difference you create a `RelaySet` class and pass it through the `Request` object.
+
+```php
+$subscription = new Subscription();
+$subscriptionId = $subscription->setId();
+
+$filter1 = new Filter();
+$filter1->setKinds([1]);
+$filter1->setLimit(5);
+$filters = [$filter1];
+$requestMessage = new RequestMessage($subscriptionId, $filters);
+$relays = [
+    new Relay('wss://nostr-websocket-1.tld'),
+    new Relay('wss://nostr-websocket-2.tld'),
+    new Relay('wss://nostr-websocket-3.tld'),
+];
+$relaySet = new RelaySet();
+$relaySet->setRelays($relays);
+
+$request = new Request($relaySet, $requestMessage);
+$response = $request->send();
+```
+
 ## Generating a private key and a public key
 
 ```php
@@ -171,16 +276,23 @@ private key on command line.
 - [x] Keypair generation and validation
   - [x] Convert from hex to bech32-encoded keys
 - [x] Event signing with Schnorr signatures (`secp256k1`)
-- [x] Event validation (issue [#17](https://github.com/swentel/nostr-php/issues/17))
-- [ ] Support NIP-01 basic protocol flow description
+- [x] Event validation (issue [#17](https://github.com/nostrver-se/nostr-php/issues/17))
+- [x] Support NIP-01 basic protocol flow description
   - [x] Publish events
-  - [ ] Request events (pr [#48](https://github.com/swentel/nostr-php/pull/48))
-- [ ] Improve handling relay responses
+  - [x] Request events (issue [#55](https://github.com/nostrver-se/nostr-php/pull/55) credits to [kriptonix](https://github.com/kriptonix))
+  - [x] Implement all types of relay responses 
+    - [x] `EVENT` - sends events requested by the client
+    - [x] `OK` - indicate an acceptance or denial of an EVENT message
+    - [x] `EOSE` - end of stored events
+    - [x] `CLOSED` - subscription is ended on the server side
+    - [x] `NOTICE` - used to send human-readable messages (like errors) to clients
+- [x] Improve handling relay responses
 - [ ] Support NIP-19 bech32-encoded identifiers
-- [ ] Support NIP-42 authentication of clients to relays
+- [ ] Support NIP-42 authentication of clients to relays => AUTH relay response
 - [ ] Support NIP-45 event counts
 - [ ] Support NIP-50 search capability
-- [ ] Support multi-threading for handling requests simultaneously
+- [ ] Support multi-threading (async concurrency) for handling requests simultaneously
+- [ ] Support realtime (runtime) subscriptions with the `bin/nostr-php` CLI client to listen to new events from relays
 
 ## Community
 
@@ -194,3 +306,7 @@ In May 2024 OpenSats granted Sebastian Hagens for further development of this li
 
 * [@sebastix](https://github.com/Sebastix)  `npub1qe3e5wrvnsgpggtkytxteaqfprz0rgxr8c3l34kk3a9t7e2l3acslezefe`
 * [@swentel](https://github.com/swentel) (original author, inactive)  `npub1z8n2zt0vzkefhrhpf60face4wwq2nx87sz7wlgcvuk4adddkkycqknzjk5`
+
+## Contributors
+
+See https://github.com/nostrver-se/nostr-php/graphs/contributors

REFERENCES.md

@@ -1,23 +1,3 @@
 # References
 
-Using nostr-php:
-* https://github.com/pj8912/nostrdev
-* https://github.com/fabianfabian/nostr-media (is using a fork for PHP8.0 compatibility)
-* https://github.com/OpenAgentsInc/openagents 
-
-List with other helper libraries in different languages for Nostr:
-
-* https://github.com/nbd-wtf/go-nostr
-* https://github.com/rust-nostr/nostr
-* https://github.com/KiPSOFT/nostr-deno 
-* https://github.com/holgern/pynostr
-* https://github.com/jeffthibault/python-nostr
-* https://github.com/relaystr/dart_ndk 
-* https://github.com/kawax/laravel-nostr
-* https://github.com/nbd-wtf/nostr-tools
-* https://github.com/dtonon/nostr-ruby 
-* https://github.com/penpenpng/rx-nostr
-
-### Used resources
-
-* https://github.com/aljazceru/awesome-nostr?tab=readme-ov-file#libraries
+All references are mentioned on https://nostr-php.dev/references

composer.json

@@ -26,7 +26,7 @@
     "ext-gmp": "*",
     "ext-xml": "*",
     "bitwasp/bech32": "^0.0.1",
-    "phrity/websocket": "^2.1",
+    "phrity/websocket": "^3.0",
     "simplito/elliptic-php": "^1.0",
     "uma/phpecc": "^0.1.3"
   },

src/Application/Client.php

@@ -93,6 +93,6 @@ public function run($args): void
     protected function showHelp($message): void
     {
         print "\n[error] " . $message . "\n\nUsage:\n";
-        print "nostr-php --content \"Hello world!\" --key /home/path/to/nostr-private.key --relay wss://nostr.pleb.network\n\n";
+        print "bin/nostr-php --content \"Hello world!\" --key /home/path/to/nostr-private.key --relay wss://nostr.pleb.network\n\n";
     }
 }