← All changes | json-endpoints/class.wpcom-json-api-sharing-buttons-endpoint.php +802 -0 16.2-beta → 16.3 View file →

		@@ -1,0 +1,802 @@
	1	+<?php // phpcs:ignore WordPress.Files.FileName.InvalidClassFileName
	2	+
	3	+// phpcs:disable Generic.Files.OneObjectStructurePerFile.MultipleFound
	4	+
	5	+if ( ! defined( 'ABSPATH' ) ) {
	6	+ exit( 0 );
	7	+}
	8	+
	9	+/**
	10	+ * Sharing button endpoint class.
	11	+ */
	12	+abstract class WPCOM_JSON_API_Sharing_Button_Endpoint extends WPCOM_JSON_API_Endpoint {
	13	+
	14	+ /**
	15	+ * All visibilties.
	16	+ *
	17	+ * @var array
	18	+ */
	19	+ public static $all_visibilities = array( 'visible', 'hidden' );
	20	+
	21	+ /**
	22	+ * Sharing service.
	23	+ *
	24	+ * @var Sharing_Service
	25	+ */
	26	+ protected $sharing_service;
	27	+
	28	+ /**
	29	+ * Setup function.
	30	+ *
	31	+ * @return null|WP_Error
	32	+ */
	33	+ protected function setup() {
	34	+ if ( class_exists( 'Sharing_Service' ) ) {
	35	+ $this->sharing_service = new Sharing_Service();
	36	+ }
	37	+
	38	+ if ( ! current_user_can( 'manage_options' ) ) {
	39	+ return new WP_Error( 'forbidden', 'You do not have the capability to manage sharing buttons for this site', 403 );
	40	+ } elseif ( ! class_exists( 'Sharing_Service' ) || ! class_exists( 'Sharing_Source' ) ||
	41	+ ( method_exists( 'Jetpack', 'is_module_active' ) && ! Jetpack::is_module_active( 'sharedaddy' ) ) ) {
	42	+ return new WP_Error( 'missing_jetpack_module', 'The Sharing module must be activated in order to use this endpoint', 400 );
	43	+ }
	44	+ }
	45	+
	46	+ /**
	47	+ * Format the sharing button.
	48	+ *
	49	+ * @param object $button - the button object.
	50	+ * @return array
	51	+ */
	52	+ public function format_sharing_button( $button ) {
	53	+ $response = array(
	54	+ 'ID' => $button->get_id(),
	55	+ 'name' => $button->get_name(),
	56	+ 'shortname' => $button->shortname,
	57	+ 'custom' => is_a( $button, 'Share_Custom' ),
	58	+ 'enabled' => $this->is_button_enabled( $button ),
	59	+ );
	60	+
	61	+ if ( $response['enabled'] ) {
	62	+ // Status is either "disabled" or the visibility value
	63	+ $response['visibility'] = $this->get_button_visibility( $button );
	64	+ }
	65	+
	66	+ if ( ! empty( $button->icon ) ) {
	67	+ // Only pre-defined sharing buttons include genericon
	68	+ $response['genericon'] = $button->icon;
	69	+ }
	70	+
	71	+ if ( method_exists( $button, 'get_options' ) ) {
	72	+ // merge get_options() values into response, primarily to account
	73	+ // for custom sharing button values
	74	+ foreach ( $button->get_options() as $key => $value ) {
	75	+ // Capitalize URL property
	76	+ if ( 'url' === strtolower( $key ) ) {
	77	+ $key = strtoupper( $key );
	78	+ }
	79	+
	80	+ $response[ $key ] = $value;
	81	+ }
	82	+ }
	83	+
	84	+ return $response;
	85	+ }
	86	+
	87	+ /**
	88	+ * Get the button visibility.
	89	+ *
	90	+ * @param object $button - the button object.
	91	+ *
	92	+ * @return string|false
	93	+ */
	94	+ public function get_button_visibility( $button ) {
	95	+ $services = $this->sharing_service->get_blog_services();
	96	+ $visibilities = self::$all_visibilities;
	97	+ $button_id = $button->get_id();
	98	+
	99	+ foreach ( $visibilities as $visibility ) {
	100	+ if ( isset( $services[ $visibility ][ $button_id ] ) ) {
	101	+ return $visibility;
	102	+ }
	103	+ }
	104	+
	105	+ return false;
	106	+ }
	107	+
	108	+ /**
	109	+ * Check if the button is enabled.
	110	+ *
	111	+ * @param object $button - the button object.
	112	+ *
	113	+ * @return bool
	114	+ */
	115	+ public function is_button_enabled( $button ) {
	116	+ return false !== $this->get_button_visibility( $button );
	117	+ }
	118	+
	119	+ /**
	120	+ * Check if button is for custom (?).
	121	+ *
	122	+ * @param array $button - the button array.
	123	+ *
	124	+ * @return bool
	125	+ */
	126	+ protected function is_button_input_for_custom( $button ) {
	127	+ return ( isset( $button['custom'] ) && $button['custom'] ) ||
	128	+ ( isset( $button['ID'] ) && 1 === preg_match( '/^custom-/', $button['ID'] ) ) ||
	129	+ ! empty( $button['name'] ) || ! empty( $button['URL'] ) || ! empty( $button['icon'] );
	130	+ }
	131	+
	132	+ /**
	133	+ * Validate the button input.
	134	+ *
	135	+ * @param array $button - the button array.
	136	+ * @param bool $is_new - if the button is new.
	137	+ *
	138	+ * @return null|WP_Error
	139	+ */
	140	+ protected function validate_button_input( $button, $is_new = false ) {
	141	+ if ( ! empty( $button['visibility'] ) && ! in_array( $button['visibility'], self::$all_visibilities, true ) ) {
	142	+ return new WP_Error( 'invalid_visibility', sprintf( 'The visibility field must be one of the following values: %s', implode( ', ', self::$all_visibilities ) ), 400 );
	143	+ } elseif ( $is_new && empty( $button['URL'] ) ) {
	144	+ return new WP_Error( 'invalid_request', 'The URL field is required', 400 );
	145	+ } elseif ( $is_new && empty( $button['icon'] ) ) {
	146	+ return new WP_Error( 'invalid_request', 'The icon field is required', 400 );
	147	+ }
	148	+ }
	149	+
	150	+ /**
	151	+ * Create a custom button.
	152	+ *
	153	+ * @param array $button - the button array.
	154	+ *
	155	+ * @return Share_Custom|false
	156	+ */
	157	+ public function create_custom_button( $button ) {
	158	+ // Default visibility to 'visible' if enabled
	159	+ if ( empty( $button['visibility'] ) && true === $button['enabled'] ) {
	160	+ $button['visibility'] = 'visible';
	161	+ }
	162	+
	163	+ $updated_service = $this->sharing_service->new_service( $button['name'], $button['URL'], $button['icon'] );
	164	+ if ( false !== $updated_service && ( true === $button['enabled'] || ! empty( $button['visibility'] ) ) ) {
	165	+ $blog_services = $this->sharing_service->get_blog_services();
	166	+ $blog_services[ $button['visibility'] ][ (string) $updated_service->get_id() ] = $updated_service;
	167	+ $this->sharing_service->set_blog_services( array_keys( $blog_services['visible'] ), array_keys( $blog_services['hidden'] ) );
	168	+ }
	169	+
	170	+ return $updated_service;
	171	+ }
	172	+
	173	+ /**
	174	+ * Update the button.
	175	+ *
	176	+ * @param int $button_id - the button id.
	177	+ * @param array $button - the button array.
	178	+ *
	179	+ * @return Share_Custom|WP_Error
	180	+ */
	181	+ public function update_button( $button_id, $button ) {
	182	+ $blog_services = $this->sharing_service->get_blog_services();
	183	+
	184	+ // Find existing button
	185	+ $all_buttons = $this->sharing_service->get_all_services_blog();
	186	+ if ( ! array_key_exists( $button_id, $all_buttons ) ) {
	187	+ // Button doesn't exist
	188	+ return new WP_Error( 'not_found', 'The specified sharing button was not found', 404 );
	189	+ }
	190	+
	191	+ $updated_service = $all_buttons[ $button_id ];
	192	+ $service_id = $updated_service->get_id();
	193	+ if ( is_a( $all_buttons[ $button_id ], 'Share_Custom' ) ) {
	194	+ // Replace options for existing custom button
	195	+ $options = $updated_service->get_options();
	196	+ $name = $button['name'] ?? $options['name'];
	197	+ $url = $button['URL'] ?? $options['url'];
	198	+ $icon = $button['icon'] ?? $options['icon'];
	199	+ $updated_service = new Share_Custom(
	200	+ $service_id,
	201	+ array(
	202	+ 'name' => $name,
	203	+ 'url' => $url,
	204	+ 'icon' => $icon,
	205	+ )
	206	+ );
	207	+ $this->sharing_service->set_service( $button_id, $updated_service );
	208	+ }
	209	+
	210	+ // Default visibility to 'visible' if enabled
	211	+ if ( empty( $button['visibility'] ) && true === $button['enabled'] ) {
	212	+ $button['visibility'] = 'visible';
	213	+ } elseif ( false === $button['enabled'] ) {
	214	+ unset( $button['visibility'] );
	215	+ }
	216	+
	217	+ // Update button visibility and enabled status
	218	+ $visibility_changed = ( isset( $button['visibility'] ) || true === $button['enabled'] ) && ! array_key_exists( $service_id, $blog_services[ $button['visibility'] ] );
	219	+ $is_disabling = false === $button['enabled'];
	220	+ if ( $visibility_changed || $is_disabling ) {
	221	+ // Remove from all other visibilities
	222	+ foreach ( $blog_services as $service_visibility => $services ) {
	223	+ if ( $is_disabling || $service_visibility !== $button['visibility'] ) {
	224	+ unset( $blog_services[ $service_visibility ][ $service_id ] );
	225	+ }
	226	+ }
	227	+
	228	+ if ( $visibility_changed ) {
	229	+ $blog_services[ $button['visibility'] ][ $service_id ] = $updated_service;
	230	+ }
	231	+
	232	+ $this->sharing_service->set_blog_services( array_keys( $blog_services['visible'] ), array_keys( $blog_services['hidden'] ) );
	233	+ }
	234	+
	235	+ return $updated_service;
	236	+ }
	237	+}
	238	+
	239	+new WPCOM_JSON_API_Get_Sharing_Buttons_Endpoint(
	240	+ array(
	241	+ 'description' => 'Get a list of a site\'s sharing buttons.',
	242	+ 'group' => 'sharing',
	243	+ 'stat' => 'sharing-buttons',
	244	+ 'method' => 'GET',
	245	+ 'path' => '/sites/%s/sharing-buttons/',
	246	+ 'path_labels' => array(
	247	+ '$site' => '(int|string) Site ID or domain',
	248	+ ),
	249	+ 'query_parameters' => array(
	250	+ 'enabled_only' => '(bool) If true, only enabled sharing buttons are included in the response',
	251	+ 'visibility' => '(string) The type of enabled sharing buttons to filter by, either "visible" or "hidden"',
	252	+ ),
	253	+ 'response_format' => array(
	254	+ 'found' => '(int) The total number of sharing buttons found that match the request.',
	255	+ 'sharing_buttons' => '(array:object) Array of sharing button objects',
	256	+ ),
	257	+ 'example_request' => 'https://public-api.wordpress.com/rest/v1/sites/30434183/sharing-buttons/',
	258	+ 'example_request_data' => array(
	259	+ 'headers' => array( 'authorization' => 'Bearer YOUR_API_TOKEN' ),
	260	+ ),
	261	+ 'example_response' => '
	262	+{
	263	+ "found": 2,
	264	+ "sharing_buttons": [
	265	+ {
	266	+ "ID": "twitter",
	267	+ "name": "Twitter",
	268	+ "shortname": "twitter",
	269	+ "custom": false,
	270	+ "enabled": true,
	271	+ "visibility": "visible",
	272	+ "genericon": "\\f202"
	273	+ },
	274	+ {
	275	+ "ID": "facebook",
	276	+ "name": "Facebook",
	277	+ "shortname": "facebook",
	278	+ "custom": false,
	279	+ "enabled": true,
	280	+ "visibility": "visible",
	281	+ "genericon": "\\f203"
	282	+ }
	283	+ ]
	284	+}',
	285	+ )
	286	+);
	287	+
	288	+/**
	289	+ * Get sharing buttons endpoint class.
	290	+ *
	291	+ * GET /sites/%s/sharing-buttons -> $blog_id
	292	+ *
	293	+ * @phan-constructor-used-for-side-effects
	294	+ */
	295	+class WPCOM_JSON_API_Get_Sharing_Buttons_Endpoint extends WPCOM_JSON_API_Sharing_Button_Endpoint {
	296	+
	297	+ /**
	298	+ * API Callback.
	299	+ *
	300	+ * @param string $path - the path.
	301	+ * @param int $blog_id - the blog ID.
	302	+ * @return array|WP_Error
	303	+ */
	304	+ public function callback( $path = '', $blog_id = 0 ) {
	305	+ $args = $this->query_args();
	306	+
	307	+ // Validate request
	308	+ $blog_id = $this->api->switch_to_blog_and_validate_user( $this->api->get_blog_id( $blog_id ) );
	309	+ if ( is_wp_error( $blog_id ) ) {
	310	+ return $blog_id;
	311	+ }
	312	+
	313	+ $continue = $this->setup();
	314	+ if ( is_wp_error( $continue ) ) {
	315	+ return $continue;
	316	+ }
	317	+
	318	+ if ( ! empty( $args['visibility'] ) && ! in_array( $args['visibility'], self::$all_visibilities, true ) ) {
	319	+ return new WP_Error( 'invalid_visibility', sprintf( 'The visibility field must be one of the following values: %s', implode( ', ', self::$all_visibilities ) ), 400 );
	320	+ }
	321	+
	322	+ // Determine which visibilities to include based on request
	323	+ $visibilities = empty( $args['visibility'] ) ? self::$all_visibilities : array( $args['visibility'] );
	324	+
	325	+ // Discover enabled services
	326	+ $buttons = array();
	327	+ $enabled_services = $this->sharing_service->get_blog_services();
	328	+ $all_services = $this->sharing_service->get_all_services_blog();
	329	+
	330	+ // Include buttons of desired visibility
	331	+ foreach ( $visibilities as $visibility ) {
	332	+ $buttons = array_merge( $buttons, $enabled_services[ $visibility ] );
	333	+ }
	334	+
	335	+ // Unless `enabled_only` or `visibility` is specified, append the
	336	+ // remaining buttons to the end of the array
	337	+ if ( ( ! isset( $args['enabled_only'] ) || ! $args['enabled_only'] ) && empty( $args['visibility'] ) ) {
	338	+ foreach ( $all_services as $id => $button ) {
	339	+ if ( ! array_key_exists( $id, $buttons ) ) {
	340	+ $buttons[ $id ] = $button;
	341	+ }
	342	+ }
	343	+ }
	344	+
	345	+ // Format each button in the response
	346	+ $response = array();
	347	+ foreach ( $buttons as $button ) {
	348	+ $response[] = $this->format_sharing_button( $button );
	349	+ }
	350	+
	351	+ return array(
	352	+ 'found' => count( $response ),
	353	+ 'sharing_buttons' => $response,
	354	+ );
	355	+ }
	356	+}
	357	+
	358	+new WPCOM_JSON_API_Get_Sharing_Button_Endpoint(
	359	+ array(
	360	+ 'description' => 'Get information about a single sharing button.',
	361	+ 'group' => '__do_not_document',
	362	+ 'stat' => 'sharing-buttons:1',
	363	+ 'method' => 'GET',
	364	+ 'path' => '/sites/%s/sharing-buttons/%s',
	365	+ 'path_labels' => array(
	366	+ '$site' => '(int|string) Site ID or domain',
	367	+ '$button_id' => '(string) The button ID',
	368	+ ),
	369	+ 'response_format' => array(
	370	+ 'ID' => '(int) Sharing button ID',
	371	+ 'name' => '(string) Sharing button name, used as a label on the button itself',
	372	+ 'shortname' => '(string) A generated short name for the sharing button',
	373	+ 'URL' => '(string) The URL pattern defined for a custom sharing button',
	374	+ 'icon' => '(string) URL to the 16x16 icon defined for a custom sharing button',
	375	+ 'genericon' => '(string) Icon character in Genericons icon set',
	376	+ 'custom' => '(bool) Is the button a user-created custom sharing button?',
	377	+ 'enabled' => '(bool) Is the button currently enabled for the site?',
	378	+ 'visibility' => '(string) If enabled, the current visibility of the sharing button, either "visible" or "hidden"',
	379	+ ),
	380	+ 'example_request' => 'https://public-api.wordpress.com/rest/v1/sites/30434183/sharing-buttons/facebook',
	381	+ 'example_request_data' => array(
	382	+ 'headers' => array( 'authorization' => 'Bearer YOUR_API_TOKEN' ),
	383	+ ),
	384	+ 'example_response' => '{
	385	+ "ID": "facebook",
	386	+ "name": "Facebook",
	387	+ "shortname": "facebook",
	388	+ "custom": false,
	389	+ "enabled": true,
	390	+ "visibility": "visible",
	391	+ "genericon": "\\f203"
	392	+}',
	393	+ )
	394	+);
	395	+
	396	+/**
	397	+ * Get sharing button endpoint class.
	398	+ *
	399	+ * GET /sites/%s/sharing-buttons/%s -> $blog_id, $button_id
	400	+ *
	401	+ * @phan-constructor-used-for-side-effects
	402	+ */
	403	+class WPCOM_JSON_API_Get_Sharing_Button_Endpoint extends WPCOM_JSON_API_Sharing_Button_Endpoint {
	404	+
	405	+ /**
	406	+ * API Callback.
	407	+ *
	408	+ * @param string $path - the path.
	409	+ * @param int $blog_id - the blog ID.
	410	+ * @param int $button_id - the button id.
	411	+ * @return array|WP_Error
	412	+ */
	413	+ public function callback( $path = '', $blog_id = 0, $button_id = 0 ) {
	414	+ // Validate request
	415	+ $blog_id = $this->api->switch_to_blog_and_validate_user( $this->api->get_blog_id( $blog_id ) );
	416	+ if ( is_wp_error( $blog_id ) ) {
	417	+ return $blog_id;
	418	+ }
	419	+
	420	+ $continue = $this->setup();
	421	+ if ( is_wp_error( $continue ) ) {
	422	+ return $continue;
	423	+ }
	424	+
	425	+ // Search existing services for button
	426	+ $all_buttons = $this->sharing_service->get_all_services_blog();
	427	+ if ( ! array_key_exists( $button_id, $all_buttons ) ) {
	428	+ return new WP_Error( 'not_found', 'The specified sharing button was not found', 404 );
	429	+ } else {
	430	+ return $this->format_sharing_button( $all_buttons[ $button_id ] );
	431	+ }
	432	+ }
	433	+}
	434	+
	435	+new WPCOM_JSON_API_Update_Sharing_Buttons_Endpoint(
	436	+ array(
	437	+ 'description' => 'Edit all sharing buttons for a site.',
	438	+ 'group' => 'sharing',
	439	+ 'stat' => 'sharing-buttons:X:POST',
	440	+ 'method' => 'POST',
	441	+ 'path' => '/sites/%s/sharing-buttons',
	442	+ 'path_labels' => array(
	443	+ '$site' => '(int|string) Site ID or domain',
	444	+ ),
	445	+ 'request_format' => array(
	446	+ 'sharing_buttons' => '(array:sharing_button) An array of sharing button objects',
	447	+ ),
	448	+ 'response_format' => array(
	449	+ 'success' => '(bool) Confirmation that all sharing buttons were updated as specified',
	450	+ 'updated' => '(array) An array of updated sharing buttons',
	451	+ ),
	452	+ 'example_request' => 'https://public-api.wordpress.com/rest/v1/sites/30434183/sharing-buttons',
	453	+ 'example_request_data' => array(
	454	+ 'headers' => array(
	455	+ 'authorization' => 'Bearer YOUR_API_TOKEN',
	456	+ ),
	457	+ 'body' => array(
	458	+ 'sharing_buttons' => array(
	459	+ array(
	460	+ 'ID' => 'facebook',
	461	+ 'visibility' => 'hidden',
	462	+ ),
	463	+ ),
	464	+ ),
	465	+ ),
	466	+ 'example_response' => '{
	467	+ "success": true,
	468	+ "updated": [
	469	+ {
	470	+ "ID": "facebook",
	471	+ "name": "Facebook",
	472	+ "shortname": "facebook",
	473	+ "custom": false,
	474	+ "enabled": true,
	475	+ "visibility": "hidden",
	476	+ "genericon": "\\f204"
	477	+ }
	478	+ ]
	479	+}',
	480	+ )
	481	+);
	482	+
	483	+/**
	484	+ * Update sharing buttons endpoint.
	485	+ *
	486	+ * POST /sites/%s/sharing-buttons -> $blog_id
	487	+ *
	488	+ * @phan-constructor-used-for-side-effects
	489	+ */
	490	+class WPCOM_JSON_API_Update_Sharing_Buttons_Endpoint extends WPCOM_JSON_API_Sharing_Button_Endpoint {
	491	+
	492	+ /**
	493	+ * API Callback.
	494	+ *
	495	+ * @param string $path - the path.
	496	+ * @param int $blog_id - the blog ID.
	497	+ *
	498	+ * @return array|WP_Error
	499	+ */
	500	+ public function callback( $path = '', $blog_id = 0 ) {
	501	+ $input = $this->input();
	502	+
	503	+ // Validate request
	504	+ $blog_id = $this->api->switch_to_blog_and_validate_user( $this->api->get_blog_id( $blog_id ) );
	505	+ if ( is_wp_error( $blog_id ) ) {
	506	+ return $blog_id;
	507	+ }
	508	+
	509	+ $continue = $this->setup();
	510	+ if ( is_wp_error( $continue ) ) {
	511	+ return $continue;
	512	+ }
	513	+
	514	+ $all_buttons = $this->sharing_service->get_all_services_blog();
	515	+
	516	+ if ( ! isset( $input['sharing_buttons'] ) ) {
	517	+ $input['sharing_buttons'] = array();
	518	+ }
	519	+
	520	+ // We do a first pass of all buttons to verify that no validation
	521	+ // issues exist before continuing to update
	522	+ foreach ( $input['sharing_buttons'] as $button ) {
	523	+ $button_exists = isset( $button['ID'] ) && array_key_exists( $button['ID'], $all_buttons );
	524	+ $is_custom = $this->is_button_input_for_custom( $button );
	525	+
	526	+ // If neither custom nor existing, bail
	527	+ if ( ! $button_exists && ! $is_custom ) {
	528	+ return new WP_Error( 'not_found', 'The specified sharing button was not found', 404 );
	529	+ }
	530	+
	531	+ // Validate input, only testing custom values if the button doesn't
	532	+ // already exist
	533	+ $validation_error = $this->validate_button_input( $button, ! $button_exists );
	534	+ if ( is_wp_error( $validation_error ) ) {
	535	+ return $validation_error;
	536	+ }
	537	+ }
	538	+
	539	+ // Reset all existing buttons
	540	+ $this->sharing_service->set_blog_services( array(), array() );
	541	+
	542	+ // Finally, we iterate over each button and update or create
	543	+ $success = true;
	544	+ $updated = array();
	545	+ foreach ( $input['sharing_buttons'] as $button ) {
	546	+ $button_exists = isset( $button['ID'] ) && array_key_exists( $button['ID'], $all_buttons );
	547	+ if ( $button_exists ) {
	548	+ $updated_service = $this->update_button( $button['ID'], $button );
	549	+ } else {
	550	+ $updated_service = $this->create_custom_button( $button );
	551	+ }
	552	+
	553	+ // We'll allow the request to continue if a failure occurred, but
	554	+ // log it for the response
	555	+ if ( false === $updated_service ) {
	556	+ $success = false;
	557	+ } else {
	558	+ $updated[] = $this->format_sharing_button( $updated_service );
	559	+ }
	560	+ }
	561	+
	562	+ return array(
	563	+ 'success' => $success,
	564	+ 'updated' => $updated,
	565	+ );
	566	+ }
	567	+}
	568	+
	569	+new WPCOM_JSON_API_Update_Sharing_Button_Endpoint(
	570	+ array(
	571	+ 'description' => 'Create a new custom sharing button.',
	572	+ 'group' => '__do_not_document',
	573	+ 'stat' => 'sharing-buttons:new',
	574	+ 'method' => 'POST',
	575	+ 'path' => '/sites/%s/sharing-buttons/new',
	576	+ 'path_labels' => array(
	577	+ '$site' => '(int|string) Site ID or domain',
	578	+ ),
	579	+ 'request_format' => array(
	580	+ 'name' => '(string) The name for your custom sharing button, used as a label on the button itself',
	581	+ 'URL' => '(string) The URL to use for share links, including optional placeholders (%post_id%, %post_title%, %post_slug%, %post_url%, %post_full_url%, %post_excerpt%, %post_tags%, %home_url%)',
	582	+ 'icon' => '(string) The full URL to a 16x16 icon to display on the sharing button',
	583	+ 'enabled' => '(bool) Is the button currently enabled for the site?',
	584	+ 'visibility' => '(string) If enabled, the visibility of the sharing button, either "visible" (default) or "hidden"',
	585	+ ),
	586	+ 'response_format' => array(
	587	+ 'ID' => '(string) Sharing button ID',
	588	+ 'name' => '(string) Sharing button name, used as a label on the button itself',
	589	+ 'shortname' => '(string) A generated short name for the sharing button',
	590	+ 'URL' => '(string) The URL pattern defined for a custom sharing button',
	591	+ 'icon' => '(string) URL to the 16x16 icon defined for a custom sharing button',
	592	+ 'genericon' => '(string) Icon character in Genericons icon set',
	593	+ 'custom' => '(bool) Is the button a user-created custom sharing button?',
	594	+ 'enabled' => '(bool) Is the button currently enabled for the site?',
	595	+ 'visibility' => '(string) If enabled, the current visibility of the sharing button, either "visible" or "hidden"',
	596	+ ),
	597	+ 'example_request' => 'https://public-api.wordpress.com/rest/v1/sites/30434183/sharing-buttons/new/',
	598	+ 'example_request_data' => array(
	599	+ 'headers' => array(
	600	+ 'authorization' => 'Bearer YOUR_API_TOKEN',
	601	+ ),
	602	+ 'body' => array(
	603	+ 'name' => 'Custom',
	604	+ 'URL' => 'https://www.wordpress.com/%post_name%',
	605	+ 'icon' => 'https://en.wordpress.com/i/stats-icon.gif',
	606	+ 'enabled' => true,
	607	+ 'visibility' => 'visible',
	608	+ ),
	609	+ ),
	610	+ 'example_response' => '{
	611	+ "ID": "custom-123456789",
	612	+ "name": "Custom",
	613	+ "shortname": "custom",
	614	+ "url": "https://www.wordpress.com/%post_name%",
	615	+ "icon": "https://en.wordpress.com/i/stats-icon.gif",
	616	+ "custom": true,
	617	+ "enabled": true,
	618	+ "visibility": "visible"
	619	+}',
	620	+ )
	621	+);
	622	+
	623	+new WPCOM_JSON_API_Update_Sharing_Button_Endpoint(
	624	+ array(
	625	+ 'description' => 'Edit a sharing button.',
	626	+ 'group' => '__do_not_document',
	627	+ 'stat' => 'sharing-buttons:1:POST',
	628	+ 'method' => 'POST',
	629	+ 'path' => '/sites/%s/sharing-buttons/%s',
	630	+ 'path_labels' => array(
	631	+ '$site' => '(int|string) Site ID or domain',
	632	+ '$button_id' => '(string) The button ID',
	633	+ ),
	634	+ 'request_format' => array(
	635	+ 'name' => '(string) Only if a custom sharing button, a new name used as a label on the button itself',
	636	+ 'URL' => '(string) Only if a custom sharing button, the URL to use for share links, including optional placeholders (%post_title%, %post_url%, %post_full_url%, %post_excerpt%, %post_tags%)',
	637	+ 'icon' => '(string) Only if a custom sharing button, the full URL to a 16x16 icon to display on the sharing button',
	638	+ 'enabled' => '(bool) Is the button currently enabled for the site?',
	639	+ 'visibility' => '(string) If enabled, the visibility of the sharing button, either "visible" (default) or "hidden"',
	640	+ ),
	641	+ 'response_format' => array(
	642	+ 'ID' => '(string) Sharing button ID',
	643	+ 'name' => '(string) Sharing button name, used as a label on the button itself',
	644	+ 'shortname' => '(string) A generated short name for the sharing button',
	645	+ 'URL' => '(string) The URL pattern defined for a custom sharing button',
	646	+ 'icon' => '(string) URL to the 16x16 icon defined for a custom sharing button',
	647	+ 'genericon' => '(string) Icon character in Genericons icon set',
	648	+ 'custom' => '(bool) Is the button a user-created custom sharing button?',
	649	+ 'enabled' => '(bool) Is the button currently enabled for the site?',
	650	+ 'visibility' => '(string) If enabled, the current visibility of the sharing button, either "visible" or "hidden"',
	651	+ ),
	652	+ 'example_request' => 'https://public-api.wordpress.com/rest/v1/sites/30434183/sharing-buttons/custom-123456789/',
	653	+ 'example_request_data' => array(
	654	+ 'headers' => array(
	655	+ 'authorization' => 'Bearer YOUR_API_TOKEN',
	656	+ ),
	657	+ 'body' => array(
	658	+ 'enabled' => false,
	659	+ ),
	660	+ ),
	661	+ 'example_response' => '{
	662	+ "ID": "custom-123456789",
	663	+ "name": "Custom",
	664	+ "shortname": "custom",
	665	+ "custom": true,
	666	+ "enabled": false,
	667	+ "icon": "https://en.wordpress.com/i/stats-icon.gif",
	668	+ "url": "https://www.wordpress.com/%post_name%"
	669	+}',
	670	+ )
	671	+);
	672	+
	673	+/**
	674	+ * Sharing button endpoint class.
	675	+ *
	676	+ * POST /sites/%s/sharing-buttons/new -> $blog_id
	677	+ * POST /sites/%s/sharing-buttons/%s -> $blog_id, $button_id
	678	+ *
	679	+ * @phan-constructor-used-for-side-effects
	680	+ */
	681	+class WPCOM_JSON_API_Update_Sharing_Button_Endpoint extends WPCOM_JSON_API_Sharing_Button_Endpoint {
	682	+
	683	+ /**
	684	+ * API Callback.
	685	+ *
	686	+ * @param string $path - the path.
	687	+ * @param int $blog_id - the blog ID.
	688	+ * @param int $button_id - the button ID.
	689	+ *
	690	+ * @return array|WP_Error
	691	+ */
	692	+ public function callback( $path = '', $blog_id = 0, $button_id = 0 ) {
	693	+ $new = $this->api->ends_with( $path, '/new' );
	694	+ $input = $this->input();
	695	+
	696	+ // Validate request
	697	+ $blog_id = $this->api->switch_to_blog_and_validate_user( $this->api->get_blog_id( $blog_id ) );
	698	+ if ( is_wp_error( $blog_id ) ) {
	699	+ return $blog_id;
	700	+ }
	701	+
	702	+ $continue = $this->setup();
	703	+ if ( is_wp_error( $continue ) ) {
	704	+ return $continue;
	705	+ }
	706	+
	707	+ $validation_error = $this->validate_button_input( $input, $new );
	708	+ if ( is_wp_error( $validation_error ) ) {
	709	+ return $validation_error;
	710	+ }
	711	+
	712	+ // Update or create button
	713	+ if ( $new ) {
	714	+ $updated_service = $this->create_custom_button( $input );
	715	+ } else {
	716	+ $updated_service = $this->update_button( $button_id, $input );
	717	+ }
	718	+
	719	+ if ( false === $updated_service ) {
	720	+ return new WP_Error( 'invalid_request', sprintf( 'The sharing button was not %s', $new ? 'created' : 'updated' ), 400 );
	721	+ } elseif ( is_wp_error( $updated_service ) ) {
	722	+ return $updated_service;
	723	+ } else {
	724	+ return $this->format_sharing_button( $updated_service );
	725	+ }
	726	+ }
	727	+}
	728	+
	729	+new WPCOM_JSON_API_Delete_Sharing_Button_Endpoint(
	730	+ array(
	731	+ 'description' => 'Delete a custom sharing button.',
	732	+ 'group' => '__do_not_document',
	733	+ 'stat' => 'sharing-buttons:1:delete',
	734	+ 'method' => 'POST',
	735	+ 'path' => '/sites/%s/sharing-buttons/%s/delete',
	736	+ 'path_labels' => array(
	737	+ '$site' => '(int|string) Site ID or domain',
	738	+ '$button_id' => '(string) The button ID',
	739	+ ),
	740	+ 'response_format' => array(
	741	+ 'ID' => '(int) The ID of the deleted sharing button',
	742	+ 'success' => '(bool) Confirmation that the sharing button has been removed',
	743	+ ),
	744	+ 'example_request' => 'https://public-api.wordpress.com/rest/v1/sites/30434183/sharing-buttons/custom-123456789/delete',
	745	+ 'example_request_data' => array(
	746	+ 'headers' => array( 'authorization' => 'Bearer YOUR_API_TOKEN' ),
	747	+ ),
	748	+ 'example_response' => '{
	749	+ "ID": "custom-123456789",
	750	+ "success": "true"
	751	+}',
	752	+ )
	753	+);
	754	+
	755	+/**
	756	+ * Delete sharing button endpoint class.
	757	+ *
	758	+ * POST /sites/%s/sharing-buttons/%s/delete -> $blog_id, $button_id
	759	+ *
	760	+ * @phan-constructor-used-for-side-effects
	761	+ */
	762	+class WPCOM_JSON_API_Delete_Sharing_Button_Endpoint extends WPCOM_JSON_API_Sharing_Button_Endpoint {
	763	+ /**
	764	+ * API Callback.
	765	+ *
	766	+ * @param string $path - the path.
	767	+ * @param int $blog_id - the blog ID.
	768	+ * @param int $button_id - the button ID.
	769	+ *
	770	+ * @return array|WP_Error
	771	+ */
	772	+ public function callback( $path = '', $blog_id = 0, $button_id = 0 ) {
	773	+ // Validate request
	774	+ $blog_id = $this->api->switch_to_blog_and_validate_user( $this->api->get_blog_id( $blog_id ) );
	775	+ if ( is_wp_error( $blog_id ) ) {
	776	+ return $blog_id;
	777	+ }
	778	+
	779	+ $continue = $this->setup();
	780	+ if ( is_wp_error( $continue ) ) {
	781	+ return $continue;
	782	+ }
	783	+
	784	+ // Find existing button
	785	+ $all_buttons = $this->sharing_service->get_all_services_blog();
	786	+ if ( ! array_key_exists( $button_id, $all_buttons ) ) {
	787	+ // Button doesn't exist
	788	+ return new WP_Error( 'not_found', 'The specified sharing button was not found', 404 );
	789	+ }
	790	+
	791	+ // Verify button is custom
	792	+ if ( ! is_a( $all_buttons[ $button_id ], 'Share_Custom' ) ) {
	793	+ return new WP_Error( 'invalid_request', 'Only custom sharing buttons can be deleted', 400 );
	794	+ }
	795	+
	796	+ $success = $this->sharing_service->delete_service( $button_id );
	797	+ return array(
	798	+ 'ID' => $button_id,
	799	+ 'success' => $success,
	800	+ );
	801	+ }
	802	+}