care-book-block-ultimate/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Essential Development Commands

# Dependency Management
composer install                    # Install PHP dependencies
composer dump-autoload              # Regenerate autoloader

# Testing
composer test                       # Run full PHPUnit test suite
composer test:coverage             # Generate coverage report
vendor/bin/phpunit tests/Unit       # Run unit tests only
vendor/bin/phpunit tests/Integration # Run integration tests only

# Code Quality
composer phpcs                      # Check WordPress coding standards
composer phpcbf                     # Auto-fix coding standards
composer phpstan                    # Static analysis (level 6)
composer quality                    # Run all quality checks

# WordPress Plugin Testing
wp plugin activate care-book-block-ultimate
wp plugin deactivate care-book-block-ultimate
wp db query "SELECT * FROM wp_care_booking_restrictions"

Architecture Overview

This is a WordPress plugin that integrates with KiviCare to provide advanced appointment control through CSS-first filtering. The architecture follows modern PHP 8.3+ practices:

Core Design Patterns

• CSS-First Filtering: Immediate UI hiding via injected CSS, backed by PHP data filtering
• PSR-4 Autoloading: Modern namespace organization under CareBook\Ultimate\
• Strict Typing: All files use declare(strict_types=1)
• Immutable Models: Readonly classes for data security
• Performance Caching: WordPress transients with intelligent invalidation

Key Components

• src/Admin/: WordPress admin interface and AJAX handlers
• src/Cache/: Cache management and invalidation logic
• src/Database/: Query builders, migrations, health checks
• src/Models/: Readonly data models with strict typing
• src/Services/: Business logic for restrictions and filtering
• src/Integration/: KiviCare plugin hooks and compatibility

Database Architecture

• Custom table: wp_care_booking_restrictions
• Optimized for MySQL 8.0+ with JSON metadata columns
• Proper indexing for high-performance queries
• WordPress $wpdb integration with prepared statements

Code Standards

PHP Requirements

• Version: PHP 8.1+ (optimized for 8.3+)
• Features: Uses readonly classes, enums, typed properties, strict types
• Standards: WordPress Coding Standards via PHPCS
• Analysis: PHPStan level 6 with WordPress-specific ignores

WordPress Integration

• Never modify core WordPress or KiviCare files
• Use WordPress hooks/filters exclusively
• Follow WordPress security practices (nonces, capability checks, sanitization)
• Maintain WordPress admin UI consistency

Performance Targets

• <1.5% page load overhead
• <200ms admin AJAX response times
• <300ms for restriction toggles (including cache invalidation)
• Support for thousands of concurrent restrictions

Testing Strategy

The project uses RED-GREEN-Refactor methodology:

1. Unit Tests (tests/Unit/): Individual class testing with mocks
2. Integration Tests (tests/Integration/): WordPress + KiviCare integration
3. Coverage Requirements: Maintain >80% code coverage
4. Mock System: Custom mocks for WordPress and KiviCare APIs in tests/Mocks/

Key Test Files

• tests/bootstrap.php: WordPress test environment setup
• tests/Integration/KiviCareIntegrationTest.php: Plugin compatibility tests
• tests/Integration/WordPressHooksTest.php: WordPress hooks validation

Development Notes

Plugin Structure

• Main plugin file: care-book-block-ultimate.php
• Version: 1.0.0 (defined in multiple locations - keep synchronized)
• Text domain: care-book-ultimate
• Namespace: CareBook\Ultimate

Dependencies & Compatibility

• WordPress: 6.0+ (tested up to 6.8)
• KiviCare: 3.6.8+
• MySQL: 8.0+ recommended
• Browser Support: CSS-first approach requires modern CSS support

• Utilizamos sempre snippets WP Code em vez de modificar functions.php em sites WordPress
• Ligação SSH ao server.descomplicar.pt é porta 9443
• Nunca criar files a menos que absolutamente necessários
• Sempre preferir editar file existente em vez de criar novo
• Nunca criar files de documentação (*.md) ou README proativamente