yphp

This provides PHP bindings for Y-CRDT, a Rust implementation of the Yjs algorithm, wrapping the official Rust library implementation using PHP FFI.

This project aims to provide a fairly complete and robust coverage of the underlying Y-CRDT library while only exposing an intuitive PHP-only interface for it.

Considerations

• Supported operating systems:
  • Linux: x86_64, aarch64, armv7 | GNU and MUSL
  • Windows: x86_64
  • We could support others but would need help building/testing for those platforms.
• This is currently built against Y-CRDT v0.27.
• This library is not battle-hardened/testing in real use yet. There's a possibility of running into issues such as memory leaks or errors from the underlying Y-CRDT library.
• Use of WeakLink objects is awkward right now due to limitations of the library we're wrapping. You may want to avoid their use for now.
• Due to the way this wraps another library, you may get scenarios where instances of objects point to the same underlying data objects, but are not themselves the same PHP object. Therefore, it's not advised to assume/check exact equality across PHP-based objects in this library.

Installation & Usage

This package can be installed using composer:

composer require ssddanbrown/yphp

Then you can use it via composer autoloading like so:

<?php

use Ssddanbrown\Yphp\YTypes\YDoc;

require __DIR__ . '/vendor/autoload.php';

$doc = new YDoc();
$map = $doc->getYMap('my-map');
$map->set('a', 'A value');

For further guidance see docs/index.md.

Development

This code-base makes heavy use of PHP FFI to wrap the Y-CRDT library, for which modified headers can be found in the lib/libyrs_php.h file, with built versions of the library found in lib/. All core FFI calls should go through the Yrs class, which contains various helper functions for FFI usage.

For testing, PHPUnit is used, and can be run via php vendor/bin/phpunit. All test cases can be found in tests/. The project aims for a high level of testing coverage.

For refactoring and standardisation, we make use of Rector. This can be used like so:

# Perform a dry run to check what changes will be made
php vendor/bin/rector process --dry-run

# Make changes using rector
php vendor/bin/rector process

Please don't provide any unrelated Rector-based changes in any contributions since this can add noise to code changes. We'd prefer to run rector changes post-PR at a convenient point.

Contributing

Contributions are welcome, either as issues or pull requests. Pull requests should also provide suitable testing.

Please don't make heavy use of AI for code changes. Please avoid AI/LLM use for text/content in issues or pull requests in this project.

We do aim for this to be a low-maintenance project. We don't intend to grow the scope of the project too far, so feature requests may be closed early, and other issues/requests may also be closed without resolution if they can't be addressed without a lot of time or effort.

AI Disclaimer

AI has been used to create guidance (based on y.js codebases) to aid the creation of this library. That said, all code has been originally handwritten and has not been largely generated via an LLM. Some handwritten parts may have been assisted by PHPStorm's line autocomplete, which may use LLM-based technologies.

Licensing & Attribution

The project is provided under the MIT license provided in LICENSE.txt.

As part of this project, we also include built binaries and modified headers for Y-CRDT. These can be found in the lib/ directory, under the terms shown in the lib/LIB_LICENSE.txt file.

The project is built upon, and relies upon, the work by the contributors of the Y-CRDT project. If you make heavy use of this library, consider supporting the upstream project.