{{ post.title }}
{{ post.readingTime }} min read
{% if post.hasFeaturedVideo %} {# Show video player #} {% endif %} {{ post.content }}%s
%s
%s
',
esc_url($atts['url']), // URLs
esc_html($atts['name']), // Plain text
wp_kses_post($atts['bio']) // Rich HTML
);
}
```
See [Security Guide](/guide/security) for detailed escaping guidance.
## Related
* [Guide: Shortcodes](/guide/shortcodes)
* [Guide: Security](/guide/security)
---
---
url: /foehn-framework/api/as-taxonomy.md
---
# #\[AsTaxonomy]
Register a class as a custom WordPress taxonomy.
## Signature
```php
#[Attribute(Attribute::TARGET_CLASS)]
final readonly class AsTaxonomy
{
public function __construct(
public string $name,
public array $postTypes = [],
public ?string $singular = null,
public ?string $plural = null,
public bool $public = true,
public bool $hierarchical = false,
public bool $showInRest = true,
public bool $showAdminColumn = true,
public ?string $rewriteSlug = null,
public array $labels = [],
public array|false|null $rewrite = null,
) {}
}
```
## Parameters
| Parameter | Type | Default | Description |
| ----------------- | ----------------------- | ------- | -------------------------------------------------- |
| `name` | `string` | — | Taxonomy slug (required) |
| `postTypes` | `string[]` | `[]` | Associated post type slugs |
| `singular` | `?string` | `null` | Singular label |
| `plural` | `?string` | `null` | Plural label |
| `public` | `bool` | `true` | Whether publicly visible |
| `hierarchical` | `bool` | `false` | Hierarchical like categories |
| `showInRest` | `bool` | `true` | Enable REST API and Gutenberg |
| `showAdminColumn` | `bool` | `true` | Show column in admin post list |
| `rewriteSlug` | `?string` | `null` | Custom URL slug (shorthand for `rewrite`) |
| `labels` | `array%s
{% if title %}
{{ title }}
{% endif %} {% if content %}{{ content }}
{% endif %}
Please add content
';
}
return $this->view->render('blocks/hero', $context);
}
```
## File Structure
Organize blocks with their templates:
```
app/Blocks/
├── Hero/
│ └── HeroBlock.php
├── Features/
│ └── FeaturesBlock.php
├── Testimonial/
│ └── TestimonialBlock.php
└── Cta/
└── CtaBlock.php
templates/blocks/
├── hero.twig
├── features.twig
├── testimonial.twig
└── cta.twig
```
## Attribute Parameters
| Parameter | Type | Default | Description |
| ------------- | ---------- | ----------- | ---------------------------------- |
| `name` | `string` | *required* | Block name (without `acf/` prefix) |
| `title` | `string` | *required* | Display title |
| `category` | `string` | `'widgets'` | Block category |
| `icon` | `?string` | `null` | Dashicon or SVG |
| `description` | `?string` | `null` | Block description |
| `keywords` | `string[]` | `[]` | Search keywords |
| `mode` | `string` | `'preview'` | `'preview'`, `'edit'`, or `'auto'` |
| `supports` | `array` | `[]` | Block supports |
| `template` | `?string` | `null` | Custom template path |
| `postTypes` | `string[]` | `[]` | Allowed post types |
| `parent` | `?string` | `null` | Parent block name |
## See Also
* [Native Blocks](./native-blocks)
* [Block Patterns](./block-patterns)
* [API Reference: #\[AsAcfBlock\]](/api/as-acf-block)
* [API Reference: AcfBlockInterface](/api/acf-block-interface)
---
---
url: /foehn-framework/guide/field-fragments.md
---
# ACF Field Fragments
::: tip
Field fragments ship in `studiometa/foehn-acf`, the optional ACF package. See [ACF Blocks](/guide/acf-blocks#requirements).
:::
Field Fragments are reusable ACF field groups that can be shared across multiple blocks. By extending `FieldsBuilder`, you create self-contained field definitions that you add to any block's fields with acf-builder's `addFields()`.
## Why Use Field Fragments?
When building ACF blocks, you often repeat the same field patterns:
* Button/link with text, URL, target, and style
* Responsive images with mobile/desktop variants
* Spacing controls (margin, padding)
* Background settings (color, image, overlay)
Instead of duplicating these fields in every block, create a **Field Fragment** once and reuse it everywhere.
## Built-in Fragments
Føhn provides common fragments out of the box:
| Fragment | Description | Field names |
| ------------------------ | ------------------------------------ | ------------------------------------------------------ |
| `ButtonLinkBuilder` | Link with style and size options | `link`, `style`, `size` |
| `ResponsiveImageBuilder` | Desktop/mobile image variants | `desktop`, `mobile` |
| `SpacingBuilder` | Padding top/bottom controls | `top`, `bottom` |
| `BackgroundBuilder` | Color, image, and overlay background | `type`, `color`, `image`, `overlay`, `overlay_opacity` |
```php
use Studiometa\Foehn\Acf\Fragments\ButtonLinkBuilder;
use Studiometa\Foehn\Acf\Fragments\ResponsiveImageBuilder;
use Studiometa\Foehn\Acf\Fragments\SpacingBuilder;
use Studiometa\Foehn\Acf\Fragments\BackgroundBuilder;
```
## Creating Custom Fragments
A Field Fragment extends `FieldsBuilder` and configures its fields in the constructor:
```php
$label]);
$this
->addOembed('url', [
'label' => 'Video URL',
'instructions' => 'YouTube or Vimeo URL',
])
->addImage('poster', [
'label' => 'Poster Image',
'instructions' => 'Custom thumbnail (optional)',
'return_format' => 'id',
])
->addTrueFalse('autoplay', [
'label' => 'Autoplay',
'default_value' => false,
]);
}
}
```
## Using Fragments in Blocks
Use acf-builder's `addFields()` to add a fragment to your block's field configuration. `addFields()` copies the fragment's fields into the builder, with the field names that the fragment gives them.
The first constructor argument of a fragment (`'cta'` in `new ButtonLinkBuilder('cta')`) names the fragment's own builder. It does **not** prefix the field names: every `ButtonLinkBuilder` creates `link`, `style` and `size`. Wrap each fragment in `addGroup()` so that its fields have their own namespace:
```php
addWysiwyg('content', ['label' => 'Content'])
// Add the built-in fragments, each one in its own group
->addGroup('cta', ['label' => 'Call to Action'])
->addFields(new ButtonLinkBuilder())
->endGroup()
->addGroup('background', ['label' => 'Background'])
->addFields(new BackgroundBuilder())
->endGroup();
return $builder;
}
// ...
}
```
This produces:
* `content` (wysiwyg)
* `cta` (group)
* `link` (link)
* `style` (select)
* `size` (select)
* `background` (group)
* `type` (button\_group)
* `color` (color\_picker)
* `image` (image)
* `overlay` (true\_false)
* `overlay_opacity` (range)
The block values are nested in the same way: `$fields['cta']['link']`, `$fields['background']['type']`. The conditional logic inside a fragment keeps working in a group, because acf-builder resolves it against the field keys of the group.
Without the groups, two fragments that share a field name throw a `FieldNameCollisionException` when you add the second one. For example, two `ButtonLinkBuilder` fragments in the same builder both create `link`.
## Customizing Built-in Fragments
All built-in fragments accept constructor parameters for customization. The examples below continue a `$builder` chain like the one in `HeroBlock`.
### ButtonLinkBuilder
```php
use Studiometa\Foehn\Acf\Fragments\ButtonLinkBuilder;
// Default usage
->addGroup('button')
->addFields(new ButtonLinkBuilder())
->endGroup()
// Custom styles, no size field
->addGroup('cta', ['label' => 'Call to Action'])
->addFields(new ButtonLinkBuilder(
name: 'cta',
label: 'Call to Action',
styles: ['primary' => 'Primary', 'ghost' => 'Ghost'],
sizes: null, // Disable size field
required: true,
))
->endGroup()
```
### ResponsiveImageBuilder
```php
use Studiometa\Foehn\Acf\Fragments\ResponsiveImageBuilder;
// Default usage
->addGroup('image')
->addFields(new ResponsiveImageBuilder())
->endGroup()
// With custom instructions
->addGroup('hero_image', ['label' => 'Hero Image'])
->addFields(new ResponsiveImageBuilder(
name: 'hero_image',
label: 'Hero Image',
required: true,
desktopInstructions: 'Recommended: 2560×1440px',
mobileInstructions: 'Recommended: 750×1334px',
))
->endGroup()
```
### SpacingBuilder
```php
use Studiometa\Foehn\Acf\Fragments\SpacingBuilder;
// Default usage
->addGroup('spacing')
->addFields(new SpacingBuilder())
->endGroup()
// Custom sizes and labels
->addGroup('margin', ['label' => 'Margins'])
->addFields(new SpacingBuilder(
name: 'margin',
label: 'Margins',
sizes: ['0' => 'None', '1' => 'Small', '2' => 'Medium', '3' => 'Large'],
default: '1',
topLabel: 'Margin Top',
bottomLabel: 'Margin Bottom',
))
->endGroup()
```
### BackgroundBuilder
```php
use Studiometa\Foehn\Acf\Fragments\BackgroundBuilder;
// Default usage
->addGroup('background')
->addFields(new BackgroundBuilder())
->endGroup()
// Image-only background (no color option)
->addGroup('bg', ['label' => 'Background'])
->addFields(new BackgroundBuilder(
name: 'bg',
label: 'Background',
types: ['none' => 'None', 'image' => 'Image'],
default: 'none',
defaultOpacity: 70,
))
->endGroup()
```
## Organizing Fragments with Tabs
Fragments work well inside tabs for better editor UX:
```php
public static function fields(): FieldsBuilder
{
$builder = new FieldsBuilder('hero');
$builder
->addTab('Content')
->addText('title')
->addWysiwyg('content')
->addGroup('cta', ['label' => 'Call to Action'])
->addFields(new ButtonLinkBuilder())
->endGroup()
->addTab('Media')
->addGroup('hero_image', ['label' => 'Hero Image'])
->addFields(new ResponsiveImageBuilder(required: true))
->endGroup()
->addTab('Settings')
->addGroup('spacing', ['label' => 'Spacing'])
->addFields(new SpacingBuilder())
->endGroup()
->addGroup('background', ['label' => 'Background'])
->addFields(new BackgroundBuilder())
->endGroup();
return $builder;
}
```
`addTab()` returns the new tab field, not `$builder`. Keep the chain on a `$builder` variable and return the variable.
## File Structure
Organize fragments in a dedicated directory:
```
app/
├── Acf/
│ └── Fragments/
│ ├── BackgroundBuilder.php
│ ├── ButtonLinkBuilder.php
│ ├── ResponsiveImageBuilder.php
│ └── SpacingBuilder.php
│
├── Blocks/
│ ├── Hero/
│ │ └── HeroBlock.php
│ └── Features/
│ └── FeaturesBlock.php
```
## Best Practices
### 1. Use Constructor Parameters for Customization
Allow fragments to be configured when instantiated:
```php
final class ButtonLinkBuilder extends FieldsBuilder
{
public function __construct(
string $name = 'button',
string $label = 'Button',
array $styles = ['primary', 'secondary'],
bool $required = false,
) {
parent::__construct($name, ['label' => $label]);
$this
->addLink('link', [
'label' => 'Link',
'required' => $required,
])
->addSelect('style', [
'label' => 'Style',
'choices' => array_combine($styles, array_map('ucfirst', $styles)),
]);
}
}
```
### 2. Keep Fragments Focused
Each fragment should handle one concern. Prefer multiple small fragments over one large one:
```php
// ✅ Good: focused fragments
->addGroup('cta')
->addFields(new ButtonLinkBuilder())
->endGroup()
->addGroup('spacing')
->addFields(new SpacingBuilder())
->endGroup()
// ❌ Avoid: kitchen-sink fragment
->addFields(new ButtonWithSpacingAndBackgroundBuilder())
```
### 3. Document Field Names
Fragments do not prefix field names, so document the names that a fragment creates:
```php
/**
* Creates the following fields:
* - link (link)
* - style (select)
* - size (select) - optional
*/
final class ButtonLinkBuilder extends FieldsBuilder
```
### 4. Use Static Factory Methods for Presets
For common configurations, add static factory methods to your own fragment:
```php
final class ButtonLinkBuilder extends FieldsBuilder
{
// Constructor from practice 1...
public static function primary(string $name = 'cta'): self
{
return new self($name, 'Call to Action', ['primary', 'secondary']);
}
}
// Usage
->addGroup('cta')
->addFields(ButtonLinkBuilder::primary())
->endGroup()
```
## See Also
* [ACF Blocks](./acf-blocks) — Creating ACF blocks with `#[AsAcfBlock]`
* [acf-builder documentation](https://github.com/StoutLogic/acf-builder) — Full FieldsBuilder API
---
---
url: /foehn-framework/guide/acf-options-pages.md
---
# ACF Options Pages
Føhn provides `#[AsAcfOptionsPage]` for creating ACF options pages with type-safe fields using `stoutlogic/acf-builder`.
## Requirements
ACF is an optional package. Custom fields do not need it: [`#[AsPostMeta]`](/api/as-post-meta) registers a meta key with a REST schema, which is what puts a field in the block editor and makes it bindable. ACF is the better answer when the editing UI matters — repeaters, flexible content, conditional logic, media pickers.
```bash
composer require studiometa/foehn-acf
```
* [ACF Pro](https://www.advancedcustomfields.com/pro/) installed and active
* `studiometa/foehn-acf`, which brings `stoutlogic/acf-builder` with it. It requires the exact version of `studiometa/foehn` you have: upgrade the two packages together
Nothing registers when ACF is absent: each discovery guards on the function it needs. The classes keep their `Studiometa\Foehn\` namespaces, so a project upgrading from 0.4 changes one Composer requirement and no imports.
## Basic Options Page
```php
addText('site_name', ['label' => 'Site Name'])
->addTextarea('footer_text', ['label' => 'Footer Text'])
->addImage('logo', ['label' => 'Site Logo']);
}
}
```
## Retrieving Option Values
### Using AcfOptionsService
```php
with('site_name', $this->options->get('site_name', 'theme-settings'))
->with('footer_text', $this->options->get('footer_text', 'theme-settings'))
->with('logo', $this->options->get('logo', 'theme-settings'));
}
}
```
### Using ACF Functions Directly
```php
// Get a single field
$siteName = get_field('site_name', 'theme-settings');
// Get all fields
$settings = get_fields('theme-settings');
```
## Sub-Pages
Create child pages under a parent options page:
```php
addUrl('facebook', ['label' => 'Facebook URL'])
->addUrl('twitter', ['label' => 'Twitter URL'])
->addUrl('instagram', ['label' => 'Instagram URL'])
->addUrl('linkedin', ['label' => 'LinkedIn URL']);
}
}
```
## Full Configuration
```php
#[AsAcfOptionsPage(
pageTitle: 'Advanced Settings',
menuTitle: 'Advanced',
menuSlug: 'advanced-settings',
capability: 'manage_options',
position: 59,
iconUrl: 'dashicons-admin-settings',
redirect: false,
postId: 'advanced_options',
autoload: true,
updateButton: 'Save Settings',
updatedMessage: 'Settings saved successfully!',
)]
```
## Options Without Fields
You can create options pages without implementing `AcfOptionsPageInterface`. This is useful when fields are defined elsewhere or via the ACF UI:
```php
get('field_name', 'options-page-slug');
// Get all fields from an options page
$allFields = $options->all('options-page-slug');
// Check if a field has a value
if ($options->has('field_name', 'options-page-slug')) {
// Field has a non-empty value
}
// Get field object with metadata
$fieldObject = $options->getObject('field_name', 'options-page-slug');
```
## Using in Twig Templates
```twig
{# Get options in a context provider and pass to template #}
```
## Related
* [API: #\[AsAcfOptionsPage\]](/api/as-acf-options-page)
* [API: AcfOptionsPageInterface](/api/acf-options-page-interface)
* [Guide: ACF Blocks](/guide/acf-blocks)
* [Guide: Context Providers](/guide/context-providers)
---
---
url: /foehn-framework/api/acf-block-interface.md
---
# AcfBlockInterface
Interface for ACF (Advanced Custom Fields) blocks.
## Signature
```php
$block Block data from ACF
* @param arrayAdd content
';
}
return $this->view->render('blocks/hero', $context);
}
```
## Usage
```php
addText('title')
->addWysiwyg('content')
->addImage('background');
}
public function compose(array $block, array $fields): array
{
return [
'title' => $fields['title'] ?? '',
'content' => $fields['content'] ?? '',
'background' => $fields['background'] ?? null,
];
}
public function render(array $context, bool $isPreview = false): string
{
return $this->view->render('blocks/hero', $context);
}
}
```
## Complex Fields Example
```php
public static function fields(): FieldsBuilder
{
return (new FieldsBuilder('features'))
->addTab('Content')
->addText('title')
->addTextarea('description')
->addRepeater('items', ['layout' => 'block'])
->addImage('icon')
->addText('title')
->addTextarea('text')
->endRepeater()
->addTab('Settings')
->addSelect('columns', [
'choices' => [
'2' => '2 Columns',
'3' => '3 Columns',
'4' => '4 Columns',
],
])
->addColorPicker('background_color');
}
```
## Validation
Use the `ValidatesFields` trait to add optional validation in your `compose()` method:
```php
use Studiometa\Foehn\Blocks\Concerns\ValidatesFields;
final readonly class HeroBlock implements AcfBlockInterface
{
use ValidatesFields;
public function compose(array $block, array $fields): array
{
// Simple: validate required and sanitize
$this->validateRequired($fields, ['title']);
return [
'title' => $this->sanitizeField($fields['title'], 'string'),
'count' => $this->sanitizeField($fields['count'] ?? 0, 'int'),
];
// Or use schema-based validation
return $this->validateFields($fields, [
'title' => ['type' => 'string', 'required' => true],
'count' => ['type' => 'int', 'default' => 0],
]);
}
}
```
See [Field Validation](/guide/acf-blocks#field-validation) for full documentation.
## Related
* [Guide: ACF Blocks](/guide/acf-blocks)
* [`#[AsAcfBlock]`](./as-acf-block)
---
---
url: /foehn-framework/api/acf-config.md
---
# AcfConfig
Configuration class for ACF (Advanced Custom Fields) integration.
## Signature
```php
addText('sku', ['label' => 'SKU'])
->addNumber('price', ['label' => 'Price'])
->addWysiwyg('description', ['label' => 'Description']);
}
```
## Usage
```php
'product'],
)]
final class ProductFields implements AcfFieldGroupInterface
{
public static function fields(): FieldsBuilder
{
return (new FieldsBuilder('product_fields'))
->addText('sku', ['label' => 'SKU'])
->addNumber('price', ['label' => 'Price'])
->addWysiwyg('description', ['label' => 'Description']);
}
}
```
## Complex Fields Example
```php
public static function fields(): FieldsBuilder
{
return (new FieldsBuilder('property_fields'))
->addTab('General')
->addText('external_id', ['label' => 'External ID'])
->addText('address', ['label' => 'Address'])
->addNumber('bedrooms', ['label' => 'Bedrooms'])
->addNumber('bathrooms', ['label' => 'Bathrooms'])
->addTab('Media')
->addGallery('photos', ['label' => 'Photos'])
->addOembed('video_tour', ['label' => 'Video Tour'])
->addTab('Features')
->addRepeater('features', ['layout' => 'table'])
->addText('name')
->addText('value')
->endRepeater()
->addTab('Pricing')
->addNumber('price', ['label' => 'Price'])
->addSelect('status', [
'label' => 'Status',
'choices' => [
'available' => 'Available',
'pending' => 'Pending',
'sold' => 'Sold',
],
]);
}
```
## Comparison with AcfBlockInterface
| Feature | `AcfFieldGroupInterface` | `AcfBlockInterface` |
| ------------------ | -------------------------- | -------------------------------- |
| Purpose | Post/page/taxonomy fields | Gutenberg block fields |
| Methods | `fields()` only | `fields()`, `compose()`, `render()` |
| Location | Set via attribute | Automatically set to block |
| Rendering | WordPress handles display | Class handles rendering |
## Accessing Field Values
Field values are accessed via standard ACF functions in your templates or code:
```php
// In PHP
$sku = get_field('sku');
$price = get_field('price');
// In Twig (with Timber)
{{ post.meta('sku') }}
{{ post.meta('price') }}
// Or using ACF functions
{{ function('get_field', 'sku') }}
```
## Related
* [`#[AsAcfFieldGroup]`](./as-acf-field-group)
* [`AcfBlockInterface`](./acf-block-interface)
* [`#[AsAcfBlock]`](./as-acf-block)
---
---
url: /foehn-framework/api/acf-options-page-interface.md
---
# AcfOptionsPageInterface
Interface for ACF options pages that define fields programmatically.
## Signature
```php
interface AcfOptionsPageInterface
{
public static function fields(): FieldsBuilder;
}
```
## Methods
### fields()
Define ACF fields for this options page using `stoutlogic/acf-builder`.
**Returns:** `FieldsBuilder` — The configured fields builder
## Usage
### Basic Implementation
```php
addText('site_name', [
'label' => 'Site Name',
'instructions' => 'Enter your site name',
])
->addTextarea('footer_text', [
'label' => 'Footer Text',
'rows' => 4,
]);
}
}
```
### With Tabs and Groups
```php
public static function fields(): FieldsBuilder
{
return (new FieldsBuilder('theme_settings'))
->addTab('general', ['label' => 'General'])
->addText('site_name')
->addImage('logo')
->addTab('social', ['label' => 'Social Media'])
->addUrl('facebook')
->addUrl('twitter')
->addUrl('instagram')
->addTab('footer', ['label' => 'Footer'])
->addWysiwyg('footer_content')
->addText('copyright');
}
```
### With Repeater Fields
```php
public static function fields(): FieldsBuilder
{
return (new FieldsBuilder('partners_settings'))
->addRepeater('partners', ['label' => 'Partners', 'layout' => 'block'])
->addText('name', ['label' => 'Partner Name'])
->addImage('logo', ['label' => 'Partner Logo'])
->addUrl('website', ['label' => 'Website URL'])
->endRepeater();
}
```
### With Conditional Logic
```php
public static function fields(): FieldsBuilder
{
return (new FieldsBuilder('display_settings'))
->addTrueFalse('show_banner', [
'label' => 'Show Banner',
'default_value' => false,
])
->addImage('banner_image', ['label' => 'Banner Image'])
->conditional('show_banner', '==', '1')
->addText('banner_text', ['label' => 'Banner Text'])
->conditional('show_banner', '==', '1');
}
```
## When to Implement
Implement this interface when you want to:
* Define fields programmatically with type safety
* Version control your field definitions
* Share field configurations across environments
## When Not to Implement
Skip implementing this interface when:
* Fields are defined via ACF UI
* Fields are imported from JSON
* You're using a third-party ACF field group
```php
#[AsAcfOptionsPage(pageTitle: 'External Settings')]
final class ExternalSettings
{
// No interface needed - fields defined elsewhere
}
```
## Related
* [Guide: ACF Options Pages](/guide/acf-options-pages)
* [`#[AsAcfOptionsPage]`](./as-acf-options-page)
* [`AcfBlockInterface`](./acf-block-interface)
---
---
url: /foehn-framework/guide/admin-cache-controls.md
---
# Admin Cache Controls
Føhn adds one admin page and one admin-bar menu, so the two questions that come up at the worst moment can be answered without a shell: **what state is this installation actually in**, and **clear this page now**.
Both are on by default. There is nothing to add to `foehn.config.php`: a project that had to switch on the page it would read the cache's state on has no way to find out that it needed to.
## The Føhn page
A top-level **Føhn** entry in the admin menu, visible to users with `manage_options`. It reports:
| Row | What it says |
| --------------------- | -------------------------------------------------------------------------------------------- |
| `WP_ENVIRONMENT_TYPE` | The environment as `Helpers\Env` resolves it, not as a file declares it. |
| `WP_DEBUG` | Whether debug mode is on. |
| Configured | The `enabled` flag from your [`PageCacheConfig`](/api/page-cache-config). |
| Effective | **Active**, **Disabled**, or **enabled but unavailable in this environment**. |
| Cache path | Where responses are stored. |
| TTL | The configured lifetime, or "purge-driven" when it is `0`. |
| Cached responses | How many stored response bodies exist right now. |
| Section responses | How many of those are [section](/guide/section-rendering) fragments rather than whole pages. |
| Total size | What the cache directory holds on disk, headers sidecars included. |
| Last full purge | When the cache was last emptied in full. Per-URL and per-section clears are not recorded. |
| Last real run | When the container's WP-Cron runner last succeeded, or **Never**. |
The two environment rows are labelled with the constant names rather than with prose on purpose. When somebody reports that "it thinks it is staging", you both have to be looking at the same name.
The **Effective** row is worth reading before anything else. `enabled: true` in an environment your config does not list writes nothing and serves nothing, and a page that reported only "enabled" would send you hunting a broken cache when what you have is a missing environment name.
**Last real run is Never until the container's cron runner is in place.** That is the honest answer for a site with no real cron, and it is the same answer a site whose runner has broken gives — which is the reason the row exists.
## The two buttons on the page
* **Clear the whole page cache** — every stored response, pages and fragments alike.
* **Clear the section cache only** — the variants keyed by `foehn_sections`, leaving whole pages and unrelated keyed variants where they are.
Both are plain `POST` forms. **This page is the no-JavaScript path**: it works with scripting off, which is what makes it the one to rely on when something else on the site is broken.
## The admin-bar menu
A **Føhn Cache** node for `manage_options`, with three items:
* **Clear whole cache**
* **Clear section cache**
* **Clear this page** — the current post, its cached 404, its keyed query variants and its section fragments.
The third item appears **only** when WordPress itself supplies the post: a singular front-end request, or a post edit screen. Anywhere else it is absent rather than disabled, because an item that appears everywhere and works somewhere is one nobody learns to trust. It is also absent for a post no visitor could have been served — a draft has no cached page to clear.
The node's own link goes to the Føhn page and nothing else. **The items do not mutate anything through their `href`**: each one submits a hidden, nonce-protected form rendered in the footer, through a few lines of inline script. A link that cleared a cache would be cleared by every prefetching browser, every link checker and every crawler holding a logged-in cookie, and no nonce fixes that — the browser is following the link on the user's behalf. With scripting off the items do nothing, which is the correct failure for a control that must not fire by accident; the page's buttons are still there.
## What the handlers require
Every mutation goes through one of three `admin_post_` handlers, and each of them refuses a request that fails any of the following:
1. **The request must be a `POST`.** `admin-post.php` fires `admin_post_{action}` for a `GET` too, so this is a real check and not decoration.
2. **The user must have `manage_options`.**
3. **The nonce must have been minted for that action.** Each action has its own nonce action string, so the token on "clear everything" cannot authorise "clear this post".
4. **A post id, when one is present, must resolve to a real, publicly viewable post.**
A refused request answers `403` and says nothing about which check failed. A successful one redirects — through `wp_safe_redirect()`, to a referrer WordPress itself validated or to the Føhn page — carrying only a fixed result code and an integer count.
**The browser posts an id and never a URL or a path.** The permalink is resolved server-side with `get_permalink()`, so there is no parameter for a caller to point somewhere else. That is by construction rather than by validation: a handler that accepted a filesystem path would be a remote deletion endpoint one bug away from working.
Deletion itself is [`PageCache\Invalidator`](/guide/page-cache#invalidation) and nothing else, so a button and an automatic purge always agree about which files a page owns. A clear takes the static page cache and only that — the discovery cache, transformed images, application transients and PHP's OPcache have their own lifecycles.
## They keep working with caching off
Every control stays available while `enabled` is `false`, and the page says so. A release that had the cache on leaves files behind, and the project switching it off is exactly the one who needs them gone.
## Reaching the same operations elsewhere
| Where | How |
| ------------- | ------------------------------------------------------------------------------------------ |
| WP-CLI | `wp foehn cache:clear [--url={{ title }}
{% if cta_link %} {{ cta_link.title }} {% endif %}' . esc_html($title) . '
'; // ❌ Bad: Unescaped user input echo '' . $title . '
'; ``` #### `esc_attr()` — HTML Attributes Use for values inside HTML attributes: ```php // ✅ Good: Escaped attribute echo ''; echo '';
echo '
';
// ❌ Bad: Unescaped attribute (XSS via " onclick="alert(1))
echo '';
```
#### `esc_url()` — URLs
Use for any URL output:
```php
// ✅ Good: Escaped URL
echo 'Click';
echo ' . ')
';
// ❌ Bad: Allows javascript: protocol XSS
echo 'Click';
```
#### `wp_kses_post()` — Rich HTML Content
Use when you need to allow safe HTML (like post content):
```php
// ✅ Good: Allows safe HTML, strips dangerous tags
echo '
' . wp_kses_post($content) . '
';
// ❌ Bad: Allows all HTML including