Save this content to: AGENTS.md

# Working with WpStarter

## Project context

This repository is the `wpstarter/framework` Composer package, not the application skeleton. WpStarter is a Laravel port for WordPress: 1.x is based on Laravel 8.x, and 2.x on Laravel 12.x. This checkout targets PHP 8.2 or later; consult `composer.json` for dependency constraints.

Use the installed source as the authority for APIs and behavior. Laravel documentation is useful background, but WordPress integration differs from a standalone Laravel application.

When this package is installed under `vendor/wpstarter/framework`, treat the paths below as relative to that package directory. For application work, put customizations in the application's controllers, providers, middleware, and configuration. Change framework source when the task is explicitly about the framework itself.

## Namespaces and helpers

- Use `WpStarter\` in place of `Illuminate\` for ported framework classes, including imports, type hints, contracts, and facade references.
- Laravel-style global helpers use `ws_`, such as `ws_app()`, `ws_config()`, `ws_request()`, `ws_view()`, and `ws_route()`. The translation helper corresponding to `__()` is `ws___()`.
- WordPress integration has additional helpers with distinct names: `is_wp()`, `wp_view()`, `content_view()`, and `shortcode_view()`. Verify helper names and signatures in the relevant helper file instead of applying a prefix mechanically.
- Do not assume a third-party Laravel package works unchanged if it depends on `Illuminate` classes or a standalone Laravel bootstrap.

## Routing and WordPress lifecycle

There are three separate routers. Choose imports deliberately; their facades are all named `Route`.

| Container binding | Facade | Purpose |
| --- | --- | --- |
| `router` | `WpStarter\Support\Facades\Route` | HTTP URL routing |
| `wp.router` | `WpStarter\Wordpress\Facades\Route` | Routes matched by shortcode tags in singular post content |
| `wp.admin.router` | `WpStarter\Wordpress\Admin\Facades\Route` | Admin menus and screen routing |

- Content routes use the URI as a shortcode tag. `ShortcodeValidator` checks the current singular post; the WordPress `RouteCollection` extracts shortcode attributes into route parameters.
- The WordPress HTTP kernel falls back to content routing when the HTTP router does not match. Deferred content handling uses `template_redirect` at priority 1 by default; preserve hook timing when changing bootstrap or dispatch.
- The admin kernel registers menus on `admin_menu` and dispatches on `current_screen`. Menu registration populates `hookSuffix`; `ScreenIdValidator` compares it with the current screen ID. Keep these operations at runtime.
- The current `route:cache` command only caches `router`. Load content and admin route definitions even when HTTP routes are cached. The HTTP compiled URL matcher does not replace shortcode or admin screen matching.
- WordPress routing collections preserve custom matching and request-time state. Do not replace them with the base compiled collection without accounting for those behaviors.
- Responses have different rendering targets: `wp_view()` for a full page, `content_view()` for post content, `shortcode_view()` for shortcode output, and `ws_pass()` to continue WordPress handling. Follow the response handler when changing rendering or termination.
- Some provider boot paths are guarded by `is_wp()`. CLI boot and WordPress request boot are different contexts; inspect both when changing providers.

## Source map

Read the entries relevant to the task rather than loading the whole framework.

| Area | Entry points |
| --- | --- |
| Autoload and requirements | `composer.json` |
| Framework services | `src/WpStarter/` by component; `src/WpStarter/Contracts/` for interfaces |
| Core helpers | `src/WpStarter/Foundation/helpers.php`, `src/WpStarter/Support/helpers.php`; other helper files are listed in Composer's `autoload.files` |
| WordPress helpers and services | `src/WpStarter/Wordpress/helpers.php`, `src/WpStarter/Wordpress/WordpressServiceProvider.php` |
| Bootstrap and HTTP lifecycle | `src/WpStarter/Wordpress/Application.php`, `src/WpStarter/Wordpress/Kernel.php`, `src/WpStarter/Foundation/Configuration/ApplicationBuilder.php` |
| HTTP routing and cache | `src/WpStarter/Routing/`, `src/WpStarter/Foundation/Support/Providers/RouteServiceProvider.php`, `src/WpStarter/Foundation/Console/RouteCacheCommand.php` |
| Content routing | `src/WpStarter/Wordpress/Routing/` |
| Admin menus and dispatch | `src/WpStarter/Wordpress/Admin/AdminServiceProvider.php`, `src/WpStarter/Wordpress/Admin/Kernel.php`, `src/WpStarter/Wordpress/Admin/Routing/` |
| WordPress rendering | `src/WpStarter/Wordpress/Http/Response/` |
| Default configuration | `config/`, `config-stubs/` |
| Bundled libraries | `lib/` |
| Tests and static-analysis fixtures | `tests/`, `types/` |

## Changes and verification

- Follow surrounding code and `.editorconfig`: UTF-8, LF, four spaces for PHP, and a final newline. `pint.json` describes formatting rules; avoid unrelated formatting changes.
- Preserve public API compatibility unless the requested change calls for a break. Update related contracts, facade PHPDoc, and relevant `types/` fixtures when signatures change.
- Use existing tests as examples. Add focused regression coverage for behavior changes, particularly lifecycle, matching, and response handling. Documentation-only changes need link and diff checks rather than PHP tests.
- With development dependencies installed, run a focused test using `php vendor/bin/phpunit tests/Routing/RouteCollectionTest.php` or `php vendor/bin/phpunit --filter TestName`. Select the path or filter relevant to the change.
- PHPUnit configuration is in `phpunit.xml.dist`; CI commands and service requirements are in `.github/workflows/tests.yml` and `.github/workflows/databases.yml`. Integration tests may require databases or other services. Report missing prerequisites rather than treating unrun tests as passing.
- For changes needing static analysis, use `php vendor/bin/phpstan analyse -c phpstan.src.neon.dist` for source or `php vendor/bin/phpstan analyse -c phpstan.types.neon.dist` for type fixtures.
- Before finishing, run `git diff --check` and summarize the change, verification, and any unresolved limitations.