Add foundation-view + docs

AGENTS.md

@@ -14,6 +14,7 @@ Split packages:
 - `stellarwp/foundation-identifier`
 - `stellarwp/foundation-pipeline`
 - `stellarwp/foundation-shutdown`
+- `stellarwp/foundation-view`
 - `stellarwp/foundation-wpcli`
 - `stellarwp/foundation-cli`
 - `stellarwp/foundation-docs`
@@ -49,6 +50,10 @@ Feature-local interfaces should live in a `Contracts/` folder inside the feature
 
 Shared infrastructure interfaces should live under that shared namespace's `Contracts/` folder, for example `Process/Contracts/ProcessRunner.php`.
 
+Design public contracts as the smallest stable capabilities consumers need so applications can replace the supplied implementation without inheriting unrelated backend assumptions. Do not put filesystem, database, transport, framework, or other implementation-specific behavior on a general contract merely because the default concrete class supports it. Use a separate capability contract when only some implementations provide optional behavior, and bind each supported contract to the default implementation in the package provider. Follow interface segregation and dependency inversion: application code should be able to supply a substantially different implementation without implementing meaningless methods or extending Foundation internals.
+
+Keep convenience methods and implementation machinery on the concrete class unless they form a genuine reusable capability. Do not expose private helpers as public API speculatively. Prefer composition, and extract a focused collaborator when another real implementation needs to share the same policy or behavior.
+
 Avoid `use ... as ...` import aliases unless they resolve a real class-name collision or ambiguity. Prefer importing the class by its actual short name. The standing exception is `use lucatume\DI52\Container as C;`, which may be used for concise container factory callbacks.
 
 Exceptions should live in an `Exceptions/` folder. Put shared package exceptions at the package root, for example `src/Database/Exceptions/DatabaseException.php`; put feature-only exceptions under that feature's `Exceptions/` folder only when they are not shared outside that feature.

README.md

@@ -19,6 +19,7 @@ See the [Foundation documentation](https://foundation.stellarwp.com/) for instal
 | [stellarwp/foundation-lock-redis](https://github.com/stellarwp/foundation-lock-redis) | Multiple processes or servers coordinate through dedicated Redis | Runtime |
 | [stellarwp/foundation-database](https://github.com/stellarwp/foundation-database) | A WordPress application needs queries, migrations, or database-backed locks | Runtime |
 | [stellarwp/foundation-identifier](https://github.com/stellarwp/foundation-identifier) | Services need injectable ULID generation and validation | Runtime |
+| [stellarwp/foundation-view](https://github.com/stellarwp/foundation-view) | Services need scoped PHP template rendering without global state | Runtime |
 | [stellarwp/foundation-wpcli](https://github.com/stellarwp/foundation-wpcli) | A shipped WordPress plugin exposes WP-CLI commands | Runtime |
 | [stellarwp/foundation-cli](https://github.com/stellarwp/foundation-cli) | Developers need Foundation generators or monorepo maintenance commands | Development |
 | [stellarwp/foundation-docs](https://github.com/stellarwp/foundation-docs) | Contributors maintain or deploy the Foundation documentation site | Documentation |

composer.json

@@ -46,6 +46,7 @@
         "stellarwp/foundation-log": "self.version",
         "stellarwp/foundation-pipeline": "self.version",
         "stellarwp/foundation-shutdown": "self.version",
+        "stellarwp/foundation-view": "self.version",
         "stellarwp/foundation-wpcli": "self.version"
     },
     "minimum-stability": "dev",
@@ -61,6 +62,7 @@
             "StellarWP\\Foundation\\Log\\": "src/Log/",
             "StellarWP\\Foundation\\Pipeline\\": "src/Pipeline/",
             "StellarWP\\Foundation\\Shutdown\\": "src/Shutdown/",
+            "StellarWP\\Foundation\\View\\": "src/View/",
             "StellarWP\\Foundation\\WPCli\\": "src/WPCli/"
         },
         "exclude-from-classmap": [

src/Docs/astro.config.mjs

@@ -46,6 +46,7 @@ export default defineConfig({
             { slug: 'components/identifier' },
             { slug: 'components/pipeline' },
             { slug: 'components/shutdown' },
+            { slug: 'components/view' },
             { slug: 'components/wp-cli' },
           ],
         },

src/Docs/src/content/docs/components/view.mdx

@@ -0,0 +1,285 @@
+---
+title: View
+description: Render trusted PHP templates to strings from configured or runtime-selected directories.
+sidebar:
+  order: 9
+---
+
+import { CardGrid, LinkCard } from '@astrojs/starlight/components';
+
+Foundation View provides a small contract for rendering named views and a default `PhpView` implementation that renders trusted PHP templates from an explicit directory. It keeps markup in view files while application services remain responsible for selecting the view and preparing its data.
+
+`PhpView` uses ordinary PHP templates without introducing custom template syntax. It captures their output and returns it as a string instead of echoing it automatically. A configured renderer can also create an immutable renderer for another trusted directory at runtime.
+
+## Installation
+
+Install the split package:
+
+```shell
+composer require stellarwp/foundation-view
+```
+
+### Prepare the application
+
+Foundation View uses the shared application configuration and provider architecture established in these guides:
+
+<CardGrid>
+  <LinkCard
+    title="Configure the Container"
+    description="Make config.php available to Foundation providers."
+    href="/start/configure-the-container/"
+  />
+  <LinkCard
+    title="Bootstrap a WordPress Plugin"
+    description="Construct the application before registering feature providers."
+    href="/start/bootstrap-wordpress-plugin/"
+  />
+  <LinkCard
+    title="Register Service Providers"
+    description="Register view infrastructure before features that render templates."
+    href="/start/register-service-providers/"
+  />
+</CardGrid>
+
+## Configuration
+
+### Choose the default view directory
+
+Create a `views/` directory at the application root. In the root `config.php`, provide its absolute path:
+
+```php title="config.php"
+<?php declare(strict_types=1);
+
+return [
+	'view' => [
+		'directory' => __DIR__ . '/views',
+	],
+];
+```
+
+`view.directory` is required and must identify an existing, readable directory. Foundation resolves it to its canonical path before rendering.
+
+### Register the view provider
+
+In `src/App.php`, add `ViewProvider` before feature providers that consume the `View` contract:
+
+```php title="App.php"
+use StellarWP\Foundation\Container\Contracts\Providable;
+use StellarWP\Foundation\View\ViewProvider;
+use YourPlugin\Admin;
+
+/** @var list<class-string<Providable>> */
+private const array PROVIDERS = [
+	ViewProvider::class,
+	Admin\Provider::class,
+];
+```
+
+`ViewProvider` binds one shared `PhpView` instance to `StellarWP\Foundation\View\Contracts\View` and `StellarWP\Foundation\View\Contracts\DirectoryAwareView`.
+
+## Usage
+
+### Create a view before rendering it
+
+View names are relative to the configured directory and omit the `.php` extension. For the name `admin/product-summary`, first create `views/admin/product-summary.php`:
+
+```php title="product-summary.php"
+<?php
+/**
+ * @var string $title   The notice heading.
+ * @var string $summary The product availability summary.
+ */
+?>
+<div class="notice notice-info">
+	<p><strong><?php echo esc_html( $title ); ?></strong></p>
+	<p><?php echo esc_html( $summary ); ?></p>
+</div>
+```
+
+:::note[Document every view variable]
+Add a typed `@var` annotation, including a short description, for every value the view expects. These annotations define the template's input contract, allow PHPStan to analyze the file without undefined-variable errors, and provide type-aware completion in supported IDEs.
+:::
+
+:::caution[Escape output in the view]
+Foundation passes data into trusted PHP files but does not escape it automatically. Escape each value for its HTML, attribute, URL, or JavaScript context when the view outputs it. Do not render user-uploaded PHP templates.
+:::
+
+### Render the view from a service
+
+In `src/Admin/Product_Summary_Notice.php`, inject the `View` contract and return or echo the rendered string at the application boundary:
+
+```php title="Product_Summary_Notice.php"
+<?php declare(strict_types=1);
+
+namespace YourPlugin\Admin;
+
+use StellarWP\Foundation\View\Contracts\View;
+
+/**
+ * Displays the current product count in WordPress administration.
+ */
+final readonly class Product_Summary_Notice {
+
+	public function __construct(
+		private View $view,
+		private Product_Repository $products
+	) {
+	}
+
+	/**
+	 * @action admin_notices
+	 */
+	public function display(): void {
+		$count = $this->products->count();
+
+		echo $this->view->render(
+			'admin/product-summary',
+			[
+				'title'   => __( 'Product catalog', 'your-plugin' ),
+				'summary' => sprintf(
+					/* translators: %d: number of products. */
+					_n( '%d product is available.', '%d products are available.', $count, 'your-plugin' ),
+					$count
+				),
+			]
+		);
+	}
+}
+```
+
+Register the WordPress callback from `src/Admin/Provider.php`:
+
+```php title="Provider.php"
+<?php declare(strict_types=1);
+
+namespace YourPlugin\Admin;
+
+use StellarWP\Foundation\Container\Contracts\Provider as Service_Provider;
+
+/**
+ * Registers administration services and hooks.
+ */
+final class Provider extends Service_Provider {
+
+	public function register(): void {
+		add_action(
+			'admin_notices',
+			$this->container->callback( Product_Summary_Notice::class, 'display' )
+		);
+	}
+}
+```
+
+### Select another directory at runtime
+
+Inject `DirectoryAwareView` instead of the base `View` contract when a service must select another trusted template root, such as a theme override directory:
+
+```php title="Receipt_Renderer.php"
+<?php declare(strict_types=1);
+
+namespace YourPlugin\Receipt;
+
+use StellarWP\Foundation\View\Contracts\DirectoryAwareView;
+
+final readonly class Receipt_Renderer {
+
+	public function __construct(
+		private DirectoryAwareView $view
+	) {
+	}
+
+	public function render( string $trusted_template_directory, Receipt $receipt ): string {
+		$renderer = $this->view->withDirectory( $trusted_template_directory );
+
+		return $renderer->render(
+			'email/receipt',
+			[ 'receipt' => $receipt ]
+		);
+	}
+}
+```
+
+`withDirectory()` returns a new renderer. It does not mutate the shared renderer or affect other services using the configured directory.
+
+:::caution[Do not accept a directory from request input]
+Runtime directory selection is for trusted application paths. Never pass a URL parameter, form value, REST field, or other untrusted input to `withDirectory()`.
+:::
+
+### Supply another renderer
+
+The base `View` contract requires only named rendering. A renderer that does not use PHP files or directories can implement it without supporting `withDirectory()`:
+
+```php title="Json_View.php"
+<?php declare(strict_types=1);
+
+namespace YourPlugin\View;
+
+use JsonException;
+use StellarWP\Foundation\View\Contracts\View;
+
+final class Json_View implements View {
+
+	/**
+	 * @throws JsonException When the supplied data cannot be encoded.
+	 */
+	public function render( string $name, array $data = [] ): string {
+		return json_encode(
+			[
+				'view' => $name,
+				'data' => $data,
+			],
+			JSON_THROW_ON_ERROR
+		);
+	}
+}
+```
+
+Bind the replacement from the application's feature provider instead of registering `ViewProvider`:
+
+```php title="Provider.php"
+use StellarWP\Foundation\View\Contracts\View;
+
+public function register(): void {
+	$this->container->singleton( View::class, Json_View::class );
+}
+```
+
+Use a separate capability contract when a custom renderer supports optional behavior such as runtime directory selection. Application services that only call `render()` should continue depending on `View`.
+
+### Handle missing views
+
+The renderer throws `ViewNotFoundException` when a view is missing, unreadable, or resolves outside the selected directory. Empty names, absolute paths, null bytes, and parent traversal such as `../private` are rejected with `InvalidArgumentException`.
+
+Exceptions thrown by the view itself are propagated after Foundation removes any removable buffers opened while rendering. A view may use balanced buffers of its own, but it must not clean, flush, close, or replace Foundation's rendering buffer. Invalid buffer state is rejected instead of returning incomplete output. Let application-level error handling record or present those failures rather than returning a partial template.
+
+:::danger[Do not create non-removable output buffers]
+A PHP template must not start a buffer without `PHP_OUTPUT_HANDLER_REMOVABLE`. PHP cannot close such a buffer before the process ends, so no in-process PHP renderer can restore the request's output-buffer stack afterward. Treat view files as trusted application code and keep any buffers they open balanced and removable.
+:::
+
+## Testing
+
+Place small PHP view fixtures under the test data directory. For example, create `tests/_data/views/message.php`:
+
+```php title="message.php"
+<?php
+/** @var string $message */
+?><p><?php echo htmlspecialchars( $message, ENT_QUOTES, 'UTF-8' ); ?></p>
+```
+
+Render the fixture with the concrete class:
+
+```php
+use StellarWP\Foundation\View\PhpView;
+
+$view = new PhpView( codecept_data_dir( 'views' ) );
+
+$this->assertSame(
+	'<p>Hello, Foundation</p>',
+	$view->render(
+		'message',
+		[ 'message' => 'Hello, Foundation' ]
+	)
+);
+```
+
+Test feature services through the `View` contract when the rendered markup is part of their observable behavior. Use a temporary directory under `tests/_data/temp` for path-containment or runtime-directory tests that must create files.

src/Docs/src/content/docs/start/what-is-foundation.md

@@ -5,7 +5,7 @@ sidebar:
   order: 1
 ---
 
-Foundation is a Composer monorepo of reusable PHP components maintained for libraries and WordPress plugin ecosystems. It provides common application infrastructure without requiring every project to invent its own container, logging, locking, database, identifier, pipeline, shutdown, or command conventions.
+Foundation is a Composer monorepo of reusable PHP components maintained for libraries and WordPress plugin ecosystems. It provides common application infrastructure without requiring every project to invent its own container, logging, locking, database, identifier, pipeline, shutdown, view, or command conventions.
 
 Foundation is primarily developed for internal Nexcess projects. Its packages are publicly available and designed to remain reusable, but the needs of Nexcess applications will primarily drive changes, priorities, and the project roadmap.
 

src/View/.gitattributes

@@ -0,0 +1,7 @@
+# Path-based git attributes
+# https://www.kernel.org/pub/software/scm/git/docs/gitattributes.html
+
+# Ignore paths when git creates an archive of this package
+.gitattributes         export-ignore
+.gitignore             export-ignore
+.github                export-ignore

src/View/.github/workflows/close-pull-request.yml

@@ -0,0 +1,13 @@
+name: Close Pull Request
+
+on:
+  pull_request_target:
+    types: [opened]
+
+jobs:
+  run:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: superbrothers/close-pull-request@v3
+        with:
+          comment: "This is a read-only repository. Please submit your PR on the https://github.com/stellarwp/foundation repository.<br><br>Thanks!"

src/View/.gitignore

@@ -0,0 +1,2 @@
+vendor/
+composer.lock

src/View/Contracts/DirectoryAwareView.php

@@ -0,0 +1,18 @@
+<?php declare(strict_types=1);
+
+namespace StellarWP\Foundation\View\Contracts;
+
+use InvalidArgumentException;
+
+/**
+ * Renders named views and can select another trusted template directory at runtime.
+ */
+interface DirectoryAwareView extends View
+{
+	/**
+	 * Return a new renderer scoped to another view directory.
+	 *
+	 * @throws InvalidArgumentException When the directory does not exist, is unreadable, or is not a directory.
+	 */
+	public function withDirectory(string $directory): DirectoryAwareView;
+}