includes/edit/ParsoidRenderID.php

   1 <?php
   2
   3 namespace MediaWiki\Edit;
   4
   5 use InvalidArgumentException;
   6 use MediaWiki\Parser\ParserOutput;
   7
   8 /**
   9  * Represents the identity of a specific rendering of a specific revision
  10  * at some point in time.
  11  *
  12  * @since 1.39
  13  * @unstable since 1.39, should be stable by 1.39 release.
  14  */
  15 class ParsoidRenderID {
  16         private int $revisionID;
  17         private string $uniqueID;
  18         private string $stashKey;
  19
  20         /**
  21          * @param int $revisionID Revision that was rendered
  22          * @param string $uniqueID An identifier for a point in time.
  23          */
  24         public function __construct( int $revisionID, string $uniqueID ) {
  25                 $this->revisionID = $revisionID;
  26                 $this->uniqueID = $uniqueID;
  27                 $this->stashKey = $revisionID . '/' . $uniqueID;
  28         }
  29
  30         /**
  31          * @param string $key String representation of render ID
  32          * (synonymous with an etag with double quotes) as returned by ::getKey().
  33          *
  34          * @return self
  35          * @see newFromETag()
  36          *
  37          */
  38         public static function newFromKey( string $key ): self {
  39                 [ $revisionID, $uniqueID ] = explode( '/', $key, 2 );
  40
  41                 if ( $revisionID === null || $uniqueID === null ) {
  42                         throw new InvalidArgumentException( 'Bad key: ' . $key );
  43                 }
  44
  45                 return new self( (int)$revisionID, $uniqueID );
  46         }
  47
  48         /**
  49          * Create a ParsoidRenderID from the revision and render id stored in
  50          * a ParserOutput.
  51          * @param ParserOutput $parserOutput
  52          * @return self
  53          */
  54         public static function newFromParserOutput( ParserOutput $parserOutput ): self {
  55                 $revisionID = $parserOutput->getCacheRevisionId();
  56                 $uniqueID = $parserOutput->getRenderId();
  57
  58                 if ( $revisionID === null || $uniqueID === null ) {
  59                         throw new InvalidArgumentException( 'Missing render id' );
  60                 }
  61
  62                 return new self( $revisionID, $uniqueID );
  63         }
  64
  65         /**
  66          * This constructs a new render ID from the given ETag.
  67          *
  68          * Any suffix after a second forward slash will be ignored e.g.
  69          * ->newFromEtag( '1/abc/stash' ) will return '1/abc' when ->getKey()
  70          * is called on the ParsoidRenderID object instance.
  71          *
  72          * @param string $eTag ETag with double quotes,
  73          *   see https://www.rfc-editor.org/rfc/rfc7232#section-2.3
  74          *
  75          * @return ParsoidRenderID|null The render ID embedded in the ETag,
  76          *         or null if the ETag was malformed.
  77          * @see newFromKey() if ETag already has outside quotes trimmed
  78          *
  79          */
  80         public static function newFromETag( string $eTag ): ?self {
  81                 if ( !preg_match( '@^(?:W/)?"(\d+)/([^/]+)(:?/.*)?"$@', $eTag, $m ) ) {
  82                         return null;
  83                 }
  84
  85                 [ , $revisionID, $uniqueID ] = $m;
  86
  87                 return new self( (int)$revisionID, $uniqueID );
  88         }
  89
  90         /**
  91          * This returns the canonical string representation from
  92          * the parsoid render ID which can be used to in newFromString().
  93          *
  94          * @return string
  95          */
  96         public function getKey(): string {
  97                 return $this->stashKey;
  98         }
  99
 100         public function __toString() {
 101                 return $this->stashKey;
 102         }
 103
 104         /**
 105          * Get the revision ID from the parsoid render ID object.
 106          *
 107          * @return int
 108          */
 109         public function getRevisionID(): int {
 110                 return $this->revisionID;
 111         }
 112
 113         /**
 114          * Get the unique identifier from the parsoid render ID object.
 115          *
 116          * @return string
 117          */
 118         public function getUniqueID(): string {
 119                 return $this->uniqueID;
 120         }
 121
 122 }
 123
 124 /** @deprecated since 1.42 */
 125 class_alias( ParsoidRenderID::class, 'MediaWiki\\Parser\\Parsoid\\ParsoidRenderID' );