README

by Andrew Brampton

Deprecated: Since PHP 8.0, the crc32 algorithms within PHP are using hardware accelerated instructions, and are surprisingly fast. Thus this extension is not needed anymore!

CRC32 implementations, that support all crc32 polynomials, as well as (if you install the pecl extension) hardware accelerated versions of CRC32C (Castagnoli).

Supports PHP 7.4 though PHP 8.2. Older PHP versions are supported with "v0.1.0".

Usage

require 'vendor/autoload.php';

use Google\CRC32\CRC32;

$crc = CRC32::create(CRC32::CASTAGNOLI);
$crc->update('hello');
echo $crc->hash();

Depending on the environment and the polynomial, CRC32::create will choose the fastest available version, and return one of the following classes:

Google\CRC32\PHP - A pure PHP implementation.
Google\CRC32\Builtin - A PHP Hash framework implementation.
Google\CRC32\Google - A hardware accelerated implementation (using google/crc32c).

When reading 1M byte chunks, using CRC32::CASTAGNOLI with PHP 7.4 on a 2014 Macbook Pro we get the following performance (higher is better):

Google\CRC32\PHP           12.27 MB/s
Google\CRC32\Builtin       468.74 MB/s (available since PHP 7.4)
Google\CRC32\Google        24,684.46 MB/s (using crc32c.so)

Install

$ composer require google/crc32

crc32c.so

To use the hardware accelerated, a custom PHP extension must be installed. This makes use of google/crc32c which provides a highly optomised CRC32C (Castagnoli) implementation using the SSE 4.2 instruction set of Intel CPUs.

The extension can be installed from pecl, or compiled from stratch.

TODO pecl install crc32c

Once installed or compiled, you'll need to add extension=crc32c.so to your php.ini file.

Compile (Linux / Mac)

Ensure that composer, build tools (e.g build-essential, cmake, etc), and php dev headers (e.g php-dev) are installed.

Simple (using Makefile):

make test

Alternatively (manually):

cd ext

# Install the google/crc32c library
./install_crc32c.sh # From source (recommended)

# or use your favorite package manager, e.g.
# brew install crc32c

# Prepare the build environment
phpize
./configure

# or if using a custom crc32c
# ./configure --with-crc32c=$(brew --prefix crc32c)

## Build and test
make test

The extension will now be at ext/modules/crc32c.so. This file should be copied to your extension directory and reference in your php.ini.

# php.ini
extension=crc32c.so

Testing

make test will test with the current PHP. make test_all will search for available PHP installs, and test with all of them.

Benchmark

To compare the performance of the different CRC32C implementations, run make benchmark.

https://bugs.php.net/bug.php?id=71890

TODO

Test if this works on 32 bit machine.
Add php unit (or similar) testing.
Publish to packagist
Publish to pecl (https://pecl.php.net/account-request.php)
Update instructions for linux.

Licence (Apache 2)

This is not an official Google product (experimental or otherwise), it is just code that happens to be owned by Google.

Copyright 2023 Google Inc. All Rights Reserved.

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

google / crc32

Maintainers

Details