waitUntilObjectExists() Amazon S3 PHP SDK method, exactly how does it work?

waitUntilObjectExists is basically a waiter that periodically checks (polls) S3 at specific time intervals to see if the resource is available. The script's execution is blocked until the resource is located or the maximum number of retries is reached.

As the AWS docs defines them:

Waiters help make it easier to work with eventually consistent systems by providing an easy way to wait until a resource enters into a particular state by polling the resource.

By default, the waitUntilObjectExists waiter is configured to try to locate the resource 20 times, with a 5 seconds delay between each try. You can override these default values with your desired ones by passing additional parameters to the waitUntilObjectExists method.

If the waiter is unable to locate the resource after the maximum number of tries, it will throw an exception.

You can learn more about waiters at:

http://docs.aws.amazon.com/aws-sdk-php-2/guide/latest/feature-waiters.html

For your use case, I don't think it makes sense to call waitUntilObjectExists after you uploaded the object, unless the same PHP script tries to retrieve the same object from S3 later in the code.

If the putObject API call has returned a successful response, then the object will eventually show up in S3 and you don't necessarily need to wait for this to happen before you remove the local files.