Getting started with the PHP SDK
Steve
I'm having some issues getting started with the PHP SDK (verson 1.6).
I'll tell my story from the start even though I've resolved a few of
the issues myself as they may help others :) Also, don't forget to
ensure you have PHP 5.2.x or greater or you'll get a ton more strange
errors (I upgraded to 5.3.3; the latest stable release)
Goal: To use the use the demos contained in \examples\index.html with
the Veriplace PHP SDK (version 1.6) to get a handle on how the SDK
works so I can start pulling it apart to build my own application.
##### Problem #1 [SOLVED]
** Issue **
Browsing to /examples/index.html resulted in the PHP error:
Warning: require_once(Veriplace/Configuration.php): failed to open
stream: No such file or directory...
** Solution **
Copy the /Veriplace/ folder containing all the code into the /
examples/ folder (or all the examples into the root) so the paths can
correctly access the Veriplace folder (or alternatively either add the
Veriplace folder to the "include_path" in your php.ini or I suppose
modify the code in the specific example you want to execute to point
to the files correctly as '../Veriplace/Configuration', etc.)
##### Problem #2 [SOLVED]
** Issue **
Browsing to /examples/index.html resulted in the PHP error:
Fatal error: Uncaught Veriplace_ConfigurationException: missing
required property: veriplace.application.consumer.key thrown in...
** Solution **
Realize there is a config file (duh? ;). Open up the \examples
\config.php and fill in correct values for my consumer.key,
consumer.secret, token.value, token.secret which can be found under My
Apps of the developer website for a specific application (http://
developer.veriplace.com/devportal/applications)
##### Problem #3 [SOLVED]
** Issue **
Browsing to /examples/index.html resulted in the PHP error:
Fatal error: Uncaught Veriplace_ConfigurationException: invalid or
unwriteable log file: /tmp/vp_php.log thrown in
** Solution **
I'm on a Windows server, so the log.file value in /examples/config.php
was of course was invalid. I replaced it with C:\Windows\Temp
\vp_php.log (side tip: ensure PHP on your webserver has permission to
write to this folder).
** Suggestion for the SDK Developer **
Maybe reference getenv('TEMP') instead of having users manually
specify the folder in the config at all, I believe this is defined for
both UNIX & Windows based machines and saves lazy developers
effort ;). A similar update may be able to be made RE: problem #6
below and any other hardcoded references to /tmp/.
##### Problem #4 [SOLVED]
** Issue **
Browsing to /examples/index.html... success! However selecting any
example to run resulted in several PHP errors, but centered on an
error accessing SSL via curl:
Veriplace_TransportException: SSL certificate problem, verify that the
CA cert is OK. Details: error:14090086:SSL
routines:SSL3_GET_SERVER_CERTIFICATE:certificate verify failed
** Solution **
My PHP/curl install didn't come setup with any CA certificates
required to properly autheticate use of SSL when making API calls so I
had to find the manually. My solution was to:
1. Download cacert.pem from http://curl.haxx.se/docs/caextract.html
and place it in C:\PHP\
2. Add a line in /Veriplace/internal/Network.php on line 269 (in the
executeInternal() function of the Veriplace_CurlHttpRequest class)
containing the code: curl_setopt($curl, CURLOPT_CAINFO, 'C:\PHP
\cacert.pem');
##### Problem #5 [SOLVED - Bug in the API v1.6.0]
** Issue **
Selecting the "Invitation API" results in the PHP error:
Parse error: syntax error, unexpected T_VARIABLE in C:\path\to\examples
\invitation.php on line 72 PHP Parse error: syntax error, unexpected
T_VARIABLE in C:\path\to\examples\invitation.php on line 72
** Solution **
Open up \examples\invitation.php and add a semicolon to the end of
line 71
##### Problem #6 [SOLVED]
** Issue **
Selecting the "Invitation API" results in the PHP error:
Warning: file_put_contents(/tmp/veriplace-invitation-example-data):
failed to open stream: No such file or directory in C:\path\to\examples
\common.php on line 163
** Solution **
Once again a path issue since I'm on a Windows box. Open up \examples
\invitation.php and replace line 28 with:
define('INVITATION_DATA_FILE', getenv('TEMP').'\veriplace-invitation-
example-data');
...or fill in C:\Windows\Temp\ as the comment instructs, but the above
code I believe works cross-platform.
##### Problem #7 [Need help!]
** Issue **
Executing the "Invitation API" with any mobile phone # results in the
PHP notice:
Notice: Undefined index: REQUEST_URI in C:\path\to\examples\Veriplace
\Interfaces.php on line 197
as well as errors:
Unable to send invitation for mobile number :
Veriplace_UnknownTokenException
Unable to send invitation for mobile number 19095551234:
Veriplace_UnknownTokenException
** Solution **
I'm not sure how essential the REQUEST_URI is for this method, so I'm
not sure how great a solution this is, but you can suppress the notice
by modifying line 197 of Veriplace\Interfaces.php to read: $uri = @
$_SERVER['REQUEST_URI'];
The "unable to send invitation" errors I'm not sure how to resolve
yet.
##### Problem #8 [Need help!]
** Issue **
When I select any of the "Basic Location Request" examples in /
examples/index.html it now spends a few seconds and then forwards me
to http://veriplace.com/userAuthorizationError and displays the error:
We couldn't process your request.
It's possible that you encountered this page through an error or that
the content on this page has expired. If you got here from another
site or application, please return there and try again.
** Solution **
I'm not to sure yet! A couple of the "Other APIs" examples work (e.g.
Permitted Users), but most of them produce the same error as above.
Eli Bishop
Thanks for sharing these tips and problems, and for being so thorough!
I have a few comments - see below.
On Thu, 2010-09-16 at 17:53 -0700, Steve wrote:
> ##### Problem #1 [SOLVED]
> ** Issue **
> Browsing to /examples/index.html resulted in the PHP error:
> Warning: require_once(Veriplace/Configuration.php): failed to open
> stream: No such file or directory...
>
> ** Solution **
> Copy the /Veriplace/ folder containing all the code into the /
> examples/ folder (or all the examples into the root) so the paths can
> correctly access the Veriplace folder (or alternatively either add the
> Veriplace folder to the "include_path" in your php.ini or I suppose
> modify the code in the specific example you want to execute to point
> to the files correctly as '../Veriplace/Configuration', etc.)
The other way to do this, if your server has PEAR and if you have the
necessary permissions to install PEAR modules on your server, is to
install the Veriplace SDK as described in the Readme file:
pear install Veriplace-1.7.0.tar.gz
That basically just copies the Veriplace code into a common area that is
always included in your include_path.
> ##### Problem #3 [SOLVED]
> ** Issue **
> Browsing to /examples/index.html resulted in the PHP error:
> Fatal error: Uncaught Veriplace_ConfigurationException: invalid or
> unwriteable log file: /tmp/vp_php.log thrown in
>
> ** Solution **
> I'm on a Windows server, so the log.file value in /examples/config.php
> was of course was invalid. I replaced it with C:\Windows\Temp
> \vp_php.log (side tip: ensure PHP on your webserver has permission to
> write to this folder).
>
> ** Suggestion for the SDK Developer **
> Maybe reference getenv('TEMP') instead of having users manually
> specify the folder in the config at all, I believe this is defined for
> both UNIX & Windows based machines and saves lazy developers
> effort ;). A similar update may be able to be made RE: problem #6
> below and any other hardcoded references to /tmp/.
Yes, that really should be handled better in the example code - sorry.
Unfortunately, it's not quite as simple as using getenv('TEMP'): this
is one area where different builds of PHP are very inconsistent, and to
be absolutely sure of getting the right temporary file path for every
OS, you may need to use any one of five(!) different methods (see
comments at http://php.net/manual/en/function.sys-get-temp-dir.php ).
The most recent version of our SDK includes a convenience function to
handle this (it's hidden away in Veriplace/internal/Util.php) and the
example code should probably just use that.
> ##### Problem #4 [SOLVED]
> ** Issue **
> Browsing to /examples/index.html... success! However selecting any
> example to run resulted in several PHP errors, but centered on an
> error accessing SSL via curl:
> Veriplace_TransportException: SSL certificate problem, verify that the
> CA cert is OK. Details: error:14090086:SSL
> routines:SSL3_GET_SERVER_CERTIFICATE:certificate verify failed
>
> ** Solution **
> My PHP/curl install didn't come setup with any CA certificates
> required to properly autheticate use of SSL when making API calls so I
> had to find the manually. My solution was to:
> 1. Download cacert.pem from http://curl.haxx.se/docs/caextract.html
> and place it in C:\PHP\
> 2. Add a line in /Veriplace/internal/Network.php on line 269 (in the
> executeInternal() function of the Veriplace_CurlHttpRequest class)
> containing the code: curl_setopt($curl, CURLOPT_CAINFO, 'C:\PHP
> \cacert.pem');
We really need to add this to the next version of the SDK as an optional
configuration property (i.e., path to your CA cert file if any), because
as you found, if you have this problem there's really no way to fix it
without modifying the code that calls curl. Another PHP developer
brought up this issue on the list earlier - I'm unable to find it right
now for some reason, but the solution was the same. (Of course if you
have superuser permissions, you can configure curl to have the standard
CA certificates, but many PHP developers are in environments where they
can't do that.)
> ##### Problem #5 [SOLVED - Bug in the API v1.6.0]
> ** Issue **
> Selecting the "Invitation API" results in the PHP error:
> Parse error: syntax error, unexpected T_VARIABLE in C:\path\to\examples
> \invitation.php on line 72 PHP Parse error: syntax error, unexpected
> T_VARIABLE in C:\path\to\examples\invitation.php on line 72
>
> ** Solution **
> Open up \examples\invitation.php and add a semicolon to the end of
> line 71
This is a bug in the example code rather than in the API, but thanks for
finding and fixing it! Somehow we missed running the latest version of
this script.
>##### Problem #7 [Need help!]
> ** Issue **
> Executing the "Invitation API" with any mobile phone # results in the
> PHP notice:
> Notice: Undefined index: REQUEST_URI in C:\path\to\examples\Veriplace
> \Interfaces.php on line 197
> as well as errors:
> Unable to send invitation for mobile number :
> Veriplace_UnknownTokenException
> Unable to send invitation for mobile number 19095551234:
> Veriplace_UnknownTokenException
>
> ** Solution **
> I'm not sure how essential the REQUEST_URI is for this method, so I'm
> not sure how great a solution this is, but you can suppress the notice
> by modifying line 197 of Veriplace\Interfaces.php to read: $uri = @
> $_SERVER['REQUEST_URI'];
> The "unable to send invitation" errors I'm not sure how to resolve
> yet.
Hmm... I'm not sure what's going on here. I don't believe the
Invitation API itself uses $_SERVER['REQUEST_URI']. The invitation
*example* does use it, in order to construct a callback URL that will go
to the same script.
The only way I know of that you'd get an "undefined index" error for
that expression is if you're running the script from the command line,
rather than inside a web server. The invitation example is a web
script. You can still use the Invitation API to send invitations from a
non-web script; you'd just need to construct your callback URL some
other way, rather than using $_SERVER['REQUEST_URI'].
Please let me know if that makes sense, or if I've misunderstood the
problem report.
> ##### Problem #8 [Need help!]
> ** Issue **
> When I select any of the "Basic Location Request" examples in /
> examples/index.html it now spends a few seconds and then forwards me
> to http://veriplace.com/userAuthorizationError and displays the error:
> We couldn't process your request.
> It's possible that you encountered this page through an error or that
> the content on this page has expired. If you got here from another
> site or application, please return there and try again.
Hmm. I would've guessed that maybe you didn't have the necessary
properties in config.php, but then *none* of the examples would work. I
can try to reproduce this; could you email me your config.php file
directly?
best,
Eli (ULS/Veriplace Developer Support)
--
Eli Bishop
Wavemarket, Inc. / Location Labs
e...@location-labs.com
Steve
I tried the PEAR install method, but recieved an error referecing a
file that doesn't appear to be in the SDK download:
ERROR: file C:\PHP\tmp\Veriplace-1.6.0\Veriplace\internal\JSON.php
does not exist
I'll do some more digging and see if I can figure out whats going on
regarding the REQUEST_URI, I am running things on a web server but
you're right, it's really "should" be defined. We had recently made
upgrades to our development server hardware, so my PHP install is
essentially fresh out of the box with all default settings right now,
I'll see what I can find out or if the error goes away on its own
somehow.
I'll emailed you a copy of my config.php momentarily to see what you
can see. I haven't "published" my application yet if that's
relevant... I assumed I'd be able to use it in the development state
with test/simulated users prior to that though?
Eli Bishop
See responses below--
On Mon, 2010-09-20 at 10:12 -0700, Steve wrote:
> Hi Eli, thanks for your detailed response!
>
> I tried the PEAR install method, but recieved an error referecing a
> file that doesn't appear to be in the SDK download:
> ERROR: file C:\PHP\tmp\Veriplace-1.6.0\Veriplace\internal\JSON.php
> does not exist
Ugh-- you've found another mistake in our SDK distribution. The
manifest in the PEAR package did not get updated when the source files
changed. I apologize again for something that should've been caught in
pre-release testing!
The PEAR package will be fixed in the next release, but in the meantime
either of the other two solutions you mentioned will work: a) copying
the source directory Veriplace to ./Veriplace (where . is the directory
where your scripts are) or b) copying it somewhere else that's
accessible from your scripts and setting your include_path to include
that location.
> I'll do some more digging and see if I can figure out whats going on
> regarding the REQUEST_URI, I am running things on a web server but
> you're right, it's really "should" be defined. We had recently made
> upgrades to our development server hardware, so my PHP install is
> essentially fresh out of the box with all default settings right now,
> I'll see what I can find out or if the error goes away on its own
> somehow.
I looked into this further, and it seems that this is a known problem
with PHP under IIS; you're using Windows, so I'm guessing you're using
IIS too. If I'm right, then this is one more thing to add to the list
of annoying PHP implementation inconsistencies, and we should add a
workaround for that in the next release too.
Fortunately the workaround seems to be pretty simple, if you want to
patch Interfaces.php in the meantime:
http://davidwalsh.name/iis-php-server-request_uri
maplap
( Problem 8 )
would you like me to send my config?
Eli Bishop
I believe the "userAuthorizationError" you were seeing when running
the interactive web authorization example was due to a faulty setting
in the platform - it was not accepting authorization redirects with
API version 1.2, which is the version used by the most recent SDK
release. That's been fixed as of today, so please try again and let me
know if it works for you now.
best,
Eli
C.L. Hammond
..what's the difference between php sdk 1.6 and the 1.2 api release? .. sdk and api considered as two different products?
--
Lappin Hammond
Steve
When I first clicked through the "Web API" example, it did take me to
the page where I end my mobile # (http://veriplace.com/
userDiscoveryInfo) instead of the userAuthorizationError. I entered
one of my simulator user #'s, it had me sign-in, then directed me to
http://veriplace.com/grantUserDiscovery which was a blank white page.
If i go back, it appears to have correctly signed me into veriplace as
I can start browsing my simulator user settings. If I go back and re-
select the "Web API" example, I get sent to the userAuthorization page
again, but it's also a blank white screen.
As an unrelated aside/bug report, if it helps at all, I've also also
noticed some PHP errors playing with async-location.php which I
believe are related to references in Types.php (lines 596 & 626) that
reference: Veriplace_ClientConfiguration.XML_CONTENT_TYPE which are
reported as undefined constants. I believe the intention was to
reference: Veriplace_Configuration::XML_CONTENT_TYPE.
For curiosities sake, what do you figure is the most "stable" way of
interacting with Location Labs today? I do most of my programming in
ColdFusion which is built on a Java base, and even allows me to
install your servlet tags for JSP, but I wound up running into errors
there as well (java.lang.ClassFormatError: Illegal field name "require-
user2" in class cfindex2ecfm999038228 when invoking <vp:require-user
interactive="true" />; the <vp:setup id="veriplace"
viewparams="tutorial" propertiesId="properties" /> call is successful
however. And if I cheat a bit and invoke veriplace.requireUser()
manually using the veriplace object returned by vp:setup it even re-
directs me to the sign-in pages, but eventually bugs out similar to
PHP (and I'd prefer to be using the proper jsp tags rather than nifty
hacks ;).
Should I continue to explore the servlet/jsp method seeking some debug
assistance for the problem above (probably my preference for
development simplicity if it worked)?
Should I use the Java SDK itself and write my own wrapper methods that
I can use ColdFusion to invoke as a bit of a Java/CF hybrid solution?
Should I stick with PHP (eventually requiring my to proxy it back to
ColdFusion and/or reverse engineer the SDK for ColdFusion)?
Should I give up on the SDK's entirely and try to learn/invoke the API
methods manually?
or should I simply take a few weeks off from experimenting and wait
for more stable releases of all of the above and try again then?
Thanks!
Eli Bishop
Right-- by API, I meant the HTTP/REST interface exposed by the server,
which is what's documented in the Veriplace Developer Guide. The various
language-specific SDKs are wrappers for that. Sometimes we'll release a
new SDK version without changing the server API, if it's just to fix a
bug in the SDK or add a convenience feature that's entirely on the
client side, but for new platform features we usually update them all
together.
--
Eli Bishop
See responses below -
On Thu, 2010-09-23 at 13:48 -0700, Steve wrote:
> Hi Eli,
>
> When I first clicked through the "Web API" example, it did take me to
> the page where I end my mobile # (http://veriplace.com/
> userDiscoveryInfo) instead of the userAuthorizationError. I entered
> one of my simulator user #'s, it had me sign-in, then directed me to
> http://veriplace.com/grantUserDiscovery which was a blank white page.
> If i go back, it appears to have correctly signed me into veriplace as
> I can start browsing my simulator user settings. If I go back and re-
> select the "Web API" example, I get sent to the userAuthorization page
> again, but it's also a blank white screen.
It sounds like Veriplace has completed the user authorization process
and is trying to redirect back to your application. Looking at the
parameters we got from your app in the request logs, I see what might be
the problem: for the callback parameter (i.e. the URI that Veriplace
will try to redirect to), I'm seeing a malformed URI in the form
"https://Hostname:PortPath/"-- that is, there's a missing slash after
the port number. I imagine that if Veriplace sent an HTTP redirect like
that, the browser might just ignore it and leave you with a blank page.
We should probably have just rejected that callback parameter when you
made the original request-- we do validate URI parameters for other
APIs, but apparently didn't do so in this case.
If you were running the example code as-is, then I presume the problem
is in the code that constructs callbacks automatically from the current
request URI (Veriplace_DefaultCallbackFactory, in Interfaces.php). I
don't see anything in that code that could omit a slash-- but this could
be the result of another IIS+PHP peculiarity, that is, where the
REQUEST_URI parameter in PHP always has a leading slash, the IIS
implementation might omit this.
If so, we can easily add a workaround for that, but in the meantime you
could try patching Veriplace_DefaultCallbackFactory as follows: change
the last line of getRequestPath() from "return $uri;" to "return '/' .
$uri;". Please let me know if this is on target.
> As an unrelated aside/bug report, if it helps at all, I've also also
> noticed some PHP errors playing with async-location.php which I
> believe are related to references in Types.php (lines 596 & 626) that
> reference: Veriplace_ClientConfiguration.XML_CONTENT_TYPE which are
> reported as undefined constants. I believe the intention was to
> reference: Veriplace_Configuration::XML_CONTENT_TYPE.
How embarrassing, and how helpful - you're finding all the PHP mistakes
I should've found in the last release. Thank you. There should be a
new release of the PHP SDK within about a week, which will include fixes
for the things you've mentioned so far (including the workaround for
missing certificates in curl), and we'll be sure to run through the demo
code more exhaustively this time. Can you tell that we're more used to
compiled languages, where such things would be caught at build time?
> For curiosities sake, what do you figure is the most "stable" way of
> interacting with Location Labs today? I do most of my programming in
> ColdFusion which is built on a Java base, and even allows me to
> install your servlet tags for JSP, but I wound up running into errors...
The Java SDK has always been the most mature, since (a) we do most of
our own development in Java and (b) it's been the most widely used by
third-party developers too. Unfortunately, the exception to that is the
JSP tag library-- a nice idea that (as far as I know) no one's really
used, so it has clearly fallen behind in feature development and in
testing. I'll look into the <vp:require-user> bug you found; it sounds
like it's probably a fairly dumb mistake that can be easily patched.
We are starting to put more effort into the PHP SDK and seeing more
developer interest in it now too, but as you can see, there are still
some rough edges there. It's also got a few limitations in its feature
set that are just inevitable in PHP as compared to Java, e.g. it's not
possible to do a location request on a background thread.
.NET wouldn't be relevant to your ColdFusion project, but in terms of
the feature set it's equivalent to the Java SDK (except for having no
tag library) and in terms of thoroughness of testing it's probably
midway between Java and PHP. We have a couple of third-party apps using
it fairly heavily with good results so far.
Thanks as always for your feedback!
best,
Eli
Eli Bishop
I wanted to follow up on the item below, which is a bit mysterious to
me. The JSP tag library works correctly for me in Apache Tomcat, but
we haven't tested in ColdFusion. This error appears to be related to
how ColdFusion translates JSPs into Java code: specifically, it looks
like it is trying to use the tag name as a Java identifier without
escaping the hyphen (which is a legal character in a tag name, but not
in a Java identifier). If so, that seems like a rather silly error
for ColdFusion to make, but perhaps people who write tag libraries
just haven't been using hyphens in names very often.
The workaround would be simple: for maximum compatibility with this
and other platforms that might have the same problem, we could change
the hyphens to underscores. That would break any existing code that
used the JSP tag library, although I don't think it has been widely
used so far. I've added it to the to-do list, and in the meantime if
you wanted to try rebuilding the SDK from source code after changing
the "-"s to "_" in "taglib.tld", I'd be curious to hear whether that
fixed the problem.
best,
Eli