cvs: peardoc /en/package/console console-commandline.xml /en/package/console/console-commandline web.xml /en/package/console/console-commandline/examples web-2.php web.php

http://cvs.php.net/viewvc.cgi/peardoc/en/package/console/console-commandline.xml?r1=1.10&r2=1.11&diff_format=u
Index: peardoc/en/package/console/console-commandline.xml
diff -u peardoc/en/package/console/console-commandline.xml:1.10 peardoc/en/package/console/console-commandline.xml:1.11
--- peardoc/en/package/console/console-commandline.xml:1.10	Sat Dec  6 15:01:01 2008
+++ peardoc/en/package/console/console-commandline.xml	Sat Jun 13 09:04:14 2009
@@ -26,6 +26,7 @@
   &package.console.console-commandline.arguments;
   &package.console.console-commandline.sub-commands;
   &package.console.console-commandline.extending;
+  &package.console.console-commandline.web;
   &package.console.console-commandline.examples;
  </chapter>
 </book>

http://cvs.php.net/viewvc.cgi/peardoc/en/package/console/console-commandline/web.xml?view=markup&rev=1.1
Index: peardoc/en/package/console/console-commandline/web.xml
+++ peardoc/en/package/console/console-commandline/web.xml
<?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.console.console-commandline.web"
>
 <refnamediv>
  <refname>Using Console_CommandLine in web environments</refname>
  <refpurpose>How to use the same script from your browser</refpurpose>
 </refnamediv>

 <refsection>
  <info>
   <title>Introduction</title>
  </info>
  <para>
   So there is a nice shell script that does everything it ever should do,
   and other people - without shell access - have to use it now.
   Or the script needs to be called
   regularly from outside the server it is running on. What now?
  </para>
  <para>
   If your server runs a HTTP server with PHP, the problem is already solved
   because <classname>Console_Commandline</classname> supports reading HTTP
   <literal>$_GET</literal> and <literal>$_POST</literal> variables
   out of the box.
  </para>
 </refsection>
 
 <refsection>
  <info>
   <title>A simple example</title>
  </info>
  <para>
   The scripts task in this example is to print out the current time. The
   user may customize the output by specifying the format string.
  </para>
  <para>
   Between shell and web access is only one difference: On the web, the text
   shall be printed out in large letters by wrapping it in a
   <literal>h1</literal> tag.
  </para>
  <para>
   <classname>Console_CommandLine</classname> by itself cares about reading
   HTTP GET and POST variables when it is run through PHP's CGI or web
   server (e.g. Apache with <literal>mod_php</literal>). Let's try it:
  </para>

  <programlisting role="php">
   <xi:include parse="text"
    xmlns:xi="http://www.w3.org/2001/XInclude"
    href="&package.console.console-commandline.examples.web.php;"
   >
    <xi:fallback>FIXME:MISSING XINCLUDE CONTENT</xi:fallback>
   </xi:include>
  </programlisting>
  
  <example>
   <info>
    <title>Shell output</title>
   </info>
   <screen><![CDATA[$ php web.php 
2009-06-13 10:10:15
$ php web.php --help
Print out the current time

Usage:
  web.php [options]

Options:
  -f format, --format=format  date()-compatible format string
  -h, --help                  show this help message and exit
  -v, --version               show the program version and exit

$ php web.php --format=d.m.Y
13.06.2009]]></screen>
  </example>
  
  <example>
   <info>
    <title>Web output without parameters</title>
   </info>
   <screen><![CDATA[2009-06-13 10:10:15]]></screen>
  </example>
  
  <example>
   <info>
    <title>Web output for web.php?--help</title>
   </info>
   <screen><![CDATA[Print out the current time Usage: --help [options]
Options: -f format, --format=format date()-compatible format string -h,
--help show this help message and exit -v, --version show the program
version and exit]]></screen>
  </example>
  
  <example>
   <info>
    <title>Web output for web.php?format=d.m.Y</title>
   </info>
   <screen><![CDATA[13.06.2009]]></screen>
  </example>
  
  <para>
   The functionality is there, but it does not look nice.
  </para>
  
  <note>
   <para>
    When using <literal>GET</literal> and <literal>POST</literal>
    parameters, <classname>Console_CommandLine</classname> accepts
    three types of parameter names:
   </para>
   <itemizedlist>
    <listitem>
     <para><literal>short_name</literal> as configured for the option</para>
    </listitem>
    <listitem>
     <para><literal>long_name</literal> as configured</para>
    </listitem>
    <listitem>
     <para><emphasis>option name</emphasis> as passed as first parameter
      to <phd:pearapi phd:package="Console_CommandLine"
       phd:linkend="Console_CommandLine::addOption"
      />.
     </para>
    </listitem>
   </itemizedlist>
   <para>
    So in our example, one can call
   </para>
   <itemizedlist>
    <listitem>
     <para><literal>web.php?-f=d.m.Y</literal></para>
    </listitem>
    <listitem>
     <para><literal>web.php?--format=d.m.Y</literal></para>
    </listitem>
    <listitem>
     <para><literal>web.php?format=d.m.Y</literal></para>
    </listitem>
   </itemizedlist>
  </note>
 </refsection>


 <refsection>
  <info>
   <title>A prettier example</title>
  </info>
  
  <para>
   Building upon our previous example, we care about pretty output here:
  </para>
  <itemizedlist>
   <listitem>
    <para>Time wrapped in <literal>h1</literal> tags.</para>
   </listitem>
   <listitem>
    <para>Monospaced help text</para>
   </listitem>
   <listitem>
    <para>Monospaced error text</para>
   </listitem>
  </itemizedlist>
  
  <para>
   While we did not catch any errors - as there are nearly none to produce
   in that example - the code contains it now for completeness.
  </para>
  
  <para>
   First and foremost, we check if we are in an HTTP environment by checking
   the SAPI (Server API) name. If we are not in CLI, we echo out
   <literal>&lt;h1&gt;</literal> and <literal>&lt;/h1&gt;</literal>.
  </para>
  <para>
   To get the help text printed with monospaced text, a custom
   <phd:pearapi phd:package="Console_CommandLine"
    phd:linkend="Console_CommandLine_Renderer">renderer</phd:pearapi>
   is defined. For the sake of easiness, the
   <phd:pearapi phd:package="Console_CommandLine"
    phd:linkend="Console_CommandLine_Renderer_Default">default console
   renderer</phd:pearapi> is extendet since it does nearly everything we
   need here.
  </para>

  <programlisting role="php">
   <xi:include parse="text"
    xmlns:xi="http://www.w3.org/2001/XInclude"
    href="&package.console.console-commandline.examples.web-2.php;"
   >
    <xi:fallback>FIXME:MISSING XINCLUDE CONTENT</xi:fallback>
   </xi:include>
  </programlisting>
  
  
 </refsection>
</refentry>

http://cvs.php.net/viewvc.cgi/peardoc/en/package/console/console-commandline/examples/web-2.php?view=markup&rev=1.1
Index: peardoc/en/package/console/console-commandline/examples/web-2.php
+++ peardoc/en/package/console/console-commandline/examples/web-2.php
<?php
require_once 'Console/CommandLine.php';
$parser = new Console_CommandLine();
$parser->description = 'Print out the current time';
$parser->version     = '1.23';
$parser->addOption(
    'format',
    array(
        'short_name'  => '-f',
        'long_name'   => '--format',
        'action'      => 'StoreString',
        'default'     => 'Y-m-d H:i:s',
        'description' => 'date()-compatible format string',
    )
);

class HtmlRenderer extends Console_CommandLine_Renderer_Default
{
    public function usage()
    {
        return '<pre>' . parent::usage() . '</pre>';
    }
    
    public function error($error)
    {
        return '<pre>' . parent::error($error) . '</pre>';
    }
}

$parser->accept(new HtmlRenderer());

$http = (php_sapi_name() != 'cli');
try {
   $result = $parser->parse();
   if ($http) {
       echo '<h1>';
   }
   echo date($result->options['format']) . "\n";
   if ($http) {
       echo '</h1>';
   }
} catch (Exception $exc) {
   $parser->displayError($exc->getMessage());
}
?>
http://cvs.php.net/viewvc.cgi/peardoc/en/package/console/console-commandline/examples/web.php?view=markup&rev=1.1
Index: peardoc/en/package/console/console-commandline/examples/web.php
+++ peardoc/en/package/console/console-commandline/examples/web.php
<?php
require_once 'Console/CommandLine.php';
$parser = new Console_CommandLine();
$parser->description = 'Print out the current time';
$parser->version     = '1.23';
$parser->addOption(
    'format',
    array(
        'short_name'  => '-f',
        'long_name'   => '--format',
        'action'      => 'StoreString',
        'default'     => 'Y-m-d H:i:s',
        'description' => 'date()-compatible format string',
    )
);

$result = $parser->parse();
echo date($result->options['format']) . "\n";
?>