Skip to content

CLAUDE.md

Latest commit

 

History

History
202 lines (161 loc) · 7.02 KB

CLAUDE.md

File metadata and controls

202 lines (161 loc) · 7.02 KB

StellarWP DB - Claude Instructions

Project Overview

StellarWP DB is a WordPress database wrapper and query builder library that provides a fluent interface for constructing and executing database queries. It's built on top of WordPress's $wpdb global and adds a modern, chainable API with proper error handling.

Key Features:

  • Fluent query builder interface
  • SQL injection protection via WordPress's prepared statements
  • Support for complex queries (joins, unions, subqueries, etc.)
  • Meta table abstractions for WordPress-style data
  • Error handling with exceptions
  • Full compatibility with $wpdb methods

Architecture

Core Classes

  1. DB (src/DB/DB.php)

    • Static facade/decorator for $wpdb
    • Entry point for creating query builders via DB::table()
    • Provides static methods that wrap $wpdb methods with error checking
    • Throws DatabaseQueryException on SQL errors

  2. QueryBuilder (src/DB/QueryBuilder/QueryBuilder.php)

    • Main query building class
    • Uses traits to organize functionality:
      • Aggregate - COUNT, SUM, AVG, MIN, MAX operations
      • CRUD - INSERT, UPDATE, DELETE, UPSERT operations
      • FromClause - FROM table handling
      • WhereClause - WHERE conditions
      • JoinClause - JOIN operations
      • SelectStatement - SELECT column handling
      • MetaQuery - WordPress meta table helpers
      • And more...

  3. Config (src/DB/Config.php)

    • Configuration management
    • Allows setting custom exception classes
    • Hook prefix configuration for WordPress integration

Directory Structure

/home/matt/git/db/
├── src/DB/                    # Main source code
│   ├── Config.php            # Configuration class
│   ├── DB.php               # Main DB facade
│   ├── Database/            # Database-specific classes
│   │   ├── Actions/         # Database actions (e.g., EnableBigSqlSelects)
│   │   ├── Exceptions/      # Custom exceptions
│   │   └── Provider.php     # Service provider
│   └── QueryBuilder/        # Query builder components
│       ├── Clauses/         # SQL clause representations
│       ├── Concerns/        # Traits for QueryBuilder
│       ├── Types/           # Type definitions (JoinType, Operator, etc.)
│       ├── QueryBuilder.php # Main query builder
│       ├── JoinQueryBuilder.php
│       └── WhereQueryBuilder.php
├── tests/                    # Test suite
│   ├── wpunit/              # WordPress unit tests
│   └── _support/            # Test support classes
├── .github/workflows/        # GitHub Actions CI/CD
├── composer.json            # PHP dependencies
├── phpstan.neon.dist        # PHPStan configuration
└── README.md                # Documentation

Development Commands

Composer Scripts

# Run static analysis with PHPStan
composer test:analysis

Testing

The project uses Codeception with WordPress testing framework (wp-browser) and a tool called "slic" for managing the test environment:

# Run tests using slic (see .github/workflows/tests-php.yml)
${SLIC_BIN} run wpunit --ext DotReporter

Static Analysis

PHPStan is configured at level 5 with WordPress-specific rules:

  • Configuration: phpstan.neon.dist
  • Includes WordPress stubs via szepeviktor/phpstan-wordpress
  • Analyzes only the src/ directory

Code Conventions

Namespacing

  • Root namespace: StellarWP\DB
  • Follow PSR-4 autoloading standard
  • Tests use StellarWP\DB\Tests namespace

WordPress Integration

  • All table names are automatically prefixed with $wpdb->prefix
  • Use DB::raw() to bypass automatic prefixing
  • Methods match $wpdb signatures where applicable

Error Handling

  • SQL errors throw DatabaseQueryException by default
  • Custom exception classes can be configured via Config::setDatabaseQueryException()
  • All database operations should be wrapped in try-catch blocks in production code

Query Building Patterns

// Basic query
DB::table('posts')
    ->select('ID', 'post_title')
    ->where('post_status', 'publish')
    ->orderBy('post_date', 'DESC')
    ->limit(10)
    ->getAll();

// Complex query with joins and meta
DB::table('posts', 'p')
    ->select(['p.ID', 'id'], ['p.post_title', 'title'])
    ->attachMeta('postmeta', 'p.ID', 'post_id',
        ['_thumbnail_id', 'thumbnailId'],
        ['_custom_field', 'customValue']
    )
    ->leftJoin('term_relationships', 'p.ID', 'tr.object_id', 'tr')
    ->where('p.post_type', 'post')
    ->where('p.post_status', 'publish')
    ->getAll();

Important Notes

For Strauss Integration

The library is designed to be included via Strauss for namespace isolation in WordPress plugins. The README examples assume a namespace prefix like Boom\Shakalaka\.

WordPress Compatibility

  • Requires WordPress with $wpdb global
  • Compatible with WordPress coding standards
  • Follows WordPress database structure conventions (posts, postmeta, etc.)

Performance Considerations

  • Queries are not executed until terminal methods are called (get(), getAll(), count(), etc.)
  • Use attachMeta() for efficient meta queries instead of multiple joins
  • The library generates SQL using WordPress's prepare() method for security

Recent Updates (v1.0.8)

  • Added DB::generate_results() and DB::generate_col() for handling large result sets with bounded queries
  • PHP 8.1 compatibility improvements
  • Better type safety in docblocks

CI/CD

GitHub Actions Workflows

  1. Tests (.github/workflows/tests-php.yml)

    • Runs on every push
    • Uses stellarwp/slic for test environment setup
    • Executes wpunit test suite

  2. Static Analysis (.github/workflows/static-analysis.yml)

    • Runs on every push
    • PHP 8.0 environment
    • Executes PHPStan via composer test:analysis

Common Tasks

Adding New Query Features

  1. Create a new trait in src/DB/QueryBuilder/Concerns/
  2. Add the trait to the QueryBuilder class
  3. Implement the SQL generation method (e.g., getYourFeatureSQL())
  4. Add it to the getSQL() method if needed
  5. Write tests in tests/wpunit/QueryBuilder/

Debugging Queries

// Get the generated SQL without executing
$sql = DB::table('posts')
    ->where('post_status', 'publish')
    ->getSQL();

// Use wpdb's last_query after execution
$results = DB::table('posts')->getAll();
$lastQuery = $wpdb->last_query;

Meta Table Patterns

The library provides special handling for WordPress meta tables:

  • attachMeta() - Efficiently join and select meta values
  • configureMetaTable() - Customize meta table column names
  • Automatic LEFT JOIN generation for each meta key
  • Support for multiple meta values with the same key

Resources