From 5aedac010fa0ec10e31ee39c81688830d1e0e3ea Mon Sep 17 00:00:00 2001
From: Remi Collet <remi@remirepo.net>
Date: Fri, 26 Jan 2018 13:29:22 +0100
Subject: rewrite README.md

---
 README.md   | 92 ++++++++++++++++++++++++++++++++++++++++++++-----------------
 package.xml |  1 +
 2 files changed, 67 insertions(+), 26 deletions(-)

diff --git a/README.md b/README.md
index 1584173..d572920 100644
--- a/README.md
+++ b/README.md
@@ -1,43 +1,83 @@
-rpminfo
-=======
+# RPM information extension for PHP
 
-Experimental wrapper for librpm
+Retrieve RPM information from PHP code using librpm.
 
-For now, only expose
+**Notice**: this is a experimental extension, a work in progress, so don't expect a stable API yet.
 
-	int rpmvercmp(string evr1, string evr2);
-	array rpminfo(string path [, bool full ]);
+----
 
+# Build
 
-Mostly a PoC build for fun because of
+You need the rpm development files (rpm-devel) version >= 4.11.3.
 
-https://bugzilla.redhat.com/1537981
-performance issue: dnf repomanage is really slow
+From the sources tree
 
+    $ phpize
+    $ ./configure --enable-rpminfo
+    $ make
+    $ make test
 
-Some benchmark results (find 15 old RPMs among 5000)
+----
 
-# DNF on Fedora 27
+# Usage
 
-    $ time dnf repomanage --old --keep 5 .
-    ...
-    real	0m15,971s
+## rpmvercmp
 
-# DNF on Fedora 25
+	int rpmvercmp(string evr1, string evr2);
 
-    $ time dnf repomanage --old --keep 5 .
-    ...
-    real	0m0,269s
+Allow to compare 2 EVR (epoch:version-release) strings. The return value is < 0 if evr1 < evr2, > 0 if evr1 > evr2, 0 if equal.
 
-# YUM on RHEL / CentOS
+    $ php -a
+    php > var_dump(rpmvercmp("1.0", "1.1"));
+    int(-1)
+    php > var_dump(rpmvercmp("1:1.0", "1.1"));
+    int(1)
 
-    $ time repomanage --old --keep 5 .
-    ...
-    real	0m5.519s
 
-# PHP script
+## rpminfo
 
-    $ time php repomanage.php --old --keep 5 .
-    ...
-    real	0m0,135s
+	array rpminfo(string path [, bool full ]);
 
+Retrieve information from a rpm file, reading its metadata.
+The return value is a hash table, or false if it fails.
+
+    $ php -a
+    php > print_r(rpminfo("tests/bidon.rpm"));
+    Array
+    (
+        [Name] => bidon
+        [Version] => 1
+        [Release] => 1.fc25.remi
+        [Arch] => x86_64
+    )
+    php > print_r(rpminfo("tests/bidon.rpm", true));
+    Array
+    (
+        [Headeri18ntable] => C
+        [Sigsize] => 2304
+        [Sigmd5] => 644819c3566819b1e10a5c97943de094
+        [Sha1header] => 0a86742fe53973ac9ab4611187a83ffb44f1de5a
+        [Sha256header] => 9aab7242a80212ad1fe4fdd3b250c0c4f176c0b3fb1355c0d62ff094fc3f7da0
+        [Name] => bidon
+        [Version] => 1
+        [Release] => 1.fc25.remi
+        [Summary] => Bidon
+        [Description] => A dummy package
+        ...
+        [IsSource] => 
+    )
+
+----
+
+# LICENSE
+
+Author: Remi Collet
+
+This extension is licensed under [The PHP License, version 3.01](http://www.php.net/license/3_01.txt)
+
+-----
+
+# History
+
+Created as a PoC, for fun, see history on
+https://blog.remirepo.net/post/2018/01/26/About-repomanage-performance-regression
diff --git a/package.xml b/package.xml
index 2af2fac..fe437ff 100644
--- a/package.xml
+++ b/package.xml
@@ -34,6 +34,7 @@
       <file name="CREDITS" role="doc"/>
       <file name="EXPERIMENTAL" role="doc"/>
       <file name="LICENSE" role="doc"/>
+      <file name="README.md" role="doc"/>
       <dir name ="examples">
         <file name="repomanage.php" role="doc"/>
         <file name="rpmvercmp.php" role="doc"/>
-- 
cgit