---
type: Document
title: Claude
description: >-
  This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository
timestamp: 2025-09-14T02:57:13.748100+00:00
layer: wiki
---
# CLAUDE.md

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

## Essential Development Commands

```bash
# 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

<!-- MANUAL ADDITIONS START -->
- 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
<!-- MANUAL ADDITIONS END -->