post_content; $owner = PageBuilders::owner( $post ); $locked = self::locked_by( (int) $post->ID ); $notes = array(); if ( null !== $owner ) { $notes[] = sprintf( /* translators: %s: page builder name. */ __( 'This page is built with %s. What is below is the stored body, and it is NOT what visitors see — the layout lives in the builder. edit-content refuses it for that reason.', 'agentimus' ), $owner['name'] ); } if ( '' !== $locked ) { $notes[] = sprintf( /* translators: %s: display name of the user editing. */ __( '%s has this post open in the editor right now. An edit made here would be overwritten by their next autosave, so edit-content refuses until they are done.', 'agentimus' ), $locked ); } return array( 'postId' => (int) $post->ID, 'title' => (string) $post->post_title, 'type' => (string) $post->post_type, 'status' => (string) $post->post_status, 'scheduledFor' => ContentWriter::scheduled_for( $post ), 'url' => (string) get_permalink( $post ), 'modified' => (string) $post->post_modified_gmt, // "blocks" or "classic" — an agent editing block markup needs to know // which it is holding, because a paragraph in one is a bare
and in
// the other is wrapped in comments it must not break.
'format' => has_blocks( $content ) ? 'blocks' : 'classic',
'builder' => null === $owner ? '' : (string) $owner['name'],
'lockedBy' => $locked,
'editable' => null === $owner && '' === $locked,
'content' => $content,
'length' => (int) mb_strlen( $content ),
// ⭐ THE IMAGES, NAMED. Without this an agent holding an `alt_text`
// row knows a page has undescribed pictures and has to find them by
// eye in raw block markup, then retype a whole tag to add one
// attribute. Each row here is aimable at describe-content-image, and
// `needs` says which ones the checks are actually asking about.
'images' => self::images_in( $content ),
'note' => implode( ' ', $notes ),
);
}
/**
* The images in a body, as an agent needs to see them.
*
* ⚠️ SCANNED FROM THE STORED BODY, while the alt_text check reads the
* RENDERED one. The two can differ, and the difference is the honest
* answer: a picture drawn by a shortcode, a gallery block or a theme
* template is not in this list because it is not in this body — and it
* cannot be fixed by editing this body either. describe-content-image
* refuses those by name rather than writing somewhere that has no effect.
*
* @param string $content Post content, as stored.
* @return array
tags in this page’s stored body. If a check reports images on it, they are drawn by a shortcode, a gallery or the theme rather than written into the body — and no edit to the body can describe them. read-content lists exactly what is here.', 'agentimus' ),
array( 'status' => 409 )
);
}
$found = self::pick_image( $images, $input );
if ( is_wp_error( $found ) ) {
return $found;
}
$replace = ! empty( $input['replace'] );
if ( ! empty( $found['hasAlt'] ) && ! $replace ) {
// ⭐ A CAPTIONED blank is not a decision — the checks flag it, so this
// writes it without asking, exactly as it does a file-name alt. Only
// an UNCAPTIONED blank is somebody saying "this picture means
// nothing", and only that is refused.
if ( '' === (string) $found['alt'] && empty( $found['hasCaption'] ) ) {
return new \WP_Error(
'agentimus_decorative_image',
__( 'This image is marked decorative — it carries alt="", which is the standard way of saying it holds no meaning a reader needs, and it has no caption suggesting otherwise, so the content checks do not flag it. Nothing was written. If that is wrong and the picture does say something, send replace=true.', 'agentimus' ),
array( 'status' => 409 )
);
}
if ( '' !== (string) $found['alt'] && PageCheck::counts_as_described( (string) $found['alt'], (string) $found['src'] ) ) {
return new \WP_Error(
'agentimus_already_described',
sprintf(
/* translators: %s: the description already on the image. */
__( 'This image is already described: “%s”. Nothing was written. A description somebody wrote is not something a fixing run replaces, and no content check asks for that — if this one is genuinely wrong, read it, then send replace=true with the correction.', 'agentimus' ),
$found['alt']
),
array( 'status' => 409 )
);
}
}
$tag = BodyImages::with_alt( $found['tag'], $alt );
$after = BodyImages::replace( $content, $found, $tag );
$out = $this->apply(
$post,
$content,
$after,
(int) $found['offset'] + strlen( $tag ),
! empty( $input['dry_run'] ),
'' === (string) $found['alt']
? __( 'Described. The picture reaches readers and screen readers with a description now; everything else on the page is exactly as it was.', 'agentimus' )
: __( 'Description replaced. Everything else on the page is exactly as it was.', 'agentimus' )
);
if ( is_wp_error( $out ) ) {
return $out;
}
// ⛔ THE LIBRARY COPY IS A SEPARATE FACT, AND THIS TOOL DOES NOT WRITE IT.
// Filling it quietly would change what `featured_alt` reports on every
// other page using this picture, without marking any of them for
// re-reading — the exact staleness MediaWriter exists to avoid. So it is
// REPORTED instead: the agent is told the library still needs a
// description and can call describe-image, which closes that loop
// properly.
$library = (int) $found['attachmentId'] > 0
? trim( (string) get_post_meta( (int) $found['attachmentId'], '_wp_attachment_image_alt', true ) )
: '';
$owes = (int) $found['attachmentId'] > 0
&& ! PageCheck::counts_as_described( $library, (string) wp_get_attachment_url( (int) $found['attachmentId'] ) );
return array_merge(
$out,
array(
'index' => (int) $found['index'],
'src' => (string) $found['src'],
'attachmentId' => (int) $found['attachmentId'],
'alt' => $alt,
'previous' => (string) $found['alt'],
'libraryAlt' => $library,
'libraryNeedsDescribing' => (bool) $owes,
)
);
}
/**
* Which of a page's images this call means.
*
* ⛔ IT NEVER GUESSES BETWEEN TWO. Three ways to aim — the library id, the
* file, or the position — and naming more than one is refused rather than
* ranked. The single exception is a page with exactly ONE image, where
* there is nothing to choose between and demanding a choice is friction for
* its own sake.
*
* @param array $images Rows from {@see BodyImages::scan()}.
* @param array $input The ability input.
* @return array|\WP_Error
*/
private static function pick_image( array $images, array $input ) {
$attachment = isset( $input['attachment_id'] ) ? (int) $input['attachment_id'] : 0;
$src = isset( $input['src'] ) ? trim( (string) $input['src'] ) : '';
$index = isset( $input['index'] ) ? (int) $input['index'] : 0;
$given = ( $attachment > 0 ? 1 : 0 ) + ( '' !== $src ? 1 : 0 ) + ( $index > 0 ? 1 : 0 );
if ( $given > 1 ) {
return new \WP_Error(
'agentimus_two_targets',
__( 'Name the image one way — attachment_id, src or index — not several. They can point at different pictures, and this tool never guesses which one you meant.', 'agentimus' ),
array( 'status' => 400 )
);
}
if ( 0 === $given ) {
if ( 1 === count( $images ) ) {
return $images[0];
}
return new \WP_Error(
'agentimus_which_image',
sprintf(
/* translators: 1: how many images, 2: a list of "index N: file". */
__( 'This page has %1$d images, so which one to describe has to be said: pass index, src or attachment_id. They are %2$s.', 'agentimus' ),
count( $images ),
self::image_list( $images )
),
array( 'status' => 400 )
);
}
if ( $index > 0 ) {
foreach ( $images as $image ) {
if ( (int) $image['index'] === $index ) {
return $image;
}
}
return new \WP_Error(
'agentimus_no_such_image',
sprintf(
/* translators: 1: the index asked for, 2: how many images the page has. */
__( 'There is no image %1$d on this page — it has %2$d. read-content lists them with the index each one answers to.', 'agentimus' ),
$index,
count( $images )
),
array( 'status' => 404 )
);
}
if ( $attachment > 0 ) {
$hits = array();
foreach ( $images as $image ) {
if ( (int) $image['attachmentId'] === $attachment ) {
$hits[] = $image;
}
}
// ⭐ THE CLASSIC-EDITOR FALLBACK. `wp-image-123` is written by the
// block editor; an image placed years ago, or by hand, carries no
// class at all and would look like somebody else's picture. Its file
// still names it, so the file is tried before giving up.
if ( ! $hits ) {
$file = (string) wp_get_attachment_url( $attachment );
$base = '' !== $file ? basename( (string) preg_replace( '/[?#].*$/', '', $file ) ) : '';
if ( '' !== $base ) {
foreach ( $images as $image ) {
if ( false !== strpos( (string) $image['src'], $base ) ) {
$hits[] = $image;
}
}
}
}
return self::one_of( $hits, __( 'attachment_id', 'agentimus' ), $images );
}
$hits = array();
foreach ( $images as $image ) {
if ( (string) $image['src'] === $src || false !== strpos( (string) $image['src'], $src ) ) {
$hits[] = $image;
}
}
return self::one_of( $hits, __( 'src', 'agentimus' ), $images );
}
/**
* Exactly one match, or a refusal that says what happened.
*
* @param array $hits What matched.
* @param string $by Which parameter was used, for the message.
* @param array $images Every image on the page, for the list.
* @return array|\WP_Error
*/
private static function one_of( array $hits, $by, array $images ) {
if ( 1 === count( $hits ) ) {
return $hits[0];
}
if ( ! $hits ) {
return new \WP_Error(
'agentimus_no_such_image',
sprintf(
/* translators: 1: the parameter used, 2: a list of "index N: file". */
__( 'No image on this page matches that %1$s. Nothing was written — the picture is not where the caller thinks it is. The page holds %2$s.', 'agentimus' ),
$by,
self::image_list( $images )
),
array( 'status' => 404 )
);
}
return new \WP_Error(
'agentimus_many_images',
sprintf(
/* translators: 1: how many matched, 2: the parameter used, 3: a list of "index N: file". */
__( '%1$d images on this page match that %2$s, so which one is a guess — and nothing was written. Aim it with index instead: the page holds %3$s.', 'agentimus' ),
count( $hits ),
$by,
self::image_list( $images )
),
array( 'status' => 409 )
);
}
/** "index 1: sunrise.jpg, index 2: bridge.png" — bounded, for a refusal. */
private static function image_list( array $images ) {
$parts = array();
foreach ( array_slice( $images, 0, 8 ) as $image ) {
$src = (string) preg_replace( '/[?#].*$/', '', (string) $image['src'] );
$parts[] = sprintf(
/* translators: 1: the image's position on the page, 2: its file name. */
__( 'index %1$d: %2$s', 'agentimus' ),
(int) $image['index'],
'' === $src ? __( '(no src)', 'agentimus' ) : basename( $src )
);
}
if ( count( $images ) > 8 ) {
$parts[] = sprintf(
/* translators: %d: how many more images there are. */
__( 'and %d more', 'agentimus' ),
count( $images ) - 8
);
}
return implode( ', ', $parts );
}
/* ------------------------------------------------------------------ */
/**
* The post both calls act on, with the two checks they share.
*
* @param mixed $post_id Post ID.
* @return \WP_Post|\WP_Error
*/
private static function post_for( $post_id ) {
$post_id = (int) $post_id;
if ( $post_id < 1 ) {
return new \WP_Error(
'agentimus_bad_post',
__( 'A post id is required. Every row read-content-issues returns carries one, as `id`.', 'agentimus' ),
array( 'status' => 400 )
);
}
$post = get_post( $post_id );
if ( ! $post instanceof \WP_Post ) {
return new \WP_Error( 'agentimus_not_found', __( 'No post with that id.', 'agentimus' ), array( 'status' => 404 ) );
}
if ( ! in_array( (string) $post->post_type, Content::post_types(), true ) ) {
return new \WP_Error( 'agentimus_bad_type', __( 'That post’s type is not agent-visible on this site.', 'agentimus' ), array( 'status' => 400 ) );
}
return $post;
}
/**
* Who has this post open in the editor, by name — '' when nobody does.
*
* @param int $post_id Post ID.
* @return string
*/
public static function locked_by( $post_id ) {
if ( ! function_exists( 'wp_check_post_lock' ) ) {
require_once ABSPATH . 'wp-admin/includes/post.php';
}
$user_id = wp_check_post_lock( $post_id );
if ( ! $user_id ) {
return '';
}
$user = get_userdata( (int) $user_id );
// A name, never an id: this sentence is read by the owner.
return $user ? (string) $user->display_name : __( 'Somebody', 'agentimus' );
}
/**
* How many block comments are left hanging: opens that are not self-closing,
* minus closes. Zero in a well-formed document, and the number an edit is
* required to leave exactly as it found it.
*
* @param string $html Post content.
* @return int
*/
private static function imbalance( $html ) {
$opens = preg_match_all( '//', $html );
$closes = preg_match_all( '#