Joomla! Documentation - User contributions [en]

Selecting data using JDatabase

2019-10-19T06:30:29Z

Mickmackusa: implemented the chained syntax recommended earlier on the same page, added spaces around concatenating dots

Selecting data using JDatabase

2019-10-19T06:22:18Z

Mickmackusa: adding and removing spaces in snippets

Selecting data using JDatabase

2019-10-19T06:20:37Z

Mickmackusa: it is entirely useless to add parentheses to ON statements that only have one expression

Selecting data using JDatabase

2019-10-19T06:11:55Z

Mickmackusa: fixed redundant/incorrect single quotes within quote()

Joomla and MySQL 8

2019-10-19T06:00:34Z

Mickmackusa: improved English

<noinclude><languages /></noinclude>
<translate>
==MySQL default authentication plugin issue== 
</translate>
<translate> It's not possible to connect to a MySQL 8 Database using Joomla 3.8, 3.9 or 4.0. The reason is that MySQL 8 has a lot of changes under the hood. One change that affects Joomla is the default authentication plugin which is <tt>sha256_password</tt> instead of <tt>mysql_native_password</tt>. The native PHP MySQL-Driver don't support MySQL 8 with this plugin yet other programming languages like GO or PERL are struggling too. [https://github.com/php/php-src/commit/d6e81f0bfd0cb90586dd83d4fd47a4302605261a PHP 7.3 (alpha)] is supporting MySQL 8 though.</translate>

<translate>
==Workaround to get Joomla working with MySQL 8== 
</translate>
<translate>
Fortunately there is a workaround! We can use the <tt>mysql_native_password</tt> default authentication plugin for MySQL.
We need to open our configuration file <tt>sudo nano /etc/my.cnf</tt> (Please note that your file may be under a different directory) and add the following configuration:</translate>
<source lang="ini">
[mysqld]
default-authentication-plugin=mysql_native_password
</source>
<translate> If you don't have access to your config file then you can update your user as follows:</translate>
<source lang="mysql">
ALTER USER 'username'@'localhost' IDENTIFIED WITH mysql_native_password BY 'password';
</source>
<translate> Replace username with the name of the user account and password with the password belonging to the account. Restart MySQL and you are done ...well, only if you have Joomla 3.8 or 3.9 installed.</translate>

<translate> If you want to work with Joomla 4.0, you have to do some extra work, because the administration dashboard is blank after the installation with Joomla 4.0 and MySQL 8.</translate>

<translate>
Fortunately there is a fix for that too!
MySQL 8 is returning <tt>Incorrect date value: '0000-00-00'</tt> after running following insertion from the installation file <tt>/installation/sql/mysql/joomla.sql</tt>.</translate>

<translate> The following query must be run to fix this. Replace #_ with your table prefix.</translate>
<source lang=sql>
UPDATE `#__modules` SET `checked_out_time` = '1000-01-01 00:00:00', `publish_up` = '1000-01-01 00:00:00', `publish_down` = '1000-01-01 00:00:00';
</source>

<translate> This is happening because since MySQL 5.7, MySQL stops supporting zeros value in date / datetime.</translate>

<translate>
==How MySQL default authentication plugin works== 
</translate>
<translate> The advantage of <tt>mysql_native_password</tt> is that it supports the challenge-response mechanism which is very quick and does not require encrypted connection. However, <tt>mysql_native_password</tt> relies on SHA1 algorithm and NIST has recommended to stop using it.</translate>

<translate> Further, if two user accounts use the same password, <tt>mysql_native_password</tt> transformation is the same in the mysql.user table. Although the hash does not expose information about the actual password, it still tells which two users use the same password. To avoid that, a salt should be used. A salt is basically a random number that is used as one of the parameters to cryptographic hash functions used to transform user passwords. Since a salt is random and different for each execution, even if two users use the same passwords, the end result of transformation would look very different.</translate>
<translate>

Since MySQL 5.6, sha256_password authentication plugin is supported. It uses multiple rounds of SHA256 hash on a salted password to make sure that the hash transformation is more secure. However, it requires either encrypted connections or support for an RSA key pair. So, while password security is stronger, secure connections and multiple rounds of hash transformations require more time in the authentication process.</translate>

<translate> caching_sha2_password tries to combine the best of both worlds.</translate> <ref>https://mysqlserverteam.com/mysql-8-0-4-new-default-authentication-plugin-caching_sha2_password/</ref>

<noinclude>
[[Category:Server configurations{{#translation:}}]]
[[Category:Installation{{#translation:}}]]
[[Category:Tutorials{{#translation:}}]]
</noinclude>

J3.x:Developing a MVC Component/Adding ACL/en

2019-10-19T05:51:13Z

Mickmackusa: improved English

<noinclude><languages /></noinclude>
{{review}}
{{:J3.1:Developing a MVC Component/en}}
== Introduction ==
This tutorial is part of the [[S:MyLanguage/J3.2:Developing a MVC Component | Developing a MVC Component for Joomla! 3.2]] tutorial. You are encouraged to read the previous parts of the tutorial before reading this.

== Adding Access Control ==
With Joomla!'s Access Control we can define which user groups are allowed or denied specific actions in your component. In this example, we use actions that are defined in the core. For the component as a whole: core.admin (access to the configuration) and core.manage (access to the backend). And at various levels actions like create, delete and edit. Besides those core actions, you can define your own actions, but that is often not necessary and is not shown in this example. View/Read Access is not managed via those actions but with View Access Levels; see general documentation about Joomla!'s ACL for that.

In the #__assets table, the actual list is stored: which user groups are allowed or denied specific actions on specific resources (assets). This is the implementation of the Access Control List (ACL).

In this article, we will show how to add and use access permissions at several levels of granularity: for your component as a whole, for categories and for individual items.

Note: In this HelloWorld example we are working in the backend, so the only access level available are ''administrator'' and ''superuser''.
To test this tutorial, first create a new administrator user and then set its permissions (working as superuser).
After logging in as administrator you will see the changes.

== Minimal ACL requirements at the component level ==
There are 2 actions that need to be defined at the component level for a Joomla! 2.5+ component to offer basic ACL support:
* '''Configure''' (core.admin): which groups are allowed to configure the component level permissions via the 'Options' toolbar button?
* '''Access Component''' (core.manage): which groups are allowed to access the component's backend?

This basic ACL support is done in 4 simple steps:
* [[#Add_the_2_minimal_component_level_actions_to_access.xml|Add the 2 minimal component level actions to access.xml]]
* [[#Add_the_permissions_fieldset_to_config.xml|Add the permissions fieldset to config.xml]]
* [[#Add_the_.27Options.27_toolbar_button_when_user_is_authorised_for_it|Add the 'Options' toolbar button]]
* [[#Restrict_the_access_to_the_component.27s_backend_to_authorised_usergroups|Restrict the access to the component's backend]]

=== Add the 2 minimal component level actions to access.xml ===
A minimal ACL </tt>access.xml</tt> would consist of only those 2 basic actions:

<tt>Basic admin/access.xml</tt>
<source lang="xml">
<?xml version="1.0" encoding="utf-8" ?>
<access component="com_helloworld">
<section name="component">
<action name="core.admin" title="JACTION_ADMIN" description="JACTION_ADMIN_COMPONENT_DESC" />
<action name="core.manage" title="JACTION_MANAGE" description="JACTION_MANAGE_COMPONENT_DESC" />
</section>
</access>
</source>

See ''[[S:MyLanguage/J3.2:Developing_a_MVC_Component/Adding_categories#admin/access.xml|admin/access.xml]]'' for the current and more elaborate version.

=== Add the permissions fieldset to config.xml ===
Add the following permissions fieldset to <tt>admin/config.xml</tt> in order to be able to set our component level permissions.

<source lang="xml">
<fieldset
name="permissions"
label="JCONFIG_PERMISSIONS_LABEL"
description="JCONFIG_PERMISSIONS_DESC"
>
<field
name="rules"
type="rules"
label="JCONFIG_PERMISSIONS_LABEL"
class="inputbox"
validate="rules"
filter="rules"
component="com_helloworld"
section="component"
/>
</fieldset>
</source>

See the [[#admin.2Fconfig.xml|more elaborate config.xml example]] further downwards for the exact place where to insert this code.

=== Add the 'Options' toolbar button when user is authorised for it ===
In the <tt>admin/views/helloworlds/view.html.php</tt> file you can add the following code to check if the user can edit the preferences:

<source lang="php" highlight="2-3,5">
// Options button.
if (JFactory::getUser()->authorise('core.admin', 'com_helloworld'))
{
JToolBarHelper::preferences('com_helloworld');
}
</source>

See further downwards for a [[#admin/views/helloworlds/view.html.php|more elaborated example of ''admin/views/helloworlds/view.html.php'']] where this ''JToolBarHelper::preferences('com_helloworld')'' is done in an addToolBar()-method together with the other toolbar buttons and the ''JUser->authorise()''-check is done with JHelperContent, resulting in the $canDo-property.

=== Restrict the access to the component's backend to authorised usergroups ===
To control the access to the backend of the component add the following lines to the <tt>admin/helloworld.php</tt> entry-file:

<source lang="php">
// Access check: is this user allowed to access the backend of this component?
if (!JFactory::getUser()->authorise('core.manage', 'com_helloworld'))
{
throw new Exception(JText::_('JERROR_ALERTNOAUTHOR'));
}
</source>

See further downwards for the [[#admin/helloworld.php|whole code of the ''admin/helloworld.php'' file]].

== Adding more actions, also at category level and item level ==
When adding more actions and more levels, the above described 4 steps are done too:
* [[#Describing_the_actions_you_want_to_control_the_access_to|Add the actions to access.xml; here we can add more actions and levels]]
* [[#Adding_the_setting_of_permissions_in_the_component.27s_Preferences|Add the permissions-fieldset to config.xml]]
* [[#Displaying_only_the_right_toolbar_buttons|Add the 'Options' toolbar button]]
* [[#Restricting_access_to_the_component|Restrict the access to the component's backend
]]

In addition we also have to do the following steps:
* [[#Add_the_asset_id_column_to_the_database_table|Add an asset_id to the item's database table for item level access control]]
* [[#Setting_the_permission_values_in_the_assets_table|Store the permissions in the assets table. Especially take care of setting the asset_id of the parent-asset]]
* [[#Showing_the_setting_of_permissions_on_the_item_level|Make the settings of the permissions at the item level editable]]
* [[#Adding_language_strings|Add some language strings]]

=== Describing the actions you want to control the access to ===
Each component (or part of it) has its own set of permissions that can be controlled. They are described in an <tt>access.xml</tt> file located at the root of the ''admin'' folder. In this helloworld-example the actions to which access is controlled are divided in three sections: at the component level, the category level and the item level. An 'item' is called a 'message' in our example component, hence the name of the third section.

<span id="admin/access.xml">
<tt>admin/access.xml</tt>
<source lang="xml" highlight="10-16">
<?xml version="1.0" encoding="utf-8" ?>
<access component="com_helloworld">
<section name="component">
<action name="core.admin" title="JACTION_ADMIN" description="JACTION_ADMIN_COMPONENT_DESC" />
<action name="core.manage" title="JACTION_MANAGE" description="JACTION_MANAGE_COMPONENT_DESC" />
<action name="core.create" title="JACTION_CREATE" description="JACTION_CREATE_COMPONENT_DESC" />
<action name="core.delete" title="JACTION_DELETE" description="JACTION_DELETE_COMPONENT_DESC" />
<action name="core.edit" title="JACTION_EDIT" description="JACTION_EDIT_COMPONENT_DESC" />
</section>
<section name="category">
<action name="core.create" title="JACTION_CREATE" description="COM_CATEGORIES_ACCESS_CREATE_DESC" />
<action name="core.delete" title="JACTION_DELETE" description="COM_CATEGORIES_ACCESS_DELETE_DESC" />
<action name="core.edit" title="JACTION_EDIT" description="COM_CATEGORIES_ACCESS_EDIT_DESC" />
<action name="core.edit.state" title="JACTION_EDITSTATE" description="COM_CATEGORIES_ACCESS_EDITSTATE_DESC" />
<action name="core.edit.own" title="JACTION_EDITOWN" description="COM_CATEGORIES_ACCESS_EDITOWN_DESC" />
</section>
<section name="message">
<action name="core.delete" title="JACTION_DELETE" description="COM_HELLOWORLD_ACCESS_DELETE_DESC" />
<action name="core.edit" title="JACTION_EDIT" description="COM_HELLOWORLD_ACCESS_EDIT_DESC" />
</section>
</access>
</source>
</span>

=== Adding the setting of permissions in the component's Preferences ===
Since we now use Access Control permissions in our component, we need to be able to set them at the component level. That is done in the Preferences of this component: the screen you see after clicking the 'Options' button. The config.xml-file is a form-definition for those Preferences. We could define the component level actions here too, as a child of the "rules" field-tag, but it is now preferred to also put those actions in <tt>access.xml</tt> in that way all access rules for this component are on one spot.

<span id="admin/config.xml">
<tt>admin/config.xml</tt>
<source lang="xml" highlight="19-34">
<?xml version="1.0" encoding="utf-8"?>
<config>
<fieldset
name="greetings"
label="COM_HELLOWORLD_CONFIG_GREETING_SETTINGS_LABEL"
description="COM_HELLOWORLD_CONFIG_GREETING_SETTINGS_DESC"
>
<field
name="show_category"
type="radio"
label="COM_HELLOWORLD_HELLOWORLD_FIELD_SHOW_CATEGORY_LABEL"
description="COM_HELLOWORLD_HELLOWORLD_FIELD_SHOW_CATEGORY_DESC"
default="0"
>
<option value="0">JHIDE</option>
<option value="1">JSHOW</option>
</field>
</fieldset>
<fieldset
name="permissions"
label="JCONFIG_PERMISSIONS_LABEL"
description="JCONFIG_PERMISSIONS_DESC"
>
<field
name="rules"
type="rules"
label="JCONFIG_PERMISSIONS_LABEL"
class="inputbox"
validate="rules"
filter="rules"
component="com_helloworld"
section="component"
/>
</fieldset>
</config>

</source>
</span>

=== Displaying only the right toolbar buttons ===

Which toolbar buttons to display depends on the Access Control permissions for the user. We put all permissions for this user in the $canDo property of the view; so we can eventually refer to it in layouts (in the edit-form for example).

In the <tt>admin/views/helloworlds/view.html.php</tt>, put this code:

<span id="admin/views/helloworlds/view.html.php">
<tt>admin/views/helloworlds/view.html.php</tt>
<source lang="php" highlight="42-44,83-85,87-89,91-93,95-98,100" >
<?php
/**
* @package Joomla.Administrator
* @subpackage com_helloworld
*
* @copyright Copyright (C) 2005 - 2015 Open Source Matters, Inc. All rights reserved.
* @license GNU General Public License version 2 or later; see LICENSE.txt
*/

// No direct access to this file
defined('_JEXEC') or die('Restricted access');

/**
* HelloWorlds View
*
* @since 0.0.1
*/
class HelloWorldViewHelloWorlds extends JViewLegacy
{
/**
* Display the Hello World view
*
* @param string $tpl The name of the template file to parse; automatically searches through the template paths.
*
* @return void
*/
function display($tpl = null)
{

// Get application
$app = JFactory::getApplication();
$context = "helloworld.list.admin.helloworld";
// Get data from the model
$this->items = $this->get('Items');
$this->pagination = $this->get('Pagination');
$this->state = $this->get('State');
$this->filter_order = $app->getUserStateFromRequest($context.'filter_order', 'filter_order', 'greeting', 'cmd');
$this->filter_order_Dir = $app->getUserStateFromRequest($context.'filter_order_Dir', 'filter_order_Dir', 'asc', 'cmd');
$this->filterForm = $this->get('FilterForm');
$this->activeFilters = $this->get('ActiveFilters');

// What Access Permissions does this user have? What can (s)he do?
$this->canDo = JHelperContent::getActions();

// Check for errors.
if (count($errors = $this->get('Errors')))
{
throw new Exception(implode("\n", $errors), 500);
}

// Set the submenu
HelloWorldHelper::addSubmenu('helloworlds');

// Set the toolbar and number of found items
$this->addToolBar();

// Display the template
parent::display($tpl);

// Set the document
$this->setDocument();
}

/**
* Add the page title and toolbar.
*
* @return void
*
* @since 1.6
*/
protected function addToolBar()
{
$title = JText::_('COM_HELLOWORLD_MANAGER_HELLOWORLDS');

if ($this->pagination->total)
{
$title .= "<span style='font-size: 0.5em; vertical-align: middle;'>(" . $this->pagination->total . ")</span>";
}

JToolBarHelper::title($title, 'helloworld');

if ($this->canDo->get('core.create'))
{
JToolBarHelper::addNew('helloworld.add', 'JTOOLBAR_NEW');
}
if ($this->canDo->get('core.edit'))
{
JToolBarHelper::editList('helloworld.edit', 'JTOOLBAR_EDIT');
}
if ($this->canDo->get('core.delete'))
{
JToolBarHelper::deleteList('', 'helloworlds.delete', 'JTOOLBAR_DELETE');
}
if ($this->canDo->get('core.admin'))
{
JToolBarHelper::divider();
JToolBarHelper::preferences('com_helloworld');
}
}
/**
* Method to set up the document properties
*
* @return void
*/
protected function setDocument()
{
$document = JFactory::getDocument();
$document->setTitle(JText::_('COM_HELLOWORLD_ADMINISTRATION'));
}
}
</source>
<span>

In the ''admin/views/helloworld/view.html.php'', put this code

<span id="admin/views/helloworld/view.html.php">
''admin/views/helloworld/view.html.php''
<source lang="php" highlight="23,39-41,76-78,81-89,93-112">
<?php
/**
* @package Joomla.Administrator
* @subpackage com_helloworld
*
* @copyright Copyright (C) 2005 - 2015 Open Source Matters, Inc. All rights reserved.
* @license GNU General Public License version 2 or later; see LICENSE.txt
*/

// No direct access to this file
defined('_JEXEC') or die('Restricted access');

/**
* HelloWorld View
*
* @since 0.0.1
*/
class HelloWorldViewHelloWorld extends JViewLegacy
{
protected $form;
protected $item;
protected $script;
protected $canDo;

/**
* Display the Hello World view
*
* @param string $tpl The name of the template file to parse; automatically searches through the template paths.
*
* @return void
*/
public function display($tpl = null)
{
// Get the Data
$this->form = $this->get('Form');
$this->item = $this->get('Item');
$this->script = $this->get('Script');

// What Access Permissions does this user have? What can (s)he do?
$this->canDo = JHelperContent::getActions($this->item->id);

// Check for errors.
if (count($errors = $this->get('Errors')))
{
throw new Exception(implode("\n", $errors), 500);
}

// Set the toolbar
$this->addToolBar();

// Display the template
parent::display($tpl);

// Set the document
$this->setDocument();
}

/**
* Add the page title and toolbar.
*
* @return void
*
* @since 1.6
*/
protected function addToolBar()
{
$input = JFactory::getApplication()->input;

// Hide Joomla Administrator Main menu
$input->set('hidemainmenu', true);

$isNew = ($this->item->id == 0);

JToolBarHelper::title($isNew ? JText::_('COM_HELLOWORLD_MANAGER_HELLOWORLD_NEW')
: JText::_('COM_HELLOWORLD_MANAGER_HELLOWORLD_EDIT'), 'helloworld');
// Build the actions for new and existing records.
if ($isNew)
{
// For new records, check the create permission.
if ($this->canDo->get('core.create'))
{
JToolBarHelper::apply('helloworld.apply', 'JTOOLBAR_APPLY');
JToolBarHelper::save('helloworld.save', 'JTOOLBAR_SAVE');
JToolBarHelper::custom('helloworld.save2new', 'save-new.png', 'save-new_f2.png',
'JTOOLBAR_SAVE_AND_NEW', false);
}
JToolBarHelper::cancel('helloworld.cancel', 'JTOOLBAR_CANCEL');
}
else
{
if ($this->canDo->get('core.edit'))
{
// We can save the new record
JToolBarHelper::apply('helloworld.apply', 'JTOOLBAR_APPLY');
JToolBarHelper::save('helloworld.save', 'JTOOLBAR_SAVE');

// We can save this record, but check the create permission to see
// if we can return to make a new one.
if ($this->canDo->get('core.create'))
{
JToolBarHelper::custom('helloworld.save2new', 'save-new.png', 'save-new_f2.png',
'JTOOLBAR_SAVE_AND_NEW', false);
}
}
if ($this->canDo->get('core.create'))
{
JToolBarHelper::custom('helloworld.save2copy', 'save-copy.png', 'save-copy_f2.png',
'JTOOLBAR_SAVE_AS_COPY', false);
}
JToolBarHelper::cancel('helloworld.cancel', 'JTOOLBAR_CLOSE');
}
}
/**
* Method to set up the document properties
*
* @return void
*/
protected function setDocument()
{
$isNew = ($this->item->id == 0);
$document = JFactory::getDocument();
$document->setTitle($isNew ? JText::_('COM_HELLOWORLD_HELLOWORLD_CREATING')
: JText::_('COM_HELLOWORLD_HELLOWORLD_EDITING'));
$document->addScript(JURI::root() . $this->script);
$document->addScript(JURI::root() . "/administrator/components/com_helloworld"
. "/views/helloworld/submitbutton.js");
JText::script('COM_HELLOWORLD_HELLOWORLD_ERROR_UNACCEPTABLE');
}
}

</source>
</span>

These two files use the ''getActions'' method defined in the <tt>admin/helpers/helloworld.php</tt> file.

In the helper-file, put this code:

<span id="admin/helpers/helloworld.php">
<tt>admin/helpers/helloworld.php</tt>
<source lang="php" highlight="50-72">
<?php
/**
* @package Joomla.Administrator
* @subpackage com_helloworld
*
* @copyright Copyright (C) 2005 - 2015 Open Source Matters, Inc. All rights reserved.
* @license GNU General Public License version 2 or later; see LICENSE.txt
*/

// No direct access to this file
defined('_JEXEC') or die('Restricted access');

/**
* HelloWorld component helper.
*
* @param string $submenu The name of the active view.
*
* @return void
*
* @since 1.6
*/
abstract class HelloWorldHelper
{
/**
* Configure the Linkbar.
*/
public static function addSubmenu($submenu)
{
JSubMenuHelper::addEntry(
JText::_('COM_HELLOWORLD_SUBMENU_MESSAGES'),
'index.php?option=com_helloworld',
$submenu == 'messages'
);

JSubMenuHelper::addEntry(
JText::_('COM_HELLOWORLD_SUBMENU_CATEGORIES'),
'index.php?option=com_categories&view=categories&extension=com_helloworld',
$submenu == 'categories'
);

// set some global property
$document = JFactory::getDocument();
$document->addStyleDeclaration('.icon-48-helloworld ' .
'{background-image: url(../media/com_helloworld/images/tux-48x48.png);}');
if ($submenu == 'categories')
{
$document->setTitle(JText::_('COM_HELLOWORLD_ADMINISTRATION_CATEGORIES'));
}
}

/**
* Get the actions
*/
public static function getActions($messageId = 0)
{
$result = new JObject;

if (empty($messageId)) {
$assetName = 'com_helloworld';
}
else {
$assetName = 'com_helloworld.message.'.(int) $messageId;
}

$actions = JAccess::getActions('com_helloworld', 'component');

foreach ($actions as $action) {
$result->set($action->name, JFactory::getUser()->authorise($action->name, $assetName));
}

return $result;
}
}

</source>
</span>

=== Restricting access to the component ===

The main idea in ACL is to restrict actions to groups of users. The first action to be restricted is access to the administrative backend of the component itself. With your favourite file editor, edit the <tt>admin/helloworld.php</tt> file and add the lines with the access check.

<span id="admin/helloworld.php">
<tt>admin/helloworld.php</tt>
<source lang="php" highlight="17-22">
<?php
/**
* @package Joomla.Administrator
* @subpackage com_helloworld
*
* @copyright Copyright (C) 2005 - 2015 Open Source Matters, Inc. All rights reserved.
* @license GNU General Public License version 2 or later; see LICENSE.txt
*/

// No direct access to this file
defined('_JEXEC') or die('Restricted access');

// Set some global property
$document = JFactory::getDocument();
$document->addStyleDeclaration('.icon-helloworld {background-image: url(../media/com_helloworld/images/tux-16x16.png);}');

// Access check: is this user allowed to access the backend of this component?
if (!JFactory::getUser()->authorise('core.manage', 'com_helloworld'))
{
throw new Exception(JText::_('JERROR_ALERTNOAUTHOR'));
}

// Require helper file
JLoader::register('HelloWorldHelper', JPATH_COMPONENT . '/helpers/helloworld.php');

// Get an instance of the controller prefixed by HelloWorld
$controller = JControllerLegacy::getInstance('HelloWorld');

// Perform the Request task
$controller->execute(JFactory::getApplication()->input->get('task'));;

// Redirect if set by the controller
$controller->redirect();

</source>
<span>

=== Add the asset_id column to the database table ===

In order to be able to work with JTable an asset_id column has to be added to the database #__helloworld table.

So, <tt>admin/sql/install.mysql.utf8.sql</tt> becomes:

<span id="admin/sql/install.mysql.utf8.sql">
<tt>admin/sql/install.mysql.utf8.sql</tt>
<source lang="mysql" highlight="5">
DROP TABLE IF EXISTS `#__helloworld`;

CREATE TABLE `#__helloworld` (
`id` INT(11) NOT NULL AUTO_INCREMENT,
`asset_id` INT(10) NOT NULL DEFAULT '0',
`greeting` VARCHAR(25) NOT NULL,
`published` tinyint(4) NOT NULL,
`catid` int(11) NOT NULL DEFAULT '0',
`params` VARCHAR(1024) NOT NULL DEFAULT '',
PRIMARY KEY (`id`)
)
ENGINE =MyISAM
AUTO_INCREMENT =0
DEFAULT CHARSET =utf8;

INSERT INTO `#__helloworld` (`greeting`) VALUES
('Hello World!'),
('Good bye World!');

</source>
</span>

For updates we add a sql-update-file:

<span id="admin/sql/updates/mysql/0.0.14.sql">
<tt>admin/sql/updates/mysql/0.0.14.sql</tt>
<source lang="mysql">
ALTER TABLE`#__helloworld` ADD COLUMN `asset_id` INT(10) UNSIGNED NOT NULL DEFAULT '0' AFTER `id`;
</source>
</span>

=== Restricting access to the messages ===

So far we have restricted access to the component itself, but we also need to do that at ''message'' level.

To check the '''"core.delete"''' permission you need to modify the model class: <tt>admin/models/helloworld.php</tt> by adding these lines:

<span id="admin/models/helloworld.php">
<tt>admin/models/helloworld.php</tt>
<source lang='php' highlight="96-105">
<?php
/**
* @package Joomla.Administrator
* @subpackage com_helloworld
*
* @copyright Copyright (C) 2005 - 2015 Open Source Matters, Inc. All rights reserved.
* @license GNU General Public License version 2 or later; see LICENSE.txt
*/

// No direct access to this file
defined('_JEXEC') or die('Restricted access');

/**
* HelloWorld Model
*
* @since 0.0.1
*/
class HelloWorldModelHelloWorld extends JModelAdmin
{
/**
* Method to get a table object, load it if necessary.
*
* @param string $type The table name. Optional.
* @param string $prefix The class prefix. Optional.
* @param array $config Configuration array for model. Optional.
*
* @return JTable A JTable object
*
* @since 1.6
*/
public function getTable($type = 'HelloWorld', $prefix = 'HelloWorldTable', $config = array())
{
return JTable::getInstance($type, $prefix, $config);
}

/**
* Method to get the record form.
*
* @param array $data Data for the form.
* @param boolean $loadData True if the form is to load its own data (default case), false if not.
*
* @return mixed A JForm object on success, false on failure
*
* @since 1.6
*/
public function getForm($data = array(), $loadData = true)
{
// Get the form.
$form = $this->loadForm(
'com_helloworld.helloworld',
'helloworld',
array(
'control' => 'jform',
'load_data' => $loadData
)
);

if (empty($form))
{
return false;
}

return $form;
}
/**
* Method to get the script that have to be included on the form
*
* @return string Script files
*/
public function getScript()
{
return 'administrator/components/com_helloworld/models/forms/helloworld.js';
}
/**
* Method to get the data that should be injected in the form.
*
* @return mixed The data for the form.
*
* @since 1.6
*/
protected function loadFormData()
{
// Check the session for previously entered form data.
$data = JFactory::getApplication()->getUserState(
'com_helloworld.edit.helloworld.data',
array()
);

if (empty($data))
{
$data = $this->getItem();
}

return $data;
}
/**
* Method to check if it's OK to delete a message. Overwrites JModelAdmin::canDelete
*/
protected function canDelete($record)
{
if( !empty( $record->id ) )
{
return JFactory::getUser()->authorise( "core.delete", "com_helloworld.message." . $record->id );
}
}
}

</source>
</span>

To check '''"core.edit"''' (and '''core.add''' if you wish) you need to update the sub-controller (''not'' the model). I am not sure why this is so, but that's how other standard Joomla components do it. You need to add the following lines in the file: <tt>admin/controllers/helloworld.php</tt>

<span id="admin/controllers/helloworld.php">
<tt>admin/controllers/helloworld.php</tt>
<source lang='php' highlight="21-49">
<?php
/**
* @package Joomla.Administrator
* @subpackage com_helloworld
*
* @copyright Copyright (C) 2005 - 2015 Open Source Matters, Inc. All rights reserved.
* @license GNU General Public License version 2 or later; see LICENSE.txt
*/
// No direct access to this file
defined('_JEXEC') or die('Restricted access');

/**
* HelloWorld Controller
*
* @package Joomla.Administrator
* @subpackage com_helloworld
* @since 0.0.9
*/
class HelloWorldControllerHelloWorld extends JControllerForm
{
/**
* Implement to allowAdd or not
*
* Not used at this time (but you can look at how other components use it....)
* Overwrites: JControllerForm::allowAdd
*
* @param array $data
* @return bool
*/
protected function allowAdd($data = array())
{
return parent::allowAdd($data);
}
/**
* Implement to allow edit or not
* Overwrites: JControllerForm::allowEdit
*
* @param array $data
* @param string $key
* @return bool
*/
protected function allowEdit($data = array(), $key = 'id')
{
$id = isset( $data[ $key ] ) ? $data[ $key ] : 0;
if( !empty( $id ) )
{
return JFactory::getUser()->authorise( "core.edit", "com_helloworld.message." . $id );
}
}
}

</source>
</span>

Please note that ''allowAdd'' simply calls its parent. I've put it here in case you want to actually use it in your component. If you look at your <tt>admin/access.xml</tt> file, you will notice there is no ''core.add'' action defined for "messages", so you will need to add it there as well if you want to be able to configure it in the interface.

=== Setting the permission values in the assets table ===

In order to store permissions for each message in the assets database table, we have to instruct the table class associated with the model to save those permissions in the assets table.

JTable not only provides an interface for storing the data of the record itself in the item's database table, but also for storing the permissions for that record in the assets database table. Therefore we must add information to the bind()-method about the permission-values. We also have to provide the asset name, asset title and the id of the asset parent via the helloworld JTable. Therefore we override 3 methods:
* _getAssetName(): a unique name for this asset, by which it can be retrieved
* _getAssetTitle(): a more human-friendly way to identify the asset (not necessarily unique)
* _getAssetParentId(): the asset_id of the parent in the asset database table (from whom permissions are inherited)

<span id="admin/tables/helloworld.php">
<tt>admin/tables/helloworld.php</tt>
<source lang="php" highlight="45-52,80-133">
<?php
/**
* @package Joomla.Administrator
* @subpackage com_helloworld
*
* @copyright Copyright (C) 2005 - 2015 Open Source Matters, Inc. All rights reserved.
* @license GNU General Public License version 2 or later; see LICENSE.txt
*/
// No direct access
defined('_JEXEC') or die('Restricted access');

/**
* Hello Table class
*
* @since 0.0.1
*/
class HelloWorldTableHelloWorld extends JTable
{
/**
* Constructor
*
* @param JDatabaseDriver &$db A database connector object
*/
function __construct(&$db)
{
parent::__construct('#__helloworld', 'id', $db);
}
/**
* Overloaded bind function
*
* @param array named array
* @return null|string null is operation was satisfactory, otherwise returns an error
* @see JTable:bind
* @since 1.5
*/
public function bind($array, $ignore = '')
{
if (isset($array['params']) && is_array($array['params']))
{
// Convert the params field to a string.
$parameter = new JRegistry;
$parameter->loadArray($array['params']);
$array['params'] = (string)$parameter;
}

// Bind the rules.
if (isset($array['rules']) && is_array($array['rules']))
{
$rules = new JAccessRules($array['rules']);
$this->setRules($rules);
}

return parent::bind($array, $ignore);
}

/**
* Overloaded load function
*
* @param int $pk primary key
* @param boolean $reset reset data
* @return boolean
* @see JTable:load
*/
public function load($pk = null, $reset = true)
{
if (parent::load($pk, $reset))
{
// Convert the params field to a registry.
$params = new JRegistry;
$params->loadString($this->params, 'JSON');

$this->params = $params;
return true;
}
else
{
return false;
}
}
/**
* Method to compute the default name of the asset.
* The default name is in the form `table_name.id`
* where id is the value of the primary key of the table.
*
* @return string
* @since 2.5
*/
protected function _getAssetName()
{
$k = $this->_tbl_key;
return 'com_helloworld.message.'.(int) $this->$k;
}
/**
* Method to return the title to use for the asset table.
*
* @return string
* @since 2.5
*/
protected function _getAssetTitle()
{
return $this->greeting;
}
/**
* Method to get the asset-parent-id of the item
*
* @return int
*/
protected function _getAssetParentId(JTable $table = NULL, $id = NULL)
{
// We will retrieve the parent-asset from the Asset-table
$assetParent = JTable::getInstance('Asset');
// Default: if no asset-parent can be found we take the global asset
$assetParentId = $assetParent->getRootId();

// Find the parent-asset
if (($this->catid) && !empty($this->catid))
{
// The item has a category as asset-parent
$assetParent->loadByName('com_helloworld.category.' . (int) $this->catid);
}
else
{
// The item has the component as asset-parent
$assetParent->loadByName('com_helloworld');
}

// Return the found asset-parent-id
if ($assetParent->id)
{
$assetParentId=$assetParent->id;
}
return $assetParentId;
}
}

</source>
</span>

This code for _getAssetParentId() above uses JTableAsset to retrieve the asset_id of the asset-parent. This is different from the code in the current version of com_content, where the asset_id of the category is retrieved from the #__categories database table. That is another possibility; many ways leading to Rome. In com_content however, if an item would not be under a category, then the asset_id of the global asset is returned. That would of course not be right, but is fixed by providing a default category "uncategorised", so that an article is ''always'' under a category. That is why you cannot just copy the code of _getAssetParentId() in com_content to your own component. The code above is more general.

=== Showing the setting of permissions on the item level ===

Adding the rules field to the form-definition of the edit-form.

<span id="admin/models/forms/helloworld.xml">
<tt>admin/models/forms/helloworld.xml</tt>
<source lang="xml" highlight="55-74">
<?xml version="1.0" encoding="utf-8"?>
<form
addrulepath="/administrator/components/com_helloworld/models/rules"
>
<fieldset
name="details"
label="COM_HELLOWORLD_HELLOWORLD_DETAILS"
>
<field
name="id"
type="hidden"
/>
<field
name="greeting"
type="text"
label="COM_HELLOWORLD_HELLOWORLD_GREETING_LABEL"
description="COM_HELLOWORLD_HELLOWORLD_GREETING_DESC"
size="40"
class="inputbox validate-greeting"
validate="greeting"
required="true"
default=""
/>
<field
name="catid"
type="category"
extension="com_helloworld"
class="inputbox"
default=""
label="COM_HELLOWORLD_HELLOWORLD_FIELD_CATID_LABEL"
description="COM_HELLOWORLD_HELLOWORLD_FIELD_CATID_DESC"
required="true"
>
<option value="0">JOPTION_SELECT_CATEGORY</option>
</field>
</fieldset>
<fields name="params">
<fieldset
name="params"
label="JGLOBAL_FIELDSET_DISPLAY_OPTIONS"
>
<field
name="show_category"
type="list"
label="COM_HELLOWORLD_HELLOWORLD_FIELD_SHOW_CATEGORY_LABEL"
description="COM_HELLOWORLD_HELLOWORLD_FIELD_SHOW_CATEGORY_DESC"
default=""
>
<option value="">JGLOBAL_USE_GLOBAL</option>
<option value="0">JHIDE</option>
<option value="1">JSHOW</option>
</field>
</fieldset>
</fields>
<fieldset
name="accesscontrol"
label="COM_HELLOWORLD_FIELDSET_RULES"
>
<field
name="asset_id"
type="hidden"
filter="unset"
/>
<field
name="rules"
type="rules"
label="COM_HELLOWORLD_FIELD_RULES_LABEL"
filter="rules"
validate="rules"
class="inputbox"
component="com_helloworld"
section="message"
/>
</fieldset>
</form>

</source>
</span>

Now the ACL interface is displayed at the bottom of the Helloworld editform too (the ''edit.php'' file automatically get the fieldsets from the above xml).

=== Adding language strings ===
We used 4 language strings that have to be added to the backend language-file.

<span id="admin/language/en-GB/en-GB.com_helloworld.ini">
<tt>admin/language/en-GB/en-GB.com_helloworld.ini</tt>
<source lang="text" highlight="41-44">
; Joomla! Project
; Copyright (C) 2005 - 2015 Open Source Matters. All rights reserved.
; License GNU General Public License version 2 or later; see LICENSE.txt, see LICENSE.php
; Note : All ini files need to be saved as UTF-8

COM_HELLOWORLD_ADMINISTRATION="HelloWorld - Administration"
COM_HELLOWORLD_ADMINISTRATION_CATEGORIES="HelloWorld - Categories"
COM_HELLOWORLD_NUM="#"
COM_HELLOWORLD_HELLOWORLDS_FILTER="Filters"
COM_HELLOWORLD_PUBLISHED="Published"
COM_HELLOWORLD_HELLOWORLDS_NAME="Name"
COM_HELLOWORLD_ID="Id"

COM_HELLOWORLD_HELLOWORLD_CREATING="HelloWorld - Creating"
COM_HELLOWORLD_HELLOWORLD_DETAILS="Details"
COM_HELLOWORLD_HELLOWORLD_EDITING="HelloWorld - Editing"
COM_HELLOWORLD_HELLOWORLD_ERROR_UNACCEPTABLE="Some values are unacceptable"
COM_HELLOWORLD_HELLOWORLD_FIELD_CATID_DESC="The category the messages belongs to"
COM_HELLOWORLD_HELLOWORLD_FIELD_CATID_LABEL="Category"
COM_HELLOWORLD_HELLOWORLD_FIELD_GREETING_DESC="This message will be displayed"
COM_HELLOWORLD_HELLOWORLD_FIELD_GREETING_LABEL="Message"
COM_HELLOWORLD_HELLOWORLD_FIELD_SHOW_CATEGORY_LABEL="Show category"
COM_HELLOWORLD_HELLOWORLD_FIELD_SHOW_CATEGORY_DESC="If set to Show, the title of the message’s category will show."
COM_HELLOWORLD_HELLOWORLD_HEADING_GREETING="Greeting"
COM_HELLOWORLD_HELLOWORLD_HEADING_ID="Id"
COM_HELLOWORLD_MANAGER_HELLOWORLD_EDIT="HelloWorld manager: Edit Message"
COM_HELLOWORLD_MANAGER_HELLOWORLD_NEW="HelloWorld manager: New Message"
COM_HELLOWORLD_MANAGER_HELLOWORLDS="HelloWorld manager"
COM_HELLOWORLD_EDIT_HELLOWORLD="Edit message"
COM_HELLOWORLD_N_ITEMS_DELETED_1="One message deleted"
COM_HELLOWORLD_N_ITEMS_DELETED_MORE="%d messages deleted"
COM_HELLOWORLD_N_ITEMS_PUBLISHED="%d message(s) published"
COM_HELLOWORLD_N_ITEMS_UNPUBLISHED="%d message(s) unpublished"
COM_HELLOWORLD_HELLOWORLD_GREETING_LABEL="Greeting"
COM_HELLOWORLD_HELLOWORLD_GREETING_DESC="Add Hello World Greeting"
COM_HELLOWORLD_SUBMENU_MESSAGES="Messages"
COM_HELLOWORLD_SUBMENU_CATEGORIES="Categories"
COM_HELLOWORLD_CONFIGURATION="HelloWorld Configuration"
COM_HELLOWORLD_CONFIG_GREETING_SETTINGS_LABEL="Messages settings"
COM_HELLOWORLD_CONFIG_GREETING_SETTINGS_DESC="Settings that will be applied to all messages by default"
COM_HELLOWORLD_FIELDSET_RULES="Message Permissions"
COM_HELLOWORLD_FIELD_RULES_LABEL="Permissions"
COM_HELLOWORLD_ACCESS_DELETE_DESC="Is this group allowed to edit this message?"
COM_HELLOWORLD_ACCESS_DELETE_DESC="Is this group allowed to delete this message?"

</source>
</span>

== Further reading ==
More information on actions, assets and ACL can be found on the following pages:
* General information and use: [[S:MyLanguage/Access Control List/1.6-2.5/Tutorial|Access Control List/1.6-2.5/Tutorial]]
* Technical information, under construction: [[S:MyLanguage/ACL Technique in Joomla!|ACL Technique in Joomla!]]
* [[S:MyLanguage/How to implement actions in your code|How to implement actions in your code]]
* [[S:MyLanguage/Adding ACL rules to your component|Adding ACL rules to your component]]

== Deprecated classes ==
For the moment we leave the '''deprecated JError'''-references as they are. They will probably still be available in Joomla! 3.x. We cannot just change them to JLog::add() statements because in Joomla! 2.5 the messages will then not be enqueued (as there is no messagequeue-logger added as is in /libraries/cms.php in Joomla! 3.0). Other solutions, like using $app->enqueueMessage() or directly throwing PHP-exceptions as showstopper are also possible, but then there would still be numerous references to JError throughout the application. For instance in the view, we now check for errors raised in the model with: <span style="color:#900">count($errors = $this->get('Errors'))</span>, which uses JError from the JObject that was the base for JModel. To get the same functionality without using JError at all, we would have to change the way the Model raises those errors and warnings now. If we want to make an application that would work in Joomla! 2.5 and 3.x we can continue using JError. The moment we want to use our 3.x extensions also in 4.x we will have to change this (and probably a lot more too). This tutorial is now primarily focused on Joomla! 3.x., so we notice the upcoming change, but leave it there for the moment.

Since Joomla! 2.5.5 the MVC-base-classes JController, JModel and JView got proxies JControllerLegacy, JModelLegacy and JViewLegacy. It is recommended to use those proxies instead of the original classes for forward compatibility with Joomla! CMS 3.x legacy classes.

== Packaging the component ==

Content of your code directory
* ''[[S:MyLanguage/J3.2:Developing_a_MVC_Component/Developing_a_Basic_Component#helloworld.xml|helloworld.xml]]''
* ''[[S:MyLanguage/J3.2:Developing_a_MVC_Component/Adding_a_view_to_the_site_part#site/helloworld.php|site/helloworld.php]]''
* ''[[S:MyLanguage/J3.2:Developing_a_MVC_Component/Developing_a_Basic_Component#index.html|site/index.html]]''
* ''[[S:MyLanguage/J3.2:Developing_a_MVC_Component/Adding_a_view_to_the_site_part#site/controller.php|site/controller.php]]''
* ''[[S:MyLanguage/J3.2:Developing_a_MVC_Component/Developing_a_Basic_Component#index.html|site/views/index.html]]''
* ''[[S:MyLanguage/J3.2:Developing_a_MVC_Component/Developing_a_Basic_Component#index.html|site/views/helloworld/index.html]]''
* ''[[S:MyLanguage/J3.2:Developing_a_MVC_Component/Adding_a_view_to_the_site_part#site/views/helloworld/view.html.php|site/views/helloworld/view.html.php]]''
* ''[[S:MyLanguage/J3.2:Developing_a_MVC_Component/Developing_a_Basic_Component#index.html|site/views/helloworld/tmpl/index.html]]''
* ''[[S:MyLanguage/J3.2:Developing_a_MVC_Component/Using_the_database#site/views/helloworld/tmpl/default.xml|site/views/helloworld/tmpl/default.xml]]''
* ''[[S:MyLanguage/J3.2:Developing_a_MVC_Component/Adding_a_view_to_the_site_part#site/views/helloworld/tmpl/default.php|site/views/helloworld/tmpl/default.php]]''
* ''[[S:MyLanguage/J3.2:Developing_a_MVC_Component/Developing_a_Basic_Component#index.html|site/models/index.html]]''
* ''[[S:MyLanguage/J3.2:Developing_a_MVC_Component/Using_the_database#site/models/helloworld.php|site/models/helloworld.php]]''
* ''[[S:MyLanguage/J3.2:Developing_a_MVC_Component/Developing_a_Basic_Component#index.html|site/language/index.html]]''
* ''[[S:MyLanguage/J3.2:Developing_a_MVC_Component/Developing_a_Basic_Component#index.html|site/language/en-GB/index.html]]''
* ''[[S:MyLanguage/J3.x:Developing a MVC Component/Adding language management#site.2Flanguage.2Fen-GB.2Fen-GB.com_helloworld.ini|site/language/en-GB/en-GB.com_helloworld.ini]]''
* ''[[S:MyLanguage/J3.2:Developing_a_MVC_Component/Developing_a_Basic_Component#index.html|admin/index.html]]''
* ''[[S:MyLanguage/J3.2:Developing_a_MVC_Component/Basic_backend#admin/helloworld.php|admin/helloworld.php]]''
* ''[[S:MyLanguage/J3.2:Developing_a_MVC_Component/Adding_configuration#admin/config.xml|admin/config.xml]]''
* ''[[S:MyLanguage/J3.2:Developing_a_MVC_Component/Basic_backend#admin/controller.php|admin/controller.php]]''
* ''[[S:MyLanguage/J3.2:Developing_a_MVC_Component/Adding_categories#admin/access.xml|admin/access.xml]]''
* ''[[S:MyLanguage/J3.2:Developing_a_MVC_Component/Adding_categories#admin/helpers/helloworld.php|admin/helpers/helloworld.php]]''
* ''[[S:MyLanguage/J3.2:Developing_a_MVC_Component/Developing_a_Basic_Component#index.html|admin/helpers/index.html]]''
* ''[[S:MyLanguage/J3.2:Developing_a_MVC_Component/Developing_a_Basic_Component#index.html|admin/sql/index.html]]''
* ''[[S:MyLanguage/J3.2:Developing_a_MVC_Component/Using_the_database#admin/sql/install.mysql.utf8.sql|admin/sql/install.mysql.utf8.sql]]''
* ''[[S:MyLanguage/J3.2:Developing_a_MVC_Component/Using_the_database#admin/sql/uninstall.mysql.utf8.sql|admin/sql/uninstall.mysql.utf8.sql]]''
* ''[[S:MyLanguage/J3.2:Developing_a_MVC_Component/Developing_a_Basic_Component#index.html|admin/sql/updates/index.html]]''
* ''[[S:MyLanguage/J3.2:Developing_a_MVC_Component/Developing_a_Basic_Component#index.html|admin/sql/updates/mysql/index.html]]''
* ''[[S:MyLanguage/J3.2:Developing_a_MVC_Component/Developing_a_Basic_Component#admin/sql/updates/mysql/0.0.1.sql|admin/sql/updates/mysql/0.0.1.sql]]''
* ''[[S:MyLanguage/J3.2:Developing_a_MVC_Component/Using_the_database#admin/sql/install.mysql.utf8.sql|admin/sql/updates/mysql/0.0.6.sql]]''
* ''[[S:MyLanguage/J3.2:Developing_a_MVC_Component/Adding_categories#admin/sql/updates/mysql/0.0.12.sql|admin/sql/updates/mysql/0.0.12.sql]]''
* ''[[S:MyLanguage/J3.2:Developing_a_MVC_Component/Adding_configuration#admin/sql/updates/mysql/0.0.13.sql|admin/sql/updates/mysql/0.0.13.sql]]''
* ''[[S:MyLanguage/J3.2:Developing_a_MVC_Component/Adding_ACL#admin/sql/updates/mysql/0.0.14.sql|admin/sql/updates/mysql/0.0.14.sql]]''
* ''[[S:MyLanguage/J3.2:Developing_a_MVC_Component/Developing_a_Basic_Component#index.html|admin/models/index.html]]''
* ''[[S:MyLanguage/J3.2:Developing_a_MVC_Component/Developing_a_Basic_Component#index.html|admin/models/fields/index.html]]''
* ''[[S:MyLanguage/J3.2:Developing_a_MVC_Component/Using_the_database#admin/models/fields/helloworld.php|admin/models/fields/helloworld.php]]''
* ''[[S:MyLanguage/J3.2:Developing_a_MVC_Component/Basic_backend#admin/models/helloworlds.php|admin/models/helloworlds.php]]''
* ''[[S:MyLanguage/J3.2:Developing_a_MVC_Component/Adding_backend_actions#admin/models/helloworlds.php|admin/models/helloworld.php]]''
* ''[[S:MyLanguage/J3.2:Developing_a_MVC_Component/Developing_a_Basic_Component#index.html|admin/models/forms/index.html]]''
* ''[[S:MyLanguage/J3.2:Developing_a_MVC_Component/Adding_verifications#admin/models/forms/helloworld.js|admin/models/forms/helloworld.js]]''
* ''[[S:MyLanguage/J3.2:Developing_a_MVC_Component/Adding_backend_actions#admin/models/forms/helloworld.xml|admin/models/forms/helloworld.xml]]''
* ''[[S:MyLanguage/J3.2:Developing_a_MVC_Component/Adding_verifications#admin/models/rules/greeting.php|admin/models/rules/greeting.php]]''
* ''[[S:MyLanguage/J3.2:Developing_a_MVC_Component/Developing_a_Basic_Component#index.html|admin/models/rules/index.html]]''
* ''[[S:MyLanguage/J3.2:Developing_a_MVC_Component/Adding_backend_actions#admin/controllers/helloworld.php|admin/controllers/helloworld.php]]''
* ''[[S:MyLanguage/J3.2:Developing_a_MVC_Component/Adding_backend_actions#admin/controllers/helloworlds.php|admin/controllers/helloworlds.php]]''
* ''[[S:MyLanguage/J3.2:Developing_a_MVC_Component/Developing_a_Basic_Component#index.html|admin/controllers/index.html]]''
* ''[[S:MyLanguage/J3.2:Developing_a_MVC_Component/Developing_a_Basic_Component#index.html|admin/views/index.html]]''
* ''[[S:MyLanguage/J3.2:Developing_a_MVC_Component/Developing_a_Basic_Component#index.html|admin/views/helloworld/index.html]]''
* ''[[S:MyLanguage/J3.2:Developing_a_MVC_Component/Adding_backend_actions#admin/views/helloworld/view.html.php|admin/views/helloworld/view.html.php]]''
* ''[[S:MyLanguage/J3.2:Developing_a_MVC_Component/Adding_backend_actions#admin/views/helloworld/tmpl/edit.php|admin/views/helloworld/tmpl/edit.php]]''
* ''[[S:MyLanguage/J3.2:Developing_a_MVC_Component/Adding_verifications#admin/views/helloworld/submitbutton.js|admin/views/helloworld/submitbutton.js]]''
* ''[[S:MyLanguage/J3.2:Developing_a_MVC_Component/Developing_a_Basic_Component#index.html|admin/views/helloworlds/index.html]]''
* ''[[S:MyLanguage/J3.2:Developing_a_MVC_Component/Basic_backend#admin/views/helloworlds/view.html.php|admin/views/helloworlds/view.html.php]]''
* ''[[S:MyLanguage/J3.2:Developing_a_MVC_Component/Developing_a_Basic_Component#index.html|admin/views/helloworlds/tmpl/index.html]]''
* ''[[S:MyLanguage/J3.2:Developing_a_MVC_Component/Basic_backend#admin/views/helloworlds/tmpl/default.php|admin/views/helloworlds/tmpl/default.php]]''
* ''[[S:MyLanguage/J3.2:Developing_a_MVC_Component/Developing_a_Basic_Component#index.html|admin/tables/index.html]]''
* ''[[S:MyLanguage/J3.2:Developing_a_MVC_Component/Using_the_database#admin/tables/helloworld.php|admin/tables/helloworld.php]]''
* ''[[S:MyLanguage/J3.2:Developing_a_MVC_Component/Developing_a_Basic_Component#index.html|admin/language/index.html]]''
* ''[[S:MyLanguage/J3.2:Developing_a_MVC_Component/Developing_a_Basic_Component#index.html|admin/language/en-GB/index.html]]''
* ''[[S:MyLanguage/J3.x:Developing a MVC Component/Adding language management#admin.2Flanguage.2Fen-GB.2Fen-GB.com_helloworld.ini|admin/language/en-GB/en-GB.com_helloworld.ini]]''
* ''[[S:MyLanguage/J3.x:Developing a MVC Component/Adding language management#admin.2Flanguage.2Fen-GB.2Fen-GB.com_helloworld.sys.ini|admin/language/en-GB/en-GB.com_helloworld.sys.ini]]''
* ''[[S:MyLanguage/J3.2:Developing_a_MVC_Component/Developing_a_Basic_Component#index.html|media/index.html]]''
* ''[[S:MyLanguage/J3.2:Developing_a_MVC_Component/Developing_a_Basic_Component#index.html|media/images/index.html]]''
* ''[[S:MyLanguage/J3.x:Developing_a_MVC_Component/Adding_decorations_to_the_backend#Adding_some_icons|media/images/tux-16x16.png]]''
* ''[[S:MyLanguage/J3.x:Developing_a_MVC_Component/Adding_decorations_to_the_backend#Adding_some_icons|media/images/tux-48x48.png]]''

Create a compressed file of this directory or directly download the [https://github.com/scionescire/Joomla-3.2-Hello-World-Component/archive/step-14-adding-ACL.zip archive] and install it using the extension manager of Joomla. You can add a menu item of this component using the menu manager in the backend.

<span id="helloworld.xml">
<tt>helloworld.xml</tt>
<source lang="xml">
<?xml version="1.0" encoding="utf-8"?>
<extension type="component" version="3.2.0" method="upgrade">

<name>COM_HELLOWORLD</name>

<creationDate>February 2015</creationDate>
<author>John Doe</author>
<authorEmail>john.doe@example.org</authorEmail>
<authorUrl>http://www.example.org</authorUrl>
<copyright>Copyright Info</copyright>
<license>License Info</license>

<version>0.0.14</version>

<description>COM_HELLOWORLD_DESCRIPTION</description>

<install> 
<sql>
<file driver="mysql" charset="utf8">sql/install.mysql.utf8.sql</file>
</sql>
</install>
<uninstall> 
<sql>
<file driver="mysql" charset="utf8">sql/uninstall.mysql.utf8.sql</file>
</sql>
</uninstall>
<update> 
<schemas>
<schemapath type="mysql">sql/updates/mysql</schemapath>
</schemas>
</update>



<files folder="site">
<filename>index.html</filename>
<filename>helloworld.php</filename>
<filename>controller.php</filename>
<folder>views</folder>
<folder>models</folder>
</files>

<languages folder="site/language">
<language tag="en-GB">en-GB/en-GB.com_helloworld.ini</language>
</languages>

<media destination="com_helloworld" folder="media">
<filename>index.html</filename>
<folder>images</folder>
</media>

<administration>

<menu link='index.php?option=com_helloworld' img="../media/com_helloworld/images/tux-16x16.png">COM_HELLOWORLD_MENU</menu>


<files folder="admin">

<filename>index.html</filename>
<filename>config.xml</filename>
<filename>helloworld.php</filename>
<filename>controller.php</filename>
<filename>access.xml</filename>

<folder>sql</folder>

<folder>tables</folder>

<folder>models</folder>

<folder>views</folder>

<folder>controllers</folder>

<folder>helpers</folder>
</files>
<languages folder="admin/language">
<language tag="en-GB">en-GB/en-GB.com_helloworld.ini</language>
<language tag="en-GB">en-GB/en-GB.com_helloworld.sys.ini</language>
</languages>
</administration>

</extension>
</source>
</span>

== Contributors ==
*[[User:Dwarkesh0204|Dwarkesh Soni]]
*[[User:cdemko|Christophe Demko]]
*[[User:oaksu|Ozgur Aksu]]
*[[User:florian_denizot|Florian Denizot]]
*[[User:HermanPeeren|Herman Peeren]]
* TDZweb (Ståle Rolf Sæbøe), Elin Waring, Neil via https://groups.google.com/forum/#!topic/joomla-dev-general/aCH3GNA91m4
*[[User:Scionescire|Scionescire]]

<div class="row">
<div class="large-6 columns">{{Basic button|S:MyLanguage/J3.x:Developing_a_MVC_Component/Adding configuration|Prev: Adding configuration|class=expand success}}</div>
<div class="large-6 columns">{{Basic button|S:MyLanguage/J3.x:Developing_a_MVC_Component/Adding an install-uninstall-update script file|Next: Adding an install-uninstall-update script file|class=expand}}</div>
</div>

<noinclude>
[[Category:Joomla! 3.x]]
[[Category:Joomla! 3.0]]
[[Category:Joomla! 3.1]]
[[Category:Joomla! 3.2]]
[[Category:Joomla! 3.3]]
[[Category:Joomla! 3.4]]
[[Category:Beginner Development]]
[[Category:Component Development]]
[[Category:Tutorials]]
[[Category:Tutorials in a Series]]
</noinclude>

J1.5:Add text to an article using template overrides

2019-10-19T05:21:41Z

Mickmackusa: Improved formatting. Best practice is === false. I am concerned that the whole string value of var text should be wrapped in quotes (but currently isn't).

{{review}}
Automatically add text to an article in Joomla! If you want to add standard text ("This text has been added automatically by Joomla!") to the end of each article that is submitted from the front end, follow these steps:

# Create a template override for the file <tt><joomla_root>/components/com_content/views/article/tmpl/form.php</tt>.
#* Create a folder called <tt><joomla_root>/templates/<your template>/html/com_content/article</tt>.<br>For the "beez" template, this folder is called <tt><joomla_root>/templates/beez/html/com_content/article</tt>.
#* Copy the standard <tt>form.php</tt> file from the components folder above to the templates folder.<br>Note: If you already have a form.php file in this folder, don't copy the file. Just edit it as indicated below.
# Edit the copy of the file you made in the override folder as follows. Find the line <source lang="javascript">
var text = <?php echo $this->editor->getContent( 'text' ); ?></source> This is line 49 in the 1.5.8 version of this file. Change this to the following: <source lang="javascript">
var text = <?php
$addToText = '<p>Joomla! automatically added this text.</p>';
if (strpos($this->article->text, $addToText) === false) {
$this->article->text .= $addToText;
}
echo $this->editor->getContent( 'text' ); ?> </source> This is checking that the text to be added is not already in the article. If it is not, then it is added to the article.
Don't forget to change the text in the variable <code>$addToText</code> to whatever you need.

That's it. Now, when you edit an article from the front end, this text will automatically be added. Note that this change does not affect editing from the back end. Also, since this is done as a template override, it only affects pages that use the overridden template.

For more information on template overrides, see the tip [[How to override the output from the Joomla! core]].

[[Category:Tips and tricks]]
[[Category:Tips and tricks 1.5]]
[[Category:Article Management]]
[[Category:Templates]]
[[Category:Template Development]]
[[Category:Tutorials]]

How to use JDate

2019-10-19T04:59:52Z

Mickmackusa: some rewording in the description

<noinclude><languages /></noinclude>

<translate>
== Introduction == 
JDate is a helper class, extended from PHP's DateTime class, which allows developers to handle date formatting more efficiently. The class allows developers to format dates for readable strings, MySQL interaction, UNIX timestamp calculation, and also provides helper methods for working in different timezones.
</translate>

<translate>
== Using JDate == 
</translate>

<translate>
=== Creating a JDate Instance === 
All of the date helper methods require an instance of the JDate class. To begin, you must create one. A JDate object may be created in two ways. One is the typical native method of simply creating a new instance:
</translate>

<source lang="php">
$date = new JDate(); // Creates a new JDate object equal to the current time.
</source>

<translate>

You may also create an instance using the static method defined in JDate:
</translate>

<source lang="php">
$date = JDate::getInstance(); // Alias of 'new JDate();'
</source>

<translate>

There is no difference between these methods, as JDate::getInstance simply creates a new instance of JDate exactly like the first method shown.


Alternatively, you may also retrieve the current date (as a JDate object) from JApplication, by using:
</translate>
<source lang="php">$date = JFactory::getDate();</source>

<translate>
=== Arguments === 


The JDate constructor (and getInstance static method) accepts two optional parameters: a date string to format and a timezone. Not passing a date string will create a JDate object with the current date and time. Not passing a timezone will allow the JDate object to use the default timezone set.
</translate>

<translate>

The first argument, if used, must be a string that can be parsed using php's native DateTime constructor. E.g:
</translate>
<source lang="php">
$currentTime = new JDate('now'); // Current date and time
$tomorrowTime = new JDate('now +1 day'); // Current date and time, + 1 day.
$Plus1MonthTime = new JDate('now +1 month'); // Current date and time, + 1 month.
$Plus1YearTime = new JDate('now +1 year'); // Current date and time, + 1 year.
$Plus1YearAnd1MonthTime = new JDate('now +1 year +1 month'); // Current date and time, + 1 year and 1 month.
$PlusTimeToTime = new JDate('now +1 hour +30 minutes +3 seconds'); // Current date and time, + 1 hour, 30 minutes and 3 seconds
$PlusTimeToTime = new JDate('now -1 hour +30 minutes +3 seconds'); // Current date and time, + 1 hour, 30 minutes and 3 seconds
$CombinedTimeToTime = new JDate('now -1 hour -30 minutes 23 seconds'); // Current date and time, - 1 hour, +30 minutes and +23 seconds

$date = new JDate('2012-12-1 15:20:00'); // 3:20 PM, December 1st, 2012
</source>

<translate>

=== Examples === 
</translate>
<translate>
=== Temporary example of date formats=== 
</translate>

<translate>

JFactory::getDate() gets a JDate object and we then do the JDate toFormat function
</translate>
<source lang="php">JFactory::getDate()->toFormat('%a %d %b %Y - %H:%M')</source>

<translate>

In Joomla! CMS 3.3 API the function "toFormat" was changed to "format", so the example above should be:
</translate>
<source lang="php">JFactory::getDate()->format('%a %d %b %Y - %H:%M')</source>

<translate>
=== Function: toISO8601(boolean $local = false) : string === 
</translate>

<source lang="php">
$date = new JDate('2016-01-01 02:00:00'); // A.M. time, in GMT timezone
</source>

<translate>

The user's local timezone can be ignored by passing a false boolean value as the function parameter or by passing no parameter at all. Passing a boolean value of true will adjust the datetime to the user's timezone. In the following example, the user's timezone is set to "America/New_York".
</translate>

<source lang="php">
$timezone = new DateTimeZone( JFactory::getUser()->getParam('timezone') );
$date->setTimezone($timezone);
echo $date->toISO8601(false); // 2016-01-01 T 02:00:00 +00:00
echo $date->toISO8601(true); // 2015-12-31 T 21:00:00-05:00 (local time in New York)
</source>

<translate>

[[Category:Development]]
</translate>

How to use JDate

2019-10-19T04:50:21Z

Mickmackusa: improved English

<noinclude><languages /></noinclude>

<translate>
== Introduction == 
JDate is a helper class, extended from PHP's DateTime class, which allows developers to handle date formatting more efficiently. The class allows developers to format dates for readable strings, MySQL interaction, UNIX timestamp calculation, and also provides helper methods for working in different timezones.
</translate>

<translate>
== Using JDate == 
</translate>

<translate>
=== Creating a JDate Instance === 
All of the date helper methods require an instance of the JDate class. To begin, you must create one. A JDate object may be created in two ways. One is the typical native method of simply creating a new instance:
</translate>

<source lang="php">
$date = new JDate(); // Creates a new JDate object equal to the current time.
</source>

<translate>

You may also create an instance using the static method defined in JDate:
</translate>

<source lang="php">
$date = JDate::getInstance(); // Alias of 'new JDate();'
</source>

<translate>

There is no difference between these methods, as JDate::getInstance simply creates a new instance of JDate exactly like the first method shown.


Alternatively, you may also retrieve the current date (as a JDate object) from JApplication, by using:
</translate>
<source lang="php">$date = JFactory::getDate();</source>

<translate>
=== Arguments === 


The JDate constructor (and getInstance static method) accepts two optional parameters: a date string to format and a timezone. Not passing a date string will create a JDate object with the current date and time. Not passing a timezone will allow the JDate object to use the default timezone set.
</translate>

<translate>

The first argument, if used, must be a string that can be parsed using php's native DateTime constructor. E.g:
</translate>
<source lang="php">
$currentTime = new JDate('now'); // Current date and time
$tomorrowTime = new JDate('now +1 day'); // Current date and time, + 1 day.
$Plus1MonthTime = new JDate('now +1 month'); // Current date and time, + 1 month.
$Plus1YearTime = new JDate('now +1 year'); // Current date and time, + 1 year.
$Plus1YearAnd1MonthTime = new JDate('now +1 year +1 month'); // Current date and time, + 1 year and 1 month.
$PlusTimeToTime = new JDate('now +1 hour +30 minutes +3 seconds'); // Current date and time, + 1 hour, 30 minutes and 3 seconds
$PlusTimeToTime = new JDate('now -1 hour +30 minutes +3 seconds'); // Current date and time, + 1 hour, 30 minutes and 3 seconds
$CombinedTimeToTime = new JDate('now -1 hour -30 minutes 23 seconds'); // Current date and time, - 1 hour, +30 minutes and +23 seconds

$date = new JDate('2012-12-1 15:20:00'); // 3:20 PM, December 1st, 2012
</source>

<translate>

=== Examples === 
</translate>
<translate>
=== Temporary example of date formats=== 
</translate>

<translate>

JFactory::getDate() gets a JDate object and we then do the JDate toFormat function
</translate>
<source lang="php">JFactory::getDate()->toFormat('%a %d %b %Y - %H:%M')</source>

<translate>

In Joomla! CMS 3.3 API the function "toFormat" was changed to "format", so the example above should be:
</translate>
<source lang="php">JFactory::getDate()->format('%a %d %b %Y - %H:%M')</source>

<translate>
=== Function: toISO8601(boolean $local = false) : string === 
</translate>

<source lang="php">
$date = new JDate('2016-01-01 02:00:00'); // A.M. time, in GMT timezone
</source>

<translate>

We set function param before to "false" and after to "true" (user timezone is set to "America/New_York"), we get:
</translate>

<source lang="php">
$timezone = new DateTimeZone( JFactory::getUser()->getParam('timezone') );
$date->setTimezone($timezone);
echo $date->toISO8601(false); // 2016-01-01 T 02:00:00 +00:00
echo $date->toISO8601(true); // 2015-12-31 T 21:00:00-05:00 (local time in New York)
</source>

<translate>

[[Category:Development]]
</translate>

Using the JFactory class

2019-10-19T03:46:14Z

Mickmackusa: /* JFactory::getUser() */ rewording in the description, fixed deadlink

{{Top portal heading|color=white-bkgd|icon=magic|icon-color=#5091cd|size=3x|text-color=#333|title=Tutorial<br />
Using the JFactory Class}}
<noinclude>{{Joomla version|version=3.0|time=and after|comment=<series}}</noinclude>
{{-}}
== Introduction ==

JFactory is the Joomla! Platform class, giving you access to the most important (mostly singletons) parts in Joomla. It contains multiple other objects, like the application one or the Joomla! global configuration.

== JFactory::getApplication() ==

Returns the JApplicationCMS, through it you can access for the example do redirects, access the configuration and the input variables, the Menu or enqueue messages which are shown to the user.

*See [[S:MyLanguage/Using the JFactory class/Using the JApplication class|Using the JApplication class]] for more details.

== JFactory::getDocument() ==

Provides access to the current JDocument, with it you can set Meta data, add styles and scripts and more related to the document.

*See [https://docs.joomla.org/J3.x:Adding_JavaScript_and_CSS_to_the_page Adding JavaScript and CSS to the page]

== JFactory::getDbo() ==

Returns a database object. [https://api.joomla.org/cms-3/classes/JDatabaseDriver.html JDatabase methods] are executed by chaining to the database object.

Examples:

<source lang="php">
$db = JFactory::getDbo();
$query = $db->getQuery(true);
</source>

<source lang="php">$query = JFactory::getDbo()->getQuery(true);</source>

*See also [https://docs.joomla.org/Selecting_data_using_JDatabase Selecting data using JDatabase]

== JFactory::getUser() ==

Returns the user object for the currently logged in user (JUser). The object provides access to preloaded values specific to the logged in user as well as methods within the class. If no user is logged in, the user is deemed a "guest" and the id of the user is set to zero.

*See [https://docs.joomla.org/Accessing_the_current_user_object Accessing the current user object]

== JFactory::getDate() ==

Returns a [[S:MyLanguage/Using the JFactory class/How to use JDate|How to use JDate]] instance, you can also add a time and a timezone offset to it. Without parameters it uses the current time.

== JFactory::getMailer() ==

Provides access to the Joomla Mailer (wrapper around PHPMailer) for sending emails with Joomla.

*See also [[Sending email from extensions]]

== JFactory::getConfig() ==

Returns a registry with the Joomla! configuration file (configuration.php), see JConfig for more details. To access single values you can use <tt>JFactory::getApplication()->get('configValue')</tt>

*See also Getting global configuration parameters

== JFactory::getSession() ==

Returns the current visitors session. (Make sure Joomla! is called as Webapplication)

== External Links ==

*[https://api.joomla.org/cms-3/classes/JFactory.html API Docs for JFactory]

<noinclude>
[[Category:JFactory]]
[[Category:Tutorials]][[Category:Framework]]
[[Category:Module Development]]
[[Category:Plugin Development]]
[[Category:Component Development]]
</noinclude>

Using the JFactory class

2019-10-19T03:31:21Z

Mickmackusa: /* JFactory::getDocument() */ fixed broken link

{{Top portal heading|color=white-bkgd|icon=magic|icon-color=#5091cd|size=3x|text-color=#333|title=Tutorial<br />
Using the JFactory Class}}
<noinclude>{{Joomla version|version=3.0|time=and after|comment=<series}}</noinclude>
{{-}}
== Introduction ==

JFactory is the Joomla! Platform class, giving you access to the most important (mostly singletons) parts in Joomla. It contains multiple other objects, like the application one or the Joomla! global configuration.

== JFactory::getApplication() ==

Returns the JApplicationCMS, through it you can access for the example do redirects, access the configuration and the input variables, the Menu or enqueue messages which are shown to the user.

*See [[S:MyLanguage/Using the JFactory class/Using the JApplication class|Using the JApplication class]] for more details.

== JFactory::getDocument() ==

Provides access to the current JDocument, with it you can set Meta data, add styles and scripts and more related to the document.

*See [https://docs.joomla.org/J3.x:Adding_JavaScript_and_CSS_to_the_page Adding JavaScript and CSS to the page]

== JFactory::getDbo() ==

Returns a database object. [https://api.joomla.org/cms-3/classes/JDatabaseDriver.html JDatabase methods] are executed by chaining to the database object.

Examples:

<source lang="php">
$db = JFactory::getDbo();
$query = $db->getQuery(true);
</source>

<source lang="php">$query = JFactory::getDbo()->getQuery(true);</source>

*See also [https://docs.joomla.org/Selecting_data_using_JDatabase Selecting data using JDatabase]

== JFactory::getUser() ==

Returns the current Joomla! user object (JUser), with it you can access information and methods related to users. It is also created for guests, where the id is zero.

*See [[S:MyLanguage/Using the JFactory class/Accessing the current user object|Accessing the current user object]]

== JFactory::getDate() ==

Returns a [[S:MyLanguage/Using the JFactory class/How to use JDate|How to use JDate]] instance, you can also add a time and a timezone offset to it. Without parameters it uses the current time.

== JFactory::getMailer() ==

Provides access to the Joomla Mailer (wrapper around PHPMailer) for sending emails with Joomla.

*See also [[Sending email from extensions]]

== JFactory::getConfig() ==

Returns a registry with the Joomla! configuration file (configuration.php), see JConfig for more details. To access single values you can use <tt>JFactory::getApplication()->get('configValue')</tt>

*See also Getting global configuration parameters

== JFactory::getSession() ==

Returns the current visitors session. (Make sure Joomla! is called as Webapplication)

== External Links ==

*[https://api.joomla.org/cms-3/classes/JFactory.html API Docs for JFactory]

<noinclude>
[[Category:JFactory]]
[[Category:Tutorials]][[Category:Framework]]
[[Category:Module Development]]
[[Category:Plugin Development]]
[[Category:Component Development]]
</noinclude>

Using the JFactory class

2019-10-19T03:08:12Z

Mickmackusa: /* JFactory::getDbo() */ rewording of description, removed unnecessary parentheses, fixed deadlink, added new relevant link

{{Top portal heading|color=white-bkgd|icon=magic|icon-color=#5091cd|size=3x|text-color=#333|title=Tutorial<br />
Using the JFactory Class}}
<noinclude>{{Joomla version|version=3.0|time=and after|comment=<series}}</noinclude>
{{-}}
== Introduction ==

JFactory is the Joomla! Platform class, giving you access to the most important (mostly singletons) parts in Joomla. It contains multiple other objects, like the application one or the Joomla! global configuration.

== JFactory::getApplication() ==

Returns the JApplicationCMS, through it you can access for the example do redirects, access the configuration and the input variables, the Menu or enqueue messages which are shown to the user.

*See [[S:MyLanguage/Using the JFactory class/Using the JApplication class|Using the JApplication class]] for more details.

== JFactory::getDocument() ==

Provides access to the current JDocument, with it you can set Meta data, add styles and scripts and more related to the document.

*See [[S:MyLanguage/Using the JFactory class/Adding JavaScript and CSS to the page|Adding JavaScript and CSS to the page]]

== JFactory::getDbo() ==

Returns a database object. [https://api.joomla.org/cms-3/classes/JDatabaseDriver.html JDatabase methods] are executed by chaining to the database object.

Examples:

<source lang="php">
$db = JFactory::getDbo();
$query = $db->getQuery(true);
</source>

<source lang="php">$query = JFactory::getDbo()->getQuery(true);</source>

*See also [https://docs.joomla.org/Selecting_data_using_JDatabase Selecting data using JDatabase]

== JFactory::getUser() ==

Returns the current Joomla! user object (JUser), with it you can access information and methods related to users. It is also created for guests, where the id is zero.

*See [[S:MyLanguage/Using the JFactory class/Accessing the current user object|Accessing the current user object]]

== JFactory::getDate() ==

Returns a [[S:MyLanguage/Using the JFactory class/How to use JDate|How to use JDate]] instance, you can also add a time and a timezone offset to it. Without parameters it uses the current time.

== JFactory::getMailer() ==

Provides access to the Joomla Mailer (wrapper around PHPMailer) for sending emails with Joomla.

*See also [[Sending email from extensions]]

== JFactory::getConfig() ==

Returns a registry with the Joomla! configuration file (configuration.php), see JConfig for more details. To access single values you can use <tt>JFactory::getApplication()->get('configValue')</tt>

*See also Getting global configuration parameters

== JFactory::getSession() ==

Returns the current visitors session. (Make sure Joomla! is called as Webapplication)

== External Links ==

*[https://api.joomla.org/cms-3/classes/JFactory.html API Docs for JFactory]

<noinclude>
[[Category:JFactory]]
[[Category:Tutorials]][[Category:Framework]]
[[Category:Module Development]]
[[Category:Plugin Development]]
[[Category:Component Development]]
</noinclude>

Secure coding guidelines

2019-10-19T01:59:10Z

Mickmackusa: /* Secure arrays of integers */ $catId is NOT modified by reference; the return value must overwrite the input variable. https://joomla.stackexchange.com/a/22898/12352

Joomla includes many features that help with the task of securing applications and extensions built on it. You should always use these features if at all possible as they have been tried and tested by the many eyes of the developer community and any updates that might conceivably be required in the future will be automatically available whenever a Joomla update is applied. What follows is a description of best practice in using the Joomla API to ensure that your extensions are as secure as possible.

==Getting data from the request==
{{JVer|3.x}} Starting with Joomla version 3.0, [[Retrieving_request_data_using_JInput|JInput]] should be used instead of [[JRequest]].

All input originating from a user must be considered potentially dangerous and must be cleaned before being used. You should always use the Joomla [[Retrieving_request_data_using_JInput|JInput]] class to retrieve data from the request, rather than the raw $_GET, $_POST or $_REQUEST variables as the [[Retrieving_request_data_using_JInput|JInput]] methods apply input filtering by default. JInput deals with all aspects of the user request in a way that is independent of the request method used. It can also be used to retrieve cookie data and even server and environment variables. However, it is important to use the correct [[Retrieving_request_data_using_JInput|JInput]] method to ensure maximum security. It is very easy to just use the [[Retrieving_request_data_using_JInput#Getting_Values|JInput->get]] method with default parameters and ignore the fact that in many cases it is possible to apply a more stringent requirement on user input.

It very important to understand that the [[Retrieving_request_data_using_JInput|JInput]] methods are not SQL-aware and further work is required to guard against SQL injection attacks.There is no default value that will be returned if no default is specified in the call the [[Retrieving_request_data_using_JInput#Getting_Values|JInput->get]]. If no default is specified and the argument is not present in the request variable then it will return undefined.

Using [[Retrieving_request_data_using_JInput|JInput]] also obviates the need to pay attention to the setting of magic_quotes_gpc. [[Retrieving_request_data_using_JInput|JInput]] does the right thing, regardless of whether magic_quotes_gpc is on or off. See http://php.net/manual/en/security.magicquotes.php for further information.

When considering user input you should think about the data type you are expecting to retrieve and apply the most stringent form of [[Retrieving_request_data_using_JInput#Getting_Values|JInput]] that is applicable in each case. In particular, avoid the lazy approach of using [[Retrieving_request_data_using_JInput#Getting_Values|JInput->get]] as this will return an array that may contain entries that you did not expect and although each of those entries will have been cleaned, it is often the case that additional filtering could have been applied to some individual arguments. For example, the get method treats all arguments as strings, whereas it may be possible to restrict some arguments to be integers.

The first three parameters of each of the JInput get methods are the same. Only the first parameter is mandatory. In general, the format is
<source lang="php">
JFactory::getApplication->input-><data-source>->get<type>( <name>, <default> )
</source>
where

{| class="wikitable" border="1"
| <type> || the data type to be retrieved (see below for the types available).
|-
| <name> || the name of the variable to be retrieved (for example, the name of an argument in a URL).
|-
| <default> || the default value.
|-
| <data-source> || specifies where the variable is to be retrieved from (see below).
|}

The following values for <data-source> are supported:

{| class="wikitable" border="1"
| get || Data submitted in the query part of the URL.
|-
| post || Data submitted from form fields.
|-
| method || The same as either GET or POST depending on how the request was made.
|-
| cookie || Data submitted in cookies.
|-
| request || All the GET, POST and COOKIE data combined. This is the default.
|-
| files || Information about files uploaded as part of a POST request.
|-
| env || Environment variables (platform-specific).
|-
| server || Web server variables (platform-specific).
|}

Notice that the default is REQUEST, which includes cookie data.

The following sections look at each of the data types in more detail.

===Integer===
The following will accept an integer. An integer can include a leading minus sign, but a plus sign is not permitted.
<source lang="php">
$integer = JFactory::getApplication->input->getInt( 'id' );
</source>
will return the value of the "id" argument from the request (which by default includes all GET, POST and COOKIE data). The default value is zero.
<source lang="php">
$integer = JFactory::getApplication->input->cookie->getInt( 'myId', 12 );
</source>
will return the value of the "myId" variable from a cookie, with a default value of 12.

===Floating point number===
A floating point number can include a leading minus sign, but not a plus sign. If the number includes a decimal point, then there must be at least one digit before the decimal point. For example,
<source lang="php">
$float = JFactory::getApplication->input->getFloat( 'price' );
</source>
will return the value of the 'price' argument from the request. The default is "0.0".
<source lang="php">
$float = JFactory::getApplication->input->post->getFloat( 'total', 100.00 );
</source>
will retrieve the value of the 'total' argument from a POST request (but not a GET), with a default value of 100.00.

===Boolean value===
Any non-zero value is regarded as being true; zero is false.
<source lang="php">
$boolean = JFactory::getApplication->input->getBool( 'show' );
</source>
will return false if the value of the 'show' argument in the request is zero, or 1 (true) if the argument is anything else. The default is false. Note that any string argument will result in a return value of true, so calling the above with a URL containing "?show=false" will actually return true!
<source lang="php">
$boolean = JFactory::getApplication->input->get->getBool( 'hide', true );
</source>
will retrieve the value of the 'hide' argument from a GET request (but not a POST), with a default value of true.

===Word===
A word is defined as being a string of alphabetic characters. The underscore character is permitted as part of a word.
<source lang="php">
$word = JFactory::getApplication->input->cookie->getWord( 'search-word' );
</source>
will retrieve the value of the 'search-word' argument from the request. The default is an empty string.
<source lang="php">
$word = JFactory::getApplication->input->cookie->getWord( 'keyword', '' );
</source>
will retrieve the value of the 'keyword' variable from a cookie, with the default being an empty string.

===Command===
A command is like a word but a wider range of characters is permitted. Allowed characters are: all alphanumeric characters, dot, dash (hyphen) and underscore.
<source lang="php">
$command = JFactory::getApplication->input->getCmd( 'option' );
</source>
will retrieve the value of the "option" argument from the request. The default value is an empty string.
<source lang="php">
$command = JFactory::getApplication->input->post->getCmd( 'controller', 'view' );
</source>
will retrieve the value of the "controller" argument from a POST request (but not a GET), with a default value of 'view'.

===String===
The string type allows a much wider range of input characters. It also takes an optional fourth argument specifying some additional mask options. See [[#Filter options]] for information on the available masks.
<source lang="php">
$string = JFactory::getApplication->input->getString( 'description' );
</source>
will retrieve the value of the "description" argument from the request. The default value is an empty string. The input will have whitespace removed from the left and right ends and any HTML tags will be removed.
<source lang="php">
$string = JFactory::getApplication->input->getString( 'text', '' );
</source>
will retrieve the value of the "text" argument from the request.. The default value is an empty string.
<source lang="php">
$string = JFactory::getApplication->input->getString( 'template', '<html />' );
</source>
will retrieve the value of the "template" argument from the request. The default value is '<html />'.

===JSON String===
<source lang="php">
$json = JFactory::getApplication->input->json->get( 'var_name' );
</source>

===Generic and other data types===
If the above methods do not meet your needs, there is a small number of additional filter types which you can use by calling the [[Retrieving_request_data_using_JInput#Getting_Values|JInput->get]] method directly. The syntax is:
<source lang="php">
JFactory::getApplication->input->get( <name>, <default>, <type> );
</source>
where:

{| class="wikitable" border="1"
| <name> || the name of the variable to be retrieved (for example, the name of an argument in a URL).
|-
| <default> || the default value. There is no default value that will be returned if no default is specified in the call the [[Retrieving_request_data_using_JInput#Getting_Values|JInput->get]]. If no default is specified and the argument is not present in the request variable then it will return undefined.
|-
| <type> || specifies the data type expected (see below).
|}

The first three arguments are the same as for the more specific methods described earlier. Only the first argument is mandatory.

Allowed values of the <type>, which is case-insensitive, are as follows:

{| class="wikitable" border="1"
| INT, INTEGER || Equivalent to [[Retrieving_request_data_using_JInput#Getting_Values|JInput->getInt]].
|-
| UINT || Get an unsigned integer. Equivalent to [[Retrieving_request_data_using_JInput#Getting_Values|JInput->getUint]].
|-
| FLOAT, DOUBLE || Equivalent to [[Retrieving_request_data_using_JInput#Getting_Values|JInput->getFloat]].
|-
| BOOL, BOOLEAN || Equivalent to [[Retrieving_request_data_using_JInput#Getting_Values|JInput->getBool]].
|-
| WORD || Equivalent to [[Retrieving_request_data_using_JInput#Getting_Values|JInput->getWord]].
|-
| ALNUM || Allow only alphanumeric characters (a-z, A-Z, 0-9). Equivalent to [[Retrieving_request_data_using_JInput#Getting_Values|JInput->getAlnum]].
|-
| CMD || Equivalent to [[Retrieving_request_data_using_JInput#Getting_Values|JInput->getCmd]].
|-
| BASE64 || Allow only those characters that could be present in a base64-encoded string (ie. a-z, A-Z, 0-9, /, + and =). Equivalent to [[Retrieving_request_data_using_JInput#Getting_Values|JInput->getBase64]].
|-
| STRING || Equivalent to [[Retrieving_request_data_using_JInput#Getting_Values|JInput->getString]].
|-
| ARRAY || Source is not filtered but is cast to array type.
|-
| HTML || A sanitised string. Equivalent to [[Retrieving_request_data_using_JInput#Getting_Values|JInput->getHtml]].
|-
| PATH || Valid pathname regex that filters out common attacks. For example, any path beginning with a "/" will return an empty string. Simliarly, any path containing "/./" or "/../" will return an empty string. Dots within filenames are okay though. Equivalent to [[Retrieving_request_data_using_JInput#Getting_Values|JInput->getPath]].
|-
| USERNAME || Removes control characters (0x00 - 0x1F), 0x7F, <, >, ", ', % and &. Equivalent to [[Retrieving_request_data_using_JInput#Getting_Values|JInput->getUsername]].
|}

===Filter options===
All input values can be filtered using JFilterInput->clean.

Filter an array of values.
<source lang="php">
$data = JFactory::getApplication()->input->post->get('data', array(), 'array');
$filter = JFilterInput::getInstance();

foreach ($data as $value)
{
$array[] = $filter->clean($value, 'string');
}
</source>
For more filter types see [https://github.com/joomla/joomla-cms/blob/master/libraries/joomla/filter/input.php#L115 JFilterInput source].

Options listed bellow available only in deprecated [[JRequest]] library.
Allowed values of <options> are as follows (none of these are applied by default):

{| class="wikitable" border="1"
| JREQUEST_NOTRIM || Does not remove whitespace from the start and ends of strings.
|-
| JREQUEST_ALLOWRAW || Does not do any filtering at all. Use with extreme caution.
|-
| JREQUEST_ALLOWHTML || Does not remove HTML from string inputs.
|}

Masks can be combined by logically OR'ing them. If no filter options are specified, then by default, whitespace is trimmed and HTML is removed.

===File uploads===
Web servers already have a good deal of security around handling file uploads, but it is still necessary to take additional steps to ensure that file names and paths cannot be abused. A simplified form which requests a file to be uploaded looks like this:
<source lang="html4strict">
<form action="index.php?option=com_mycomponent/form_handler.php" method="post" enctype="multipart/form-data">
<input type="file" name="Filedata" />
<input type="submit" />
</form>
</source>
On clicking the submit button, the browser will upload the file in a POST request, passing control to Joomla which will call "components/com_mycomponent/form_handler.php". This will include code like the following. The variable $somepath must be set to some path where the web server has permission to create files.
<source lang="php">
// Check to ensure this file is included in Joomla!
defined('_JEXEC') or die( 'Restricted access' );

// Get the file data array from the request.
$file = JFactory::getApplication->input->get( 'Filedata', '', 'files', 'array' );

// Make the file name safe.
jimport('joomla.filesystem.file');
$file['name'] = JFile::makeSafe($file['name']);

// Move the uploaded file into a permanent location.
if (isset( $file['name'] )) {

// Make sure that the full file path is safe.
$filepath = JPath::clean( $somepath.'/'.strtolower( $file['name'] ) );

// Move the uploaded file.
JFile::upload( $file['tmp_name'], $filepath );
}
</source>

===Saving a request variable into user state===
Because setting a user state variable from a variable in the request is such a common operation, there is an API method to make the task easier. This is generally safe to use because it calls [[Retrieving_request_data_using_JInput#Getting_Values|JInput->get]] to obtain the input from the request, but remember that none of the input filtering calls will protect against SQL injection attempts.
<source lang="php">
$app = JFactory::getApplication();
$app->getUserStateFromRequest( <key>, <name>, <default>, <type> );
</source>
where
{| class="wikitable" border="1"
| <key> || the name of the variable in the user state.
|-
| <name> || the name of the request variable (same as the first argument of a [[Retrieving_request_data_using_JInput#Getting_Values|JInput->get]] call).
|-
| <default> || the default value to be assigned to the user state variable if the request variable is absent. The default is null.
|-
| <type> || the type of variable expected.
|}

For example, getting an integer variable called 'id' from the request with a default value of 0, then saving it into a session variable called 'myid' can be done like this:
<source lang="php">
$app = JFactory::getApplication();
$app->getUserStateFromRequest( 'myid', 'id, 0, 'int' );
</source>
instead of something like this:
<source lang="php">
$app = JFactory::getApplication();
$app->setUserState( 'myid', $app->input->getInt( 'id', 0 ) );
</source>

==Constructing SQL queries==
One of the most common forms of attack on web applications is SQL injection, where the aim of the attacker is to change a database query by exploiting a poorly filtered input variable. Injecting modified SQL statements into the database can damage data or reveal private information. It is important to ensure that when SQL statements are constructed, they are correctly escaped and quoted so that bad input data cannot result in a bad SQL statement. You cannot rely on the [[Retrieving_request_data_using_JInput|JInput]] methods to do this as they are not SQL-aware.

===Secure integers and the rest of numeric values===
With the MySQL database, numeric fields should not be quoted, so it is important that they be typecast instead. Failure to do this will leave your code vulnerable to an attacker inserting a string containing SQL data.

Depending on the type, numeric types are cast like this:
<source lang="php">
// For SQL data types: INT, INTEGER, TINYINT, SMALLINT, MEDIUMINT, BIGINT, YEAR
$query = 'SELECT * FROM #__table WHERE `id`=' . (int) $id;

// For SQL data types: FLOAT, DOUBLE
$query = 'SELECT * FROM #__table WHERE `id`=' . (float) $id;
</source>
It's a good idea to get into the habit of always typecasting integers like this even if the variable was previously obtained using JInput->getInt. Further information on SQL injection attacks can be found here: http://php.net/manual/en/security.database.sql-injection.php and here: [[Retrieving_request_data_using_JInput#Getting_Values]].

===Secure strings===
In the examples that follow it is assumed that $db is an instance of a Joomla database object. This can always be obtained from [[JFactory]] using
<source lang="php">
$db = JFactory::getDBO();
</source>
Strings should always be escaped before being used in an SQL statement. This is actually very simple as the [[JDatabase/quote|JDatabase->quote]] method escapes everything for you. You can also use the [[JDatabase/escape|JDatabase->escape]] method directly. The following statements are equivalent:
<source lang="php">
$query = 'SELECT * FROM #__table WHERE `field` = ' . $db->quote( $db->escape( $field ), false );

$query = 'SELECT * FROM #__table WHERE `field` = ' . $db->quote( $field );
</source>
===Secure on search===
Special attention should be paid to LIKE clauses which contain the % wildcard character as these require special escaping in order to avoid possible denial of service attacks. LIKE clauses can be handled like this:
<source lang="php">
// Construct the search term by escaping the user-supplied string and, if required, adding the % wildcard characters manually.
$search = '%' . $db->escape( $search, true ) . '%';

// Construct the SQL query, being careful to suppress the default behaviour of Quote so as to prevent double-escaping.
$query = 'SELECT * FROM #__table WHERE `field` LIKE ' . $db->quote( $search, false );
</source>

===Secure dates===
If data is to be entered into a datetime column then you can use the Joomla API to ensure a valid date format:
<source lang="php">
$date = JFactory::getDate( $mydate );
$query = 'UPDATE #__table SET `date` = ' . $db->quote( $date->toMySQL(), false );
</source>
Note that it is necessary to suppress database escaping as legitimate dates may contain characters that should not be escaped.

===Secure field names===
In the comparatively rare case where a field name is a variable, that should also be quoted using an API call:
<source lang="php">
$query = 'SELECT * FROM #__table WHERE ' . $db->quoteName( $field->name ) . '=' . $db->quote( $field->value );
</source>

===Secure arrays of integers===
When you have an array of ids, typically used for IN() queries, you have to sanitise it also with JArrayHelper::toInteger($cid); before imploding:

<source lang="php">
...
$catId = JArrayHelper::toInteger($catId);
$query->where($db->quoteName('x.category_id') . ' IN (' . implode(',', $catId) . ')');
</source>

===Short aliases of Quote and QuoteName===
Shorter alternatives to the quote methods may also be used. The following statements are equivalent:
<source lang="php">
$query = 'SELECT * FROM #__table WHERE ' . $db->quoteName( $field->name ) . '=' . $db->quote( $field->value );
$query = 'SELECT * FROM #__table WHERE ' . $db->qn( $field->name ) . '=' . $db->q( $field->value );
</source>

==Securing forms==
Apart from cleaning input variables as described above, you can also implement a simple technique which makes it more difficult for a cross-site request forgery attack (CSRF) to succeed. This involves adding a randomly-generated unique token to the form which is checked against a copy of the token held in the user's session. By checking that the submitted token matches the one contained in the stored session, it is possible to tie a rendered form to the request variables presented.

In POST forms you should add a hidden token field using:
<source lang="php">
echo JHTML::_( 'form.token' );
</source>
This outputs the token as a hidden form field looking like this:
<source lang="html4strict">
<input type="hidden" name="8cb24ae69ffd7828ccecbcf06056e6fc" value="1" />
</source>
and places a copy of the token into the user's session, for later checking.

If you need to add the token to a URL rather than a form then you can use something like this:
<source lang="php">
echo JRoute::_( 'index.php?option=com_mycomponent&' . JSession::getFormToken() . '=1' );
</source>

In the most common scenario, you will want to check the token following a POST to the form handler. This can be done by adding this line of code to form handler:
<source lang="php">
JSession::checkToken() or die( JText::_( 'Invalid Token' ) );
</source>
If you need to pass the token in a GET request then you can check it like this:
<source lang="php">
JSession::checkToken( 'get' ) or die( JText::_( 'Invalid Token' ) );
</source>

In both cases the code will die if the token is omitted from the request, or the submitted token does not match the session token. If the token is correct but has expired, then [[JSession/checkToken|JSession::checkToken]] will automatically redirect to the site front page.

==Cleaning filesystem paths==
If there is any possibility that a filesystem path might be constructed using data that originated from user input, then the path must be cleaned and checked before being used. This can be done quite simply like this:
<source lang="php">
JPath::check( $path );
</source>
This will raise an error and terminate Joomla if the path contains a ".." or leads to a location outside the Joomla root directory. If you want to deal with the error yourself without terminating the application, then you can use code like this:
<source lang="php">
$path = JPath::clean( $path );
if (strpos( $path, JPath::clean( JPATH_ROOT ) ) !== 0) {
// Handle the error here.
}
</source>
The [[JPath:clean]] method can be used in your own code too. It merely removes leading and trailing whitespace and replace double slashes and backslashes with the standard directory separator.

==Cleaning filesystem file names==
As with filesystem paths, if there is any possibility that a file name might be constructed using user-originated data, then the file name must be cleaned and checked before use. This can be done like this:
<source lang="php">
jimport('joomla.filesystem.file');
$clean = JFile::makeSafe( $unclean );
</source>
This method removes sequences of two or more "." characters and any character that is not alphabetic, numeric or a dot, dash or underscore character. If there is a leading dot then that is removed too.
[[Category:Development]][[Category:Security]]

Secure coding guidelines

2019-10-19T01:49:37Z

Mickmackusa: /* Short aliases of Quote and QuoteName */ fixed syntax error regarding property arrow

Joomla includes many features that help with the task of securing applications and extensions built on it. You should always use these features if at all possible as they have been tried and tested by the many eyes of the developer community and any updates that might conceivably be required in the future will be automatically available whenever a Joomla update is applied. What follows is a description of best practice in using the Joomla API to ensure that your extensions are as secure as possible.

==Getting data from the request==
{{JVer|3.x}} Starting with Joomla version 3.0, [[Retrieving_request_data_using_JInput|JInput]] should be used instead of [[JRequest]].

All input originating from a user must be considered potentially dangerous and must be cleaned before being used. You should always use the Joomla [[Retrieving_request_data_using_JInput|JInput]] class to retrieve data from the request, rather than the raw $_GET, $_POST or $_REQUEST variables as the [[Retrieving_request_data_using_JInput|JInput]] methods apply input filtering by default. JInput deals with all aspects of the user request in a way that is independent of the request method used. It can also be used to retrieve cookie data and even server and environment variables. However, it is important to use the correct [[Retrieving_request_data_using_JInput|JInput]] method to ensure maximum security. It is very easy to just use the [[Retrieving_request_data_using_JInput#Getting_Values|JInput->get]] method with default parameters and ignore the fact that in many cases it is possible to apply a more stringent requirement on user input.

It very important to understand that the [[Retrieving_request_data_using_JInput|JInput]] methods are not SQL-aware and further work is required to guard against SQL injection attacks.There is no default value that will be returned if no default is specified in the call the [[Retrieving_request_data_using_JInput#Getting_Values|JInput->get]]. If no default is specified and the argument is not present in the request variable then it will return undefined.

Using [[Retrieving_request_data_using_JInput|JInput]] also obviates the need to pay attention to the setting of magic_quotes_gpc. [[Retrieving_request_data_using_JInput|JInput]] does the right thing, regardless of whether magic_quotes_gpc is on or off. See http://php.net/manual/en/security.magicquotes.php for further information.

When considering user input you should think about the data type you are expecting to retrieve and apply the most stringent form of [[Retrieving_request_data_using_JInput#Getting_Values|JInput]] that is applicable in each case. In particular, avoid the lazy approach of using [[Retrieving_request_data_using_JInput#Getting_Values|JInput->get]] as this will return an array that may contain entries that you did not expect and although each of those entries will have been cleaned, it is often the case that additional filtering could have been applied to some individual arguments. For example, the get method treats all arguments as strings, whereas it may be possible to restrict some arguments to be integers.

The first three parameters of each of the JInput get methods are the same. Only the first parameter is mandatory. In general, the format is
<source lang="php">
JFactory::getApplication->input-><data-source>->get<type>( <name>, <default> )
</source>
where

{| class="wikitable" border="1"
| <type> || the data type to be retrieved (see below for the types available).
|-
| <name> || the name of the variable to be retrieved (for example, the name of an argument in a URL).
|-
| <default> || the default value.
|-
| <data-source> || specifies where the variable is to be retrieved from (see below).
|}

The following values for <data-source> are supported:

{| class="wikitable" border="1"
| get || Data submitted in the query part of the URL.
|-
| post || Data submitted from form fields.
|-
| method || The same as either GET or POST depending on how the request was made.
|-
| cookie || Data submitted in cookies.
|-
| request || All the GET, POST and COOKIE data combined. This is the default.
|-
| files || Information about files uploaded as part of a POST request.
|-
| env || Environment variables (platform-specific).
|-
| server || Web server variables (platform-specific).
|}

Notice that the default is REQUEST, which includes cookie data.

The following sections look at each of the data types in more detail.

===Integer===
The following will accept an integer. An integer can include a leading minus sign, but a plus sign is not permitted.
<source lang="php">
$integer = JFactory::getApplication->input->getInt( 'id' );
</source>
will return the value of the "id" argument from the request (which by default includes all GET, POST and COOKIE data). The default value is zero.
<source lang="php">
$integer = JFactory::getApplication->input->cookie->getInt( 'myId', 12 );
</source>
will return the value of the "myId" variable from a cookie, with a default value of 12.

===Floating point number===
A floating point number can include a leading minus sign, but not a plus sign. If the number includes a decimal point, then there must be at least one digit before the decimal point. For example,
<source lang="php">
$float = JFactory::getApplication->input->getFloat( 'price' );
</source>
will return the value of the 'price' argument from the request. The default is "0.0".
<source lang="php">
$float = JFactory::getApplication->input->post->getFloat( 'total', 100.00 );
</source>
will retrieve the value of the 'total' argument from a POST request (but not a GET), with a default value of 100.00.

===Boolean value===
Any non-zero value is regarded as being true; zero is false.
<source lang="php">
$boolean = JFactory::getApplication->input->getBool( 'show' );
</source>
will return false if the value of the 'show' argument in the request is zero, or 1 (true) if the argument is anything else. The default is false. Note that any string argument will result in a return value of true, so calling the above with a URL containing "?show=false" will actually return true!
<source lang="php">
$boolean = JFactory::getApplication->input->get->getBool( 'hide', true );
</source>
will retrieve the value of the 'hide' argument from a GET request (but not a POST), with a default value of true.

===Word===
A word is defined as being a string of alphabetic characters. The underscore character is permitted as part of a word.
<source lang="php">
$word = JFactory::getApplication->input->cookie->getWord( 'search-word' );
</source>
will retrieve the value of the 'search-word' argument from the request. The default is an empty string.
<source lang="php">
$word = JFactory::getApplication->input->cookie->getWord( 'keyword', '' );
</source>
will retrieve the value of the 'keyword' variable from a cookie, with the default being an empty string.

===Command===
A command is like a word but a wider range of characters is permitted. Allowed characters are: all alphanumeric characters, dot, dash (hyphen) and underscore.
<source lang="php">
$command = JFactory::getApplication->input->getCmd( 'option' );
</source>
will retrieve the value of the "option" argument from the request. The default value is an empty string.
<source lang="php">
$command = JFactory::getApplication->input->post->getCmd( 'controller', 'view' );
</source>
will retrieve the value of the "controller" argument from a POST request (but not a GET), with a default value of 'view'.

===String===
The string type allows a much wider range of input characters. It also takes an optional fourth argument specifying some additional mask options. See [[#Filter options]] for information on the available masks.
<source lang="php">
$string = JFactory::getApplication->input->getString( 'description' );
</source>
will retrieve the value of the "description" argument from the request. The default value is an empty string. The input will have whitespace removed from the left and right ends and any HTML tags will be removed.
<source lang="php">
$string = JFactory::getApplication->input->getString( 'text', '' );
</source>
will retrieve the value of the "text" argument from the request.. The default value is an empty string.
<source lang="php">
$string = JFactory::getApplication->input->getString( 'template', '<html />' );
</source>
will retrieve the value of the "template" argument from the request. The default value is '<html />'.

===JSON String===
<source lang="php">
$json = JFactory::getApplication->input->json->get( 'var_name' );
</source>

===Generic and other data types===
If the above methods do not meet your needs, there is a small number of additional filter types which you can use by calling the [[Retrieving_request_data_using_JInput#Getting_Values|JInput->get]] method directly. The syntax is:
<source lang="php">
JFactory::getApplication->input->get( <name>, <default>, <type> );
</source>
where:

{| class="wikitable" border="1"
| <name> || the name of the variable to be retrieved (for example, the name of an argument in a URL).
|-
| <default> || the default value. There is no default value that will be returned if no default is specified in the call the [[Retrieving_request_data_using_JInput#Getting_Values|JInput->get]]. If no default is specified and the argument is not present in the request variable then it will return undefined.
|-
| <type> || specifies the data type expected (see below).
|}

The first three arguments are the same as for the more specific methods described earlier. Only the first argument is mandatory.

Allowed values of the <type>, which is case-insensitive, are as follows:

{| class="wikitable" border="1"
| INT, INTEGER || Equivalent to [[Retrieving_request_data_using_JInput#Getting_Values|JInput->getInt]].
|-
| UINT || Get an unsigned integer. Equivalent to [[Retrieving_request_data_using_JInput#Getting_Values|JInput->getUint]].
|-
| FLOAT, DOUBLE || Equivalent to [[Retrieving_request_data_using_JInput#Getting_Values|JInput->getFloat]].
|-
| BOOL, BOOLEAN || Equivalent to [[Retrieving_request_data_using_JInput#Getting_Values|JInput->getBool]].
|-
| WORD || Equivalent to [[Retrieving_request_data_using_JInput#Getting_Values|JInput->getWord]].
|-
| ALNUM || Allow only alphanumeric characters (a-z, A-Z, 0-9). Equivalent to [[Retrieving_request_data_using_JInput#Getting_Values|JInput->getAlnum]].
|-
| CMD || Equivalent to [[Retrieving_request_data_using_JInput#Getting_Values|JInput->getCmd]].
|-
| BASE64 || Allow only those characters that could be present in a base64-encoded string (ie. a-z, A-Z, 0-9, /, + and =). Equivalent to [[Retrieving_request_data_using_JInput#Getting_Values|JInput->getBase64]].
|-
| STRING || Equivalent to [[Retrieving_request_data_using_JInput#Getting_Values|JInput->getString]].
|-
| ARRAY || Source is not filtered but is cast to array type.
|-
| HTML || A sanitised string. Equivalent to [[Retrieving_request_data_using_JInput#Getting_Values|JInput->getHtml]].
|-
| PATH || Valid pathname regex that filters out common attacks. For example, any path beginning with a "/" will return an empty string. Simliarly, any path containing "/./" or "/../" will return an empty string. Dots within filenames are okay though. Equivalent to [[Retrieving_request_data_using_JInput#Getting_Values|JInput->getPath]].
|-
| USERNAME || Removes control characters (0x00 - 0x1F), 0x7F, <, >, ", ', % and &. Equivalent to [[Retrieving_request_data_using_JInput#Getting_Values|JInput->getUsername]].
|}

===Filter options===
All input values can be filtered using JFilterInput->clean.

Filter an array of values.
<source lang="php">
$data = JFactory::getApplication()->input->post->get('data', array(), 'array');
$filter = JFilterInput::getInstance();

foreach ($data as $value)
{
$array[] = $filter->clean($value, 'string');
}
</source>
For more filter types see [https://github.com/joomla/joomla-cms/blob/master/libraries/joomla/filter/input.php#L115 JFilterInput source].

Options listed bellow available only in deprecated [[JRequest]] library.
Allowed values of <options> are as follows (none of these are applied by default):

{| class="wikitable" border="1"
| JREQUEST_NOTRIM || Does not remove whitespace from the start and ends of strings.
|-
| JREQUEST_ALLOWRAW || Does not do any filtering at all. Use with extreme caution.
|-
| JREQUEST_ALLOWHTML || Does not remove HTML from string inputs.
|}

Masks can be combined by logically OR'ing them. If no filter options are specified, then by default, whitespace is trimmed and HTML is removed.

===File uploads===
Web servers already have a good deal of security around handling file uploads, but it is still necessary to take additional steps to ensure that file names and paths cannot be abused. A simplified form which requests a file to be uploaded looks like this:
<source lang="html4strict">
<form action="index.php?option=com_mycomponent/form_handler.php" method="post" enctype="multipart/form-data">
<input type="file" name="Filedata" />
<input type="submit" />
</form>
</source>
On clicking the submit button, the browser will upload the file in a POST request, passing control to Joomla which will call "components/com_mycomponent/form_handler.php". This will include code like the following. The variable $somepath must be set to some path where the web server has permission to create files.
<source lang="php">
// Check to ensure this file is included in Joomla!
defined('_JEXEC') or die( 'Restricted access' );

// Get the file data array from the request.
$file = JFactory::getApplication->input->get( 'Filedata', '', 'files', 'array' );

// Make the file name safe.
jimport('joomla.filesystem.file');
$file['name'] = JFile::makeSafe($file['name']);

// Move the uploaded file into a permanent location.
if (isset( $file['name'] )) {

// Make sure that the full file path is safe.
$filepath = JPath::clean( $somepath.'/'.strtolower( $file['name'] ) );

// Move the uploaded file.
JFile::upload( $file['tmp_name'], $filepath );
}
</source>

===Saving a request variable into user state===
Because setting a user state variable from a variable in the request is such a common operation, there is an API method to make the task easier. This is generally safe to use because it calls [[Retrieving_request_data_using_JInput#Getting_Values|JInput->get]] to obtain the input from the request, but remember that none of the input filtering calls will protect against SQL injection attempts.
<source lang="php">
$app = JFactory::getApplication();
$app->getUserStateFromRequest( <key>, <name>, <default>, <type> );
</source>
where
{| class="wikitable" border="1"
| <key> || the name of the variable in the user state.
|-
| <name> || the name of the request variable (same as the first argument of a [[Retrieving_request_data_using_JInput#Getting_Values|JInput->get]] call).
|-
| <default> || the default value to be assigned to the user state variable if the request variable is absent. The default is null.
|-
| <type> || the type of variable expected.
|}

For example, getting an integer variable called 'id' from the request with a default value of 0, then saving it into a session variable called 'myid' can be done like this:
<source lang="php">
$app = JFactory::getApplication();
$app->getUserStateFromRequest( 'myid', 'id, 0, 'int' );
</source>
instead of something like this:
<source lang="php">
$app = JFactory::getApplication();
$app->setUserState( 'myid', $app->input->getInt( 'id', 0 ) );
</source>

==Constructing SQL queries==
One of the most common forms of attack on web applications is SQL injection, where the aim of the attacker is to change a database query by exploiting a poorly filtered input variable. Injecting modified SQL statements into the database can damage data or reveal private information. It is important to ensure that when SQL statements are constructed, they are correctly escaped and quoted so that bad input data cannot result in a bad SQL statement. You cannot rely on the [[Retrieving_request_data_using_JInput|JInput]] methods to do this as they are not SQL-aware.

===Secure integers and the rest of numeric values===
With the MySQL database, numeric fields should not be quoted, so it is important that they be typecast instead. Failure to do this will leave your code vulnerable to an attacker inserting a string containing SQL data.

Depending on the type, numeric types are cast like this:
<source lang="php">
// For SQL data types: INT, INTEGER, TINYINT, SMALLINT, MEDIUMINT, BIGINT, YEAR
$query = 'SELECT * FROM #__table WHERE `id`=' . (int) $id;

// For SQL data types: FLOAT, DOUBLE
$query = 'SELECT * FROM #__table WHERE `id`=' . (float) $id;
</source>
It's a good idea to get into the habit of always typecasting integers like this even if the variable was previously obtained using JInput->getInt. Further information on SQL injection attacks can be found here: http://php.net/manual/en/security.database.sql-injection.php and here: [[Retrieving_request_data_using_JInput#Getting_Values]].

===Secure strings===
In the examples that follow it is assumed that $db is an instance of a Joomla database object. This can always be obtained from [[JFactory]] using
<source lang="php">
$db = JFactory::getDBO();
</source>
Strings should always be escaped before being used in an SQL statement. This is actually very simple as the [[JDatabase/quote|JDatabase->quote]] method escapes everything for you. You can also use the [[JDatabase/escape|JDatabase->escape]] method directly. The following statements are equivalent:
<source lang="php">
$query = 'SELECT * FROM #__table WHERE `field` = ' . $db->quote( $db->escape( $field ), false );

$query = 'SELECT * FROM #__table WHERE `field` = ' . $db->quote( $field );
</source>
===Secure on search===
Special attention should be paid to LIKE clauses which contain the % wildcard character as these require special escaping in order to avoid possible denial of service attacks. LIKE clauses can be handled like this:
<source lang="php">
// Construct the search term by escaping the user-supplied string and, if required, adding the % wildcard characters manually.
$search = '%' . $db->escape( $search, true ) . '%';

// Construct the SQL query, being careful to suppress the default behaviour of Quote so as to prevent double-escaping.
$query = 'SELECT * FROM #__table WHERE `field` LIKE ' . $db->quote( $search, false );
</source>

===Secure dates===
If data is to be entered into a datetime column then you can use the Joomla API to ensure a valid date format:
<source lang="php">
$date = JFactory::getDate( $mydate );
$query = 'UPDATE #__table SET `date` = ' . $db->quote( $date->toMySQL(), false );
</source>
Note that it is necessary to suppress database escaping as legitimate dates may contain characters that should not be escaped.

===Secure field names===
In the comparatively rare case where a field name is a variable, that should also be quoted using an API call:
<source lang="php">
$query = 'SELECT * FROM #__table WHERE ' . $db->quoteName( $field->name ) . '=' . $db->quote( $field->value );
</source>

===Secure arrays of integers===
When you have an array of ids, typically used for IN() queries, you have to sanitise it also with JArrayHelper::toInteger($cid); before imploding:

<source lang="php">
...
JArrayHelper::toInteger($catId);
$query->where($db->quoteName('x.category_id') . ' IN (' . implode(',', $catId) . ')');
</source>

===Short aliases of Quote and QuoteName===
Shorter alternatives to the quote methods may also be used. The following statements are equivalent:
<source lang="php">
$query = 'SELECT * FROM #__table WHERE ' . $db->quoteName( $field->name ) . '=' . $db->quote( $field->value );
$query = 'SELECT * FROM #__table WHERE ' . $db->qn( $field->name ) . '=' . $db->q( $field->value );
</source>

==Securing forms==
Apart from cleaning input variables as described above, you can also implement a simple technique which makes it more difficult for a cross-site request forgery attack (CSRF) to succeed. This involves adding a randomly-generated unique token to the form which is checked against a copy of the token held in the user's session. By checking that the submitted token matches the one contained in the stored session, it is possible to tie a rendered form to the request variables presented.

In POST forms you should add a hidden token field using:
<source lang="php">
echo JHTML::_( 'form.token' );
</source>
This outputs the token as a hidden form field looking like this:
<source lang="html4strict">
<input type="hidden" name="8cb24ae69ffd7828ccecbcf06056e6fc" value="1" />
</source>
and places a copy of the token into the user's session, for later checking.

If you need to add the token to a URL rather than a form then you can use something like this:
<source lang="php">
echo JRoute::_( 'index.php?option=com_mycomponent&' . JSession::getFormToken() . '=1' );
</source>

In the most common scenario, you will want to check the token following a POST to the form handler. This can be done by adding this line of code to form handler:
<source lang="php">
JSession::checkToken() or die( JText::_( 'Invalid Token' ) );
</source>
If you need to pass the token in a GET request then you can check it like this:
<source lang="php">
JSession::checkToken( 'get' ) or die( JText::_( 'Invalid Token' ) );
</source>

In both cases the code will die if the token is omitted from the request, or the submitted token does not match the session token. If the token is correct but has expired, then [[JSession/checkToken|JSession::checkToken]] will automatically redirect to the site front page.

==Cleaning filesystem paths==
If there is any possibility that a filesystem path might be constructed using data that originated from user input, then the path must be cleaned and checked before being used. This can be done quite simply like this:
<source lang="php">
JPath::check( $path );
</source>
This will raise an error and terminate Joomla if the path contains a ".." or leads to a location outside the Joomla root directory. If you want to deal with the error yourself without terminating the application, then you can use code like this:
<source lang="php">
$path = JPath::clean( $path );
if (strpos( $path, JPath::clean( JPATH_ROOT ) ) !== 0) {
// Handle the error here.
}
</source>
The [[JPath:clean]] method can be used in your own code too. It merely removes leading and trailing whitespace and replace double slashes and backslashes with the standard directory separator.

==Cleaning filesystem file names==
As with filesystem paths, if there is any possibility that a file name might be constructed using user-originated data, then the file name must be cleaned and checked before use. This can be done like this:
<source lang="php">
jimport('joomla.filesystem.file');
$clean = JFile::makeSafe( $unclean );
</source>
This method removes sequences of two or more "." characters and any character that is not alphabetic, numeric or a dot, dash or underscore character. If there is a leading dot then that is removed too.
[[Category:Development]][[Category:Security]]

Pizza Bugs and Fun 2019/Contributors List

2019-10-19T01:39:50Z

Mickmackusa: /* Pizza Bugs and Fun 2019/Contributors List */

==Pizza Bugs and Fun 2019/Contributors List==
* Stuart Robertson - Brisbane, Australia
* Scott Cole - Brisbane, Australia
* Jerry Bongard - Brisbane, Australia
* Britt Ambrose - Brisbane, Australia
* Michael Olumide - Brisbane, Australia
* Mick Harner - Brisbane, Australia

Secure coding guidelines

2019-10-19T01:37:02Z

Mickmackusa: /* Secure field names */ Fixed syntax error, property arrow was incorrect

Joomla includes many features that help with the task of securing applications and extensions built on it. You should always use these features if at all possible as they have been tried and tested by the many eyes of the developer community and any updates that might conceivably be required in the future will be automatically available whenever a Joomla update is applied. What follows is a description of best practice in using the Joomla API to ensure that your extensions are as secure as possible.

==Getting data from the request==
{{JVer|3.x}} Starting with Joomla version 3.0, [[Retrieving_request_data_using_JInput|JInput]] should be used instead of [[JRequest]].

All input originating from a user must be considered potentially dangerous and must be cleaned before being used. You should always use the Joomla [[Retrieving_request_data_using_JInput|JInput]] class to retrieve data from the request, rather than the raw $_GET, $_POST or $_REQUEST variables as the [[Retrieving_request_data_using_JInput|JInput]] methods apply input filtering by default. JInput deals with all aspects of the user request in a way that is independent of the request method used. It can also be used to retrieve cookie data and even server and environment variables. However, it is important to use the correct [[Retrieving_request_data_using_JInput|JInput]] method to ensure maximum security. It is very easy to just use the [[Retrieving_request_data_using_JInput#Getting_Values|JInput->get]] method with default parameters and ignore the fact that in many cases it is possible to apply a more stringent requirement on user input.

It very important to understand that the [[Retrieving_request_data_using_JInput|JInput]] methods are not SQL-aware and further work is required to guard against SQL injection attacks.There is no default value that will be returned if no default is specified in the call the [[Retrieving_request_data_using_JInput#Getting_Values|JInput->get]]. If no default is specified and the argument is not present in the request variable then it will return undefined.

Using [[Retrieving_request_data_using_JInput|JInput]] also obviates the need to pay attention to the setting of magic_quotes_gpc. [[Retrieving_request_data_using_JInput|JInput]] does the right thing, regardless of whether magic_quotes_gpc is on or off. See http://php.net/manual/en/security.magicquotes.php for further information.

When considering user input you should think about the data type you are expecting to retrieve and apply the most stringent form of [[Retrieving_request_data_using_JInput#Getting_Values|JInput]] that is applicable in each case. In particular, avoid the lazy approach of using [[Retrieving_request_data_using_JInput#Getting_Values|JInput->get]] as this will return an array that may contain entries that you did not expect and although each of those entries will have been cleaned, it is often the case that additional filtering could have been applied to some individual arguments. For example, the get method treats all arguments as strings, whereas it may be possible to restrict some arguments to be integers.

The first three parameters of each of the JInput get methods are the same. Only the first parameter is mandatory. In general, the format is
<source lang="php">
JFactory::getApplication->input-><data-source>->get<type>( <name>, <default> )
</source>
where

{| class="wikitable" border="1"
| <type> || the data type to be retrieved (see below for the types available).
|-
| <name> || the name of the variable to be retrieved (for example, the name of an argument in a URL).
|-
| <default> || the default value.
|-
| <data-source> || specifies where the variable is to be retrieved from (see below).
|}

The following values for <data-source> are supported:

{| class="wikitable" border="1"
| get || Data submitted in the query part of the URL.
|-
| post || Data submitted from form fields.
|-
| method || The same as either GET or POST depending on how the request was made.
|-
| cookie || Data submitted in cookies.
|-
| request || All the GET, POST and COOKIE data combined. This is the default.
|-
| files || Information about files uploaded as part of a POST request.
|-
| env || Environment variables (platform-specific).
|-
| server || Web server variables (platform-specific).
|}

Notice that the default is REQUEST, which includes cookie data.

The following sections look at each of the data types in more detail.

===Integer===
The following will accept an integer. An integer can include a leading minus sign, but a plus sign is not permitted.
<source lang="php">
$integer = JFactory::getApplication->input->getInt( 'id' );
</source>
will return the value of the "id" argument from the request (which by default includes all GET, POST and COOKIE data). The default value is zero.
<source lang="php">
$integer = JFactory::getApplication->input->cookie->getInt( 'myId', 12 );
</source>
will return the value of the "myId" variable from a cookie, with a default value of 12.

===Floating point number===
A floating point number can include a leading minus sign, but not a plus sign. If the number includes a decimal point, then there must be at least one digit before the decimal point. For example,
<source lang="php">
$float = JFactory::getApplication->input->getFloat( 'price' );
</source>
will return the value of the 'price' argument from the request. The default is "0.0".
<source lang="php">
$float = JFactory::getApplication->input->post->getFloat( 'total', 100.00 );
</source>
will retrieve the value of the 'total' argument from a POST request (but not a GET), with a default value of 100.00.

===Boolean value===
Any non-zero value is regarded as being true; zero is false.
<source lang="php">
$boolean = JFactory::getApplication->input->getBool( 'show' );
</source>
will return false if the value of the 'show' argument in the request is zero, or 1 (true) if the argument is anything else. The default is false. Note that any string argument will result in a return value of true, so calling the above with a URL containing "?show=false" will actually return true!
<source lang="php">
$boolean = JFactory::getApplication->input->get->getBool( 'hide', true );
</source>
will retrieve the value of the 'hide' argument from a GET request (but not a POST), with a default value of true.

===Word===
A word is defined as being a string of alphabetic characters. The underscore character is permitted as part of a word.
<source lang="php">
$word = JFactory::getApplication->input->cookie->getWord( 'search-word' );
</source>
will retrieve the value of the 'search-word' argument from the request. The default is an empty string.
<source lang="php">
$word = JFactory::getApplication->input->cookie->getWord( 'keyword', '' );
</source>
will retrieve the value of the 'keyword' variable from a cookie, with the default being an empty string.

===Command===
A command is like a word but a wider range of characters is permitted. Allowed characters are: all alphanumeric characters, dot, dash (hyphen) and underscore.
<source lang="php">
$command = JFactory::getApplication->input->getCmd( 'option' );
</source>
will retrieve the value of the "option" argument from the request. The default value is an empty string.
<source lang="php">
$command = JFactory::getApplication->input->post->getCmd( 'controller', 'view' );
</source>
will retrieve the value of the "controller" argument from a POST request (but not a GET), with a default value of 'view'.

===String===
The string type allows a much wider range of input characters. It also takes an optional fourth argument specifying some additional mask options. See [[#Filter options]] for information on the available masks.
<source lang="php">
$string = JFactory::getApplication->input->getString( 'description' );
</source>
will retrieve the value of the "description" argument from the request. The default value is an empty string. The input will have whitespace removed from the left and right ends and any HTML tags will be removed.
<source lang="php">
$string = JFactory::getApplication->input->getString( 'text', '' );
</source>
will retrieve the value of the "text" argument from the request.. The default value is an empty string.
<source lang="php">
$string = JFactory::getApplication->input->getString( 'template', '<html />' );
</source>
will retrieve the value of the "template" argument from the request. The default value is '<html />'.

===JSON String===
<source lang="php">
$json = JFactory::getApplication->input->json->get( 'var_name' );
</source>

===Generic and other data types===
If the above methods do not meet your needs, there is a small number of additional filter types which you can use by calling the [[Retrieving_request_data_using_JInput#Getting_Values|JInput->get]] method directly. The syntax is:
<source lang="php">
JFactory::getApplication->input->get( <name>, <default>, <type> );
</source>
where:

{| class="wikitable" border="1"
| <name> || the name of the variable to be retrieved (for example, the name of an argument in a URL).
|-
| <default> || the default value. There is no default value that will be returned if no default is specified in the call the [[Retrieving_request_data_using_JInput#Getting_Values|JInput->get]]. If no default is specified and the argument is not present in the request variable then it will return undefined.
|-
| <type> || specifies the data type expected (see below).
|}

The first three arguments are the same as for the more specific methods described earlier. Only the first argument is mandatory.

Allowed values of the <type>, which is case-insensitive, are as follows:

{| class="wikitable" border="1"
| INT, INTEGER || Equivalent to [[Retrieving_request_data_using_JInput#Getting_Values|JInput->getInt]].
|-
| UINT || Get an unsigned integer. Equivalent to [[Retrieving_request_data_using_JInput#Getting_Values|JInput->getUint]].
|-
| FLOAT, DOUBLE || Equivalent to [[Retrieving_request_data_using_JInput#Getting_Values|JInput->getFloat]].
|-
| BOOL, BOOLEAN || Equivalent to [[Retrieving_request_data_using_JInput#Getting_Values|JInput->getBool]].
|-
| WORD || Equivalent to [[Retrieving_request_data_using_JInput#Getting_Values|JInput->getWord]].
|-
| ALNUM || Allow only alphanumeric characters (a-z, A-Z, 0-9). Equivalent to [[Retrieving_request_data_using_JInput#Getting_Values|JInput->getAlnum]].
|-
| CMD || Equivalent to [[Retrieving_request_data_using_JInput#Getting_Values|JInput->getCmd]].
|-
| BASE64 || Allow only those characters that could be present in a base64-encoded string (ie. a-z, A-Z, 0-9, /, + and =). Equivalent to [[Retrieving_request_data_using_JInput#Getting_Values|JInput->getBase64]].
|-
| STRING || Equivalent to [[Retrieving_request_data_using_JInput#Getting_Values|JInput->getString]].
|-
| ARRAY || Source is not filtered but is cast to array type.
|-
| HTML || A sanitised string. Equivalent to [[Retrieving_request_data_using_JInput#Getting_Values|JInput->getHtml]].
|-
| PATH || Valid pathname regex that filters out common attacks. For example, any path beginning with a "/" will return an empty string. Simliarly, any path containing "/./" or "/../" will return an empty string. Dots within filenames are okay though. Equivalent to [[Retrieving_request_data_using_JInput#Getting_Values|JInput->getPath]].
|-
| USERNAME || Removes control characters (0x00 - 0x1F), 0x7F, <, >, ", ', % and &. Equivalent to [[Retrieving_request_data_using_JInput#Getting_Values|JInput->getUsername]].
|}

===Filter options===
All input values can be filtered using JFilterInput->clean.

Filter an array of values.
<source lang="php">
$data = JFactory::getApplication()->input->post->get('data', array(), 'array');
$filter = JFilterInput::getInstance();

foreach ($data as $value)
{
$array[] = $filter->clean($value, 'string');
}
</source>
For more filter types see [https://github.com/joomla/joomla-cms/blob/master/libraries/joomla/filter/input.php#L115 JFilterInput source].

Options listed bellow available only in deprecated [[JRequest]] library.
Allowed values of <options> are as follows (none of these are applied by default):

{| class="wikitable" border="1"
| JREQUEST_NOTRIM || Does not remove whitespace from the start and ends of strings.
|-
| JREQUEST_ALLOWRAW || Does not do any filtering at all. Use with extreme caution.
|-
| JREQUEST_ALLOWHTML || Does not remove HTML from string inputs.
|}

Masks can be combined by logically OR'ing them. If no filter options are specified, then by default, whitespace is trimmed and HTML is removed.

===File uploads===
Web servers already have a good deal of security around handling file uploads, but it is still necessary to take additional steps to ensure that file names and paths cannot be abused. A simplified form which requests a file to be uploaded looks like this:
<source lang="html4strict">
<form action="index.php?option=com_mycomponent/form_handler.php" method="post" enctype="multipart/form-data">
<input type="file" name="Filedata" />
<input type="submit" />
</form>
</source>
On clicking the submit button, the browser will upload the file in a POST request, passing control to Joomla which will call "components/com_mycomponent/form_handler.php". This will include code like the following. The variable $somepath must be set to some path where the web server has permission to create files.
<source lang="php">
// Check to ensure this file is included in Joomla!
defined('_JEXEC') or die( 'Restricted access' );

// Get the file data array from the request.
$file = JFactory::getApplication->input->get( 'Filedata', '', 'files', 'array' );

// Make the file name safe.
jimport('joomla.filesystem.file');
$file['name'] = JFile::makeSafe($file['name']);

// Move the uploaded file into a permanent location.
if (isset( $file['name'] )) {

// Make sure that the full file path is safe.
$filepath = JPath::clean( $somepath.'/'.strtolower( $file['name'] ) );

// Move the uploaded file.
JFile::upload( $file['tmp_name'], $filepath );
}
</source>

===Saving a request variable into user state===
Because setting a user state variable from a variable in the request is such a common operation, there is an API method to make the task easier. This is generally safe to use because it calls [[Retrieving_request_data_using_JInput#Getting_Values|JInput->get]] to obtain the input from the request, but remember that none of the input filtering calls will protect against SQL injection attempts.
<source lang="php">
$app = JFactory::getApplication();
$app->getUserStateFromRequest( <key>, <name>, <default>, <type> );
</source>
where
{| class="wikitable" border="1"
| <key> || the name of the variable in the user state.
|-
| <name> || the name of the request variable (same as the first argument of a [[Retrieving_request_data_using_JInput#Getting_Values|JInput->get]] call).
|-
| <default> || the default value to be assigned to the user state variable if the request variable is absent. The default is null.
|-
| <type> || the type of variable expected.
|}

For example, getting an integer variable called 'id' from the request with a default value of 0, then saving it into a session variable called 'myid' can be done like this:
<source lang="php">
$app = JFactory::getApplication();
$app->getUserStateFromRequest( 'myid', 'id, 0, 'int' );
</source>
instead of something like this:
<source lang="php">
$app = JFactory::getApplication();
$app->setUserState( 'myid', $app->input->getInt( 'id', 0 ) );
</source>

==Constructing SQL queries==
One of the most common forms of attack on web applications is SQL injection, where the aim of the attacker is to change a database query by exploiting a poorly filtered input variable. Injecting modified SQL statements into the database can damage data or reveal private information. It is important to ensure that when SQL statements are constructed, they are correctly escaped and quoted so that bad input data cannot result in a bad SQL statement. You cannot rely on the [[Retrieving_request_data_using_JInput|JInput]] methods to do this as they are not SQL-aware.

===Secure integers and the rest of numeric values===
With the MySQL database, numeric fields should not be quoted, so it is important that they be typecast instead. Failure to do this will leave your code vulnerable to an attacker inserting a string containing SQL data.

Depending on the type, numeric types are cast like this:
<source lang="php">
// For SQL data types: INT, INTEGER, TINYINT, SMALLINT, MEDIUMINT, BIGINT, YEAR
$query = 'SELECT * FROM #__table WHERE `id`=' . (int) $id;

// For SQL data types: FLOAT, DOUBLE
$query = 'SELECT * FROM #__table WHERE `id`=' . (float) $id;
</source>
It's a good idea to get into the habit of always typecasting integers like this even if the variable was previously obtained using JInput->getInt. Further information on SQL injection attacks can be found here: http://php.net/manual/en/security.database.sql-injection.php and here: [[Retrieving_request_data_using_JInput#Getting_Values]].

===Secure strings===
In the examples that follow it is assumed that $db is an instance of a Joomla database object. This can always be obtained from [[JFactory]] using
<source lang="php">
$db = JFactory::getDBO();
</source>
Strings should always be escaped before being used in an SQL statement. This is actually very simple as the [[JDatabase/quote|JDatabase->quote]] method escapes everything for you. You can also use the [[JDatabase/escape|JDatabase->escape]] method directly. The following statements are equivalent:
<source lang="php">
$query = 'SELECT * FROM #__table WHERE `field` = ' . $db->quote( $db->escape( $field ), false );

$query = 'SELECT * FROM #__table WHERE `field` = ' . $db->quote( $field );
</source>
===Secure on search===
Special attention should be paid to LIKE clauses which contain the % wildcard character as these require special escaping in order to avoid possible denial of service attacks. LIKE clauses can be handled like this:
<source lang="php">
// Construct the search term by escaping the user-supplied string and, if required, adding the % wildcard characters manually.
$search = '%' . $db->escape( $search, true ) . '%';

// Construct the SQL query, being careful to suppress the default behaviour of Quote so as to prevent double-escaping.
$query = 'SELECT * FROM #__table WHERE `field` LIKE ' . $db->quote( $search, false );
</source>

===Secure dates===
If data is to be entered into a datetime column then you can use the Joomla API to ensure a valid date format:
<source lang="php">
$date = JFactory::getDate( $mydate );
$query = 'UPDATE #__table SET `date` = ' . $db->quote( $date->toMySQL(), false );
</source>
Note that it is necessary to suppress database escaping as legitimate dates may contain characters that should not be escaped.

===Secure field names===
In the comparatively rare case where a field name is a variable, that should also be quoted using an API call:
<source lang="php">
$query = 'SELECT * FROM #__table WHERE ' . $db->quoteName( $field->name ) . '=' . $db->quote( $field->value );
</source>

===Secure arrays of integers===
When you have an array of ids, typically used for IN() queries, you have to sanitise it also with JArrayHelper::toInteger($cid); before imploding:

<source lang="php">
...
JArrayHelper::toInteger($catId);
$query->where($db->quoteName('x.category_id') . ' IN (' . implode(',', $catId) . ')');
</source>

===Short aliases of Quote and QuoteName===
Shorter alternatives to the quote methods may also be used. The following statements are equivalent:
<source lang="php">
$query = 'SELECT * FROM #__table WHERE ' . $db->quoteName( $field-name ) . '=' . $db->quote( $field-value );
$query = 'SELECT * FROM #__table WHERE ' . $db->qn( $field-name ) . '=' . $db->q( $field-value );
</source>

==Securing forms==
Apart from cleaning input variables as described above, you can also implement a simple technique which makes it more difficult for a cross-site request forgery attack (CSRF) to succeed. This involves adding a randomly-generated unique token to the form which is checked against a copy of the token held in the user's session. By checking that the submitted token matches the one contained in the stored session, it is possible to tie a rendered form to the request variables presented.

In POST forms you should add a hidden token field using:
<source lang="php">
echo JHTML::_( 'form.token' );
</source>
This outputs the token as a hidden form field looking like this:
<source lang="html4strict">
<input type="hidden" name="8cb24ae69ffd7828ccecbcf06056e6fc" value="1" />
</source>
and places a copy of the token into the user's session, for later checking.

If you need to add the token to a URL rather than a form then you can use something like this:
<source lang="php">
echo JRoute::_( 'index.php?option=com_mycomponent&' . JSession::getFormToken() . '=1' );
</source>

In the most common scenario, you will want to check the token following a POST to the form handler. This can be done by adding this line of code to form handler:
<source lang="php">
JSession::checkToken() or die( JText::_( 'Invalid Token' ) );
</source>
If you need to pass the token in a GET request then you can check it like this:
<source lang="php">
JSession::checkToken( 'get' ) or die( JText::_( 'Invalid Token' ) );
</source>

In both cases the code will die if the token is omitted from the request, or the submitted token does not match the session token. If the token is correct but has expired, then [[JSession/checkToken|JSession::checkToken]] will automatically redirect to the site front page.

==Cleaning filesystem paths==
If there is any possibility that a filesystem path might be constructed using data that originated from user input, then the path must be cleaned and checked before being used. This can be done quite simply like this:
<source lang="php">
JPath::check( $path );
</source>
This will raise an error and terminate Joomla if the path contains a ".." or leads to a location outside the Joomla root directory. If you want to deal with the error yourself without terminating the application, then you can use code like this:
<source lang="php">
$path = JPath::clean( $path );
if (strpos( $path, JPath::clean( JPATH_ROOT ) ) !== 0) {
// Handle the error here.
}
</source>
The [[JPath:clean]] method can be used in your own code too. It merely removes leading and trailing whitespace and replace double slashes and backslashes with the standard directory separator.

==Cleaning filesystem file names==
As with filesystem paths, if there is any possibility that a file name might be constructed using user-originated data, then the file name must be cleaned and checked before use. This can be done like this:
<source lang="php">
jimport('joomla.filesystem.file');
$clean = JFile::makeSafe( $unclean );
</source>
This method removes sequences of two or more "." characters and any character that is not alphabetic, numeric or a dot, dash or underscore character. If there is a leading dot then that is removed too.
[[Category:Development]][[Category:Security]]

User:Mickmackusa

2019-10-19T00:45:50Z

Mickmackusa: my new user page

My name is Mickmackusa and if you want to get in touch with me, post on my '''[[User_talk:{{PAGENAME}}|talk page]]'''.

==My testing subpages==
<splist/>