From 6d28c5fee06be6bfa9c63c134873544624046500 Mon Sep 17 00:00:00 2001
From: Victor Westerlund <victor.vesterlund@gmail.com>
Date: Thu, 24 Aug 2023 13:10:50 +0200
Subject: [PATCH] feat(doc): update README

---
 README.md | 57 ++++++++++++++++++++++++++++++++++++++++---------------
 1 file changed, 42 insertions(+), 15 deletions(-)

diff --git a/README.md b/README.md
index 06e3f98..35fc4dc 100644
--- a/README.md
+++ b/README.md
@@ -2,23 +2,29 @@
 Encrypt and decrypt files with age from PHP. This library is only a wrapper for the the command line tool, it does not implement the C2CP age specification in PHP.
 
 ```php
+// Encrypt a file with a generated key
 $age = new FileEncryption("hello.txt");
-$age->encrypt("hello.txt.age", "hello.txt.age.key");
+$keypair = $age->keygen("hello.key")->encrypt("hello.txt.age");
+
+// Encrypt a file with a specific public key
+$age->public_key("age1mrf8uana2kan6jsrnf04ywxycvl4nnkzzk3et8rdz6fe6vg7upssclnak7")->encrypt("hello.txt.age");
 ```
 ```php
+// Decrypt a file with a key file
 $age = new FileEncryption("hello.txt.age");
-$age->decrypt("hello.txt.age.key", "hello-decrypted.txt");
+$age->private_key("hello.key")->decrypt("decrypted-hello.txt");
 ```
 
-## Installation
+# Installation
+This library requires PHP 8.1+ and the [age command line tool](https://github.com/FiloSottile/age).
+
 1. [Install the age command line tool](https://github.com/FiloSottile/age#installation)
 2. Install this library with composer
    ```
    composer require victorwesterlund/php-age
    ```
-3. Import and use in your project
 
-## How to use
+# How to use
 Import and use the library:
 ```php
 require_once "vendor/autoload.php";
@@ -26,27 +32,48 @@ require_once "vendor/autoload.php";
 use \Age\FileEncryption;
 ```
 
-### Encrypt a file
+## Encrypt a file
 Encrypt a file on disk by passing it to the `FileEncryption` constructor
 ```php
 // Relative or absolute path to a file that should be encrypted
 $age = new FileEncryption("hello.txt");
-// Encrypted file destination and private key destination
-// This method also returns the private key as a string
-$age->encrypt("hello.txt.age", "hello.txt.age.key");
 ```
 
-You can enable optional PEM encoding by chaining `armor()` before `encrypt()`
+> **Note**
+> The library will not archive a folder for you. You'll have to `tar` your folder before passing it to `FileEncryption`
+
+### Generated key pair
+You can encrypt a file with a generated key pair (`age-keygen`) by chaining `keygen()`
 ```php
-// Encrypt with PEM encoding
-$age->armor()->encrypt("hello.txt.age", "hello.txt.age.key");
+// encrypt() will return the generated keypair as an assoc array
+$keypair = $age->keygen()->encrypt("hello.txt.age"); // ["public" => "...", "private" => "..."]
 ```
 
-### Decrypt a file
+You can also save the generated key file to disk by passing an absolute or relative path to `keygen()`
+```php
+$keypair = $age->keygen("hello.key)->encrypt("hello.txt.age"); // ["public" => "...", "private" => "..."]
+```
+
+### Existing public key
+Encrypt a file with an existing public key by chaining the `public_key()` method
+```php
+$keypair = $age->public_key("age1mrf8uana2kan6jsrnf04ywxycvl4nnkzzk3et8rdz6fe6vg7upssclnak7")->encrypt("hello.txt.age"); // ["public" => "age1mrf8uana2kan6jsrnf04ywxycvl4nnkzzk3et8rdz6fe6vg7upssclnak7", "private" => null]
+```
+
+## Decrypt a file
 Decrypt a file on disk by passing it to the `FileEncryption` constructor
 ```php
 // Relative or absolute path to a file that should be decrypted
 $age = new FileEncryption("hello.txt.age");
-// Private key file and destination of decrypted file
-$age->decrypt("hello.txt.age.key", "hello.txt");
+```
+Chain `private_key()` with an absolute or relative path to the corresponding key file
+```
+$age->private_key("hello.key")->decrypt("decrypted-hello.txt"); // true
+```
+
+## Optional features
+
+Enable PEM encoding by chaining the optional `armor()` method
+```
+$keypair = $age->armor()->keygen()->encrypt("hello.txt.age");
 ```