PEAR
[ class tree: PEAR ] [ index: PEAR ] [ all elements ]

Source for file Command.php

Documentation is available at Command.php

  1. <?php
  2. /**
  3.  * PEAR_Command, command pattern class
  4.  *
  5.  * PHP versions 4 and 5
  6.  *
  7.  * @category   pear
  8.  * @package    PEAR
  9.  * @author     Stig Bakken <ssb@php.net>
  10.  * @author     Greg Beaver <cellog@php.net>
  11.  * @copyright  1997-2009 The Authors
  12.  * @license    http://opensource.org/licenses/bsd-license.php New BSD License
  13.  * @version    CVS: $Id: Command.php 313023 2011-07-06 19:17:11Z dufuz $
  14.  * @link       http://pear.php.net/package/PEAR
  15.  * @since      File available since Release 0.1
  16.  */
  17.  
  18. /**
  19.  * Needed for error handling
  20.  */
  21. require_once 'PEAR.php';
  22. require_once 'PEAR/Frontend.php';
  23. require_once 'PEAR/XMLParser.php';
  24.  
  25. /**
  26.  * List of commands and what classes they are implemented in.
  27.  * @var array command => implementing class
  28.  */
  29. $GLOBALS['_PEAR_Command_commandlist'= array();
  30.  
  31. /**
  32.  * List of commands and their descriptions
  33.  * @var array command => description
  34.  */
  35. $GLOBALS['_PEAR_Command_commanddesc'= array();
  36.  
  37. /**
  38.  * List of shortcuts to common commands.
  39.  * @var array shortcut => command
  40.  */
  41. $GLOBALS['_PEAR_Command_shortcuts'= array();
  42.  
  43. /**
  44.  * Array of command objects
  45.  * @var array class => object
  46.  */
  47. $GLOBALS['_PEAR_Command_objects'= array();
  48.  
  49. /**
  50.  * PEAR command class, a simple factory class for administrative
  51.  * commands.
  52.  *
  53.  * How to implement command classes:
  54.  *
  55.  * - The class must be called PEAR_Command_Nnn, installed in the
  56.  *   "PEAR/Common" subdir, with a method called getCommands() that
  57.  *   returns an array of the commands implemented by the class (see
  58.  *   PEAR/Command/Install.php for an example).
  59.  *
  60.  * - The class must implement a run() function that is called with three
  61.  *   params:
  62.  *
  63.  *    (string) command name
  64.  *    (array)  assoc array with options, freely defined by each
  65.  *             command, for example:
  66.  *             array('force' => true)
  67.  *    (array)  list of the other parameters
  68.  *
  69.  *   The run() function returns a PEAR_CommandResponse object.  Use
  70.  *   these methods to get information:
  71.  *
  72.  *    int getStatus()   Returns PEAR_COMMAND_(SUCCESS|FAILURE|PARTIAL)
  73.  *                      *_PARTIAL means that you need to issue at least
  74.  *                      one more command to complete the operation
  75.  *                      (used for example for validation steps).
  76.  *
  77.  *    string getMessage()  Returns a message for the user.  Remember,
  78.  *                         no HTML or other interface-specific markup.
  79.  *
  80.  *   If something unexpected happens, run() returns a PEAR error.
  81.  *
  82.  * - DON'T OUTPUT ANYTHING! Return text for output instead.
  83.  *
  84.  * - DON'T USE HTML! The text you return will be used from both Gtk,
  85.  *   web and command-line interfaces, so for now, keep everything to
  86.  *   plain text.
  87.  *
  88.  * - DON'T USE EXIT OR DIE! Always use pear errors.  From static
  89.  *   classes do PEAR::raiseError(), from other classes do
  90.  *   $this->raiseError().
  91.  * @category   pear
  92.  * @package    PEAR
  93.  * @author     Stig Bakken <ssb@php.net>
  94.  * @author     Greg Beaver <cellog@php.net>
  95.  * @copyright  1997-2009 The Authors
  96.  * @license    http://opensource.org/licenses/bsd-license.php New BSD License
  97.  * @version    Release: 1.9.4
  98.  * @link       http://pear.php.net/package/PEAR
  99.  * @since      Class available since Release 0.1
  100.  */
  101. {
  102.     // {{{ factory()
  103.  
  104.     /**
  105.      * Get the right object for executing a command.
  106.      *
  107.      * @param string $command The name of the command
  108.      * @param object $config  Instance of PEAR_Config object
  109.      *
  110.      * @return object the command object or a PEAR error
  111.      *
  112.      * @access public
  113.      * @static
  114.      */
  115.     function &factory($command&$config)
  116.     {
  117.         if (empty($GLOBALS['_PEAR_Command_commandlist'])) {
  118.             PEAR_Command::registerCommands();
  119.         }
  120.         if (isset($GLOBALS['_PEAR_Command_shortcuts'][$command])) {
  121.             $command $GLOBALS['_PEAR_Command_shortcuts'][$command];
  122.         }
  123.         if (!isset($GLOBALS['_PEAR_Command_commandlist'][$command])) {
  124.             $a PEAR::raiseError("unknown command `$command'");
  125.             return $a;
  126.         }
  127.         $class $GLOBALS['_PEAR_Command_commandlist'][$command];
  128.         if (!class_exists($class)) {
  129.             require_once $GLOBALS['_PEAR_Command_objects'][$class];
  130.         }
  131.         if (!class_exists($class)) {
  132.             $a PEAR::raiseError("unknown command `$command'");
  133.             return $a;
  134.         }
  135.         $ui =PEAR_Command::getFrontendObject();
  136.         $obj &new $class($ui$config);
  137.         return $obj;
  138.     }
  139.  
  140.     // }}}
  141.     // {{{ & getObject()
  142.     function &getObject($command)
  143.     {
  144.         $class $GLOBALS['_PEAR_Command_commandlist'][$command];
  145.         if (!class_exists($class)) {
  146.             require_once $GLOBALS['_PEAR_Command_objects'][$class];
  147.         }
  148.         if (!class_exists($class)) {
  149.             return PEAR::raiseError("unknown command `$command'");
  150.         }
  151.         $ui =PEAR_Command::getFrontendObject();
  152.         $config &PEAR_Config::singleton();
  153.         $obj &new $class($ui$config);
  154.         return $obj;
  155.     }
  156.  
  157.     // }}}
  158.     // {{{ & getFrontendObject()
  159.  
  160.     /**
  161.      * Get instance of frontend object.
  162.      *
  163.      * @return object|PEAR_Error
  164.      * @static
  165.      */
  166.     function &getFrontendObject()
  167.     {
  168.         $a &PEAR_Frontend::singleton();
  169.         return $a;
  170.     }
  171.  
  172.     // }}}
  173.     // {{{ & setFrontendClass()
  174.  
  175.     /**
  176.      * Load current frontend class.
  177.      *
  178.      * @param string $uiclass Name of class implementing the frontend
  179.      *
  180.      * @return object the frontend object, or a PEAR error
  181.      * @static
  182.      */
  183.     function &setFrontendClass($uiclass)
  184.     {
  185.         $a &PEAR_Frontend::setFrontendClass($uiclass);
  186.         return $a;
  187.     }
  188.  
  189.     // }}}
  190.     // {{{ setFrontendType()
  191.  
  192.     /**
  193.      * Set current frontend.
  194.      *
  195.      * @param string $uitype Name of the frontend type (for example "CLI")
  196.      *
  197.      * @return object the frontend object, or a PEAR error
  198.      * @static
  199.      */
  200.     function setFrontendType($uitype)
  201.     {
  202.         $uiclass 'PEAR_Frontend_' $uitype;
  203.         return PEAR_Command::setFrontendClass($uiclass);
  204.     }
  205.  
  206.     // }}}
  207.     // {{{ registerCommands()
  208.  
  209.     /**
  210.      * Scan through the Command directory looking for classes
  211.      * and see what commands they implement.
  212.      *
  213.      * @param bool   (optional) if FALSE (default), the new list of
  214.      *                commands should replace the current one.  If TRUE,
  215.      *                new entries will be merged with old.
  216.      *
  217.      * @param string (optional) where (what directory) to look for
  218.      *                classes, defaults to the Command subdirectory of
  219.      *                the directory from where this file (__FILE__) is
  220.      *                included.
  221.      *
  222.      * @return bool TRUE on success, a PEAR error on failure
  223.      *
  224.      * @access public
  225.      * @static
  226.      */
  227.     function registerCommands($merge = false$dir = null)
  228.     {
  229.         $parser = new PEAR_XMLParser;
  230.         if ($dir === null{
  231.             $dir dirname(__FILE__'/Command';
  232.         }
  233.         if (!is_dir($dir)) {
  234.             return PEAR::raiseError("registerCommands: opendir($dir) '$dir' does not exist or is not a directory");
  235.         }
  236.         $dp @opendir($dir);
  237.         if (empty($dp)) {
  238.             return PEAR::raiseError("registerCommands: opendir($dir) failed");
  239.         }
  240.         if (!$merge{
  241.             $GLOBALS['_PEAR_Command_commandlist'= array();
  242.         }
  243.  
  244.         while ($file readdir($dp)) {
  245.             if ($file{0== '.' || substr($file-4!= '.xml'{
  246.                 continue;
  247.             }
  248.  
  249.             $f substr($file0-4);
  250.             $class "PEAR_Command_" $f;
  251.             // List of commands
  252.             if (empty($GLOBALS['_PEAR_Command_objects'][$class])) {
  253.                 $GLOBALS['_PEAR_Command_objects'][$class= "$dir/" . $f '.php';
  254.             }
  255.  
  256.             $parser->parse(file_get_contents("$dir/$file"));
  257.             $implements $parser->getData();
  258.             foreach ($implements as $command => $desc{
  259.                 if ($command == 'attribs'{
  260.                     continue;
  261.                 }
  262.  
  263.                 if (isset($GLOBALS['_PEAR_Command_commandlist'][$command])) {
  264.                     return PEAR::raiseError('Command "' $command '" already registered in ' .
  265.                         'class "' $GLOBALS['_PEAR_Command_commandlist'][$command'"');
  266.                 }
  267.  
  268.                 $GLOBALS['_PEAR_Command_commandlist'][$command$class;
  269.                 $GLOBALS['_PEAR_Command_commanddesc'][$command$desc['summary'];
  270.                 if (isset($desc['shortcut'])) {
  271.                     $shortcut $desc['shortcut'];
  272.                     if (isset($GLOBALS['_PEAR_Command_shortcuts'][$shortcut])) {
  273.                         return PEAR::raiseError('Command shortcut "' $shortcut '" already ' .
  274.                             'registered to command "' $command '" in class "' .
  275.                             $GLOBALS['_PEAR_Command_commandlist'][$command'"');
  276.                     }
  277.                     $GLOBALS['_PEAR_Command_shortcuts'][$shortcut$command;
  278.                 }
  279.  
  280.                 if (isset($desc['options']&& $desc['options']{
  281.                     foreach ($desc['options'as $oname => $option{
  282.                         if (isset($option['shortopt']&& strlen($option['shortopt']> 1{
  283.                             return PEAR::raiseError('Option "' $oname '" short option "' .
  284.                                 $option['shortopt''" must be ' .
  285.                                 'only 1 character in Command "' $command '" in class "' .
  286.                                 $class '"');
  287.                         }
  288.                     }
  289.                 }
  290.             }
  291.         }
  292.  
  293.         ksort($GLOBALS['_PEAR_Command_shortcuts']);
  294.         ksort($GLOBALS['_PEAR_Command_commandlist']);
  295.         @closedir($dp);
  296.         return true;
  297.     }
  298.  
  299.     // }}}
  300.     // {{{ getCommands()
  301.  
  302.     /**
  303.      * Get the list of currently supported commands, and what
  304.      * classes implement them.
  305.      *
  306.      * @return array command => implementing class
  307.      *
  308.      * @access public
  309.      * @static
  310.      */
  311.     function getCommands()
  312.     {
  313.         if (empty($GLOBALS['_PEAR_Command_commandlist'])) {
  314.             PEAR_Command::registerCommands();
  315.         }
  316.         return $GLOBALS['_PEAR_Command_commandlist'];
  317.     }
  318.  
  319.     // }}}
  320.     // {{{ getShortcuts()
  321.  
  322.     /**
  323.      * Get the list of command shortcuts.
  324.      *
  325.      * @return array shortcut => command
  326.      *
  327.      * @access public
  328.      * @static
  329.      */
  330.     function getShortcuts()
  331.     {
  332.         if (empty($GLOBALS['_PEAR_Command_shortcuts'])) {
  333.             PEAR_Command::registerCommands();
  334.         }
  335.         return $GLOBALS['_PEAR_Command_shortcuts'];
  336.     }
  337.  
  338.     // }}}
  339.     // {{{ getGetoptArgs()
  340.  
  341.     /**
  342.      * Compiles arguments for getopt.
  343.      *
  344.      * @param string $command     command to get optstring for
  345.      * @param string $short_args  (reference) short getopt format
  346.      * @param array  $long_args   (reference) long getopt format
  347.      *
  348.      * @return void 
  349.      *
  350.      * @access public
  351.      * @static
  352.      */
  353.     function getGetoptArgs($command&$short_args&$long_args)
  354.     {
  355.         if (empty($GLOBALS['_PEAR_Command_commandlist'])) {
  356.             PEAR_Command::registerCommands();
  357.         }
  358.         if (isset($GLOBALS['_PEAR_Command_shortcuts'][$command])) {
  359.             $command $GLOBALS['_PEAR_Command_shortcuts'][$command];
  360.         }
  361.         if (!isset($GLOBALS['_PEAR_Command_commandlist'][$command])) {
  362.             return null;
  363.         }
  364.         $obj &PEAR_Command::getObject($command);
  365.         return $obj->getGetoptArgs($command$short_args$long_args);
  366.     }
  367.  
  368.     // }}}
  369.     // {{{ getDescription()
  370.  
  371.     /**
  372.      * Get description for a command.
  373.      *
  374.      * @param  string $command Name of the command
  375.      *
  376.      * @return string command description
  377.      *
  378.      * @access public
  379.      * @static
  380.      */
  381.     function getDescription($command)
  382.     {
  383.         if (!isset($GLOBALS['_PEAR_Command_commanddesc'][$command])) {
  384.             return null;
  385.         }
  386.         return $GLOBALS['_PEAR_Command_commanddesc'][$command];
  387.     }
  388.  
  389.     // }}}
  390.     // {{{ getHelp()
  391.  
  392.     /**
  393.      * Get help for command.
  394.      *
  395.      * @param string $command Name of the command to return help for
  396.      *
  397.      * @access public
  398.      * @static
  399.      */
  400.     function getHelp($command)
  401.     {
  402.         $cmds PEAR_Command::getCommands();
  403.         if (isset($GLOBALS['_PEAR_Command_shortcuts'][$command])) {
  404.             $command $GLOBALS['_PEAR_Command_shortcuts'][$command];
  405.         }
  406.         if (isset($cmds[$command])) {
  407.             $obj &PEAR_Command::getObject($command);
  408.             return $obj->getHelp($command);
  409.         }
  410.         return false;
  411.     }
  412.     // }}}
  413. }

Documentation generated on Wed, 06 Jul 2011 23:30:33 +0000 by phpDocumentor 1.4.3. PEAR Logo Copyright © PHP Group 2004.