feat: improve VAPID config doc and type hints

Author: Rotzbua

README.md

@@ -144,11 +144,17 @@ use Minishlink\WebPush\WebPush;
 $endpoint = 'https://fcm.googleapis.com/fcm/send/abcdef...'; // Chrome
 
 $auth = [
-    'VAPID' => [
+    'VAPID' => [ // Recommended.
+        'subject' => 'mailto:me@website.com', // can be a mailto: or your website address
+        'publicKey' => '~88 chars', // uncompressed public key P-256 encoded in Base64-URL
+        'privateKey' => '~44 chars', // in fact the secret multiplier of the private key encoded in Base64-URL
+    ],
+    'VAPID' => [ // Alternative 1.
         'subject' => 'mailto:me@website.com', // can be a mailto: or your website address
-        'publicKey' => '~88 chars', // (recommended) uncompressed public key P-256 encoded in Base64-URL
-        'privateKey' => '~44 chars', // (recommended) in fact the secret multiplier of the private key encoded in Base64-URL
         'pemFile' => 'path/to/pem', // if you have a PEM file and can link to it on your filesystem
+    ],
+    'VAPID' => [ // Alternative 2.
+        'subject' => 'mailto:me@website.com', // can be a mailto: or your website address
         'pem' => 'pemFileContent', // if you have a PEM file and want to hardcode its content
     ],
 ];

phpstan.neon

@@ -3,6 +3,7 @@ parameters:
     paths:
         - src
     reportUnmatchedIgnoredErrors: false
+    treatPhpDocTypesAsCertain: false
     ignoreErrors:
         - identifier: missingType.iterableValue
     strictRules:

src/VAPID.php

@@ -18,12 +18,30 @@
 use Jose\Component\Signature\JWSBuilder;
 use Jose\Component\Signature\Serializer\CompactSerializer;
 
+/**
+ * @phpstan-type VapidConfig array{
+ *   subject: string,
+ *   publicKey: string,    // ~88 chars Base64URL
+ *   privateKey: string    // ~44 chars Base64URL
+ * }
+ * @phpstan-type VapidPemFileConfig array{
+ *   subject: string,
+ *   pemFile: string       // path/to/pem
+ * }
+ * @phpstan-type VapidPemConfig array{
+ *   subject: string,
+ *   pem: string           // PEM file content
+ * }
+ * @phpstan-type  InputVapidConfig VapidConfig|VapidPemFileConfig|VapidPemConfig
+ */
 class VAPID
 {
     private const PUBLIC_KEY_LENGTH = 65;
     private const PRIVATE_KEY_LENGTH = 32;
 
     /**
+     * @param InputVapidConfig $vapid
+     * @return VapidConfig
      * @throws \ErrorException
      */
     public static function validate(array $vapid): array
@@ -36,19 +54,19 @@ public static function validate(array $vapid): array
             $vapid['pem'] = file_get_contents($vapid['pemFile']);
 
             if (!$vapid['pem']) {
-                throw new \ErrorException('Error loading PEM file.');
+                throw new \ErrorException('[VAPID] Error loading PEM file.');
             }
         }
 
         if (isset($vapid['pem'])) {
             $jwk = JWKFactory::createFromKey($vapid['pem']);
             if ($jwk->get('kty') !== 'EC' || !$jwk->has('d') || !$jwk->has('x') || !$jwk->has('y')) {
-                throw new \ErrorException('Invalid PEM data.');
+                throw new \ErrorException('[VAPID] Invalid PEM data.');
             }
 
             $binaryPublicKey = hex2bin(Utils::serializePublicKeyFromJWK($jwk));
             if (!$binaryPublicKey) {
-                throw new \ErrorException('Failed to convert VAPID public key from hexadecimal to binary');
+                throw new \ErrorException('[VAPID] Failed to convert VAPID public key from hexadecimal to binary.');
             }
             $vapid['publicKey'] = base64_encode($binaryPublicKey);
             $vapid['privateKey'] = base64_encode(str_pad(Base64Url::decode($jwk->get('d')), self::PRIVATE_KEY_LENGTH, '0', STR_PAD_LEFT));
@@ -113,7 +131,6 @@ public static function getVapidHeaders(
             'alg' => 'ES256',
         ];
 
-
         try {
             $jwtPayload = json_encode(
                 [
@@ -161,7 +178,7 @@ public static function getVapidHeaders(
         }
 
         // @phpstan-ignore deadCode.unreachable
-        throw new \ErrorException('This content encoding is not supported');
+        throw new \ErrorException('This content encoding is not supported.');
     }
 
     /**
@@ -176,12 +193,12 @@ public static function createVapidKeys(): array
 
         $binaryPublicKey = hex2bin(Utils::serializePublicKeyFromJWK($jwk));
         if (!$binaryPublicKey) {
-            throw new \ErrorException('Failed to convert VAPID public key from hexadecimal to binary');
+            throw new \ErrorException('Failed to convert VAPID public key from hexadecimal to binary.');
         }
 
         $binaryPrivateKey = hex2bin(str_pad(bin2hex(Base64Url::decode($jwk->get('d'))), 2 * self::PRIVATE_KEY_LENGTH, '0', STR_PAD_LEFT));
         if (!$binaryPrivateKey) {
-            throw new \ErrorException('Failed to convert VAPID private key from hexadecimal to binary');
+            throw new \ErrorException('Failed to convert VAPID private key from hexadecimal to binary.');
         }
 
         return [