Veriplace
High-level Veriplace client for web applications. The web client hides many of the details of Veriplace's OAuth-based authorization process, providing a persistent state across transactions that may involve redirects and callbacks.
An instance of Veriplace manages the following resources:
- A Veriplace_Client which handles communication with the Veriplace server. This is the lower-level client API, which you can still access if desired.
- Token caches to preserve user access tokens transparently across callbacks.
- Properties associated with the most recent request, such as the current Veriplace_User and/or Veriplace_Location.
The ''require'' methods of this class represent operations that may require one or more requests to the Veriplace server, including browser redirects. These methods may return normally, indicating success, or may throw a subclass of Veriplace_Exception, indicating either that the request failed or that the user has been redirected.
Located in /Veriplace/Web.php (line 572)
static create (line 599)
Creates a new Veriplace instance using the specified configuration properties.
- string|array $properties: Name of a property file, or associative array of property values; see Veriplace_DefaultClientFactory.
Constructor __construct (line 618)
Creates a new Veriplace instance using the specified Veriplace_Client object.
- Veriplace_Client $client: The Veriplace client instance.
- Veriplace_OAuthUserStore $userTokenStore: An implementation of Veriplace_OAuthUserStore for caching access tokens, or null to use the default implementation.
getCallbackURI (line 662)
Constructs a URI for returning to the current request from an external page, and passing along any necessary attributes to recreate the current state. You will normally not need to call this method yourself.
isCallback (line 992)
Returns true if the current request is a callback from Veriplace.
requireGetLocationPermission (line 821)
Attempts to obtain permission to locate the current Veriplace user, if that permission isn't already present in the current state. If you haven't already identified the user, then this calls requireUser() first.
Either the user discovery step or the permission step may cause a redirect to the Veriplace site. When Veriplace redirects back to your application, it will be to the same URI and with the same HTTP parameters as the initial request, but with an additional token to indicate that the permission is now available. You do not need to check for this token; just call requireGetLocationPermission() as you did before, and this time the method will return normally.
The Veriplace instance maintains a token cache containing the last known valid permission token for each user, which it will try to reuse if you call requireLocation(). However, it will not use this cache if you call requireGetLocationPermission separately from requireLocation, because the token might have expired and there would be no way to know this if you didn't go on to actually request a location. Therefore, requireGetLocationPermission always asks the Veriplace server for a current permission.
requireGetLocationPermissionImmediate (line 853)
Attempts to obtain permission to locate the current Veriplace user, if that permission isn't already present in the current state. The user must already have been identified with requireUser() or specified directly.
This method will not perform any redirects and will not ask the user for permission if it wasn't previously granted; it will simply fail in that case. If this method returns with no exceptions, permission is now available. If you need to save the permission token for future reuse, it's in the $getLocationPermissionToken property.
The Veriplace instance maintains a token cache containing the last known valid permission token for each user, which it will try to reuse if you call requireLocation(). However, requireGetLocationPermissionImmediate does not use this cache; it always asks the Veriplace server for a current permission.
requireLocation (line 899)
Attempts to locate the current Veriplace user, if a location isn't already present in the current state. If you haven't already identified the user or obtained location permission, then this calls requireUser() and/or requireGetLocationPermission() first in the correct order.
If this method returns with no exceptions, the location data is present in the $location property.
Either the user discovery step or the permission step may cause a redirect to the Veriplace site. When Veriplace redirects back to your application, it will be to the same URI and with the same HTTP parameters as the initial request, but with an additional token to indicate that the location is now available. You do not need to check for this token; just call requireLocation() as you did before, and this time the method will return normally.
Location requests are done synchronously, which may cause a noticeable delay if a new GPS fix is required. You may wish to display an intermediate "please wait" page first and then redirect to the page that performs the request.
requireLocationAsynchronous (line 950)
Attempts to locate the current Veriplace user (if a location isn't already present in the current state), without waiting for the location request to finish.
This works identically to requireLocation(), except that the first time you call it, it submits an asynchronous location request to Veriplace, stores the ID of the request, and then returns immediately. Each time you call it subsequently, it queries Veriplace to see if the request has finished. If so, it retrieves the result and returns true (or throws an exception, if the result was an error).
If the request is still in progress, the return value of Veriplace::getCallbackURI() will include the request ID as a query string parameter, so that if you subsequently redirect to that URI, the request ID will be preserved for the next call to this method.
A typical use of this method would be to display an automatically-refreshing progress page while the request is in progress: that is, if requireLocationAsynchronous() returns false, then output a "please wait" page with an HTML meta refresh tag that will reload it after a few seconds, using the return value of Veriplace::getCallbackURI() as the URL property of the refresh tag. When the page refreshes, the same script will be executed and will call requireLocationAsynchronous() again; it will detect that a request was already started and will return true if the result is ready, otherwise it will return false and repeat the previous step as needed.
requireLocationById (line 980)
Attempts to retrieve a previously retrieved location again, using its ID
(from the id property of a Veriplace_Location object). If you haven't already identified the user or obtained location permission, then this calls requireUser() and/or requireGetLocationPermission() first in the correct order, which may involve redirects. However, the location request itself happens synchronously as a single server call. <p> If this method returns with no exceptions, the location data is present in the location property of the Veriplace object.
- $locationId
requireUser (line 707)
Attempts to acquire the current Veriplace user identifier, if it isn't already present in the current state. After this method returns, the user object is in the $user property.
If the user has already been acquired, or set explicitly in the $user property, the method returns immediately. Otherwise, it redirects to the Veriplace server to begin a user discovery transaction. If the server can detect the current user without interaction, it redirects immediately back to your application; otherwise it prompts the user to log in (unless you have disabled this by setting $userInteractionAllowed to false) and redirects back once they have done so.
When your application receives the callback, it will be to the same URI and with the same HTTP parameters as the initial request, but with an additional token to indicate that the user is now available. You do not need to check for this token; just call requireUser() as you did before, and this time the method will return normally.
requireUserFromParameters (line 741)
Attempts to acquire the current Veriplace user identifier using identifying information in Veriplace_UserDiscoveryParameters. In order to do this, you must have specified an application token and token secret in your Veriplace client configuration.
If the user has already been acquired, or set explicitly in the $user property, the method returns immediately. Otherwise, it submits a request to the Veriplace server which will either succeed or immediately fail; there are no redirects. If the method returns with no exceptions, the user object is in the Veriplace $user property.
- Veriplace_UserDiscoveryParameters $parameters: parameters The identifying properties of the desired user.
requireUserImmediate (line 775)
Attempts to acquire the current Veriplace user identifier, if it isn't already present in the current state, without providing any identifying properties and without redirecting. This will only work if you have just received a callback from a successful user discovery transaction.
If the user has already been acquired, or set explicitly in the $user property, the method returns immediately. Otherwise, it submits a request to the Veriplace server which will either succeed or immediately fail; there are no redirects.
If the method returns with no exceptions, the user object is in the Veriplace $user property.
setCallbackParameter (line 650)
Stores an HTTP parameter that will be preserved across callbacks. You will normally not need to call this method yourself.
- $name
- $value
Documentation generated on Sun, 29 Aug 2010 04:08:40 -0700 by phpDocumentor 1.4.1