Skip to content

How it works#

The manifest#

Everything the front end needs is compiled into one manifest: the print tree (order → where → snippets), the rules index, each snippet's printed code, and warnings. It is a PHP file in wp-content/cache/bb-snippets/, so PHP's opcode cache keeps it in memory; when that folder is not writable it is stored in the bb_snippets_manifest option.

Every build is a new file name, recorded in the bb_snippets_state option. Rewriting one path in place would let the opcode cache keep serving the old manifest after a rebuild from WP-CLI or cron (on hosts that recheck files every 60 seconds, or never). Earlier files are removed after ten minutes.

When it rebuilds#

At the end of any request that changed a snippet:

  • status changes (publish, draft, trash, scheduled publishing),
  • saves from any screen or API, deletes, revision restores,
  • writes to the options, urls, _active, _slug or _bb_snippet meta,
  • WordPress Importer runs and changes to the shared settings.

Changes that bypass WordPress (SQL, a database push, an edited theme file) are caught by a fingerprint of the snippet rows, their meta and the theme snippet files, checked on admin loads, by WP-CLI, hourly by cron and on the front end at most every five minutes. A BB Migrate push that writes or deletes a theme snippet file, and a theme switch, rebuild at once. An expiry date passing also triggers a rebuild.

Files#

The database is the source of truth. Linked (external) snippets are written to uploads/custom-css-js/{ID}.{css|js} in the old plugin's format, and {alias}.{ext} when a file alias is set, so their URLs, the theme's residual swap and BB Cache's inline list keep working. Their ?v= is a checksum of the content. Inline snippets print from the manifest, without a file read per request; their files are refreshed too, for the old plugin's sake. Files are only rewritten when their content changed. Revisions never get files.

The old plugin left one file per revision and per abandoned alias. Tools → Health lists them and can delete them.

SASS and LESS#

SASS (SCSS syntax) and LESS compile when the manifest is built, with the compilers and versions Simple Custom CSS and JS PRO 4.43 bundles (scssphp 1.13.0, less.php 4.4.1) and their default output style. Pages get plain CSS; nothing compiles during a page request. @import looks in uploads/custom-css-js (partial snippets) and the theme snippet folders; the old plugin's ccj_preprocessor_import_paths filter still applies.

A snippet that stops compiling keeps printing the last version that compiled (its previous inline code, or its current linked file), with the error on its edit screen and under Tools → Health. A snippet that never compiled prints nothing. Editing a partial recompiles every snippet, and purges the pages of each snippet whose output changed.

Printing#

Front-end snippets are decided on the wp action (so conditional tags work) and printed on wp_head, wp_body_open and wp_footer at priority 30; admin snippets on admin_head / admin_footer; login-page snippets on login_head / login_footer; block-editor snippets are enqueued on enqueue_block_assets. Within a priority, newer snippets print first, as before. jQuery is enqueued when a front-end or block-editor JavaScript snippet needs it.

Output#

Classic (the default) prints the old plugin's markup byte for byte.

Registered (Snippets → Settings) turns front-end CSS snippets (inline and linked) and linked JavaScript snippets into registered WordPress styles and scripts with the handle bb-snippet-{key}, printed at the same place and in the same order as classic output, so the cascade does not change. Code that runs before wp_head can wp_deregister_style() or replace one by handle; style_loader_tag and script_loader_tag apply; jQuery is a real dependency of linked scripts. Inline JavaScript stays classic: WordPress would print it as a {handle}-js-after script, which page optimizers (BB Cache's delay rules among them) treat as part of a handle and never delay, so it would run earlier than it does now. HTML snippets and the admin, login and block-editor sides stay classic too.

Checked on the local mirror: all 323 public pages carry the same snippet code at the same place in both modes. The markup differs (no "Simple Custom CSS and JS" comments, id="bb-snippet-…", ?ver= on files, WordPress's sourceURL comment), so anything that matches the classic markup needs the bb_snippets_content filter instead.

Hooks#

Hook Type Use
bb_snippets_rebuilt action After every build: ( $manifest, $why, $ids, $before ); $ids is null when the scope is unknown
bb_snippets_tree filter The print tree for this request, after rules
bb_snippets_content filter A snippet's printed code: ( $code, $id, $snippet )
bb_snippets_purge filter Return false to stop BB Snippets purging BB Cache
ccj_default_url_protocol filter As in the old plugin: true keeps http(s):// on file URLs instead of //
ccj_preprocessor_import_paths filter As in the old plugin: folders SASS/LESS @import looks in
bb_snippets_file_dirs filter The theme snippet folders (default: snippets/ in the child and parent theme)