# MongoDB::ChangeStream - phpMan

## NAME
    [MongoDB::ChangeStream] - A stream providing update information for
    collections.

## VERSION
    version v2.2.2

## SYNOPSIS
        $stream = $collection->watch( $pipeline, $options );
        [while(1)] {

            # This inner loop will only iterate until there are no more
            # changes available.
            while (my $change = $stream->next) {
                ...
            }
        }

## DESCRIPTION
    This class models change stream results as returned by the "watch" in
    [MongoDB::Collection] method.

## STREAM METHODS
  next
        $change_stream = $collection->watch(...);
        $change = $change_stream->next;

    Waits for the next change in the collection and returns it.

    Note: This method will wait for the amount of milliseconds passed as
    "maxAwaitTimeMS" to "watch" in [MongoDB::Collection] or the server's
    default wait-time. It will not wait indefinitely.

  get_resume_token
    Users can inspect the "_id" on each "ChangeDocument" to use as a resume
    token. But since MongoDB 4.2, "aggregate" and "getMore" responses also
    include a "postBatchResumeToken". Drivers use one or the other when
    automatically resuming.

    This method retrieves the same resume token that would be used to
    automatically resume. Users intending to store the resume token should
    use this method to get the most up to date resume token.

    For instance:

        if ($local_change) {
            process_change($local_change);
        }

        eval {
            my $change_stream = $coll->watch([], { resumeAfter => $local_resume_token });
            while ( my $change = $change_stream->next) {
                $local_resume_token = $change_stream->get_resume_token;
                $local_change = $change;
                process_change($local_change);
            }
        };
        if (my $err = $@) {
            $log->error($err);
        }

    In this case the current change is always persisted locally, including
    the resume token, such that on restart the application can still process
    the change while ensuring that the change stream continues from the
    right logical time in the oplog. It is the application's responsibility
    to ensure that "process_change" is idempotent, this design merely makes
    a reasonable effort to process each change at least once.

## SEE ALSO
    The Change Streams manual section
    <<https://docs.mongodb.com/manual/changeStreams/>>.

    The Change Streams specification
    <<https://github.com/mongodb/specifications/blob/master/source/change-str>
    eams.rst>.

## AUTHORS
    *   David Golden <<david@mongodb.com>>

    *   Rassi <<rassi@mongodb.com>>

    *   Mike Friedman <<friedo@friedo.com>>

    *   Kristina Chodorow <<k.chodorow@gmail.com>>

    *   Florian Ragwitz <<rafl@debian.org>>

## COPYRIGHT AND LICENSE
    This software is Copyright (c) 2020 by MongoDB, Inc.

    This is free software, licensed under:

      The Apache License, Version 2.0, January 2004