Author: codemasher

README.md

@@ -6,7 +6,79 @@ PHP Extension providing XZ (LZMA2) compression/decompression functions.<br/>
 [![Linux build](https://github.com/codemasher/php-ext-xz/workflows/Linux/badge.svg)](https://github.com/codemasher/php-ext-xz/actions/workflows/linux.yml)
 [![Windows PHP8 build](https://github.com/codemasher/php-ext-xz/workflows/Windows/badge.svg)](https://github.com/codemasher/php-ext-xz/actions/workflows/windows.yml)
 
-## Build & Installation
+## Installation
+
+The recommended way to install the extension is using [PIE](https://github.com/php/pie):
+
+```bash
+pie install codemasher/php-ext-xz
+```
+
+Windows builds are now done automatically; you can download them from the  [releases](https://github.com/codemasher/php-ext-xz/releases).
+Copy the `php_xz.dll` into the `/ext` directory of your PHP installation and add the line `extension=xz` to your `php.ini`.
+
+
+## Basic usage
+
+### String-based operations
+
+You can easily compress and decompress strings.
+
+```php
+$string = 'This is a test string that will be compressed and then decompressed.';
+
+// Compress a string
+$compressed = xzencode($string);
+
+// Decompress a string
+$decompressed = xzdecode($compressed);
+```
+
+### File-based operations
+
+The extension also supports stream-based operations for working with `.xz` files.
+
+```php
+$file = '/tmp/test.xz';
+
+// Writing to an .xz file
+$wh = xzopen($file, 'w');
+xzwrite($wh, 'Data to write');
+xzclose($wh);
+
+// Reading from an .xz file and outputting its contents
+$rh = xzopen($file, 'r');
+xzpassthru($rh);
+xzclose($rh);
+```
+
+
+## Configuration
+
+You can configure the default compression level and memory limit:
+
+```ini
+
+; Default compression level. Affects `xzencode` and `xzopen`, 
+; but only when the level was not specified. Values 0-9, default is 5.
+xz.compression_level=5
+
+; The maximum amount of memory that can be used when decompressing. Default is 0 (no limit).
+xz.max_memory=65536
+```
+
+Alternatively, the compression level can be supplied as a parameter to the `xzencode()` and `xzopen()` functions:
+
+```php
+const COMPRESSION_LEVEL = 7;
+
+$compressed = xzencode($string, COMPRESSION_LEVEL);
+
+$rh = xzopen($file, 'r', COMPRESSION_LEVEL);
+```
+
+
+## Build from source
 
 ### Linux
 
@@ -28,7 +100,6 @@ sudo make install
 Do not forget to add `extension=xz.so` to your `php.ini`.
 
 ### Windows
-Windows builds are now done automatically on each push; you can download them from the [build artifacts](https://docs.github.com/en/actions/managing-workflow-runs/downloading-workflow-artifacts) or [releases](https://github.com/codemasher/php-ext-xz/releases) (after 1.1.2).
 
 If you want to build it on your own, follow the steps under "[Build your own PHP on Windows](https://wiki.php.net/internals/windows/stepbystepbuild_sdk_2)" to setup your build environment.
 Before the compilation step, clone this repository to `[...]\php-src\ext\xz` and proceed.
@@ -56,26 +127,6 @@ nmake snap
 
 Please note that the `liblzma` dependency is not included with PHP < 8, so you will need to [download it manually](https://windows.php.net/downloads/php-sdk/deps/vs16/x64/liblzma-5.2.5-vs16-x64.zip) and extract it into the `deps` directory.
 
-Copy the `php_xz.dll` into the `/ext` directory of your PHP installation and add the line `extension=xz` to your `php.ini` or in case of the versioned .dll from the artifacts something like: `extension=xz-0eebbf2-8.2-ts-vs16-x64` - omit the `php_` and `.dll`.
-
-## Basic usage
-
-```php
-$fh = xzopen('/tmp/test.xz', 'w');
-xzwrite($fh, 'Data you would like compressed and written.');
-xzclose($fh);
-
-$fh = xzopen('/tmp/test.xz', 'r');
-xzpassthru($fh);
-xzclose($fh);
-```
-
-```php
-$str = 'Data you would like compressed.';
-
-$encoded = xzencode($str);
-$decoded = xzdecode($encoded);
-```
 
 ## Disclaimer
 May or may not contain bugs. Use at your own risk.