svn: /pear/peardoc/trunk/ en/package/webservices/services-recaptcha/intro.xml en/package/webservices/services-recaptcha/mailhide.xml en/package/webservices/services-recaptcha/recaptcha.xml en/package/webservices/services-recaptcha.xml en/package/webservices-entities.xml entities/global.ent

Added: pear/peardoc/trunk/en/package/webservices/services-recaptcha/intro.xml
===================================================================
--- pear/peardoc/trunk/en/package/webservices/services-recaptcha/intro.xml	                        (rev 0)
+++ pear/peardoc/trunk/en/package/webservices/services-recaptcha/intro.xml	2010-04-10 13:03:07 UTC (rev 297800)
@@ -0,0 +1,53 @@
+<?xml version="1.0" encoding="utf-8"?>
+<refentry
+ xmlns="http://docbook.org/ns/docbook"
+ xmlns:phd="http://www.php.net/ns/phd"
+ version="lillet"
+ xml:id="package.webservices.services-recaptcha.intro"
+>
+ <refnamediv>
+  <refname>Introduction</refname>
+  <refpurpose>introduction to the <classname>Services_ReCaptcha</classname> package</refpurpose>
+ </refnamediv>
+ <refsection><info><title>Introduction</title></info>
+
+  <para>
+    <phd:pearapi phd:package="Services_ReCaptcha" phd:linkend="Services_ReCaptcha"/>
+    is a PHP5 interface to the two services offered by reCAPTCHA:
+    <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="&url.recaptcha.recaptcha;">reCAPTCHA</link> and
+    <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="&url.recaptcha.mailhide;">reCAPTCHA Mailhide</link>.
+  </para>
+  <para>
+   reCAPTCHA is a freely available CAPTCHA implementation. It distinguishes
+   humans from computers.
+   To use reCAPTCHA, you will need a public/private API key pair, available here:
+   <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="&url.recaptcha.recaptcha.getapikey;">http://recaptcha.net/api/getkey</link>.
+  </para>
+  <para>
+   reCAPTCHA Mailhide helps you protect your inbox by asking people to solve a
+   reCAPTCHA before they can view your email address.
+   The reCAPTCHA can only be solved by humans, so this stops spammers from gaining
+   access to your email address through automated programs.
+   reCAPTCHA Mailhide also requires a public and a private API key, that can be
+   generated here:
+   <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="&url.recaptcha.mailhide.getapikey;">http://mailhide.recaptcha.net/apikey</link>.
+  </para>
+ </refsection>
+
+ <refsection><info><title>Installation</title></info>
+  <para>
+   To install the package with pear just do:
+   <programlisting role="text">
+   <![CDATA[
+$ pear install Services_ReCaptcha
+   ]]>
+   </programlisting>
+   And to uninstall it:
+   <programlisting role="text">
+   <![CDATA[
+$ pear uninstall Services_ReCaptcha
+   ]]>
+   </programlisting>
+  </para>
+ </refsection>
+</refentry>

Added: pear/peardoc/trunk/en/package/webservices/services-recaptcha/mailhide.xml
===================================================================
--- pear/peardoc/trunk/en/package/webservices/services-recaptcha/mailhide.xml	                        (rev 0)
+++ pear/peardoc/trunk/en/package/webservices/services-recaptcha/mailhide.xml	2010-04-10 13:03:07 UTC (rev 297800)
@@ -0,0 +1,150 @@
+<?xml version="1.0" encoding="utf-8"?>
+<refentry
+ xmlns="http://docbook.org/ns/docbook"
+ xmlns:phd="http://www.php.net/ns/phd"
+ version="lillet"
+ xml:id="package.webservices.services-recaptcha.mailhide"
+>
+ <refnamediv>
+  <refname>reCAPTCHA Mailhide</refname>
+  <refpurpose>getting started with the Mailhide functionality of <package>Services_ReCaptcha</package></refpurpose>
+ </refnamediv>
+ <refsection><info><title>Instanciating the <classname>Services_ReCaptcha_MailHide</classname> class</title></info>
+  <para>
+   To instanciate the Services_ReCaptcha_MailHide class just do:
+   <programlisting role="php">
+   <![CDATA[
+<?php
+
+require_once 'Services/ReCaptcha/MailHide.php';
+
+$recaptcha = new Services_ReCaptcha_MailHide('your_public_key', 'your_private_key', '[email protected]');
+
+?>
+   ]]>
+   </programlisting>
+  </para>
+  <para>
+   You can also pass an array of option as third parameter, or pass options
+   later with the
+   <phd:pearapi phd:package="Services_ReCaptcha" phd:linkend="Services_ReCaptcha_Base::setOption"/>
+   or
+   <phd:pearapi phd:package="Services_ReCaptcha" phd:linkend="Services_ReCaptcha_Base::setOptions"/>
+  </para>
+  <para>
+   Available options are:
+   <table>
+    <title>Services_ReCaptcha_MailHide options</title>
+    <tgroup cols="3">
+     <thead>
+      <row>
+       <entry>Name</entry>
+       <entry>Description</entry>
+       <entry>Type</entry>
+       <entry>Default value</entry>
+      </row>
+     </thead>
+     <tbody>
+      <row>
+       <entry>mask_text</entry>
+       <entry>The chars that will be displayed in the email address to hide it</entry>
+       <entry>string</entry>
+       <entry>... (three dots)</entry>
+      </row>
+      <row>
+       <entry>link_text</entry>
+       <entry>An alternate string for the text of the link</entry>
+       <entry>string</entry>
+       <entry>null</entry>
+      </row>
+      <row>
+       <entry>link_title</entry>
+       <entry>Text to display as the title (tooltip) of the link</entry>
+       <entry>string</entry>
+       <entry>Reveal this e-mail address</entry>
+      </row>
+      <row>
+       <entry>popup_width</entry>
+       <entry>The popup width in pixels</entry>
+       <entry>integer</entry>
+       <entry>500</entry>
+      </row>
+      <row>
+       <entry>popup_height</entry>
+       <entry>The popup height in pixels</entry>
+       <entry>integer</entry>
+       <entry>300</entry>
+      </row>
+     </tbody>
+    </tgroup>
+   </table>
+  </para>
+ </refsection>
+ <refsection><info><title>Recaptcha Mailhide example</title></info>
+  <para>
+   <example>
+    <programlisting role="php">
+        <![CDATA[
+<?php
+
+/**
+ * Include the Services_ReCaptcha_MailHide class
+ */
+require_once 'Services/ReCaptcha/MailHide.php';
+
+// you must generate your API keys here:
+// http://mailhide.recaptcha.net/apikey
+$publicKey  = 'your_public_key';
+$privateKey = 'your_private_key';
+
+// we instanciate our Services_ReCaptcha_MailHide instance with the public key
+// and the private key
+$mailhide1 = new Services_ReCaptcha_MailHide(
+    $publicKey,
+    $privateKey,
+    '[email protected]'
+);
+
+$mailhide2 = new Services_ReCaptcha_MailHide(
+    $publicKey,
+    $privateKey,
+    '[email protected]',
+    array('link_text' => 'John Doe')
+);
+
+$mailhide3 = new Services_ReCaptcha_MailHide(
+    $publicKey,
+    $privateKey,
+    '[email protected]'
+);
+$mailhide3->setOptions(
+    array(
+        'link_text'    => 'Click here to display my email',
+        'link_title'   => 'Some help message',
+        'link_title'   => 'Some help message',
+        'popup_width'  => 800,
+        'popup_height' => 600,
+    )
+);
+
+?>
+<html>
+<head>
+    <title>recaptcha test</title>
+</head>
+<body>
+    <h2>Hidden emails can be displayed like this:</h2>
+    <p><?php echo $mailhide1 ?></p>
+    <h2>Like this:</h2>
+    <p><?php echo $mailhide2 ?></p>
+    <h2>And even like this:</h2>
+    <p><?php echo $mailhide3 ?></p>
+</body>
+</html>
+        ]]>
+      </programlisting>
+    </example>
+  </para>
+ </refsection>
+
+</refentry>

Added: pear/peardoc/trunk/en/package/webservices/services-recaptcha/recaptcha.xml
===================================================================
--- pear/peardoc/trunk/en/package/webservices/services-recaptcha/recaptcha.xml	                        (rev 0)
+++ pear/peardoc/trunk/en/package/webservices/services-recaptcha/recaptcha.xml	2010-04-10 13:03:07 UTC (rev 297800)
@@ -0,0 +1,220 @@
+<?xml version="1.0" encoding="utf-8"?>
+<refentry
+ xmlns="http://docbook.org/ns/docbook"
+ xmlns:phd="http://www.php.net/ns/phd"
+ version="lillet"
+ xml:id="package.webservices.services-recaptcha.recaptcha"
+>
+ <refnamediv>
+  <refname>reCAPTCHA</refname>
+  <refpurpose>getting started with the reCAPTCHA functionality of <package>Services_ReCaptcha</package></refpurpose>
+ </refnamediv>
+ <refsection><info><title>Instanciating the <classname>Services_ReCaptcha</classname> class</title></info>
+  <para>
+   To instanciate the Services_ReCaptcha class just do:
+   <programlisting role="php">
+   <![CDATA[
+<?php
+
+require_once 'Services/ReCaptcha.php';
+
+$recaptcha = new Services_ReCaptcha('your_public_key', 'your_private_key');
+
+?>
+   ]]>
+   </programlisting>
+  </para>
+  <para>
+   You can also pass an array of option as third parameter, or pass options
+   later with the
+   <phd:pearapi phd:package="Services_ReCaptcha" phd:linkend="Services_ReCaptcha_Base::setOption"/>
+   or
+   <phd:pearapi phd:package="Services_ReCaptcha" phd:linkend="Services_ReCaptcha_Base::setOptions"/>
+  </para>
+  <para>
+   Available options are:
+   <table>
+    <title>Services_ReCaptcha options</title>
+    <tgroup cols="3">
+     <thead>
+      <row>
+       <entry>Name</entry>
+       <entry>Description</entry>
+       <entry>Type</entry>
+       <entry>Default value</entry>
+      </row>
+     </thead>
+     <tbody>
+      <row>
+       <entry>secure</entry>
+       <entry>Whether to force the ssl url or not</entry>
+       <entry>boolean</entry>
+       <entry>false</entry>
+      </row>
+      <row>
+       <entry>xhtml</entry>
+       <entry>Whether the html should be xhtml compliant or not</entry>
+       <entry>boolean</entry>
+       <entry>true</entry>
+      </row>
+      <row>
+       <entry>theme</entry>
+       <entry>The theme to use for the CAPTCHA</entry>
+       <entry>string</entry>
+       <entry>red</entry>
+      </row>
+      <row>
+       <entry>lang</entry>
+       <entry>The language to use for the CAPTCHA (must be one of the reCATCHA supported languages codes)</entry>
+       <entry>string</entry>
+       <entry>en</entry>
+      </row>
+      <row>
+       <entry>custom_translations</entry>
+       <entry>An array of cutom translations to use</entry>
+       <entry>array</entry>
+       <entry>null</entry>
+      </row>
+      <row>
+       <entry>custom_theme_widget</entry>
+       <entry>The id of the HTML element corresponding to the theme widget</entry>
+       <entry>string</entry>
+       <entry>null</entry>
+      </row>
+      <row>
+       <entry>tabindex</entry>
+       <entry>The HTML tabindex attribute for the reCAPTCHA textarea</entry>
+       <entry>string</entry>
+       <entry>null</entry>
+      </row>
+     </tbody>
+    </tgroup>
+   </table>
+   For more information about these options please consult
+   <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="&url.recaptcha.recaptcha.options;">relevant reCAPTCHA API docs.</link>
+  </para>
+ </refsection>
+
+ <refsection><info><title>A simple recaptcha example</title></info>
+  <para>
+   <example>
+    <programlisting role="php">
+        <![CDATA[
+<?php
+
+/**
+ * Include the Services_ReCaptcha class
+ */
+require_once 'Services/ReCaptcha.php';
+
+// you must get your API keys here:
+// http://recaptcha.net/api/getkey
+$publicKey  = 'your_public_key';
+$privateKey = 'your_private_key';
+
+// we instanciate our Services_ReCaptcha instance with the public key and the
+// private key
+$recaptcha = new Services_ReCaptcha($publicKey, $privateKey);
+
+// if the form was submitted and the catpcha challenge response is ok, we
+// display a message and exit
+if (isset($_POST['submit']) && $recaptcha->validate()) {
+    echo "Challenge response ok !";
+    exit(0);
+}
+
+// we display the html form
+?>
+<html>
+<head>
+    <title>recaptcha test</title>
+</head>
+<body>
+    <form method="post" action="">
+<?php echo $recaptcha; ?>
+        <hr/>
+        <input type="submit" name="submit" value="Ok"/>
+    </form>
+</body>
+</html>
+        ]]>
+    </programlisting>
+   </example>
+  </para>
+ </refsection>
+
+ <refsection><info><title>A more advanced recaptcha example</title></info>
+  <para>
+   <example>
+    <programlisting role="php">
+        <![CDATA[
+<?php
+
+/**
+ * Include the Services_ReCaptcha class
+ */
+require_once 'Services/ReCaptcha.php';
+
+// you must get your API keys here:
+// http://recaptcha.net/api/getkey
+$publicKey  = 'your_public_key';
+$privateKey = 'your_private_key';
+
+// we instanciate our Services_ReCaptcha instance with the public key and the
+// private key
+$recaptcha = new Services_ReCaptcha($publicKey, $privateKey);
+
+// we are going to customize our Services_ReCaptcha instance
+$recaptcha->setOption('secure', true);   // we force the secure url
+$recaptcha->setOption('theme', 'white'); // use the white theme
+$recaptcha->setOption('lang', 'fr');     // set language to french
+
+// alternatively we could have done:
+// $recaptcha = new Services_ReCaptcha($publicKey, $privateKey, array(
+//     'secure' => true,
+//     'theme'  => 'white',
+//     'lang'   => 'fr'
+// ));
+// or:
+// $recaptcha->setOptions(array('theme' => 'white', 'lang' => 'fr'));
+
+// we use a proxy, so we need to configure it
+$recaptcha->getRequest()->setConfig(
+    array('proxy_host' => 'localhost', 'proxy_port' => 8118)
+);
+
+// if the form was submitted
+if (isset($_POST['submit'])) {
+    if ($recaptcha->validate()) {
+        // the catpcha challenge response is ok, we display a message and exit
+        echo "Challenge response ok !";
+        exit(0);
+    } else {
+        // if the captcha validation failed, instead of letting the captcha
+        // display the error, we want to echo the error and exit
+        echo $recaptcha->getError();
+        exit(1);
+    }
+}
+
+// we display the html form
+?>
+<html>
+<head>
+    <title>recaptcha test</title>
+</head>
+<body>
+    <form method="post" action="">
+<?php echo $recaptcha; ?>
+        <hr/>
+        <input type="submit" name="submit" value="Ok"/>
+    </form>
+</body>
+</html>
+        ]]>
+      </programlisting>
+    </example>
+  </para>
+ </refsection>
+
+</refentry>

Added: pear/peardoc/trunk/en/package/webservices/services-recaptcha.xml
===================================================================
--- pear/peardoc/trunk/en/package/webservices/services-recaptcha.xml	                        (rev 0)
+++ pear/peardoc/trunk/en/package/webservices/services-recaptcha.xml	2010-04-10 13:03:07 UTC (rev 297800)
@@ -0,0 +1,25 @@
+<?xml version="1.0" encoding="utf-8"?>
+<book
+ xmlns="http://docbook.org/ns/docbook"
+ xmlns:phd="http://www.php.net/ns/phd"
+ version="lillet"
+ xml:id="package.webservices.services-recaptcha"
+>
+ <info>
+  <title>Services_ReCaptcha</title>
+  <abstract>
+   <para>
+    <phd:pearapi phd:package="Services_ReCaptcha" phd:linkend="Services_ReCaptcha"/>
+    is a PHP5 interface to the two services offered by recaptcha:
+    <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="&url.recaptcha.recaptcha;">reCAPTCHA</link> and
+    <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="&url.recaptcha.mailhide;">reCAPTCHA Mailhide</link>.
+   </para>
+  </abstract>
+ </info>
+
+ <chapter>
+  &package.webservices.services-recaptcha.intro;
+  &package.webservices.services-recaptcha.recaptcha;
+  &package.webservices.services-recaptcha.mailhide;
+ </chapter>
+</book>

Modified: pear/peardoc/trunk/en/package/webservices-entities.xml
===================================================================
--- pear/peardoc/trunk/en/package/webservices-entities.xml	2010-04-10 11:53:21 UTC (rev 297799)
+++ pear/peardoc/trunk/en/package/webservices-entities.xml	2010-04-10 13:03:07 UTC (rev 297800)
@@ -5,6 +5,7 @@
 &package.webservices.services-ebay;
 &package.webservices.services-geonames;
 &package.webservices.services-google;
+&package.webservices.services-recaptcha;
 &package.webservices.services-technorati;
 &package.webservices.services-w3c-htmlvalidator;
 &package.webservices.services-weather;

Modified: pear/peardoc/trunk/entities/global.ent
===================================================================
--- pear/peardoc/trunk/entities/global.ent	2010-04-10 11:53:21 UTC (rev 297799)
+++ pear/peardoc/trunk/entities/global.ent	2010-04-10 13:03:07 UTC (rev 297800)
@@ -144,6 +144,11 @@
 <!ENTITY url.phpunit 'http://www.phpunit.de/'>
 <!ENTITY url.phpunit.get 'http://pear.phpunit.de/get/'>
 <!ENTITY url.python.doc.modindex.optparse 'http://docs.python.org/library/module-optparse.html'>
+<!ENTITY url.recaptcha.recaptcha 'http://recaptcha.net/apidocs/captcha/'>
+<!ENTITY url.recaptcha.recaptcha.getapikey 'http://recaptcha.net/api/getkey'>
+<!ENTITY url.recaptcha.recaptcha.options 'http://recaptcha.net/apidocs/captcha/client.html'>
+<!ENTITY url.recaptcha.mailhide 'http://recaptcha.net/apidocs/mailhide/'>
+<!ENTITY url.recaptcha.mailhide.getapikey 'http://mailhide.recaptcha.net/apikey'>
 <!ENTITY url.rest.chanservongooglecode 'http://docs.google.com/present/view?id=dgstxrxv_6f48xbz'>
 <!ENTITY url.rss.info 'http://tech.groups.yahoo.com/group/rss-dev/files/specification.html'>
 <!ENTITY url.simplechannelserver 'http://svn.php.net/viewvc/pear2/sandbox/SimpleChannelServer/trunk/'>