Add invoice description customization

.github/workflows/ci.yml

@@ -14,7 +14,7 @@ jobs:
     name: Coding Guidelines
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
 
       - uses: shivammathur/setup-php@v2
         with:
@@ -27,7 +27,7 @@ jobs:
         run: echo "dir=$(composer config cache-files-dir)" >> $GITHUB_OUTPUT
 
       - name: Cache dependencies
-        uses: actions/cache@v3.3.1
+        uses: actions/cache@v4
         with:
           path: ${{ steps.composer-cache.outputs.dir }}
           key: ${{ runner.os }}-composer-${{ hashFiles('**/composer.lock') }}
@@ -43,7 +43,7 @@ jobs:
     name: Type Checker
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
 
       - uses: shivammathur/setup-php@v2
         with:
@@ -56,7 +56,7 @@ jobs:
         run: echo "dir=$(composer config cache-files-dir)" >> $GITHUB_OUTPUT
 
       - name: Cache dependencies
-        uses: actions/cache@v3.3.1
+        uses: actions/cache@v4
         with:
           path: ${{ steps.composer-cache.outputs.dir }}
           key: ${{ runner.os }}-composer-${{ hashFiles('**/composer.lock') }}
@@ -82,7 +82,7 @@ jobs:
         operating-system:
           - "ubuntu-latest"
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
 
       - uses: shivammathur/setup-php@v2
         with:
@@ -95,7 +95,7 @@ jobs:
         run: echo "::set-output name=dir::$(composer config cache-files-dir)"
 
       - name: Cache dependencies
-        uses: actions/cache@v3.3.1
+        uses: actions/cache@v4
         with:
           path: ${{ steps.composercache.outputs.dir }}
           key: "php-${{ matrix.php-version }}-${{ matrix.dependencies }}-${{ hashFiles('**/composer.lock') }}"

README.md

@@ -30,6 +30,17 @@ cp lightning-config.dist.php lightning-config.php
 cp nostr.dist.json nostr.json
 ```
 
+You can customize the invoice description and the success message by editing
+`lightning-config.php`:
+
+```php
+use PhpLightning\Config\LightningConfig;
+
+return (new LightningConfig())
+    ->setDescriptionTemplate('Pay to %s on mynode')
+    ->setSuccessMessage('Thanks for the payment!');
+```
+
 Run a local PHP server listening `public/index.php`
 
 ```bash

lightning-config.dist.php

@@ -7,6 +7,8 @@
 return (new LightningConfig())
     ->setDomain('localhost')
     ->setReceiver('default-receiver')
+    ->setDescriptionTemplate('Pay to %s')
+    ->setSuccessMessage('Payment received!')
     ->setSendableRange(min: 100_000, max: 10_000_000_000)
     ->setCallbackUrl('localhost:8000/callback')
     ->addBackendsFile(getcwd() . DIRECTORY_SEPARATOR . 'nostr.json');

src/Config/LightningConfig.php

@@ -16,6 +16,8 @@ final class LightningConfig implements JsonSerializable
     private ?string $receiver = null;
     private ?SendableRange $sendableRange = null;
     private ?string $callbackUrl = null;
+    private ?string $descriptionTemplate = null;
+    private ?string $successMessage = null;
 
     public function setDomain(string $domain): self
     {
@@ -42,6 +44,18 @@ public function setCallbackUrl(string $callbackUrl): self
         return $this;
     }
 
+    public function setDescriptionTemplate(string $template): self
+    {
+        $this->descriptionTemplate = $template;
+        return $this;
+    }
+
+    public function setSuccessMessage(string $message): self
+    {
+        $this->successMessage = $message;
+        return $this;
+    }
+
     public function addBackendsFile(string $path): self
     {
         $this->backends ??= new BackendsConfig();
@@ -92,6 +106,12 @@ public function jsonSerialize(): array
         if ($this->callbackUrl !== null) {
             $result['callback-url'] = $this->callbackUrl;
         }
+        if ($this->descriptionTemplate !== null) {
+            $result['description-template'] = $this->descriptionTemplate;
+        }
+        if ($this->successMessage !== null) {
+            $result['success-message'] = $this->successMessage;
+        }
 
         return $result;
     }

src/Invoice/Application/CallbackUrl.php

@@ -8,6 +8,8 @@
 use PhpLightning\Invoice\Domain\CallbackUrl\LnAddressGeneratorInterface;
 use PhpLightning\Shared\Value\SendableRange;
 
+use function sprintf;
+
 final class CallbackUrl implements CallbackUrlInterface
 {
     private const TAG_PAY_REQUEST = 'payRequest';
@@ -16,6 +18,7 @@ public function __construct(
         private SendableRange $sendableRange,
         private LnAddressGeneratorInterface $lnAddressGenerator,
         private string $callback,
+        private string $descriptionTemplate,
     ) {
     }
 
@@ -25,7 +28,7 @@ public function getCallbackUrl(string $username): array
         // Modify the description if you want to custom it
         // This will be the description on the wallet that pays your ln address
         // TODO: Make this customizable from some external configuration file
-        $description = 'Pay to ' . $lnAddress;
+        $description = sprintf($this->descriptionTemplate, $lnAddress);
 
         // TODO: images not implemented yet; `',["image/jpeg;base64","' . base64_encode($response) . '"]';`
         $imageMetadata = '';

src/Invoice/Application/InvoiceGenerator.php

@@ -8,14 +8,16 @@
 use PhpLightning\Shared\Transfer\BackendInvoiceResponse;
 use PhpLightning\Shared\Value\SendableRange;
 
+use function sprintf;
+
 final class InvoiceGenerator
 {
-    public const MESSAGE_PAYMENT_RECEIVED = 'Payment received!';
-
     public function __construct(
         private BackendInvoiceInterface $backendInvoice,
         private SendableRange $sendableRange,
         private string $lnAddress,
+        private string $descriptionTemplate,
+        private string $successMessage,
     ) {
     }
 
@@ -27,10 +29,7 @@ public function generateInvoice(int $milliSats): array
                 'reason' => 'Amount is not between minimum and maximum sendable amount',
             ];
         }
-        // Modify the description if you want to custom it
-        // This will be the description on the wallet that pays your ln address
-        // TODO: Make this customizable from some external configuration file
-        $description = 'Pay to ' . $this->lnAddress;
+        $description = sprintf($this->descriptionTemplate, $this->lnAddress);
 
         // TODO: images not implemented yet
         $imageMetadata = '';
@@ -48,7 +47,7 @@ private function mapResponseAsArray(BackendInvoiceResponse $invoice): array
             'status' => $invoice->getStatus(),
             'successAction' => [
                 'tag' => 'message',
-                'message' => self::MESSAGE_PAYMENT_RECEIVED,
+                'message' => $this->successMessage,
             ],
             'routes' => [],
             'disposable' => false,

src/Invoice/InvoiceConfig.php

@@ -54,6 +54,16 @@ public function getSendableRange(): SendableRange
         return $this->get('sendable-range', SendableRange::default());
     }
 
+    public function getDescriptionTemplate(): string
+    {
+        return (string)$this->get('description-template', 'Pay to %s');
+    }
+
+    public function getSuccessMessage(): string
+    {
+        return (string)$this->get('success-message', 'Payment received!');
+    }
+
     public function getDomain(): string
     {
         return (string)$this->get('domain', $_SERVER['HTTP_HOST'] ?? 'localhost');

src/Invoice/InvoiceFactory.php

@@ -29,6 +29,7 @@ public function createCallbackUrl(string $username): CallbackUrlInterface
             $this->getConfig()->getSendableRange(),
             $this->createLnAddressGenerator(),
             $this->getConfig()->getCallback(),
+            $this->getConfig()->getDescriptionTemplate(),
         );
     }
 
@@ -38,6 +39,8 @@ public function createInvoiceGenerator(string $username): InvoiceGenerator
             $this->getBackendForUser($username),
             $this->getConfig()->getSendableRange(),
             $this->getConfig()->getDefaultLnAddress(),
+            $this->getConfig()->getDescriptionTemplate(),
+            $this->getConfig()->getSuccessMessage(),
         );
     }
 

tests/Feature/InvoiceFacadeTest.php

@@ -45,7 +45,7 @@ public function test_ln_bits_feature(): void
         $this->bootstrapGacela();
         $this->mockLnPaymentRequest();
 
-        $json = $this->facade->generateInvoice('alice', 2_000, 'lnbits');
+        $json = $this->facade->generateInvoice('alice', 2_000);
 
         self::assertEquals([
             'pr' => 'lnbc10u1pjzh489...fake payment_request',

tests/Unit/Config/LightningConfigTest.php

@@ -56,4 +56,16 @@ public function test_sendable_range(): void
             'sendable-range' => SendableRange::withMinMax(1_000, 5_000),
         ], $config->jsonSerialize());
     }
+
+    public function test_description_and_success_message(): void
+    {
+        $config = (new LightningConfig())
+            ->setDescriptionTemplate('Pay to %s on example')
+            ->setSuccessMessage('Thanks!');
+
+        self::assertSame([
+            'description-template' => 'Pay to %s on example',
+            'success-message' => 'Thanks!',
+        ], $config->jsonSerialize());
+    }
 }

tests/Unit/Invoice/Domain/CallbackUrl/CallbackUrlTest.php

@@ -25,6 +25,7 @@ public function test_get_callback_url(): void
             SendableRange::withMinMax(1_000, 5_000),
             $lnAddressGenerator,
             'https://domain/receiver',
+            'Pay to %s',
         );
 
         self::assertEquals([

tests/Unit/Invoice/Domain/LnAddress/InvoiceGeneratorTest.php

@@ -21,6 +21,8 @@ public function test_invalid_amount(): void
             $invoiceFacade,
             SendableRange::withMinMax(1_000, 3_000),
             'ln@address',
+            'Pay to %s',
+            'Payment received!',
         );
         $actual = $invoice->generateInvoice(100);
 
@@ -42,6 +44,8 @@ public function test_unknown_backend(): void
             $invoiceFacade,
             SendableRange::withMinMax(1_000, 3_000),
             'ln@address',
+            'Pay to %s',
+            'Payment received!',
         );
         $actual = $invoice->generateInvoice(2_000);
 
@@ -70,6 +74,8 @@ public function test_successful_payment_request_with_amount(): void
             $invoiceFacade,
             SendableRange::withMinMax(1_000, 3_000),
             'ln@address',
+            'Pay to %s',
+            'Payment received!',
         );
         $actual = $invoice->generateInvoice(2_000);