README

A PHP extension for integrating the Rust-based PageFind search indexing library into PHP applications. PageFind is a static search library that works without a backend, making it ideal for static sites and JAMstack applications.

Overview

This PHP extension wraps the PageFind Rust library, allowing you to:

Index HTML content directly from PHP
Add entire directories of HTML files to the search index
Write search index files that can be served statically

The extension handles all the interaction with the PageFind Rust library, providing a clean PHP API that follows PHP's best practices for error handling and response management.

Installation

Prerequisites: Rust toolchain must be installed.

git clone https://github.com/jaapio/php-pagefind.git
cd php-pagefind
cargo build
# Copy the resulting .so file to your PHP extensions directory

Usage

Basic Usage

<?php
// Create a configuration
$config = new Pagefind\ServiceConfig(
    true,  // keep URL
    true,  // verbose mode
    'en'   // fallback language (optional, defaults to 'en')
);

try {
    // Initialize the indexer
    $indexer = new Pagefind\Indexer($config);
    
    // Index an HTML string
    $response = $indexer->addHtmlFile(
        'document-id',
        '/page-url',
        '<h1>Page Title</h1><p>Page content for indexing</p>'
    );
    
    // Index a directory of HTML files (with optional file pattern)
    $response = $indexer->addDirectory('/path/to/html/files', '*.html');
    
    // Write the search index to a directory
    $response = $indexer->writeFiles('/path/to/output/directory');
    
    echo "Search index created successfully: " . $response->getMessage();
    
} catch (Pagefind\Exception $e) {
    echo "Error: " . $e->getMessage();
}

Response Object

All successful operations return a Pagefind\Response object with:

// Check if the operation was successful
$success = $response->isSuccess();

// Get a descriptive message about the operation
$message = $response->getMessage();

// Get any metadata from the operation (returns null if no metadata)
$metadata = $response->getMetadata();

Exception Handling

The extension uses exceptions for error handling. All errors throw a Pagefind\Exception that extends PHP's native Exception class:

try {
    $indexer->addDirectory('/non/existent/path');
} catch (Pagefind\Exception $e) {
    // Handle the error
    echo "Error indexing directory: " . $e->getMessage();
}

API Reference

Pagefind\ServiceConfig

Configuration options for the PageFind service.

__construct(bool $keep_url, bool $verbose, string $fallback_language = 'en')

$keep_url: Whether to keep the original URL in the index
$verbose: Whether to output verbose information
$fallback_language: The language to use when no language is specified (default: 'en')

Pagefind\Indexer

The main class for indexing content.

// Initialize with a configuration
__construct(Pagefind\ServiceConfig $config)

// Add an HTML file to the index
add_html_file(string $source_path, string $url, string $content): Pagefind\Response

// Add a directory of HTML files to the index
add_directory(string $path, ?string $pattern = null): Pagefind\Response

// Write the index files to the specified directory
write_files(string $output_directory): Pagefind\Response

Pagefind\Response

Response object returned by successful operations.

is_success(): bool
get_message(): string
get_metadata(): ?string

License

MIT License

Credits

Built on PageFind
PHP integration by Jaapio

jaapio / pagefind

Maintainers

Details