sanitize_bookmark_field( string $field, mixed $value, int $bookmark_id, string $context ): mixed
- Since
- 2.3.0
- Source
wp-includes/bookmark.php:399
Description
Sanitizes the bookmark fields based on what the field name is. If the field has a strict value set, then it will be tested for that, else a more generic filtering is applied. After the more strict filter is applied, if the $context is 'raw' then the value is immediately return.
Hooks exist for the more generic cases. With the 'edit' context, the 'edit_$field' filter will be called and passed the $value and $bookmark_id respectively.
With the 'db' context, the 'pre_$field' filter is called and passed the value.
The 'display' context is the final context and has the $field has the filter name and is passed the $value, $bookmark_id, and $context, respectively.
Compatibility
- WordPress
- since 2.3.0
- PHP
- 7.4–8.6-dev
- 6.7.7
- 6.8.8
- 6.9.7
- 7.0.4
- 7.1.0
Present in every tracked release (6.7.7 to 7.1.0), and compiles on PHP 7.4 through 8.6-dev.
Parameters
$fieldstring- The bookmark field.
$valuemixed- The bookmark field value.
$bookmark_idint- Bookmark ID.
$contextstring- How to filter the field value. Accepts 'raw', 'edit', 'db', 'display', 'attribute', or 'js'. Default 'display'.
Return value
mixed- The filtered value.
Performance profile
How much work a call to sanitize_bookmark_field() does, and what it touches: the algorithmic scaling, the Zend instruction count per call across PHP versions, the hooks it hands control to, and the core code that calls it. Measured from the compiled opcodes, not a stopwatch, so every number is identical on any machine running the same PHP version, and every function in core is ranked by cost.
- Cost class
- Trivial
- Scaling
- Constant
- Instructions
- 10–45
- Plugin surface
- 3 hooks
- Called by
- 5
Touches nothing outside its own arguments.
No loop in the body: the same number of instructions runs whatever you pass in.
Executed per call on PHP 8.5, depending on the branch taken. The body compiles to 89.
Third-party callbacks on 'edit_{$field}', 'pre_{$field}', '{$field}' run inside this call, and their cost is not bounded by anything here.
5 places in core call this, so the cost is paid more often than your own code shows.
What it touches
- hookthird-party callbacks
apply_filters()called directly
Further down the call graph this can also reach option, cache, serialize, query and transient. Those are the worst case, several calls deep and usually down an error path, not what a normal call pays.
What one call costs · 6 distinct outcomes
One number would be a lie: the work depends on which branch runs. These are every distinct cost sanitize_bookmark_field() can have, taken from its control-flow graph on PHP 8.5.
| When | Instructions | Calls it makes |
|---|---|---|
$context === "raw" | 10–21 | none |
| always | 14–18 | array_map() |
$context !== "raw" && $context !== "edit" | 23–41 | apply_filters() |
$context !== "raw" | 28–44 | apply_filters(), esc_attr() |
$context !== "raw" && $context === "edit" && $field === "link_notes" | 28–41 | apply_filters(), esc_html() |
$context !== "raw" && $context !== "edit" && $context !== "db" && $context !== "attribute" && $context === "js" | 32–45 | apply_filters(), esc_js() |
Across PHP versions
| PHP | Compiled | Executed | Branches | Notes |
|---|---|---|---|---|
| 8.6-dev | 89 | 10–45 | 13 | |
| 8.5 | 89 | 10–45 | 13 | |
| 8.4 | 89 | 10–45 | 13 | 3 fewer instructions than PHP 8.3 |
| 8.3 | 92 | 10–47 | 13 | |
| 8.2 | 92 | 10–47 | 13 | 1 more instruction than PHP 8.1 |
| 8.1 | 91 | 10–47 | 13 | |
| 7.4 | 91 | 10–47 | 13 |
An instruction is not a fixed amount of time, so a matching count is not necessarily the same speed; what it rules out is a difference in the work itself.
Hooks and filters fired · 3
3 hooks fire while sanitize_bookmark_field() runs, in this order:
- apply_filters( edit_{$field} )filterline 431 (+32 into the body)
Filters the value of a specific post field to edit.
- apply_filters( pre_{$field} )filterline 440 (+41 into the body)
Filters the value of a specific post field before saving.
- apply_filters( {$field} )filterline 443 (+44 into the body)
Filters the value of a specific post field for display.
Uses · 4
- apply_filters()Calls the callback functions that have been added to a filter hook.
- esc_html()Escaping for HTML blocks.
- esc_attr()Escaping for HTML attributes.
- esc_js()Escapes single quotes, `"`, ``, `&`, and fixes line endings.
Used by · 5
- _walk_bookmarks()The formatted output of a list of bookmarks.
- get_bookmark_field()Retrieves single bookmark data item or field.
- get_linkrating()Legacy function that retrieved the value of a link's link_rating field.
- get_links()Gets the links associated with category by ID.
- sanitize_bookmark()Sanitizes all bookmark fields.
Source code
function sanitize_bookmark_field( $field, $value, $bookmark_id, $context ) { $int_fields = array( 'link_id', 'link_rating' ); if ( in_array( $field, $int_fields, true ) ) { $value = (int) $value; } switch ( $field ) { case 'link_category': // array( ints ) $value = array_map( 'absint', (array) $value ); /* * We return here so that the categories aren't filtered. * The 'link_category' filter is for the name of a link category, not an array of a link's link categories. */ return $value; case 'link_visible': // bool stored as Y|N $value = preg_replace( '/[^YNyn]/', '', $value ); break; case 'link_target': // "enum" $targets = array( '_top', '_blank' ); if ( ! in_array( $value, $targets, true ) ) { $value = ''; } break; } if ( 'raw' === $context ) { return $value; } if ( 'edit' === $context ) { /** This filter is documented in wp-includes/post.php */ $value = apply_filters( "edit_{$field}", $value, $bookmark_id ); if ( 'link_notes' === $field ) { $value = esc_html( $value ); // textarea_escaped } else { $value = esc_attr( $value ); } } elseif ( 'db' === $context ) { /** This filter is documented in wp-includes/post.php */ $value = apply_filters( "pre_{$field}", $value ); } else { /** This filter is documented in wp-includes/post.php */ $value = apply_filters( "{$field}", $value, $bookmark_id, $context ); if ( 'attribute' === $context ) { $value = esc_attr( $value ); } elseif ( 'js' === $context ) { $value = esc_js( $value ); } } // Restore the type for integer fields after esc_attr(). if ( in_array( $field, $int_fields, true ) ) { $value = (int) $value; } return $value;}Changelog
Introduced in 2.3.0. Unchanged from 6.7.7 through 7.1.0.
Signature, return type and hooks compared across 5 parsed releases.
About this page
- Parsed data
- Generated from the wordpress-develop 7.1.0 tag, from
src/wp-includes/bookmark.php, and regenerated for each WordPress release so it tracks the code rather than a snapshot of it. - Corrections
- Something wrong on this page? Report it and it gets fixed in the next regeneration.