Skip to content

DEVELOPER.md

Latest commit

 

History

History
329 lines (240 loc) · 9.75 KB

DEVELOPER.md

File metadata and controls

329 lines (240 loc) · 9.75 KB

Developer Guide

This document describes how to set up your development environment to build and test the Valkey GLIDE PHP wrapper.

Development Overview

The Valkey GLIDE PHP wrapper is implemented as a PHP extension written in C that interfaces with the Rust-based Glide core library. The PHP extension communicates with the core using:

  1. Using the protobuf protocol for message passing.
  2. Using C FFI bindings to interface with the Rust core library compiled as a shared object.

The extension follows standard PHP extension development practices and uses the Zend API to expose Valkey GLIDE functionality to PHP applications.

Important: The PHP extension depends on the FFI (Foreign Function Interface) library located in the valkey-glide/ffi directory. This FFI library provides the bridge between the PHP extension and the Rust-based valkey-glide/glide-core. You must build the FFI library before attempting to build the PHP extension.

Build from source

Prerequisites

Software Dependencies

  • PHP development headers (php-dev or php-devel)
  • PHP CLI
  • git
  • GCC
  • make
  • autotools (autoconf, automake, libtool)
  • pkg-config
  • protoc (protobuf compiler) >= v3.20.0
  • openssl
  • openssl-dev
  • rustup
  • ziglang and zigbuild (for GNU Linux only)
  • valkey (for testing)

Valkey installation

See the Valkey installation guide to install the Valkey server and CLI.

Dependencies installation for Ubuntu

sudo apt update -y
sudo apt install -y php-dev php-cli git gcc make autotools-dev libtool pkg-config openssl libssl-dev unzip libprotobuf-c-dev libprotobuf-c1

# Install clang-format-18 and ensure clang-format points to it.
sudo apt install -y clang-format-18
sudo update-alternatives --install /usr/bin/clang-format clang-format /usr/bin/clang-format-18 100
clang-format --version  # Version 18.x

# Install rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source "$HOME/.cargo/env"
# Check that the Rust compiler is installed
rustc --version

Continue with Install protobuf compiler and Install ziglang and zigbuild below.

Dependencies installation for CentOS

sudo yum update -y
sudo yum install -y php-devel php-cli git gcc make autoconf automake libtool pkgconfig openssl openssl-devel unzip php-bcmath
# Install rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source "$HOME/.cargo/env"
# Check that the Rust compiler is installed
rustc --version

Continue with Install protobuf compiler and Install ziglang and zigbuild below.

Dependencies installation for MacOS

brew update
brew install php@8.3 git gcc make autoconf automake libtool pkgconfig protobuf openssl protobuf-c composer
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source "$HOME/.cargo/env"
# Check that the Rust compiler is installed
rustc --version

# Install clang-format-18 and update PATH to point to it.
brew install llvm@18
echo 'export PATH="/opt/homebrew/opt/llvm@18/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
clang-format --version  # Should show version 18.x

Install protobuf compiler

To install protobuf for MacOS, run:

brew install protobuf
# Verify the Protobuf compiler installation
protoc --version

# If protoc is not found or does not work correctly, update the PATH
echo 'export PATH="/opt/homebrew/opt/protobuf@3/bin:$PATH"' >> /Users/$USER/.bash_profile
source /Users/$USER/.bash_profile
protoc --version

For the remaining systems, do the following:

PB_REL="https://github.com/protocolbuffers/protobuf/releases"
curl -LO $PB_REL/download/v3.20.3/protoc-3.20.3-linux-x86_64.zip
unzip protoc-3.20.3-linux-x86_64.zip -d $HOME/.local
export PATH="$PATH:$HOME/.local/bin"
# Check that the protobuf compiler is installed. A minimum version of 3.20.0 is required.
protoc --version

Install ziglang and zigbuild

pip3 install ziglang
cargo install --locked cargo-zigbuild

Installing from Packagist

You can use pie to install the extension from the Packagist repository. See: https://packagist.org/packages/valkey-io/valkey-glide-php

Before starting this step, make sure you've installed all dependencies above.

Additionally, you will need to install the pie tool.

On Linux, you can download pie with curl. eg:

curl -L https://github.com/php/pie/releases/latest/download/pie.phar -o pie
chmod +x pie
sudo mv pie /usr/local/bin/pie
export PATH="$PATH:/usr/local/bin"

On MacOS, install with Homebrew:

brew install pie

To install the Valkey Glide extension, simply use the pie command:

# VERSION can be set to any release tag or branch at https://github.com/valkey-io/valkey-glide-php.git
export VERSION=1.0.0
pie install valkey-io/valkey-glide-php:$VERSION

Installing from PECL

You can install the extension using PECL from GitHub releases:

# Install from a specific release
pecl install https://github.com/valkey-io/valkey-glide-php/releases/download/v1.0.0/valkey_glide-1.0.0.tgz

# Or download and install manually
wget https://github.com/valkey-io/valkey-glide-php/releases/download/v1.0.0/valkey_glide-1.0.0.tgz
pecl install valkey_glide-1.0.0.tgz

After installation, add the extension to your php.ini:

extension=valkey_glide

Verify the installation:

php -m | grep valkey_glide
php -r "if (extension_loaded('valkey_glide')) echo 'SUCCESS: Extension loaded!'; else echo 'ERROR: Extension not loaded';"

Steps for building and installing from source

Before starting this step, make sure you've installed all software requirements.

  1. Clone the repository:

    VERSION=2.0.0 # You can modify this to other released version or set it to "main" to get the unstable branch
git clone --recurse-submodules --branch ${VERSION} https://github.com/valkey-io/valkey-glide-php.git
cd valkey-glide-php

1a. Initialize submodules (if not cloned with --recurse-submodules):

```bash
git submodule update --init --recursive
```

  1. Build the FFI library (required dependency):

    # Build the FFI library that the PHP extension depends on
python3 utils/patch_proto_and_rust.py
cd valkey-glide/ffi
cargo build --release
cd ../../

  2. Prepare the build environment:

    # Initialize the extension build system
phpize

    Note for macOS users: phpize on macOS (Homebrew) has a bug where it creates files with read-only permissions, causing permission errors on subsequent runs. If you encounter permission errors, fix them with:

    find build -type f -exec chmod u+w {} \;
chmod u+w run-tests.php configure config.h.in 2>/dev/null || true

  3. Configure the build:

    # Configure with Valkey Glide support enabled
./configure --enable-valkey-glide

  4. Build the extension:

    # Pre-build step to prepare modules
make build-modules-pre

# Build the extension
make

  5. Install the extension:

    # Install to PHP extensions directory
make install

  6. Enable the extension:

    Add the following line to your php.ini file:

    extension=valkey_glide

    You can find the php.ini file location with "php --ini"

  7. Verify installation:

    # Check if the extension is loaded
php -m | grep valkey_glide

# Get extension information
php --ri valkey_glide

Test

To run unit tests, use:

protoc --proto_path=./valkey-glide/glide-core/src/protobuf --php_out=./tests/ ./valkey-glide/glide-core/src/protobuf/connection_request.proto
composer install --no-interaction --prefer-dist --optimize-autoloader
make install
cd tests
./start_valkey_with_replicas.sh 
./create-valkey-cluster.sh 
php -n -d extension=../modules/valkey_glide.so TestValkeyGlide.php

Linters

Development on the PHP wrapper involves changes in both C and PHP code. We have comprehensive linting infrastructure to ensure code quality and consistency. All linting checks are automatically run in our GitHub Actions CI pipeline.

  • clang-format - C code formatting with Google-based style. Configured by .clang-format.
  • phpcs (PHP_CodeSniffer) - enforces PHP code standards. Configured by phpcs.xml.
  • phpcbf (PHP Code Beautifier and Fixer) - corrects PHP code standards. Configured by phpcs.xml.

Running Linters

# All linters
./lint.sh            # Check
./lint.sh --fix      # Fix

# C code only
./lint-c.sh          # Check
./lint-c.sh --fix    # Fix

# PHP code only
./lint-php.sh        # Check
./lint-php.sh --fix  # Fix

Git Hooks

Install the pre-commit hook to automatically run linters before each commit:

./git_hooks/install-git-hooks.sh

IDE Integration

VSCode is configured to automatically use the project's linting tools:

  • Real-time PHP and C code linting
  • Format on save for both languages
  • Integration with project-specific linting configurations
  • Extensions recommended: PHP, C/C++, phpcs, phpstan, clangd

Extension Development Guidelines

PHP Extension Conventions

When adding new functionality to the PHP extension:

  1. Function Naming: Use valkey_glide_ prefix for internal functions
  2. Memory Management: Always use emalloc/efree for request-scoped memory
  3. Error Handling: Use PHP's exception system via zend_throw_exception
  4. Parameter Parsing: Use ZEND_PARSE_PARAMETERS_START macros
  5. Return Values: Use appropriate RETURN_* macros

Community and Feedback

We encourage you to join our community to support, share feedback, and ask questions. You can approach us for anything on our Valkey Slack: Join Valkey Slack.