Sharing Image: hooks

Sharing Image provides developers with a large number of hooks that can be used to change the behavior of the plugin. Put the hook code in functions.php file of your theme or in your plugin.

Actions #

WordPress actions are benchmarks where the developer need to execute a specific code at a specific event.

sharing_image_settings #

Use this action to add something before the settings widget. If you want to extend js object inside settings page, use the sharing_image_settings_object filter.

Show me an example
                    
                        function my_settings_before() {
                            echo 'This text will be displayed in the settings page';
                        }

                        add_action( 'sharing_image_settings', 'my_settings_before' );
                    
                

sharing_image_widget #

Use this action to add something before metabox in post or taxonomy edition screen.

Note that the content inside the metabox is composed with js and if you want to change it, you need to use the sharing_image_widget_object filter.

Show me an example
                    
                        function my_widget_before() {
                            echo 'This text will be displayed in the metabox';
                        }

                        add_action( 'sharing_image_widget', 'my_widget_before' );
                    
                

Filters #

WordPress filters have the same idea as actions, but the main difference is that filters are used to modify variables. Unlike actions, filters code must return a value, which is the modified copy of the original value.

sharing_image_poster_src #

You can filter public poster url, width and height for current Object (Post or Term taxonomy) ID with this hook.

Show me an example
                    
                        /**
                         * @param array|false $image     List of image data, or boolean false if no image is available.
                         * @param int         $object_id Post ID or Taxonomy term ID.
                         */
                        function my_poster_src( $poster, $object_id ) {
                            $poster = array(
                                'https://example.org/image.png',
                                1200,
                                630,
                            );

                            return $poster;
                        }

                        add_filter( 'sharing_image_poster_src', 'my_poster_src', 10, 2 );
                    
                

sharing_image_singular_poster_meta #

Use this filter to update poster singular meta by Post ID.

Show me an example
                    
                        /**
                         * @param array|false $meta    Singular poster meta.
                         * @param int         $post_id Post ID.
                         */
                        function my_singular_poster_meta( $meta, $post_id ) {
                            if ( 1 === $post_id ) {
                                $meta = array(
                                    'https://example.org/image.png',
                                    1200,
                                    630,
                                );
                            }

                            return $meta;
                        }

                        add_filter( 'sharing_image_singular_poster_meta', 'my_singular_poster_meta', 10, 2 );
                    
                

sharing_image_taxonomy_poster_meta #

Use this filter to update poster taxonomy meta by Term ID. Please note that this hook is only available for Premium license.

Show me an example
                    
                        /**
                         * @param array $meta    Term poster image meta.
                         * @param int   $post_id Term ID.
                         */
                        function my_taxonomy_poster_meta( $meta, $term_id ) {
                            if ( false === $meta ) {
                                $meta = array(
                                    'https://example.org/image.png',
                                    1200,
                                    630,
                                );
                            }

                            return $meta;
                        }

                        add_filter( 'sharing_image_taxonomy_poster_meta', 'my_taxonomy_poster_meta', 10, 2 );
                    
                

sharing_image_plugin_classes #

The filter is used to update automatically initialized plugin classes. You can remove or add custom class on plugin load.

Show me an example
                    
                        /**
                         * @param array $classes List of classes.
                         */
                        function my_update_classes( $classes ) {
                            unset( $classes['Sharing_Image\Meta'] );

                            return $classes;
                        }

                        // This filter must execute before the `plugins_loaded` event.
                        add_filter( 'sharing_image_plugin_classes', 'my_update_classes' );
                    
                

sharing_image_prepare_template #

Prepare template before creating poster with this filter. Used to update fieldset texts and background image.

Show me an example
                    
                        /**
                         * @param array   $template  List of template data.
                         * @param array   $fieldset  Fieldset data from picker.
                         * @param string  $index     Template index from editor.
                         * @param int     $screen_id Post or term admin page id. Will be 0 if not set.
                         * @param string  $context   Screen ID context field. Can be settings, post or term.
                         */
                        function my_prepare_template( $template, $fieldset, $index, $screen_id, $context ) {
                            if ( 'post' === $context && 1 === $screen_id ) {
                                $template['fill'] = '#fff';
                            }

                            return $template;
                        }

                        add_filter( 'sharing_image_prepare_template', 'my_prepare_template', 10, 5 );
                    
                

sharing_image_get_fontpath #

Replace font path while poster generation according layer data.

Show me an example
                    
                        /**
                         * @param string $path  Font file path.
                         * @param array  $layer Layer data.
                         */
                        function my_get_fontpath( $path, $layer ) {
                            return WP_PLUGIN_DIR . '/my-plugin/font.ttf';
                        }

                        add_filter( 'sharing_image_get_fontpath', 'my_get_fontpath', 10, 2 );
                    
                

sharing_image_get_upload_file #

You can filter generated poster file path and url. By default used unique file name and upload directory from settings. Use sharing_image_upload_dir hook to update upload directory.

Show me an example
                    
                        /**
                         * @param array  $file Server file path and url to image.
                         * @param string $name Unique file name.
                         */
                        function my_get_upload_file( $file, $name ) {
                            $custom = 'custom.png';

                            // Replace unique file name with custom one in image url and path.
                            foreach ( $file as &$value ) {
                                $value = str_replace( $name, $custom, $value );
                            }

                            return $file;
                        }

                        add_filter( 'sharing_image_get_upload_file', 'my_get_upload_file', 10, 2 );
                    
                

sharing_image_hide_settings #

You can use this filter to hide settings page from some users or roles.

Show me an example
                    
                        /**
                         * @param bool $hide_settings Set true to hide settings page.
                         */
                        function my_hide_settings( $hide_settings ) {
                           $user = wp_get_current_user();

                           if ( empty( $user->user_login ) || 'admin' !== $user->user_login ) {
                               $hide_settings = true;
                           }

                           return $hide_settings;
                        }

                        add_filter( 'sharing_image_hide_settings', 'my_hide_settings' );
                    
                

sharing_image_disable_custom_fonts #

Use this filter to disable uploading custom fonts for templates editor. It can be useful for security reasons. Return true to disable uploading.

Show me an example
                    
                        /**
                         * @param bool $disable_fonts Set true to disable fonts uploading.
                         */
                        function my_disable_custom_fonts( $disable_fonts ) {
                            return true;
                        }

                        add_filter( 'sharing_image_disable_custom_fonts', 'my_disable_custom_fonts' );
                    
                

sharing_image_get_templates #

You can filter out the templates received from options. In addition to the settings, these templates are used in the post and taxonomy widget.

Show me an example
                    
                        /**
                         * @param array $templates List of templates.
                         */
                        function my_get_templates( $templates ) {
                            return $templates;
                        }

                        add_filter( 'sharing_image_get_templates', 'my_get_templates' );
                    
                

sharing_image_update_templates #

Update templates before saving them in database with this filter.

Show me an example
                    
                        /**
                         * @param array $templates List of reindexed templates.
                         */
                        function my_update_templates( $templates ) {
                            return $templates;
                        }

                        add_filter( 'sharing_image_update_templates', 'my_update_templates' );
                    
                

sharing_image_get_config #

Use this filter to update settigns config right after receiving from database.

Show me an example
                    
                        /**
                         * @param array List of plugin config settings.
                         */
                        function my_get_config( $config ) {
                            return $config;
                        }

                        add_filter( 'sharing_image_get_config', 'my_get_config' );
                    
                

sharing_image_update_config #

This filter is used to update config options before their update in database.

Show me an example
                    
                        /**
                         * @param array $config Settings config data.
                         */
                        function my_update_config( $config ) {
                            return $config;
                        }

                        add_filter( 'sharing_image_update_config', 'my_update_config' );
                    
                

sharing_image_develop #

If you don't have a Premium license, but you need to access all the features of the plugin for development purposes, you can use it in special mode. To do this, simply set the filter to true.

Show me an example
                    
                        /**
                         * @param bool Current development state. Disabled by default.
                         */
                        function my_develop( $is_develop ) {
                            return true;
                        }

                        add_filter( 'sharing_image_develop', 'my_develop' );
                    
                

sharing_image_get_license #

Use this filter to update license data right after receiving it from database options. Please be careful with this filter and do not use it to violate the plugin licensing policy.

Show me an example
                    
                        /**
                         * @param array List of plugin license settings.
                         */
                        function my_get_license( $license ) {
                            return $license;
                        }

                        add_filter( 'sharing_image_get_license', 'my_get_license' );
                    
                

sharing_image_upload_dir #

You can update the directory to uploaded posters with this filter. Note that the parameter is an array with the local path to the directory on the server and its external url.

Show me an example
                    
                        /**
                         * @param array $dir Path and url to upload directory.
                         */
                        function my_upload_dir( $dir ) {
                            $uploads = $dir;

                            return array( $uploads['path'], $uploads['url'] );
                        }

                        add_filter( 'sharing_image_upload_dir', 'my_upload_dir' );
                    
                

sharing_image_file_format #

Replace generated poster extension with this filter. By default it is taken from plugin settings.

Show me an example
                    
                        /**
                         * @param string $format Image file format.
                         */
                        function my_file_format( $format ) {
                            return 'png';
                        }

                        add_filter( 'sharing_image_file_format', 'my_file_format' );
                    
                

sharing_image_poster_quality #

You can rewrite generated poster quality with this filter. By default it is taken from plugin settings. Works only for JPEG posters. Set 0 for low resoulation posters and 100 for best quality.

Show me an example
                    
                        /**
                         * @param string $quality Image quality.
                         */
                        function my_poster_quality( $quality ) {
                            return 50;
                        }

                        add_filter( 'sharing_image_poster_quality', 'my_poster_quality' );
                    
                

sharing_image_hide_meta

Use this filter to hide OpenGraph and Twitter meta tags from wp_head section. Useful if you want to output these tags manually or disable them completely.

Show me an example
                    
                        /**
                         * @param bool $hide_header Set true to hide poster meta.
                         */
                        function my_default_hide_meta( $hide_meta ) {
                            return true;
                        }

                        add_filter( 'sharing_image_hide_meta', 'my_default_hide_meta' );
                    
                

sharing_image_default_poster_src #

This filter is used to change default poster for header meta. The output format is the same as in WordPress function wp_get_attachment_image_src.

Show me an example
                    
                        /**
                         * @param array|false Array of image data, or boolean false if no image is available.
                         */
                        function my_default_poster_src( $poster ) {
                            list( $image, $width, $height ) = my_get_poster_data();

                            return array( $image, $width, $height );
                        }

                        add_filter( 'sharing_image_default_poster_src', 'my_default_poster_src' );
                    
                

sharing_image_settings_object #

This filter allows you to manage an object with plugin settings.

Show me an example
                    
                        /**
                         * @param array $object Array of settings script object.
                         */
                        function my_settings_object( $object ) {
                            return $object;
                        }

                        add_filter( 'sharing_image_settings_object', 'my_settings_object' );
                    
                

sharing_image_sanitize_editor #

You can update template editor right after sanitization on the settings saving with this filter.

Show me an example
                    
                        /**
                         * @param array $sanitized List of sanitized editor fields.
                         * @param array $editor    List of editor fields before sanitization.
                         */
                        function my_sanitize_editor( $sanitized, $editor ) {
                            return $sanitized;
                        }

                        add_filter( 'sharing_image_sanitize_editor', 'my_sanitize_editor', 10, 2 );
                    
                

sharing_image_sanitize_config #

You can update config data right after sanitization on the settings saving with this filter.

Show me an example
                    
                        /**
                         * @param array $sanitized List of sanitized config fields.
                         * @param array $config    List of config fields before sanitization.
                         */
                        function my_sanitize_config( $sanitized, $config ) {
                            return $sanitized;
                        }

                        add_filter( 'sharing_image_sanitize_config', 'my_sanitize_config', 10, 2 );
                    
                

sharing_image_settings_tabs #

This filter is used to update settings tabs. You can remove existing or add a new one.

Show me an example
                    
                        /**
                         * @param array $tabs List of settings tabs.
                         */
                        function my_settings_tabs( $tabs ) {
                            unset( $tabs['premium'] );

                            return $tabs;
                        }

                        add_filter( 'sharing_image_settings_tabs', 'my_settings_tabs' );
                    
                

sharing_image_poster_fonts #

Use this filter to update availble fonts on poster generation. For example you can remove irrelevant default font.

Show me an example
                    
                        /**
                         * @param array List of availible poster fonts.
                         */
                        function my_poster_fonts( $fonts ) {
                            unset( $fonts['open-sans'] );

                            return $fonts;
                        }

                        add_filter( 'sharing_image_poster_fonts', 'my_poster_fonts' );
                    
                

sharing_image_directory_permissions #

Change permissions while creating new folders for posters storage with this filter. By default 0755.

Show me an example
                    
                        /**
                         * @param int $permissions New directory access permissions. By default 0755.
                         */
                        function my_directory_permissions() {
                            return 0777;
                        }

                        add_filter( 'sharing_image_directory_permissions', 'my_directory_permissions' );
                    
                

sharing_image_hide_metabox #

You can use this filter to hide the metabox from some users or roles.

Show me an example
                    
                        /**
                         * @param bool $hide_metabox Set true to hide metabox.
                         */
                        function my_hide_metabox( $hide_metabox ) {
                            if ( ! current_user_can( 'manage_options' ) ) {
                                $hide_metabox = true;
                            }

                            return $hide_metabox;
                        }

                        add_filter( 'sharing_image_hide_metabox', 'my_hide_metabox' );
                    
                

sharing_image_widget_object

This filter allows you to manage an object with widget settings.

Show me an example
                    
                        /**
                         * @param array $object Array of widget script object.
                         */
                        function my_widget_object( $object ) {
                            return $object;
                        }

                        add_filter( 'sharing_image_widget_object', 'my_widget_object' );
                    
                

sharing_image_metabox_post_types

Use this filter to update post types where the metabox is displayed. By default, these are all public types of posts, excluding attachments.

Show me an example
                    
                        /**
                         * @param array $post_types Array of post types for which the metabox is displayed.
                         */
                        function my_metabox_post_types( $post_types ) {
                            unset( $post_types['pages'] );

                            return $post_types;
                        }

                        add_filter( 'sharing_image_metabox_post_types', 'my_metabox_post_types' );
                    
                

sharing_image_widget_taxonomies

Use this filter to update taxonomies where the metabox is displayed. By default, these are all public taxonomies.

Show me an example
                    
                        /**
                         * @param array $taxonomies List of taxonomies to show settings.
                         */
                        function my_widget_taxonomies( $taxonomies ) {
                            unset( $taxonomies['category'] );

                            return $taxonomies;
                        }

                        add_filter( 'sharing_image_widget_taxonomies', 'my_widget_taxonomies' );
                    
                

sharing_image_autogenerated_poster since 2.0.11

This filter allows you to update autogenerated poster data. It can be useful to replace autogenerated poster or their sizes for certain Post ID.

Show me an example
                    
                        /**
                         * @since 2.0.11
                         *
                         * @param array|false $poster  Poster image, width and height data or false if undefined.
                         * @param integer     $post_id Post ID.
                         */
                        function my_autogenerated_poster( $poster, $post_id ) {
                            if ( 1 === $post_id ) {
                                $poster = my_poster_generator();
                            }

                            return $poster;
                        }

                        add_filter( 'sharing_image_autogenerated_poster', 'my_autogenerated_poster' );
                    
                

sharing_image_hide_twitter_meta since 2.0.12

This filter allows to hide only Twitter meta tags.

Show me an example
                    
                        /**
                         * @since 2.0.12
                         *
                         * @param bool $hide_twitter_meta Set true to hide poster meta.
                         */
                        function my_hide_twitter_meta( $hide_twitter_meta ) {
                            return true;
                        }

                        add_filter( 'sharing_image_hide_twitter_meta', 'my_hide_twitter_meta' );
                    
                

sharing_image_active_snippets since 3.0

Last chance to activate plugin snippets.

Show me an example
                    
                        /**
                         * @since 3.0
                         *
                         * @param bool $active_snippets Set true to activate plugin snippets.
                         */
                        function my_active_snippets( $active_snippets ) {
                            return true;
                        }

                        add_filter( 'sharing_image_active_snippets', 'my_active_snippets' );
                    
                

sharing_image_show_header since 3.0

Last chance to show customer header meta.

Show me an example
                    
                        /**
                         * @since 3.0
                         *
                         * @param bool $show_header Set true to show custom header meta.
                         */
                        function my_show_header( $show_header ) {
                            return true;
                        }

                        add_filter( 'sharing_image_show_header', 'my_show_header' );
                    
                

sharing_image_unique_index since 3.0

Filter template unique index on creation. It may be useful when you want to override template index names. Use in conjunction with the sharing_image_valid_unique_index filter.

Show me an example
                    
                        /**
                         * @since 3.0
                         *
                         * @param array $index     Generated template index.
		                 * @param array $templates List of templates.
                         */
                        function my_unique_index( $index, $templates ) {
                            return md5( time() );
                        }

                        add_filter( 'sharing_image_unique_index', 'my_unique_index', 10, 2 );
                    
                

sharing_image_valid_unique_index since 3.0

This filter allows you to change the template index validation. It may be useful when you want to override template index names. Use in conjunction with the sharing_image_unique_index filter.

Show me an example
                    
                        /**
                         * @since 3.0
                         *
                         * @param bool   $valid Valid flag.
                         * @param string $index Template index.
                         */
                        function my_valid_unique_index( $valid, $index ) {
                            if ( ! is_numeric( $index ) ) {
                                $valid = false;
                            }

                            return $valid;
                        }

                        add_filter( 'sharing_image_valid_unique_index', 'my_valid_unique_index', 10, 2 );
                    
                

sharing_image_sanitize_source since 3.0

You can update _sharing_image meta data right after sanitization on the metabox or sidebar saving with this filter.

Show me an example
                    
                        /**
                         * @since 3.0
                         *
                         * @param array $sanitized List of sanitized fields.
                         * @param array $source    List of fields before sanitization.
                         */
                        function my_sanitize_source( $sanitized, $source ) {
                            return $sanitized;
                        }

                        add_filter( 'sharing_image_sanitize_source', 'my_sanitize_source', 10, 2 );
                    
                

sharing_image_sanitize_fieldset since 3.0

You can update _sharing_image_fieldset meta data right after sanitization on the metabox or sidebar saving with this filter.

Show me an example
                    
                        /**
                         * @since 3.0
                         *
                         * @param array $sanitized Sanitized fieldset list.
                         * @param array $fieldset  Fieldset list before sanitization.
                         */
                        function my_sanitize_fieldset( $sanitized, $fieldset ) {
                            return $fieldset;
                        }

                        add_filter( 'sharing_image_sanitize_fieldset', 'my_sanitize_fieldset', 10, 2 );
                    
                

sharing_image_autogenerated_fieldset since 3.0

Use this filter to update the fieldset during poster auto-generation. This can be very useful if you want to ignore widget settings and provide your own values under certain conditions. Additionally, use this filter if you have removed the widget from the post editing page but still want to provide your own values for the poster.

Show me an example
                    
                        /**
                         * @since 3.0
                         *
                         * @param array  $fieldset Prepared fieldset data.
                         * @param string $index    Template index.
                         * @param int    $post_id  Post ID.
                         */
                        function my_autogenerated_fieldset( $fieldset, $index, $post_id ) {
                            if ( 10 === $post_id ) {
                                $fieldset['ghI3l4Ertyid'] = esc_html( 'Custom text' );
                            }

                            return $fieldset;
                        }

                        add_filter( 'sharing_image_autogenerated_fieldset', 'my_autogenerated_fieldset', 10, 3 );
                    
                

sharing_image_attachment_data since 3.0

This filter allows you to customize the attachment that will be added during poster generation if such a setting is used. Return an empty value if you do not want to save the attachment. For example, you may choose not to save the attachment only for auto-generated posts.

Show me an example
                    
                        /**
                         * @since 3.0
                         *
                         * @param string $attachment Attachment data.
                         * @param string $path       Path to poster image.
                         * @param string $screen_id  Post or taxonomy screen ID.
                         * @param string $context    Widget context. For example: metabox or autogenerate.
                         */
                        function my_attachment_data( $attachment, $path, $screen_id, $context ) {
                            if ( autogenerate === $context ) {
                                $attachment = null;
                            }

                            return $attachment;
                        }

                        add_filter( 'sharing_image_attachment_data', 'my_attachment_data', 10, 4 );
                    
                

sharing_image_snippets since 3.0

This filter allows you to add or override classes for snippets. Snippets are used to interact with third-party plugins that add their own social media posters to the page.

Show me an example
                    
                        /**
                         * @since 3.0
                         *
                         * @param array $snippets A key-value array with class name key and path to the file as value.
                         */
                        function my_image_snippets( $snippets ) {
                            unset( $snippets['Sharing_Image\Snippets\YoastSeo'] )

                            return $snippets;
                        }

                        add_filter( 'sharing_image_snippets', 'my_image_snippets', 10 );
                    
                

sharing_image_get_snippets since 3.0

Use this filter to override the list of snippet names that will be displayed in the admin configuration page.

Show me an example
                    
                        /**
                         * @since 3.0
                         *
                         * @param array $names List of snippets names.
                         */
                        function my_image_snippets( $names ) {
                            return $names;
                        }

                        add_filter( 'sharing_image_get_snippets', 'my_image_snippets', 10 );
                    
                

sharing_image_hide_meta

This hook was removed in version 3.0 and is no longer available.

Use this filter to hide OpenGraph and Twitter meta tags from wp_head section. Useful if you want to output these tags manually or disable them completely.

Show me an example
                    
                        /**
                         * @param bool $hide_header Set true to hide poster meta.
                         */
                        function my_default_hide_meta( $hide_meta ) {
                            return true;
                        }

                        add_filter( 'sharing_image_hide_meta', 'my_default_hide_meta' );
                    
                

sharing_image_update_post_meta

This hook was removed in version 3.0 and is no longer available.

This filter allows you to change the array with widget post meta right before the update_post_meta request.

Show me an example
                    
                        /**
                         * @param string $meta    Updated post meta.
                         * @param string $post_id Post ID.
                         */
                        function my_update_post_meta( $meta, $post_id ) {
                            return $meta;
                        }

                        add_filter( 'sharing_image_update_post_meta', 'my_update_post_meta', 10, 2 );
                    
                

sharing_image_update_term_meta

This hook was removed in version 3.0 and is no longer available.

This filter allows you to change the array with widget term meta right before the update_term_meta request.

Show me an example
                    
                        /**
                         * @param string $meta    Updated term meta.
                         * @param string $term_id Term ID.
                         */
                        function my_update_term_meta( $meta, $post_id ) {
                            return $meta;
                        }

                        add_filter( 'sharing_image_update_term_meta', 'my_update_term_meta', 10, 2 );
                    
                

sharing_image_sanitize_picker

This hook was removed in version 3.0 and is no longer available.

You can update widget picker data right after sanitization on the metabox saving with this filter.

Show me an example
                    
                        /**
                         * @param array $sanitized List of sanitized picker fields.
                         * @param array $picker    List of picker fields before sanitization.
                         */
                        function my_sanitize_picker( $sanitized, $picker ) {
                            return $sanitized;
                        }

                        add_filter( 'sharing_image_sanitize_picker', 'my_sanitize_picker', 10, 2 );
                    
                

sharing_image_disable_autogeneration since 2.0.12

This hook was removed in version 3.0 and is no longer available.

Use this filter to disable posters autogeneration process based on Post ID. It is good idea to skip autogeneration for some post types.

Show me an example
                    
                        /**
                         * @since 2.0.12
                         *
                         * @param int  $post_id Post ID.
                         * @param bool $disable_autogeneration Set true to disable autogeneration.
                         */
                        function my_disable_autogeneration( $disable, $post_id ) {
                            if ( 'page' === get_post_type( $post_id ) ) {
                                return true;
                            }
                        }

                        add_filter( 'sharing_image_disable_autogeneration', 'my_disable_autogeneration', 10, 2 );
                    
                
Back to Sharing Image summary