wp-parsely / src / Metadata / class-metadata-builder.php

class-metadata-builder.php in Parse.ly 3.20.0, at src/Metadata/class-metadata-builder.php

691 lines 21.2 KB

Raw Download Zip

1	<?php
2	/**
3	* Front Page Metadata Builder class
4	*
5	* @package Parsely
6	* @since 3.4.0
7	*/
8
9	declare(strict_types=1);
10
11	namespace Parsely\Metadata;
12
13	use Parsely\Parsely;
14	use Parsely\Utils\Utils;
15	use WP_Post;
16	use WP_User;
17
18	/**
19	* Abstract class that implements modular builders for Metadata.
20	*
21	* It should be extended in subclasses that implement a particular page view to render
22	* metadata for. Specifically, the `get_metadata()` method should be implemented.
23	*
24	* @since 1.0.0
25	* @since 3.3.0 Logic extracted from Parsely\Parsely class to separate file/class.
26	*
27	* @phpstan-import-type Parsely_Options from Parsely
28	*/
29	abstract class Metadata_Builder {
30	/**
31	* Instance of Parsely class.
32	*
33	* @var Parsely
34	*/
35	protected $parsely;
36
37	/**
38	* Array holding the metadata keys and values.
39	*
40	* @var array<string, mixed>
41	*/
42	protected $metadata = array();
43
44	/**
45	* Constructor.
46	*
47	* @param Parsely $parsely Instance of Parsely class.
48	*/
49	public function __construct( Parsely $parsely ) {
50	$this->parsely = $parsely;
51	}
52
53	/**
54	* Generates the metadata object by calling the build_* methods and
55	* returns the value.
56	*
57	* @since 3.4.0
58	*
59	* @return array<string, mixed>
60	*/
61	abstract public function get_metadata(): array;
62
63	/**
64	* Builds basic metadata present in all pages.
65	*
66	* @since 3.4.0
67	*/
68	protected function build_basic(): void {
69	$this->metadata['@context'] = 'https://schema.org';
70	$this->metadata['@type'] = 'WebPage';
71	}
72
73	/**
74	* Populates the url field in the metadata object.
75	*
76	* @since 3.4.0
77	*/
78	protected function build_url(): void {
79	$this->metadata['url'] = $this->get_current_url();
80	}
81
82	/**
83	* Populates the @type field in the metadata object.
84	*
85	* @param WP_Post $post The post/page for which to populate the field.
86	* @param string $parsely_type Parse.ly post type. Can be 'post' or 'non-post'.
87	*
88	* @since 3.4.0
89	* @since 3.14.0 Moved from `Post_Builder` to `Metadata_Builder`.
90	*/
91	protected function build_type( WP_Post $post, string $parsely_type ): void {
92	$default_type = 'post' === $parsely_type ? 'NewsArticle' : 'WebPage';
93
94	/**
95	* Filters the JSON-LD @type.
96	*
97	* @since 2.5.0
98	*
99	* @param string $jsonld_type JSON-LD @type value, default is NewsArticle.
100	* @param int $id Post ID.
101	* @param string $post_type The Post type in WordPress.
102	*/
103	$type = apply_filters( 'wp_parsely_post_type', $default_type, $post->ID, $post->post_type );
104	$supported_types = $this->parsely->get_all_supported_types();
105
106	// Validate type before passing it further as an invalid type will not be recognized by Parse.ly.
107	if ( ! in_array( $type, $supported_types, true ) ) {
108	$error = sprintf(
109	/* translators: 1: JSON @type like NewsArticle, 2: URL */
110	__( '@type %1$s is not supported by Parse.ly. Please use a type mentioned in %2$s', 'wp-parsely' ),
111	$type,
112	'https://docs.parse.ly/metadata-jsonld/#distinguishing-between-posts-and-non-posts-pages'
113	);
114	// phpcs:ignore WordPress.PHP.DevelopmentFunctions.error_log_trigger_error
115	trigger_error( esc_html( $error ), E_USER_WARNING );
116	$type = $default_type;
117	}
118
119	$this->metadata['@type'] = $type;
120	}
121
122	/**
123	* Populates the mainEntityOfPage field in the metadata object.
124	*
125	* @param string $build_url_type Parse.ly post type to use for building the
126	* URL. Can be 'post' or 'non-post'.
127	*
128	* @since 3.4.0
129	* @since 3.14.0 Moved from `Post_Builder` to `Metadata_Builder`.
130	*/
131	protected function build_main_entity( string $build_url_type ): void {
132	$this->metadata['mainEntityOfPage'] = array(
133	'@type' => 'WebPage',
134	'@id' => $this->get_current_url( $build_url_type ),
135	);
136	}
137
138	/**
139	* Populates the author and creator fields in the metadata object.
140	*
141	* @since 3.4.0
142	* @since 3.14.0 Moved from `Post_Builder` to `Metadata_Builder`.
143	*
144	* @param WP_Post $post The post/page for which to populate the fields.
145	*/
146	protected function build_author( WP_Post $post ): void {
147	$authors = $this->get_author_names( $post );
148	$author_objects = array();
149	foreach ( $authors as $author ) {
150	$author_tag = array(
151	'@type' => 'Person',
152	'name' => $author,
153	);
154	$author_objects[] = $author_tag;
155	}
156	$this->metadata['author'] = $author_objects;
157	$this->metadata['creator'] = $authors;
158	}
159
160	/**
161	* Populates the publisher field in the metadata object.
162	*
163	* @since 3.4.0
164	* @since 3.14.0 Moved from `Post_Builder` to `Metadata_Builder`.
165	*/
166	protected function build_publisher(): void {
167	$this->metadata['publisher'] = array(
168	'@type' => 'Organization',
169	'name' => get_bloginfo( 'name' ),
170	'logo' => $this->parsely->get_options()['logo'],
171	);
172	}
173
174	/**
175	* Populates all the fields related to time in the metadata object.
176	*
177	* @param WP_Post $post The post/page for which to populate the field.
178	*
179	* @since 3.0.2
180	* @since 3.3.0 Moved to class-metadata.
181	* @since 3.14.0 Moved from `Post_Builder` to `Metadata_Builder`.
182	*/
183	protected function build_metadata_post_times( WP_Post $post ): void {
184	$date_format = 'Y-m-d\TH:i:s\Z';
185	$post_created_gmt = get_post_time( $date_format, true, $post );
186
187	if ( false === $post_created_gmt ) {
188	return;
189	}
190
191	$this->metadata['dateCreated'] = $post_created_gmt;
192	$this->metadata['datePublished'] = $post_created_gmt;
193	$this->metadata['dateModified'] = $post_created_gmt;
194
195	$post_modified_gmt = get_post_modified_time( $date_format, true, $post );
196
197	if ( false !== $post_modified_gmt && $post_modified_gmt > $post_created_gmt ) {
198	$this->metadata['dateModified'] = $post_modified_gmt;
199	}
200	}
201
202	/**
203	* Populates the articleSection field in the metadata object.
204	*
205	* @since 3.4.0
206	* @since 3.14.0 Moved from `Post_Builder` to `Metadata_Builder`.
207	*
208	* @param WP_Post $post The post/page for which to populate the field.
209	*/
210	protected function build_article_section( WP_Post $post ): void {
211	$this->metadata['articleSection'] = $this->get_category_name( $post, $this->parsely->get_options() );
212	}
213
214	/**
215	* Populates the keywords field in the metadata object.
216	*
217	* @since 3.4.0
218	* @since 3.14.0 Moved from `Post_Builder` to `Metadata_Builder`.
219	*
220	* @param WP_Post $post The post/page for which to populate the field.
221	*/
222	protected function build_keywords( WP_Post $post ): void {
223	$options = $this->parsely->get_options();
224	$tags = $this->get_tags( $post->ID );
225	if ( $options['cats_as_tags'] ) {
226	$tags = array_merge( $tags, $this->get_categories( $post->ID ) );
227	// add custom taxonomy values.
228	$tags = array_merge( $tags, $this->get_custom_taxonomy_values( $post ) );
229	}
230	// The function 'mb_strtolower' is not enabled by default in php, so this check
231	// falls back to the native php function 'strtolower' if necessary.
232	if ( function_exists( 'mb_strtolower' ) ) {
233	$lowercase_callback = 'mb_strtolower';
234	} else {
235	$lowercase_callback = 'strtolower';
236	}
237	if ( $options['lowercase_tags'] ) {
238	$tags = array_map( $lowercase_callback, $tags );
239	}
240
241	/**
242	* Filters the post tags that are used as metadata keywords.
243	*
244	* @since 1.8.0
245	*
246	* @param array<string> $tags Post tags.
247	* @param int $ID Post ID.
248	*/
249	$tags = apply_filters( 'wp_parsely_post_tags', $tags, $post->ID );
250	$tags = array_map( array( $this, 'clean_value' ), $tags );
251
252	$this->metadata['keywords'] = array_values( array_unique( $tags ) );
253	}
254
255	/**
256	* Populates the thumbnailUrl field in the metadata object.
257	*
258	* @param WP_Post $post The post/page for which to populate the field.
259	*
260	* @since 3.4.0
261	* @since 3.14.0 Moved from `Post_Builder` to `Metadata_Builder`.
262	*/
263	protected function build_thumbnail_url( WP_Post $post ): void {
264	$thumb_url = get_the_post_thumbnail_url( $post, 'thumbnail' );
265	if ( ! is_string( $thumb_url ) ) {
266	$thumb_url = '';
267	}
268	$this->metadata['thumbnailUrl'] = $thumb_url;
269	}
270
271	/**
272	* Populates the image field in the metadata object.
273	*
274	* @param WP_Post $post The post/page for which to populate the field.
275	*
276	* @since 3.4.0
277	* @since 3.14.0 Moved from `Post_Builder` to `Metadata_Builder`.
278	*/
279	protected function build_image( WP_Post $post ): void {
280	$image_url = get_the_post_thumbnail_url( $post, 'full' );
281	if ( ! is_string( $image_url ) ) {
282	$image_url = '';
283	}
284	$this->metadata['image'] = array(
285	'@type' => 'ImageObject',
286	'url' => $image_url,
287	);
288	}
289
290	/**
291	* Sanitizes string content.
292	*
293	* @since 2.6.0
294	* @since 3.4.0 Moved to class-metadata-builder.
295	*
296	* @param string\|null $val The content you'd like sanitized.
297	* @return string
298	*/
299	protected function clean_value( ?string $val ): string {
300	if ( null === $val ) {
301	return '';
302	}
303
304	return trim( wp_strip_all_tags( str_replace( array( "\n", "\r" ), '', $val ) ) );
305	}
306
307	/**
308	* Gets the URL of the current PHP script.
309	*
310	* A fall-back implementation to determine permalink.
311	*
312	* @since 3.0.0 $parsely_type Default parameter changed to `non-post`.
313	* @since 3.4.0 Moved to class-metadata-builder.
314	*
315	* @param string $parsely_type Optional. Parse.ly post type you're interested in, either 'post'
316	* or 'non-post'. Default is 'non-post'.
317	* @param int $post_id Optional. ID of the post you want to get the URL for. Default is
318	* 0, which means the global `$post` is used.
319	* @return string
320	*/
321	protected function get_current_url( string $parsely_type = 'non-post', int $post_id = 0 ): string {
322	if ( 'post' === $parsely_type ) {
323	$permalink = (string) get_permalink( $post_id );
324
325	/**
326	* Filters the permalink for a post.
327	*
328	* @since 1.14.0
329	* @since 2.5.0 Added $post_id.
330	*
331	* @param string $permalink The permalink URL or false if post does not exist.
332	* @param string $parsely_type Parse.ly type ("post" or "non-post").
333	* @param int $post_id ID of the post you want to get the URL for. May be 0, so
334	* $permalink will be for the global $post.
335	*/
336	$url = apply_filters( 'wp_parsely_permalink', $permalink, $parsely_type, $post_id );
337	} else {
338	$request_uri = isset( $_SERVER['REQUEST_URI'] )
339	? sanitize_text_field( wp_unslash( $_SERVER['REQUEST_URI'] ) )
340	: '';
341
342	$url = home_url( $request_uri );
343	}
344
345	$options = $this->parsely->get_options();
346	return $options['force_https_canonicals']
347	? str_replace( 'http://', 'https://', $url )
348	: str_replace( 'https://', 'http://', $url );
349	}
350
351	/**
352	* Returns a properly cleaned category/taxonomy value and will optionally
353	* use the top-level category/taxonomy value, if so instructed via the
354	* use_top_level_cats option.
355	*
356	* @since 3.3.0 Moved to class-metadata.
357	* @since 3.14.0 Moved from `Post_Builder` to `Metadata_Builder`.
358	*
359	* @param WP_Post $post_obj The object for the post.
360	* @param Parsely_Options $parsely_options The parsely options.
361	* @return string Cleaned category name for the post in question.
362	*/
363	private function get_category_name( WP_Post $post_obj, $parsely_options ): string {
364	$taxonomy_dropdown_choice = get_the_terms( $post_obj->ID, $parsely_options['custom_taxonomy_section'] );
365	// Get top-level taxonomy name for chosen taxonomy and assign to $parent_name; it will be used
366	// as the category value if 'use_top_level_cats' option is checked.
367	// Assign as the default category name if no value is checked for the chosen taxonomy.
368	$category_name = get_cat_name( Utils::get_default_category() );
369	if ( false !== $taxonomy_dropdown_choice && ! is_wp_error( $taxonomy_dropdown_choice ) ) {
370	if ( $parsely_options['use_top_level_cats'] ) {
371	$first_term = array_shift( $taxonomy_dropdown_choice );
372	if ( null !== $first_term ) {
373	$term_name = $this->get_top_level_term( $first_term->term_id, $first_term->taxonomy );
374	}
375	} else {
376	$term_name = $this->get_bottom_level_term( $post_obj->ID, $parsely_options['custom_taxonomy_section'] );
377	}
378
379	if ( isset( $term_name ) && is_string( $term_name ) && 0 < strlen( $term_name ) ) {
380	$category_name = $term_name;
381	}
382	}
383
384	/**
385	* Filters the constructed category name.
386	*
387	* @since 1.8.0
388	*
389	* @param string $category Category name.
390	* @param WP_Post $post_obj Post object.
391	* @param array<string, mixed> $parsely_options The Parsely options.
392	*/
393	$category_name = apply_filters( 'wp_parsely_post_category', $category_name, $post_obj, $parsely_options );
394
395	return $this->clean_value( $category_name );
396	}
397
398	/**
399	* Returns the top-most category/taxonomy value in a hierarchy given a
400	* taxonomy value's ID.
401	*
402	* (WordPress calls taxonomy values 'terms').
403	*
404	* @since 3.3.0 Moved to class-metadata.
405	* @since 3.14.0 Moved from `Post_Builder` to `Metadata_Builder`.
406	*
407	* @param int $term_id The ID of the top level term.
408	* @param string $taxonomy_name The name of the taxonomy.
409	* @return string\|false $parent The top level name of the category/taxonomy.
410	*/
411	private function get_top_level_term( int $term_id, string $taxonomy_name ) {
412	$parent = get_term_by( 'id', $term_id, $taxonomy_name );
413
414	while ( false !== $parent && 0 !== $parent->parent ) {
415	$parent = get_term_by( 'id', $parent->parent, $taxonomy_name );
416	}
417
418	return $parent->name ?? false;
419	}
420
421	/**
422	* Returns the bottom-most category/taxonomy value in a hierarchy given a
423	* post ID.
424	*
425	* (WordPress calls taxonomy values 'terms').
426	*
427	* @since 3.3.0 Moved to class-metadata.
428	* @since 3.14.0 Moved from `Post_Builder` to `Metadata_Builder`.
429	*
430	* @param int $post_id The post id you're interested in.
431	* @param string $taxonomy_name The name of the taxonomy.
432	* @return string Name of the custom taxonomy.
433	*/
434	private function get_bottom_level_term( int $post_id, string $taxonomy_name ): string {
435	$terms = get_the_terms( $post_id, $taxonomy_name );
436
437	if ( ! is_array( $terms ) ) {
438	return '';
439	}
440
441	$term_ids = wp_list_pluck( $terms, 'term_id' );
442	$parents = array_filter( wp_list_pluck( $terms, 'parent' ) );
443
444	// Get array of IDs of terms which are not parents.
445	$term_ids_not_parents = array_diff( $term_ids, $parents );
446	// Get corresponding term objects, which are mapped to array index keys.
447	$terms_not_parents = array_intersect_key( $terms, $term_ids_not_parents );
448	// remove array index keys.
449	$terms_not_parents_cleaned = array_values( $terms_not_parents );
450
451	if ( isset( $terms_not_parents_cleaned[0] ) ) {
452	// If you assign multiple child terms in a custom taxonomy, will only return the first.
453	return $terms_not_parents_cleaned[0]->name;
454	}
455
456	return '';
457	}
458
459	/**
460	* Retrieves all the authors for a post as an array. Can include multiple
461	* authors if the Co-Authors Plus plugin is in use.
462	*
463	* @since 3.3.0 Moved to class-metadata.
464	* @since 3.14.0 Moved from `Post_Builder` to `Metadata_Builder`.
465	*
466	* @param WP_Post $post The post object.
467	* @return array<string>
468	*/
469	private function get_author_names( WP_Post $post ): array {
470	$authors = $this->get_coauthor_names( $post->ID );
471	if ( 0 === count( $authors ) ) {
472	$post_author = get_user_by( 'id', $post->post_author );
473	if ( false !== $post_author ) {
474	$authors = array( $post_author );
475	}
476	}
477
478	/**
479	* Filters the list of author WP_User objects for a post.
480	*
481	* @since 1.14.0
482	*
483	* @param array<WP_User> $authors One or more authors as WP_User objects.
484	* @param WP_Post $post Post object.
485	*/
486	$authors = apply_filters( 'wp_parsely_pre_authors', $authors, $post );
487
488	// Getting the author name for each author.
489	$authors = array_map( array( $this, 'get_author_name' ), $authors );
490
491	/**
492	* Filters the list of author names for a post.
493	*
494	* @since 1.14.0
495	*
496	* @param array<string> $authors One or more author names.
497	* @param WP_Post $post Post object.
498	*/
499	$authors = apply_filters( 'wp_parsely_post_authors', $authors, $post );
500
501	return array_map( array( $this, 'clean_value' ), $authors );
502	}
503
504	/**
505	* Returns a list of coauthors for a post assuming the Co-Authors Plus plugin
506	* is installed.
507	*
508	* Borrowed from
509	* https://github.com/Automattic/Co-Authors-Plus/blob/master/template-tags.php#L3-35
510	*
511	* @since 3.3.0 Moved to class-metadata.
512	* @since 3.14.0 Moved from `Post_Builder` to `Metadata_Builder`.
513	*
514	* @param int $post_id The ID of the post.
515	* @return array<WP_User> List of coauthors, or an empty array if the Co-Authors Plus plugin is not active.
516	*/
517	private function get_coauthor_names( int $post_id ): array {
518	$coauthors = array();
519	if ( class_exists( 'coauthors_plus' ) ) {
520	global $post, $post_ID, $coauthors_plus;
521
522	if ( $post_id <= 0 && $post_ID ) {
523	$post_id = $post_ID;
524	}
525
526	if ( ! $post_id && $post ) {
527	$post_id = $post->ID;
528	}
529
530	if ( $post_id ) {
531	$coauthor_terms = get_the_terms( $post_id, $coauthors_plus->coauthor_taxonomy );
532
533	if ( is_array( $coauthor_terms ) ) {
534	foreach ( $coauthor_terms as $coauthor ) {
535	$coauthor_slug = preg_replace( '#^cap-#', '', $coauthor->slug );
536	$post_author = $coauthors_plus->get_coauthor_by( 'user_nicename', $coauthor_slug );
537	// In case the user has been deleted while plugin was deactivated.
538	if ( false !== $post_author ) {
539	$coauthors[] = new WP_User( $post_author );
540	}
541	}
542	} elseif ( ! $coauthors_plus->force_guest_authors ) {
543	if ( $post && $post_id === $post->ID ) {
544	$post_author = get_userdata( $post->post_author );
545	}
546	if ( isset( $post_author ) && false !== $post_author ) {
547	$coauthors[] = $post_author;
548	}
549	}
550	// The empty else case is because if we force guest authors, we don't ever care what value wp_posts.post_author has.
551	}
552	}
553	return $coauthors;
554	}
555
556	/**
557	* Determines author name from display name, falling back to firstname
558	* lastname, then nickname and finally the nicename.
559	*
560	* @since 3.3.0 Moved to class-metadata.
561	* @since 3.14.0 Moved from `Post_Builder` to `Metadata_Builder`.
562	*
563	* @param ?WP_User $author The author of the post.
564	* @return string An author name.
565	*/
566	private function get_author_name( ?WP_User $author ): string {
567	// Gracefully handle situation where no author is available.
568	if ( null === $author ) {
569	return '';
570	}
571
572	if ( '' !== $author->display_name ) {
573	return $author->display_name;
574	}
575
576	$author_name = $author->user_firstname . ' ' . $author->user_lastname;
577	if ( ' ' !== $author_name ) {
578	return $author_name;
579	}
580
581	if ( '' !== $author->nickname ) {
582	return $author->nickname;
583	}
584
585	if ( '' !== $author->user_nicename ) {
586	return $author->user_nicename;
587	}
588
589	return '';
590	}
591
592	/**
593	* Returns the tags associated with this page or post.
594	*
595	* @since 3.3.0 Moved to class-metadata.
596	* @since 3.14.0 Moved from `Post_Builder` to `Metadata_Builder`.
597	*
598	* @param int $post_id The ID of the post you're trying to get tags for.
599	* @return array<string> The tags of the post represented by the post id.
600	*/
601	private function get_tags( int $post_id ): array {
602	/**
603	* Variable.
604	*
605	* @var array<\WP_Term\|null>\|\WP_Error
606	*/
607	$post_tags = wp_get_post_tags( $post_id );
608	$tags = array();
609
610	if ( ! is_wp_error( $post_tags ) ) {
611	foreach ( $post_tags as $wp_tag ) {
612	if ( null !== $wp_tag ) {
613	$tags[] = $wp_tag->name;
614	}
615	}
616	}
617
618	return $tags;
619	}
620
621	/**
622	* Returns an array of all the child categories for the current post.
623	*
624	* @since 3.3.0 Moved to class-metadata.
625	* @since 3.14.0 Moved from `Post_Builder` to `Metadata_Builder`.
626	*
627	* @param int $post_id The ID of the post you're trying to get categories for.
628	* @param string $delimiter What character will delimit the categories.
629	* @return array<string> All the child categories of the current post.
630	*/
631	private function get_categories( int $post_id, string $delimiter = '/' ): array {
632	$tags = array();
633	foreach ( get_the_category( $post_id ) as $category ) {
634	$hierarchy = get_category_parents( $category->term_id, false, $delimiter );
635	if ( ! is_wp_error( $hierarchy ) ) {
636	$tags[] = rtrim( $hierarchy, '/' );
637	}
638	}
639	// Take last element in the hierarchy, a string representing the full
640	// parent->child tree, and split it into individual category names.
641	$last_tag = end( $tags );
642	if ( false !== $last_tag ) {
643	$tags = explode( '/', $last_tag );
644	}
645
646	// Remove default category name from tags if needed.
647	$default_category_name = get_cat_name( Utils::get_default_category() );
648	return array_diff( $tags, array( $default_category_name ) );
649	}
650
651	/**
652	* Gets all term names from all custom taxonomies assigned to a post.
653	*
654	* @since 3.3.0 Moved to class-metadata.
655	* @since 3.4.0 Moved to class-post-builder.
656	* @since 3.14.0 Moved from `Post_Builder` to `Metadata_Builder`.
657	*
658	* @param WP_Post $post_obj The post object to find the terms for.
659	* @return array<string> Term names.
660	*/
661	private function get_custom_taxonomy_values( WP_Post $post_obj ): array {
662	// Filter out default WordPress taxonomies.
663	$all_taxonomies = array_diff(
664	get_taxonomies(),
665	array( 'post_tag', 'nav_menu', 'author', 'link_category', 'post_format' )
666	);
667
668	/**
669	* Filters the taxonomies.
670	*
671	* @since 3.11.0
672	*
673	* @param array<string> $all_taxonomies Taxonomies.
674	* @param WP_Post $post_obj Post object.
675	*/
676	$all_taxonomies = apply_filters( 'wp_parsely_custom_taxonomies', $all_taxonomies, $post_obj );
677	$all_values = array();
678
679	foreach ( $all_taxonomies as $taxonomy ) {
680	$custom_taxonomy_objects = get_the_terms( $post_obj->ID, $taxonomy );
681	if ( is_array( $custom_taxonomy_objects ) ) {
682	foreach ( $custom_taxonomy_objects as $custom_taxonomy_object ) {
683	$all_values[] = $custom_taxonomy_object->name;
684	}
685	}
686	}
687
688	return $all_values;
689	}
690	}
691