# WordPress Theme and Plugin Support in phprs

> **Status:** Demo stubs only — not production WordPress. Bootstrap may fail on `require` of `wp-includes/wp-db.php` until `array()` syntax is supported or the stub uses `[]`. See [README.md](README.md).

This directory demonstrates a **WordPress-style** theme and plugin stub system for phprs (not production WordPress).

## Features Implemented

### Plugin System
- **Plugin Loading**: Automatic loading of plugins from `wp-content/plugins/`
- **Activation Hooks**: `register_activation_hook()` and `register_deactivation_hook()`
- **Action Hooks**: Full `add_action()`, `do_action()`, `remove_action()` with priority support
- **Filter Hooks**: Full `add_filter()`, `apply_filters()`, `remove_filter()` with priority support
- **Hook Introspection**: `has_action()`, `has_filter()`, `did_action()`

### Theme System
- **Theme Loading**: Automatic loading of theme `functions.php`
- **Theme Support**: `add_theme_support()`, `remove_theme_support()`, `current_theme_supports()`
- **Navigation Menus**: `register_nav_menu()`, `register_nav_menus()`
- **Sidebars/Widgets**: `register_sidebar()`, `register_widget()`
- **Template Functions**: `get_header()`, `get_footer()`, `get_sidebar()`, `get_template_part()`
- **Asset Enqueuing**: `wp_enqueue_script()`, `wp_enqueue_style()` (stubs)

### Session Handling (WordPress demo stubs only)
- **wp_session_*** helpers in `wp-includes/session.php` for the example tree
- **Not** the PHP `session` extension in the main engine (`src/` has no `session_start` builtin)

### Database Integration
- **wpdb Class**: Full in-memory database abstraction
- **Options API**: `get_option()`, `update_option()`, `add_option()`, `delete_option()`

## Directory Structure

```
examples/wordpress/
├── wp-content/
│   ├── plugins/
│   │   └── example-plugin/
│   │       └── example-plugin.php    # Example plugin with hooks
│   └── themes/
│       └── example-theme/
│           ├── functions.php          # Theme setup and hooks
│           └── style.css              # Theme stylesheet
├── wp-includes/
│   ├── wp-db.php                      # Database abstraction layer
│   ├── functions.php                  # Core WordPress functions
│   ├── plugin.php                     # Plugin API and hooks system
│   ├── theme.php                      # Theme API
│   └── session.php                    # Session handling
├── wp-config.php                      # WordPress configuration
├── wp-settings.php                    # Core loading script
├── wp-load.php                        # Configuration loader
├── wp-blog-header.php                 # Main request handler
├── index.php                          # Entry point
└── test-theme-plugin.php              # Comprehensive test script
```

## Running the Examples

### Basic WordPress Bootstrap
```bash
cargo run -p phprs-cli -- run examples/wordpress/index.php
```

### Theme and Plugin Test Suite
```bash
cargo run -p phprs-cli -- run examples/wordpress/test-theme-plugin.php
```

## Example Plugin

The example plugin (`wp-content/plugins/example-plugin/example-plugin.php`) demonstrates:

1. **Plugin Header**: Standard WordPress plugin metadata
2. **Activation/Deactivation Hooks**: Setup and cleanup on plugin state changes
3. **Action Hooks**: Responding to WordPress events (`plugins_loaded`, `admin_menu`, `wp_footer`)
4. **Filter Hooks**: Modifying content (`the_content` filter)
5. **Shortcodes**: Custom `[example]` shortcode
6. **AJAX Handlers**: Example AJAX endpoint

### Plugin Code Example
```php
// Add filter to modify content
add_filter('the_content', 'example_plugin_filter_content');

function example_plugin_filter_content($content) {
    return '[Example Plugin] ' . $content;
}

// Add action to footer
add_action('wp_footer', 'example_plugin_footer');

function example_plugin_footer() {
    echo '<!-- Example Plugin Active -->';
}
```

## Example Theme

The example theme (`wp-content/themes/example-theme/`) demonstrates:

1. **Theme Setup**: Registering theme features and support
2. **Navigation Menus**: Multiple menu locations
3. **Widget Areas**: Sidebar and footer widget areas
4. **Script/Style Enqueuing**: Loading theme assets
5. **Custom Functions**: Template tags and helper functions
6. **Filters**: Modifying WordPress behavior (excerpt length, etc.)

### Theme Code Example
```php
// Theme setup
add_action('after_setup_theme', 'example_theme_setup');

function example_theme_setup() {
    add_theme_support('post-thumbnails');
    add_theme_support('custom-logo');
    
    register_nav_menus(array(
        'primary' => 'Primary Menu',
        'footer' => 'Footer Menu'
    ));
}

// Enqueue assets
add_action('wp_enqueue_scripts', 'example_theme_scripts');

function example_theme_scripts() {
    wp_enqueue_style('example-theme-style', get_stylesheet_directory_uri() . '/style.css');
}
```

## Test Script Output

The `test-theme-plugin.php` script validates:

1. ✓ Plugin loading and `plugins_loaded` action
2. ✓ Theme loading and `after_setup_theme` action
3. ✓ Custom action hooks execution
4. ✓ Filter hooks with value modification
5. ✓ Theme support features
6. ✓ Session handling (set/get/delete)
7. ✓ Database options API
8. ✓ wpdb initialization

## Hooks System Implementation

The hooks system supports:
- **Priority-based execution**: Hooks execute in priority order (default: 10)
- **Multiple callbacks**: Multiple functions can hook into the same action/filter
- **Hook removal**: `remove_action()` and `remove_filter()`
- **Hook introspection**: Check if hooks exist or have been fired
- **Filter chaining**: Filters can modify values through multiple callbacks

### Hook Execution Flow
```
1. add_action('init', 'my_function', 10)
2. add_action('init', 'another_function', 5)  // Executes first (lower priority)
3. do_action('init')
   → Executes 'another_function' (priority 5)
   → Executes 'my_function' (priority 10)
```

## Built-in Functions Added

For WordPress compatibility, the following built-in functions were added to phprs:

- `isset()`, `empty()`, `unset()` - Variable handling
- `htmlspecialchars()`, `htmlentities()` - HTML escaping
- `esc_html()`, `esc_attr()`, `esc_url()` - WordPress escaping
- `preg_match()`, `preg_replace()` - Regex (stubs)
- `shortcode_atts()` - Shortcode attribute merging
- `array_merge()` - Array merging
- `ucfirst()` - String capitalization
- `str_replace()` - String replacement
- `uniqid()`, `time()`, `dechex()` - Utility functions

## Session Handling

Session data is stored in-memory using global variables:

```php
wp_session_start();
wp_session_set('user_id', 123);
$user_id = wp_session_get('user_id');
wp_session_delete('user_id');
wp_session_destroy();
```

## Known Limitations

1. **Constant Concatenation**: Direct constant concatenation (e.g., `ABSPATH . 'file.php'`) has issues. Use `constant()` function or variables as workaround.
2. **Regex**: `preg_match()` and `preg_replace()` are stubs and don't perform actual regex operations.
3. **Database**: wpdb uses in-memory storage, not a real database connection.
4. **Sessions**: Session data is not persisted between script executions.
5. **AJAX**: AJAX handlers are stubs and don't process actual HTTP requests.

## Future Enhancements

- Real regex support with `preg_*` functions
- Persistent session storage
- Database connection to MySQL/PostgreSQL
- HTTP request handling for AJAX
- Template rendering engine
- Full shortcode parsing
- Widget rendering
- Customizer API implementation

## Testing

Run the comprehensive test suite:
```bash
cargo run -p phprs-cli -- run examples/wordpress/test-theme-plugin.php
```

Expected output shows all tests passing with "Yes" confirmations for each feature.

## Contributing

When adding new WordPress features:
1. Add function stubs to appropriate `wp-includes/*.php` files
2. Implement built-in functions in `src/engine/vm/builtins.rs` if needed
3. Add test cases to `test-theme-plugin.php`
4. Update this README with new features
5. Follow WordPress coding standards and naming conventions
