Abstract algorithm options into an Options class

[thekid]

Most compression algorithms only have one parameter: the compression level - GZip, for example, uses one between 0 and 9.

use io\streams\Compression;
use io\streams\compress\Options;

$gzip= Compression::named('gzip');

// Use defaults
$gzip->compress($data);

// Pass in the compression level, backwards compatible
$gzip->compress($data, Compression::STRONGEST);

// Pass in an Options instance
$gzip->compress($data, new Options(level: Compression::STRONGEST));

// Pass in an a map of options, e.g. from a configuration file
$gzip->compress($data, ['level' => Compression::STRONGEST]);

Other algorithms may require other parameters. Snappy, for example, requires the uncompressed length upfront, see #11 (comment)

use io\File;
use io\streams\{Compression, FileInputStream, FileOutputStream};
use io\streams\compress\Options;

$snappy= Compression::named('snappy');

$in= new FileInputStream('README.md');
try {
  $out= $snappy->open(new FileOutputStream('README.sn')), new Options(length: $in->size()));
  while ($in->available()) {
    $out->write($in->read()):
  }
  $out->close();
} finally {
  $in->close();
}

[thekid]

These changes create a BC break for classes extending this base class:

use io\streams\compress\Algorithm;

class Impl extends Algorithm {
  public function compress(string $data, int $level= -1): string { }

  /* Shortened for brevity */
}

...raises the following error: Declaration of Impl::compress(string $data, int $level = -1): string must be compatible with io\streams\compress\Algorithm::compress(string $data, $options = null): string

[thekid]

For anyone calling these methods BC is ensured, see example above.

[thekid]

Released in https://github.com/xp-forge/compression/releases/tag/v2.0.0