# AGENTS.md
# Repository guidance for agentic coding tools

## Scope and intent
- This repo is a WordPress plugin integration for Boseat Booking.
- Primary entry point is `boseat-booking-widget.php` at repo root.
- WordPress core is vendored under `wordpress/`; avoid editing core unless explicitly asked.

## Rules from tooling
- Cursor rules: not found (`.cursor/rules/` and `.cursorrules` absent).
- Copilot instructions: not found (`.github/copilot-instructions.md` absent).
- Follow any future rules if these files are added.

## Build, lint, test
No repo-level build, lint, or test scripts were found in the root.
Use the commands below only if you intentionally add a toolchain.

### PHP (if you add PHPUnit)
- Run all tests: `vendor/bin/phpunit`
- Run one test by class or method: `vendor/bin/phpunit --filter <TestName>`
- Run one test file: `vendor/bin/phpunit tests/ExampleTest.php`

### PHP lint (manual)
- Lint a file: `php -l boseat-booking-widget.php`
- Lint all plugin PHP files: `php -l boseat-booking-widget.php`

### WordPress integration
- No WP-CLI scripts are defined here. Use your local WP setup if needed.

## Repository layout
- `boseat-booking-widget.php`: main plugin file and settings UI.
- `README.md`: plugin usage and shortcode examples.
- `wordpress/`: full WordPress core (treat as external dependency).
- No `package.json` or top-level `composer.json` detected.

## Coding style and conventions
Follow existing patterns in `boseat-booking-widget.php` unless instructed otherwise.

### PHP language level
- Minimum PHP is 7.2 (see plugin header).
- Avoid features newer than PHP 7.2 unless requirement is updated.

### Formatting
- Indent with 4 spaces.
- Use braces on new lines consistent with existing file.
- Prefer `array(...)` over `[...]` to match current style.
- Keep lines readable; wrap long HTML attributes when editing HTML blocks.

### Imports and dependencies
- Do not add Composer or npm dependencies unless explicitly requested.
- If a file must be included, use `require_once` and guard paths.
- Prefer WordPress helpers (`wp_register_script`, `wp_enqueue_script`) over raw script tags.

### Types and data flow
- PHP is not strict-typed here; document expectations in phpdoc when unclear.
- Treat shortcode attributes as untrusted user input; sanitize before use.
- Keep option values as strings/booleans in `boseat_options`.

### Naming
- Classes: `PascalCase` (e.g., `Boseat_Booking`).
- Functions: `snake_case` with `boseat_booking_` prefix for global functions.
- Variables: `snake_case` for local variables, `$this->camelCase` for class members.
- Options: use the `boseat_options` array with specific keys (e.g., `tenant`).

### WordPress conventions
- Gate direct file access with `if (!defined('ABSPATH')) { exit; }`.
- Use hooks: `add_action`, `add_filter` for integration points.
- Use `register_setting` with a `sanitize_callback` for admin options.
- Use `shortcode_atts` for shortcode defaults and merging.
- Return strings from shortcodes; do not echo.

### Admin UI
- Check capability `manage_options` before rendering settings pages.
- Use `settings_fields` / `do_settings_sections` when adding new settings.
- Show feedback via `add_settings_error` and `settings_errors`.

### Output escaping
- Always escape output for HTML contexts.
  - `esc_html()` for text nodes.
  - `esc_attr()` for attributes.
  - `esc_url()` / `esc_url_raw()` for URLs.
  - `esc_js()` for inline JS data.
- Escape before echoing or concatenating into markup.

### JavaScript
- Keep inline scripts minimal and scoped; avoid global symbols.
- Use `wp_add_inline_script` tied to a registered handle.
- When embedding data, escape with `esc_js()` and validate inputs server-side.

### Input sanitization
- Sanitize all user input via `sanitize_text_field`, `esc_url_raw`, etc.
- Validate enums using `in_array` with explicit allowlists.
- Convert booleans with `filter_var(..., FILTER_VALIDATE_BOOLEAN)`.

### Settings and options
- Centralize defaults in `register_setting` and activation hook.
- Use `get_option('boseat_options', array())` and safe defaults.
- Keep option keys stable; migrations should be explicit.

### Internationalization
- Wrap user-facing strings in `__()` / `esc_html_e()` with text domain `boseat-booking`.
- Keep translations in `/languages` if added later.

### Security
- Check capabilities for admin pages: `current_user_can('manage_options')`.
- Use nonces for forms or actions that change data.
- Avoid trusting `$_GET`/`$_POST` without sanitization.

### Frontend behavior
- Enqueue scripts via `wp_register_script` / `wp_enqueue_script`.
- Use `wp_add_inline_script` for init scripts and keep data escaped.
- Avoid adding global JS unless necessary.

### Error handling
- Prefer early returns with user-friendly messages.
- Use `add_settings_error` / `settings_errors` for admin feedback.
- Log to `console.error` in frontend scripts only when necessary.

### Documentation
- Update `README.md` when shortcode behavior or parameters change.
- Keep examples consistent with defaults in `shortcode_atts`.

### HTML/CSS
- Inline styles exist; keep them minimal and consistent with current usage.
- If you add CSS, consider moving to enqueued styles later.
- Avoid DOM IDs that can collide; use `wp_rand` for unique container IDs.

## Common changes
- Shortcode changes: update defaults in `shortcode_atts` and docs in `README.md`.
- Settings changes: update `register_setting` defaults, admin UI, and sanitize logic.
- Script changes: update `$script_url` and initialization data in `get_init_script`.

## Do not touch unless asked
- WordPress core under `wordpress/`.
- Third-party libraries under `wordpress/wp-includes/`.

## Suggested workflow for agents
- Read `README.md` and `boseat-booking-widget.php` first.
- Make changes in the plugin root file unless a new file is required.
- Keep edits narrow and aligned with existing patterns.
- Update `README.md` if behavior or parameters change.

## Notes for single-test execution
- No tests are configured here; add a test runner before attempting to run tests.
- If PHPUnit is added later, prefer `--filter` for a single test case.

## File locations referenced
- `boseat-booking-widget.php`
- `README.md`
- `wordpress/`