]*>)/', '$1' . $badge, $post_html, 1 );
}
return $post_html;
}, 10, 2 );
```
---
#### `bbfsync_feed_html`
Filter the final feed HTML output by `render()` before it is returned. This
is the **last chance** to modify the rendered HTML before it reaches the page.
**Note:** This filter does NOT fire on AJAX-loaded "Load More" batches —
those go through `render_posts()` directly. If you need a filter that runs
in both code paths, use `bbfsync_post_html`.
**Arguments:**
- `string $output` — The full feed HTML.
- `array $settings` — The plugin settings array (including `_feed_id`).
**Returns:** A string of HTML.
**Example — wrap every feed in a responsive container:**
```php
add_filter( 'bbfsync_feed_html', function( $output ) {
return '
' . $output . '
';
} );
```
---
## Actions
### Lifecycle
#### `bbfsync_before_api_fetch`
Fires immediately before any Graph API call is made for a feed fetch. Useful
for logging, analytics, or pre-fetch hooks. The cursor is empty for the
first page of a feed and contains the after-cursor for paginated calls.
**Arguments:**
- `string $page_id` — Facebook Page ID being fetched.
- `string $after` — Pagination cursor (empty for first page).
**Example — log every fetch attempt:**
```php
add_action( 'bbfsync_before_api_fetch', function( $page_id, $after ) {
$page = $after ? 'cursor=' . substr( $after, 0, 12 ) . '...' : 'first page';
error_log( "[BlueBook] fetching {$page_id} ({$page})" );
}, 10, 2 );
```
---
#### `bbfsync_after_api_fetch`
Fires after a successful Graph API fetch has been cached. Receives the page
ID, the result array, and the count of posts stored in this batch. Useful
for cache busting, logging, Slack notifications, or any side-effect that
should happen on a successful refresh. Does **not** fire on failed fetches.
**Arguments:**
- `string $page_id` — Facebook Page ID that was refreshed.
- `array $result` — `['posts' => array, 'next_cursor' => string]`
- `int $stored` — Number of posts stored in this result.
**Example — bust your page cache when the feed refreshes:**
```php
add_action( 'bbfsync_after_api_fetch', function( $page_id, $result, $stored ) {
if ( $stored > 0 && function_exists( 'wp_cache_flush' ) ) {
wp_cache_flush();
}
}, 10, 3 );
```
**Example — Slack notification when new posts arrive:**
```php
add_action( 'bbfsync_after_api_fetch', function( $page_id, $result, $stored ) {
if ( $stored > 0 ) {
wp_remote_post( 'https://hooks.slack.com/services/...', array(
'body' => wp_json_encode( array(
'text' => "BlueBook refreshed page {$page_id}: {$stored} posts in this batch.",
) ),
) );
}
}, 10, 3 );
```
---
#### `bbfsync_cache_flushed`
Fires after `BBFSYNC_Cache::flush()` has finished deleting both the
transient cache and the permanent backup options. Useful for busting
downstream caches (page cache plugins, CDN purges, etc.) or audit logging.
**Arguments:** None.
**Example — purge a CDN edge cache when the plugin's feed is reset:**
```php
add_action( 'bbfsync_cache_flushed', function() {
// Trigger your CDN purge endpoint here.
error_log( '[BlueBook] cache flushed at ' . current_time( 'mysql' ) );
} );
```
---
## Patterns and conventions
- **Hook names use the `bbfsync_` prefix** consistently with the rest of the
plugin's namespace.
- **Filters return their first argument**, modified or not. Returning
`null` or omitting `return` will break the plugin.
- **Actions don't return anything.** Don't `return false` from an action
callback expecting it to cancel the operation — it won't.
- **Don't throw exceptions from hooks.** Other code (including the plugin
itself) will not catch them and your site will white-screen.
- **Don't do heavy synchronous work** in hooks that fire on every render
(like `bbfsync_post_data` and `bbfsync_post_html`, which run once per
post per render). For background work, schedule a one-off
`wp_schedule_single_event()` from inside your callback instead.
- **Anything you return from `bbfsync_post_html` or `bbfsync_feed_html`
bypasses `wp_kses_post()`** — escape your own additions with
`esc_html()`, `esc_attr()`, `esc_url()`, or `wp_kses()` as appropriate.
- **All hooks listed here are stable within major versions.** A 3.x release
will not remove or rename a documented hook. New hooks may be added in
minor versions; deprecations go through `_deprecated_hook()` with at
least one minor version of overlap.
## Two render paths to be aware of
The plugin renders feeds in two different code paths:
1. **Initial render (full feed):** `BBFSYNC_Renderer::render()` is called
from the `[bbfsync_feed]` shortcode and the Gutenberg block. Builds the
complete `
` wrapper, header, like box, posts,
load-more button, and lightbox.
2. **AJAX Load More (just the new post batch):** `BBFSYNC_Renderer::render_posts()`
is called directly from the `bbfsync_load_more` AJAX handler. Returns
only the per-post HTML — no wrapper, no header, no lightbox markup.
This affects which filters fire:
| Filter | Initial render | AJAX Load More |
|---|---|---|
| `bbfsync_post_data` | ✓ | ✓ |
| `bbfsync_post_html` | ✓ | ✓ |
| `bbfsync_feed_html` | ✓ | ✗ |
If you need a modification that must apply consistently across both paths,
use `bbfsync_post_data` or `bbfsync_post_html`. Use `bbfsync_feed_html` only
for changes that genuinely belong on the outer wrapper.
## Requesting a new hook
If you want to customize something the existing hooks don't cover, please
open a thread in the wordpress.org support forum and describe what you're
trying to do. Adding a new hook is usually a one-line change for us, and
publishing it as part of the public API gives the change permanence.