Social Planner: hooks

Social Planner 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.

social_planner_dashboard_before

Use this action to add something before the dashboard widget.

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

Show me an example
                    
                        function my_dashboard_before() {
                            echo 'This text will be displayed in the dashboard widget';
                        }

                        add_action( 'social_planner_dashboard_before', 'my_dashboard_before' );
                    
                

social_planner_metabox_before

Use this action to add something before metabox in post 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 social_planner_metabox_object filter.

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

                        add_action( 'social_planner_metabox_before', 'my_metabox_before' );
                    
                

social_planner_task_sent

Use this action to do something with the task results right after sending.

Show me an example
                
                    /**
                     * @param array  $results List of results after task sending.
                     * @param string $key     Task key.
                     * @param int    $post_id Post ID.
                     */
                    function my_task_sent( $results, $key, $post_id ) {
                        my_save_results( $results, $key );
                    }

                    add_action( 'social_planner_task_sent', 'my_task_sent', 10, 3 );
                
            

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.

social_planner_networks

The filter is used to add a custom social network for sending announcements. Read more about this in the FAQ section of this documentation.

Show me an example
                    
                        /**
                         * @param array $networks A key-value array with class name key and path to the file as value.
                         */
                        function add_example_network( $networks ) {
                            $networks['My_Network_Example'] = get_template_directory() . '/inc/class-network-example.php';

                            return $networks;
                        }

                        // This filter must execute before the `init` event.
                        add_filter( 'social_planner_networks', 'add_example_network' );
                    
                

social_planner_network_label

You can change network labels in the metabox and settings with this filter.

Show me an example
                
                    /**
                     * @param string $label Network label.
                     * @param string $class Current network class.
                     */
                    function my_network_label( $label, $class ) {
                        if ( 'Social_Planner\Network_Telegram' === $class ) {
                            $label = 'My custom ' . $label;
                        }

                        return $label;
                    }

                    add_filter( 'social_planner_network_label', 'my_network_label', 10, 2 );
                
            

social_planner_time_format

You can change the date format used by the plugin with this filter. The default is the format from the WordPress settings. Read more in codex section.

Show me an example
                
                    /**
                     * @param string $format Datetime format.
                     */
                    function my_time_format( $format ) {
                        return 'F j, Y h:i';
                    }

                    add_filter( 'social_planner_time_format', 'my_time_format' );
                
            

social_planner_hide_dashboard

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

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

                        return $hide_dashboard;
                    }

                    add_filter( 'social_planner_hide_dashboard', 'my_hide_dashboard' );
                
            

social_planner_dashboard_object

This filter allows you to manage an object with the dashboard settings.

Show me an example
                
                    /**
                     * @param array $object Array of dashboard script object.
                     */
                    function my_dashboard_object( $object ) {
                        $object['tasks'] = my_dashboard_handler( 'tasks' );

                        return $object;
                    }

                    add_filter( 'social_planner_dashboard_object', 'my_dashboard_object' );
                
            

social_planner_sanitize_tasks

You can update tasks right after sanitization on the metabox saving with this filter.

Show me an example
                
                    /**
                     * @param array $sanitized List of tasks after sanitization.
                     * @param array $tasks     List of tasks before sanitization.
                     */
                    function my_sanitize_tasks( $sanitized_tasks, $tasks ) {
                        return my_tasks_sanitization( $tasks );
                    }

                    add_filter( 'social_planner_sanitize_tasks', 'my_sanitize_tasks', 10, 2 );
                
            

social_planner_get_tasks

This filter allows you to change the array with tasks during the get_post_meta request.

Show me an example
                
                    /**
                     * @param array $tasks   List of tasks from post meta.
                     * @param int   $post_id Post ID.
                     */
                    function my_get_tasks( $tasks, $post_id ) {
                        if ( 0 === $post_id ) {
                            $tasks = array();
                        }

                        return $tasks;
                    }

                    add_filter( 'social_planner_get_tasks', 'my_get_tasks', 10, 2 );
                
            

social_planner_update_tasks

This filter allows you to change the array with tasks right before the update_post_meta request.

Show me an example
                
                    /**
                     * @param array  $tasks   List of tasks from post meta.
                     * @param int    $post_id Post ID.
                     */
                    function my_update_tasks( $tasks, $post_id ) {
                        if ( 0 === $post_id ) {
                            $tasks = array();
                        }

                        return $tasks;
                    }

                    add_filter( 'social_planner_update_tasks', 'my_update_tasks', 10, 2 );
                
            

social_planner_get_results

This filter allows you to change the array with results during the get_post_meta request.

Show me an example
                
                    /**
                     * @param array $results List of results from post meta.
                     * @param int   $post_id Post ID.
                     */
                    function my_get_results( $results, $post_id ) {
                        if ( 0 === $post_id ) {
                            $results = array();
                        }

                        return $results;
                    }

                    add_filter( 'social_planner_get_results', 'my_get_results', 10, 2 );
                
            

social_planner_update_results

This filter allows you to change the array with results right before the update_post_meta request.

Show me an example
                
                    /**
                     * @param array $results List of tasks from post meta.
                     * @param int   $post_id Post ID.
                     */
                    function my_update_results( $results, $post_id ) {
                        if ( 0 === $post_id ) {
                            $results = array();
                        }

                        return $results;
                    }

                    add_filter( 'social_planner_update_results', 'my_update_results', 10, 2 );
                
            

social_planner_metabox_object

This filter allows you to manage an object with the metabox settings.

Show me an example
                
                    /**
                     * @param array $object  Array of metabox script object.
                     * @param int   $post_id Current post ID.
                     */
                    function my_metabox_object( $object, $post_id ) {
                        $object = array(
                            'meta'      => my_metabox_handler( 'meta' ),
                            'action'    => my_metabox_handler( 'action' ),
                            'nonce'     => my_metabox_handler( 'nonce' ),
                            'tasks'     => my_metabox_handler( 'tasks' ),
                            'results'   => my_metabox_handler( 'results' ),
                            'offset'    => my_metabox_handler( 'offset' ),
                            'calendar'  => my_metabox_handler( 'calendar' ),
                            'providers' => my_metabox_handler( 'providers' ),
                            'schedules' => my_metabox_handler( 'schedules' ),
                        );

                        return $object;
                    }

                    add_filter( 'social_planner_metabox_object', 'my_metabox_object', 10, 2 );
                
            

social_planner_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( 'social_planner_hide_metabox', 'my_hide_metabox' );
                
            

social_planner_post_types

By default, the plugin shows the metabox for all public post types except attachments. You can override this behavior with this filter.

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

                        foreach ( $post_types as $i => $name ) {
                            if ( 'page' === $name ) {
                                unset( $post_types[ $i ] );
                            }
                        }

                        return $post_types;
                    }

                    add_filter( 'social_planner_post_types', 'my_post_types' );
                
            

social_planner_calendar_days

This filter manages the number of future days in schedule select box.

Show me an example
                
                    /**
                     * @param int $days_count Number of days in task calendar select box.
                     */
                    function my_calendar_days( $days_number ) {
                        return 7;
                    }

                    add_filter( 'social_planner_calendar_days', 'my_calendar_days' );
                
            

social_planner_time_offset

This filter sets a time offset. By default, it is a value between UTC and WordPress time in seconds. This offset is used in admin-side metabox to choose the time for planning.

Show me an example
                
                    /**
                     * @param int $offset Time offset in seconds from UTC.
                     */
                    function my_time_offset( $offset ) {
                        $offset = timezone_offset_get( wp_timezone(), date_create( 'now' ) );

                        return $offset;
                    }

                    add_filter( 'social_planner_time_offset', 'my_time_offset' );
                
            

social_planner_post_statuses

This filter sets post statuses that can be scheduled. By default, we can schedule only posts with statuses 'publish' or 'future'. You can change this behavior.

Show me an example
                
                    /**
                     * @param array $statuses List of post statuses.
                     */
                    function my_post_statuses( $statuses ) {
                        $statuses = array( 'private', 'pending', 'future', 'publish' );

                        return $statuses;
                    }

                    add_filter( 'social_planner_post_statuses', 'my_post_statuses' );
                
            

social_poster_prepare_message

This filter allows updating message array right before network sending method execution. This is a great place, for example, to add some text to the excerpt field or replace a post link.

Show me an example
                
                    /**
                     * @param array  $message Sending message data.
                     * @param string $target  Target provider name.
                     * @param array  $task    Scheduled task data.
                     */
                    function my_prepare_message( $message, $target, $task ) {
                        $message['link'] = my_message_link( $message['post_id'] );

                        if ( ! empty( $message['excerpt'] ) ) {
                            $message['excerpt'] = $message['excerpt'] . "\n\n" . '#some_hashtag';
                        }

                        return $message;
                    }

                    add_filter( 'social_poster_prepare_message', 'my_prepare_message', 10, 3 );
                
            

social_planner_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( 'social_planner_hide_settings', 'my_hide_settings' );
                
            

social_planner_get_providers

You can filter the list of providers from options. It can be handy to use options bypassing the settings page.

Show me an example
                
                    /**
                     * @param array $providers List of provders options.
                     */
                     function my_get_providers( $providers ) {
                        $providers = array(
                            'facebook-1' => array(
                                'token' => 'token',
                                'group' => 'group',
                            ),
                        );

                        return $providers;
                    }

                    add_filter( 'social_planner_get_providers', 'my_get_providers' );
                
            

social_planner_settings_object

This filter allows you to manage settings script object.

Show me an example
                
                    /**
                     * @param array $object Array of settings script object.
                     */
                    function my_settings_object( $object ) {
                        $object = array(
                            'option'    => my_settings_handler( 'option' ),
                            'networks'  => my_settings_handler( 'networks' ),
                            'providers' => my_settings_handler( 'providers' ),
                        );

                        return $object;
                    }

                    add_filter( 'social_planner_settings_object', 'my_settings_object' );
                
            

social_planner_prepare_excerpt

The last chance to filter message excerpt before sending to social network account.

Show me an example
                
                    /**
                     * @param string $excerpt Message excerpt.
                     * @param array  $message Original message array.
                     * @param string $network Network name.
                     */
                    function my_prepare_excerpt( $excerpt, $message, $network ) {
                        if ( empty( $excerpt ) ) {
                            $excerpt = get_the_title( $message[ $post_id ] );
                        }

                        return $message;
                    }

                    add_filter( 'social_planner_prepare_excerpt', 'my_prepare_excerpt', 10, 3 );
                
            
Back to Social Planner summary