| | 2224 | * Convenience function that echoes the HTML for the site's favicon icon. |
| | 2225 | * By default, automatically included in the header via the 'wp_head' action, which can be removed by themes if a custom favicon is desired. |
| | 2226 | * |
| | 2227 | * @uses generate_site_favicon_html() to do the actual heavy lifting |
| | 2228 | */ |
| | 2229 | function site_favicon(){ |
| | 2230 | echo generate_site_favicon_html(); |
| | 2231 | } |
| | 2232 | add_action( 'wp_head', 'site_favicon' ); |
| | 2233 | add_action( 'admin_head', 'site_favicon' ); |
| | 2234 | |
| | 2235 | /** |
| | 2236 | * Return the HTML for the site's favicon icon, if such has been defined. |
| | 2237 | * |
| | 2238 | * @uses get_site_favicon_uri(); |
| | 2239 | * |
| | 2240 | * Includes the conditional tag wrapper for an IE (.ico) version. |
| | 2241 | */ |
| | 2242 | function generate_site_favicon_html() { |
| | 2243 | $favicon_uri = get_site_favicon_uri(); |
| | 2244 | $ie_favicon_uri = get_site_favicon_uri( 'ico' ); |
| | 2245 | |
| | 2246 | $content = ""; |
| | 2247 | if (! empty( $favicon_uri ) ){ |
| | 2248 | $content .= "\n\n<!--favicon (via 'wp_head' action) -->\n"; |
| | 2249 | |
| | 2250 | if (! empty( $ie_favicon_uri )) $content .= <<<IE_FAVICON_1 |
| | 2251 | <!--[if IE]> |
| | 2252 | <link rel="shortcut icon" href="{$ie_favicon_uri}" /> |
| | 2253 | <![endif]--> |
| | 2254 | <!--[if !IE]>-->\n |
| | 2255 | IE_FAVICON_1; |
| | 2256 | |
| | 2257 | $content .= "\t<link href=\"{$favicon_uri}\" rel=\"icon\" type=\"image/png\" />\n"; |
| | 2258 | |
| | 2259 | if (! empty( $ie_favicon_uri )) $content .= "<!--<![endif]-->"; |
| | 2260 | $content .= "\n<!-- /favicon -->\n\n"; |
| | 2261 | } |
| | 2262 | return $content; |
| | 2263 | } |
| | 2264 | |
| | 2265 | /** |
| | 2266 | * Get the attachment post object associated with the current site favicon, based on the 'sitefavicon' option |
| | 2267 | * |
| | 2268 | * @param string $format Default 'png'. Format of the file we're looking for |
| | 2269 | * @return object If found, returns the post object; if not, a WP_Error object |
| | 2270 | */ |
| | 2271 | function get_site_favicon_attachment( $format = 'png' ){ |
| | 2272 | $favicon_basename = get_option ( 'sitefavicon' ); |
| | 2273 | |
| | 2274 | if ( ! empty( $favicon_basename ) ) { |
| | 2275 | $favicon_fullname = $favicon_basename . '-' . $format; |
| | 2276 | |
| | 2277 | $posts = get_posts( array( 'name' => $favicon_fullname, 'post_type' => 'attachment' ) ); |
| | 2278 | if ( count( $posts ) > 0 ){ |
| | 2279 | return $posts[0]; |
| | 2280 | } else { |
| | 2281 | return new WP_Error( 'attachment_missing', __( "No attachment for '$favicon_fullname' was found." ) ); |
| | 2282 | } |
| | 2283 | } else { |
| | 2284 | return new WP_Error( 'not_defined', __( "No favicon file provided." ) ); |
| | 2285 | } |
| | 2286 | } |
| | 2287 | |
| | 2288 | /** |
| | 2289 | * Returns the URI for the site's favicon based on the option set in Admin > Settings > General. |
| | 2290 | * |
| | 2291 | * @param string $format png|ico default 'png'. Use 'ico' for serving up an IE-compatible ICO file |
| | 2292 | * @return string fully qualified URI |
| | 2293 | */ |
| | 2294 | function get_site_favicon_uri( $format = 'png' ){ |
| | 2295 | /** @TODO provide error checking for validity of $format and $size */ |
| | 2296 | $favicon_attachment = get_site_favicon_attachment( $format ); |
| | 2297 | |
| | 2298 | /** @TODO provide the ability to define a 'default' favicon that would be distributed with fresh WP installations */ |
| | 2299 | if ( ! is_wp_error( $favicon_attachment ) ) { |
| | 2300 | return wp_get_attachment_url( $favicon_attachment->ID ); |
| | 2301 | } |
| | 2302 | |
| | 2303 | // We get here because of an error condition |
| | 2304 | /** @TODO default to the theme's favicon **/ |
| | 2305 | // ATM do nothing (so URI is blank, rather than a WP_Error) |
| | 2306 | } |
| | 2307 | |
| | 2308 | /** |
| | 2309 | * Gets the path to the favicon file, or returns a WP_Error |
| | 2310 | * @param string $format Default 'png' |
| | 2311 | * @return mixed File string or WP_Error object |
| | 2312 | */ |
| | 2313 | function get_site_favicon_file( $format = 'png' ){ |
| | 2314 | $favicon_attachment = get_site_favicon_attachment( $format ); |
| | 2315 | |
| | 2316 | /** @TODO provide the ability to define a 'default' favicon that would be distributed with fresh WP installations */ |
| | 2317 | if ( ! is_wp_error( $favicon_attachment ) ) { |
| | 2318 | $file = get_attached_file( $favicon_attachment->ID ); |
| | 2319 | if ( file_exists( $file ) ) return $file; |
| | 2320 | else return new WP_Error( 'file_missing', __( 'Favicon image file missing.' ) ); |
| | 2321 | } else { |
| | 2322 | return $favicon_attachment; // returns the WP_Error object |
| | 2323 | } |
| | 2324 | } |
| | 2325 | |
| | 2326 | /** |
| | 2327 | * Returns true or false depending on whether a custom favicon has been defined in Admin |
| | 2328 | * @return boolean |
| | 2329 | */ |
| | 2330 | function has_custom_favicon(){ |
| | 2331 | return ( get_option ( 'sitefavicon' ) && ! is_wp_error( get_site_favicon_file() ) ); |
| | 2332 | } |
| | 2333 | |
| | 2334 | /** |
| | 2335 | * Returns an HTML <img> tag populated with the site favicon, in the format specified (usually PNG) |
| | 2336 | * @param string $format Default 'png'. Valid values are 'png', 'bmp' (note 'ico' is NOT valid) |
| | 2337 | * @return mixed Returns HTML <img> tag or WP_Error if invalid format given. Returns nothing if the file is missing. |
| | 2338 | */ |
| | 2339 | function get_favicon_img( $format = 'png' ){ |
| | 2340 | if (in_array( strtolower( $format ), array( 'png', 'bmp' ) ) ){ |
| | 2341 | // Does the file actually exist? |
| | 2342 | $file = get_site_favicon_file( $format ); |
| | 2343 | if (! is_wp_error( $file ) && file_exists( $file ) ){ |
| | 2344 | $src = get_site_favicon_uri( $format ); |
| | 2345 | if (!is_wp_error( $src ) ){ |
| | 2346 | return '<img src="' . $src . '" class="favicon" alt="' . _x( 'Site favicon thumbnail', 'Thumbnail image accessibility text' ) .'" />'; |
| | 2347 | } |
| | 2348 | } |
| | 2349 | } else { |
| | 2350 | return new WP_Error( 'invalid_file_format', __( 'Invalid file format. Valid formats are "png", "bmp".' ) ); |
| | 2351 | } |
| | 2352 | } |
| | 2353 | |
| | 2354 | /** |