Get Revisions

Use getFor to retrieve all of the revisions currently kept for the specified document.

• Example:

  // Get revisions for document 'orders/1-A'
  // Revisions will be ordered by most recent revision first
  /** @var array<Order>  $orderRevisions */
  $orderRevisions = $session
      ->advanced()
      ->revisions()
      ->getFor(Order::class, id: "orders/1-A", start: 0, pageSize: 10);

• Syntax:

  public function getFor(?string $className, ?string $id, int $start = 0, int $pageSize = 25): array;

  Parameters	Type	Description
  id	string	Document ID for which to retrieve revisions
  className	string	The type of the object whose revisions we want to retrieve
  start	int	First revision to retrieve, used for paging
  pageSize	int	Number of revisions to retrieve per results page

Use getMetadataFor to retrieve the metadata for all the revisions currently kept for the specified document.

• Example:

  // Get revisions' metadata for document 'orders/1-A'
  /** @var array<MetadataAsDictionary> $orderRevisionsMetadata */
  $orderRevisionsMetadata = $session
      ->advanced()
      ->revisions()
      ->getMetadataFor(id: "orders/1-A", start: 0, pageSize: 10);
  
  // Each item returned is a revision's metadata, as can be verified in the @flags key
  $metadata = $orderRevisionsMetadata[0];
  $flagsValue = $metadata[DocumentsMetadata::FLAGS];
  
  $this->assertContains("Revision", $flagsValue);

• Syntax:

  public function getMetadataFor(?string $id, int $start = 0, int $pageSize = 25): array;

  Parameters	Type	Description
  id	string	Document ID for which to retrieve revisions' metadata
  start	int	First revision to retrieve metadata for, used for paging
  pageSize	int	Number of revisions to retrieve per results page

Use getBeforeDate to retrieve a revision by its creation time.

• Example:

  // Get a revision by its creation time
  $revisionFromLastYear = $session
      ->advanced()
      ->revisions()
       // If no revision was created at the specified time,
       // then the first revision that precedes it will be returned
      ->getBeforeDate(Order::class, "orders/1-A", (new DateTime())->sub(new DateInterval("P1Y")));

• Syntax:

  function getBeforeDate(?string $className, ?string $id, DateTime $date): ?object;

  Parameter	Type	Description
  id	string	The ID of the document whose revisions we want to retrieve by creation time
  date	DateTime	Revision creation time
  className	string	The type of the object whose revisions we want to retrieve

To retrieve a revision or multiple revisions by change vectors use getMetadataFor, extract the change vector from the metadata, and get the revision using the change vector.

• Example:

  // Get revisions metadata
  /** @var array<MetadataAsDictionary> $revisionsMetadata */
  $revisionsMetadata = $session
      ->advanced()
      ->revisions()
      ->getMetadataFor("orders/1-A", start: 0, pageSize: 25);
  
  // Get the change-vector from the metadata
  $changeVector = $revisionsMetadata[0][DocumentsMetadata::CHANGE_VECTOR];
  
  // Get the revision by its change-vector
  $revision = $session
      ->advanced()
      ->revisions()
      ->get(Order::class, $changeVector);

• Syntax:

  // Get a revision(s) by its change vector(s)
  public function get(?string $className, null|string|array|StringArray $changeVectors): mixed;

  Parameter	Type	Description
  changeVectors	null or string or array or StringArray	A list of change vector strings
  className	className	The types of the objects whose revisions we want to retrieve