Merge pull request #295 from eddieajau/documentation

Adds examples for three CLI applications

examples/applications/101-hello-world/run.php

@@ -0,0 +1,60 @@
+#!/usr/bin/php
+<?php
+/**
+ * A "hello world" command line application built on the Joomla Platform.
+ *
+ * To run this example, adjust the executable path above to suite your operating system,
+ * make this file executable and run the file.
+ *
+ * Alternatively, run the file using:
+ *
+ * php -f run.php
+ *
+ * @package    Joomla.Examples
+ * @copyright  Copyright (C) 2005 - 2011 Open Source Matters, Inc. All rights reserved.
+ * @license    GNU General Public License version 2 or later; see LICENSE
+ */
+
+// We are a valid Joomla entry point.
+// This is required to load the Joomla Platform import.php file.
+define('_JEXEC', 1);
+
+// Setup the base path related constant.
+// This is one of the few, mandatory constants needed for the Joomla Platform.
+define('JPATH_BASE', dirname(__FILE__));
+
+// Bootstrap the application.
+require dirname(dirname(dirname(dirname(__FILE__)))).'/libraries/import.php';
+
+// Import the JCli class from the platform.
+jimport('joomla.application.cli');
+
+/**
+ * A "hello world" command line application class.
+ *
+ * Simple command line applications extend the JCli class.
+ *
+ * @package  Joomla.Examples
+ * @since    11.3
+ */
+class HelloWorld extends JCli
+{
+	/**
+	 * Execute the application.
+	 *
+	 * The 'execute' method is the entry point for a command line application.
+	 *
+	 * @return  void
+	 *
+	 * @since   11.3
+	 */
+	public function execute()
+	{
+		// Send a string to standard output.
+		$this->out('Hello world!');
+	}
+}
+
+// Instantiate the application object, passing the class name to JCli::getInstance
+// and use chaining to execute the application.
+JCli::getInstance('HelloWorld')->execute();

examples/applications/argv/run.php

@@ -0,0 +1,134 @@
+#!/usr/bin/php
+<?php
+/**
+ * An example command line application built on the Joomla Platform.
+ *
+ * To run this example, adjust the executable path above to suite your operating system,
+ * make this file executable and run the file.
+ *
+ * @package    Joomla.Examples
+ * @copyright  Copyright (C) 2005 - 2011 Open Source Matters, Inc. All rights reserved.
+ * @license    GNU General Public License version 2 or later; see LICENSE
+ */
+
+// We are a valid Joomla entry point.
+define('_JEXEC', 1);
+
+// Setup the base path related constant.
+define('JPATH_BASE', dirname(__FILE__));
+
+// Bootstrap the application.
+require dirname(dirname(dirname(dirname(__FILE__)))).'/libraries/import.php';
+
+// Import the JCli class from the platform.
+jimport('joomla.application.cli');
+
+/**
+ * An example command line application class.
+ *
+ * This application shows how to access configuration file values.
+ *
+ * @package  Joomla.Examples
+ * @since    11.3
+ */
+class Argv extends JCli
+{
+	/**
+	 * Execute the application.
+	 *
+	 * @return  void
+	 *
+	 * @since   11.3
+	 */
+	public function execute()
+	{
+		// Print a blank line.
+		$this->out();
+		$this->out('JOOMLA PLATFORM ARGV EXAMPLE');
+		$this->out('============================');
+		$this->out();
+
+		// You can look for named command line arguments in the form of:
+		// (a) -n value
+		// (b) --name=value
+		//
+		// Try running file like this:
+		// $ ./run.php -fa
+		// $ ./run.php -f foo
+		// $ ./run.php --set=match
+		//
+		// The values are accessed using the $this->input->get() method.
+		// $this->input is an instance of a JInputCli object.
+
+		// This is an example of an option using short args (-).
+		$value = $this->input->get('a');
+		$this->out(
+			sprintf(
+				'%25s = %s', 'a',
+				var_export($value, true)
+			)
+		);
+
+		$value = $this->input->get('f');
+		$this->out(
+			sprintf(
+				'%25s = %s', 'f',
+				var_export($value, true)
+			)
+		);
+
+		// This is an example of an option using long args (--).
+		$value = $this->input->get('set');
+		$this->out(
+			sprintf(
+				'%25s = %s', 'set',
+				var_export($value, true)
+			)
+		);
+
+		// You can also apply defaults to the command line options.
+		$value = $this->input->get('f', 'default');
+		$this->out(
+			sprintf(
+				'%25s = %s', 'f (with default)',
+				var_export($value, true)
+			)
+		);
+
+		// You can also apply input filters found in the JFilterInput class.
+		// Try running this file like this:
+		// $ ./run.php -f one2
+
+		$value = $this->input->get('f', 0, 'INT');
+		$this->out(
+			sprintf(
+				'%25s = %s', 'f (cast to int)',
+				var_export($value, true)
+			)
+		);
+
+		// Print out all the remaining command line arguments used to run this file.
+		if (!empty($this->input->args))
+		{
+			$this->out();
+			$this->out('These are the remaining arguments passed:');
+			$this->out();
+
+			// Unallocated arguments are found in $this->input->args.
+			// Try running the file like this:
+			// $ ./run.php -f foo bar
+
+			foreach ($this->input->args as $arg)
+			{
+				$this->out($arg);
+			}
+		}
+
+		// Print a blank line at the end.
+		$this->out();
+	}
+}
+
+// Instantiate the application object, passing the class name to JCli::getInstance
+// and use chaining to execute the application.
+JCli::getInstance('Argv')->execute();

examples/applications/show-config/configuration.php

@@ -0,0 +1,48 @@
+<?php
+/**
+ * An example configuration file for an application built on the Joomla Platform.
+ *
+ * This file will be automatically loaded by the command line application.
+ *
+ * @package    Joomla.Examples
+ * @copyright  Copyright (C) 2005 - 2011 Open Source Matters, Inc. All rights reserved.
+ * @license    GNU General Public License version 2 or later; see LICENSE
+ */
+
+// Prevent direct access to this file outside of a calling application.
+defined('_JEXEC') or die;
+
+/**
+ * An example configuration class for a Joomla Platform application.
+ *
+ * Declare each configuration value as a public property of this class.
+ *
+ * @package  Joomla.Examples
+ * @since    11.3
+ */
+final class JConfig
+{
+	/**
+	 * A configuration value.
+	 *
+	 * @var    integer
+	 * @since  11.3
+	 */
+	public $weapons = 10;
+
+	/**
+	 * A configuration value.
+	 *
+	 * @var    integer
+	 * @since  11.3
+	 */
+	public $armour = 9;
+
+	/**
+	 * A configuration value.
+	 *
+	 * @var    float
+	 * @since  11.3
+	 */
+	public $health = 8.0;
+}

examples/applications/show-config/run.php

@@ -0,0 +1,125 @@
+#!/usr/bin/php
+<?php
+/**
+ * An example command line application built on the Joomla Platform.
+ *
+ * To run this example, adjust the executable path above to suite your operating system,
+ * make this file executable and run the file.
+ *
+ * Alternatively, run the file using:
+ *
+ * php -f run.php
+ *
+ * @package    Joomla.Examples
+ * @copyright  Copyright (C) 2005 - 2011 Open Source Matters, Inc. All rights reserved.
+ * @license    GNU General Public License version 2 or later; see LICENSE
+ */
+
+// We are a valid Joomla entry point.
+define('_JEXEC', 1);
+
+// Setup the base path related constant.
+define('JPATH_BASE', dirname(__FILE__));
+
+// Bootstrap the application.
+require dirname(dirname(dirname(dirname(__FILE__)))).'/libraries/import.php';
+
+// Import the JCli class from the platform.
+jimport('joomla.application.cli');
+
+/**
+ * An example command line application class.
+ *
+ * This application shows how to access configuration file values.
+ *
+ * @package  Joomla.Examples
+ * @since    11.3
+ */
+class ShowConfig extends JCli
+{
+	/**
+	 * Execute the application.
+	 *
+	 * @return  void
+	 *
+	 * @since   11.3
+	 */
+	public function execute()
+	{
+		// Print a blank line and new heading.
+		$this->out();
+		$this->out('Configuration settings loaded from configuration.php:');
+
+		// JCli will automatically look for and load 'configuration.php'.
+		// Use the 'get' method to access any configuration properties.
+		$this->out(
+			sprintf(
+				'%-25s = %2d', 'Default weapon strength',
+				$this->get('weapons')
+			)
+		);
+
+		$this->out(
+			sprintf(
+				'%-25s = %2d', 'Default armour rating',
+				$this->get('armour')
+			)
+		);
+
+		$this->out(
+			sprintf(
+				'%-25s = %4.1f', 'Default health level',
+				$this->get('health')
+			)
+		);
+
+		// Print a blank line and new heading.
+		$this->out();
+		$this->out('System settings:');
+
+		// There are also a number of built in properties available, for example:
+		$this->out(
+			sprintf(
+				'%-25s = %s', 'cwd',
+				$this->get('cwd')
+			)
+		);
+
+		$this->out(
+			sprintf(
+				'%-25s = %s', 'execution.timestamp',
+				$this->get('execution.timestamp')
+			)
+		);
+
+		$this->out(
+			sprintf(
+				'%-25s = %s', 'execution.timestamp',
+				$this->get('execution.timestamp')
+			)
+		);
+
+		// Print a blank line and new heading.
+		$this->out();
+		$this->out('Custom settings:');
+
+		// We can also make custom settings during the execution of the the application using the 'set' method.
+		$this->set('race', 'elf');
+
+		$this->out(
+			sprintf(
+				'%-25s = %s', 'Race',
+				$this->get('race')
+			)
+		);
+
+		// Finish up.
+		$this->out();
+		$this->out('Thanks for playing!');
+		$this->out();
+	}
+}
+
+// Instantiate the application object, passing the class name to JCli::getInstance
+// and use chaining to execute the application.
+JCli::getInstance('ShowConfig')->execute();

libraries/joomla/application/cli.php

@@ -27,7 +27,7 @@ class JCli
 	/**
 	 * The application input object.
 	 *
-	 * @var    JInput
+	 * @var    JInputCli
 	 * @since  11.1
 	 */
 	public $input;