> For the complete documentation index, see [llms.txt](https://whoisandywhite.gitbook.io/porterwp/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://whoisandywhite.gitbook.io/porterwp/developer-api/hooks.md).

# Hook reference

This index covers PorterWP's public custom hooks in version 1.4.95. WordPress and ACF hooks used internally are not repeated here.

## Action

| Hook                                                                    | Arguments | When it runs                                        |
| ----------------------------------------------------------------------- | --------- | --------------------------------------------------- |
| [`porter_fs_loaded`](/porterwp/developer-api/hooks/porter_fs_loaded.md) | None      | Immediately after the Freemius SDK has initialized. |

## Configuration and asset filters

| Hook                                                                                                        | Value and additional arguments      | Purpose                                                                                                 |
| ----------------------------------------------------------------------------------------------------------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------- |
| [`porter_wp_config_filepath`](/porterwp/developer-api/hooks/porter_wp_config_filepath.md)                   | `$directory, $file`                 | Change the directory containing Porter JSON configuration.                                              |
| `porter_wp_settings_cache_ttl`                                                                              | `DAY_IN_SECONDS, $file, $file_path` | Set the production object-cache TTL for decoded JSON; return `0` or less to disable persistent storage. |
| [`porter_default_object_args`](/porterwp/developer-api/hooks/porter_default_object_args.md)                 | `$defaults, $group`                 | Change the default post-type or taxonomy registration arguments.                                        |
| [`porter_public_styles_default_args`](/porterwp/developer-api/hooks/porter_public_styles_default_args.md)   | `$defaults`                         | Change defaults for public styles.                                                                      |
| [`porter_public_scripts_default_args`](/porterwp/developer-api/hooks/porter_public_scripts_default_args.md) | `$defaults`                         | Change defaults for public scripts.                                                                     |
| [`porter_editor_styles_default_args`](/porterwp/developer-api/hooks/porter_editor_styles_default_args.md)   | `$defaults`                         | Change defaults for block-editor styles.                                                                |
| [`porter_editor_scripts_default_args`](/porterwp/developer-api/hooks/porter_editor_scripts_default_args.md) | `$defaults`                         | Change defaults for block-editor scripts.                                                               |
| `porterwp/premium/skip_link_focus/enabled`                                                                  | `$enabled`                          | Enable or disable the premium skip-link focus enhancement.                                              |

## Theme include, block and pattern filters

| Hook                                                                                                        | Value and additional arguments           | Purpose                                                                         |
| ----------------------------------------------------------------------------------------------------------- | ---------------------------------------- | ------------------------------------------------------------------------------- |
| [`porter_wp_inc_filepath`](/porterwp/developer-api/hooks/porter_wp_inc_filepath.md)                         | `$directory`                             | Change the theme PHP include root.                                              |
| [`porter_wp_inc_filepath_exclusions`](/porterwp/developer-api/hooks/porter_wp_inc_filepath_exclusions.md)   | `$relative_paths`                        | Exclude files or subtrees below the include root.                               |
| [`porter_wp_inc_load_first_filepaths`](/porterwp/developer-api/hooks/porter_wp_inc_load_first_filepaths.md) | `$names`                                 | Promote named entries at each scanned directory level.                          |
| [`porter_block_path`](/porterwp/developer-api/hooks/porter_block_path.md)                                   | `$path`                                  | Change the theme block root relative to the stylesheet directory.               |
| [`porter_block_folders`](/porterwp/developer-api/hooks/porter_block_folders.md)                             | `$folders`                               | Change the subdirectories scanned for blocks.                                   |
| [`porter_blocks_array`](/porterwp/developer-api/hooks/porter_blocks_array.md)                               | `$blocks`                                | Add or remove discovered block references before registration.                  |
| [`porter_dynamic_blocks`](/porterwp/developer-api/hooks/porter_dynamic_blocks.md)                           | `$block_names`                           | Choose block types whose custom style CSS is emitted during render.             |
| [`porter_blockstyle_args`](/porterwp/developer-api/hooks/porter_blockstyle_args.md)                         | `$args, $block_name, $configured_styles` | Amend arguments passed to `register_block_style()`.                             |
| [`porter_blockstyles_path`](/porterwp/developer-api/hooks/porter_blockstyles_path.md)                       | `$directory, $block_name, $style_name`   | Change the custom block-style CSS directory.                                    |
| [`porter_core_blockstyles_path`](/porterwp/developer-api/hooks/porter_core_blockstyles_path.md)             | `$directory`                             | Change the core block CSS directory merged into `theme.json`.                   |
| [`porter_block_patterns_path`](/porterwp/developer-api/hooks/porter_block_patterns_path.md)                 | `$directory, $pattern_name`              | Change the PHP pattern-content directory.                                       |
| [`porter_core_pattern_categories`](/porterwp/developer-api/hooks/porter_core_pattern_categories.md)         | `$category_slugs`                        | Change the core categories removed when `unregisterCategories` includes `core`. |
| [`porter_acf_option_defaults`](/porterwp/developer-api/hooks/porter_acf_option_defaults.md)                 | `$defaults`                              | Change default ACF options-page arguments.                                      |

## Past-status filters

| Hook                                           | Value and additional arguments           | Purpose                                                           |
| ---------------------------------------------- | ---------------------------------------- | ----------------------------------------------------------------- |
| `porter_past_status_batch_size`                | `100, $post_type, $updater`              | Set hourly update batch size; the result is clamped to 1–1000.    |
| `porter_past_status_migration_batch_size`      | `100, $post_type, $updater`              | Set legacy migration batch size; the result is clamped to 1–1000. |
| `porter_past_status_manual_trigger_capability` | `'manage_options', $post_type, $updater` | Set the capability required by manual update and migration forms. |

## Premium filter request and query filters

| Hook                                                                                                    | Value and additional arguments                     | Purpose                                                                                                                                           |
| ------------------------------------------------------------------------------------------------------- | -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `porter/filter/max_configured_filters`                                                                  | `12`                                               | Limit configured groups; clamped to 1–20.                                                                                                         |
| `porter/filter/allowed_meta_keys`                                                                       | `$keys`                                            | Add trusted meta keys that may be placed in a request schema.                                                                                     |
| `porter/filter/max_meta_options`                                                                        | `250, $meta_key, $post_type`                       | Limit generated distinct meta options; clamped to 1–500.                                                                                          |
| `porter/filter/max_term_options`                                                                        | `250, $filter, $post_type`                         | Limit generated term options; clamped to 1–500.                                                                                                   |
| `porter/filter/max_archive_months`                                                                      | `120, $post_type`                                  | Limit generated archive months; clamped to 1–240.                                                                                                 |
| `porter/filter/max_author_options`                                                                      | `250, $post_type`                                  | Limit generated authors; clamped to 1–500.                                                                                                        |
| `porter/filter/max_clauses`                                                                             | `12`                                               | Limit parsed filter clauses; clamped to 1–20.                                                                                                     |
| `porter/filter/meta_values`                                                                             | `$values, $post_type, $filter, $settings`          | Alter generated meta choices.                                                                                                                     |
| `porter/filter/terms`                                                                                   | `$terms, $post_type, $filter, $settings`           | Alter generated taxonomy choices.                                                                                                                 |
| `porter/filter/post_types`                                                                              | `$post_types, $all_post_types, $filter, $settings` | Alter post-type choices; results are normalized back to viewable registered types.                                                                |
| `porter/filter/other_values`                                                                            | `$values, $post_type, $filter, $settings`          | Alter date or author choices.                                                                                                                     |
| `porter/filter/orderby_options`                                                                         | `$options`                                         | Relabel or remove `date`, `relevance` and `title` from the generated UI; unknown keys are discarded. It does not disable a supported query value. |
| [`porter/filter/search_placeholder`](/porterwp/developer-api/hooks/porter_filter_search_placeholder.md) | `$placeholder, $key, $post_type, $settings`        | Change search placeholder copy.                                                                                                                   |
| `porter/filter/request_schema`                                                                          | `$schema, $post_type, $filters, $settings`         | Amend a generated allowlist before it is normalized and signed.                                                                                   |
| `porter/filter/schema_registry_ttl`                                                                     | `WEEK_IN_SECONDS, $schema`                         | Set the server-side legacy schema registration TTL; minimum one hour.                                                                             |
| `porter/filter/allow_legacy_unsigned_requests`                                                          | `true, $filter_id, $params`                        | Disable or retain bounded unsigned public requests.                                                                                               |
| `porter/filter/allow_cross_route_public_fallback`                                                       | `true, $filter_id, $params, $schema`               | Control downgrade to public-only dimensions when a signed GET is submitted to another route.                                                      |
| [`porter_filter_tax_query_relation`](/porterwp/developer-api/hooks/porter_filter_tax_query_relation.md) | `'AND', $query`                                    | Set the generated taxonomy relation to `AND` or `OR`.                                                                                             |
| [`porter_filter_event_date`](/porterwp/developer-api/hooks/porter_filter_event_date.md)                 | `$meta_keys`                                       | Map event-range controls to start/end meta keys.                                                                                                  |
| [`porter_filter_parsed_query`](/porterwp/developer-api/hooks/porter_filter_parsed_query.md)             | `$query, $params, $context`                        | Amend a query after a valid Porter request has been parsed.                                                                                       |

## Geolocation filters

| Hook                                                                    | Value and additional arguments                 | Purpose                                                                                                          |
| ----------------------------------------------------------------------- | ---------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| `porter/filter/geo_distance_options`                                    | `[5, 10, 20, 30, 50]`                          | Set signed form distances in miles; normalized to at most ten values from 1–100.                                 |
| `porter/filter/legacy_geo_distance_options`                             | `[5, 10, 20, 25, 30, 50]`                      | Set distances accepted by the strict legacy geo path.                                                            |
| `porter/filter/geo_rate_limit`                                          | `20`                                           | Set allowed remote geocoder cache misses per address hash in five minutes; clamped to 1–100.                     |
| [`parse_geo_filter`](/porterwp/developer-api/hooks/parse_geo_filter.md) | `[], $post_type, $lat_lng, $distance, 'miles'` | Convert validated coordinates into theme-specific query amendments.                                              |
| `porter/filter/max_geo_candidate_posts`                                 | `500`                                          | Limit candidates in the protected example geo builder; it does not affect a theme's `parse_geo_filter` callback. |

## Site Editor preview optimiser filters

All hooks in this section use the `porterwp/acf_preview_optimizer/` prefix.

| Suffix                   | Value and additional arguments                     | Purpose                                                                          |
| ------------------------ | -------------------------------------------------- | -------------------------------------------------------------------------------- |
| `enabled`                | `true`                                             | Disable the optimiser as a whole.                                                |
| `intercept_rest`         | `true`                                             | Enable eligible REST request caching/interception.                               |
| `client_cache_ttl`       | `10000`                                            | Client cache lifetime in milliseconds; `0` disables client caching.              |
| `rest_cache_ttl`         | `30, $request, $response`                          | Server cache lifetime in seconds; `0` disables server caching.                   |
| `disable_preview_frames` | `false`                                            | Opt into disabling collection preview frames.                                    |
| `is_site_editor_screen`  | `$is_site_editor, $screen`                         | Override Site Editor screen detection.                                           |
| `collection_routes`      | `$routes`                                          | Change recognized Site Editor collection routes.                                 |
| `editor_post_types`      | `$post_types`                                      | Change recognized editor post types.                                             |
| `is_target_route`        | `$is_target, $query_args, $route_root, $post_type` | Override target-route detection.                                                 |
| `should_optimize_block`  | `$should_optimize, $block_name, $request`          | Choose ACF block previews eligible for the lightweight response.                 |
| `render_form`            | `$render, $request, $editor_context`               | Choose whether a lightweight response includes the ACF edit form.                |
| `placeholder_html`       | `$html, $block, $request, $editor_context`         | Customize placeholder markup. Trusted callbacks are responsible for safe output. |

The optimiser still performs its own authentication, route, request-size and permission checks after these filters run. See [Site Editor preview optimiser](/porterwp/features/site-editor-preview-optimiser.md).