Joomla! Documentation - User contributions [en]

Joomla CodeSniffer

2013-06-20T15:44:26Z

B.nisevic:

{{page|needs technical review|This page needs expanded installation instructions, especially for Windows-based systems}}

== A Nose For Joomla ==

This is a custom coding standard for the PHP CodeSniffer that attempts to codify and enforce the Joomla coding standards.

==Why?==

- Coherent and consisting coding practice makes the files look more professional. Conflicting styles in the same project (or worse, the same file) not only look sloppy, they encourage further sloppiness.

- When all code complies with the same standard, bad code is easier for everyone to spot.

- It makes it easier for someone new to a particular file in the project to find and fix errors, or extend functionality.

- If there is no consistent standard maintained, the sometimes developers will reformat the code to suit themselves. This causes a wide range of changes in the code repository, and if there is a later problem, a significant change could be lost in the chaff produced by a diff.

==Installation==

First of all you have to install the [http://pear.php.net/package/PHP_CodeSniffer/ PHP CodeSniffer]. This set of files is intended to work with phpcs version 1.4, so behavior with any other version is undefined. One way to do this is to start the console (cmd.exe in windows environments) and type:

<code>pear install PHP_CodeSniffer</code>

To specify a specific version of the PHP CodeSniffer, type:

<code>pear install PHP_CodeSniffer-1.4.x</code> (specify a number for x, versions 1.4.0 through 1.4.5 are available)

Pear will handle the whole installation by itself.

Then download and unzip the [https://github.com/joomla/coding-standards Joomla! CodeSniffer] and copy the contents of it into /path/to/PHP_CodeSniffer/Standards/Joomla.

In Unix systems this path is usually /usr/lib/php/PHP/PHP_CodeSniffer/Standards/Joomla but this varies from system to system. In Xubuntu 12.04, the path is /usr/share/php/PHP/CodeSniffer/Standards/Joomla.
Windows based system with XAMPP have the following path: PATH_TO_XAMMP\php\PEAR\PHP\CodeSniffer\Standards (for example: C:\xampp\php\PEAR\PHP\CodeSniffer\Standards)

Use

<code>pear config-get php_dir</code>

to find out where the PEAR directory is on your system, then add "/PHP/PHP_CodeSniffer/Standards" to it.

== Usage ==

You invoke the custom standard by

<code>phpcs --standard=Joomla file/to/sniff</code>

To test a platform file using the provided platform coding standards use

<code>phpcs --standard=build/phpcs/Joomla path/to/file/or/folder</code>

Further documentation on the use of phpcs can be found at: [http://pear.php.net/package/PHP_CodeSniffer/docs]

==IDE integration==

While everybody loves the console as it is with no doubt the most effective way to do whatever you need to do.. sometimes even linux gurus need a little bit of comfort.

Fortunately there is a plugin available for eclipse and netbeans that integrates the CodeSniffer in our favorite IDE, so any coding standard violations are shown like "normal" errors.

=== Netbeans ===

For netbeans you have to install the sniffer plugin first. You can download the plugin [http://sourceforge.net/projects/phpmdnb/files/nbm/ here].

# Start your netbeans IDE
# Open Tools => Plugins => Downloaded and press ''Add Plugin''
# Choose the loaded nbm file and confirm the installation
# Now there is a new tab in Tools => Options => PHP called "PHPCodeSniffer"
# You have to set the path to the ''phpcs.bat'' from the installed PHP_CodeSniffer PEAR package
#* for Unix based systems the path is something like /usr/bin/phpcs
#* in XAMPP (windows) you can find the file in the php root folder (e.g. C:\xampp\php\phpcs.bat)
# As "standard" type "Joomla" to use the Joomla! standard
# now you can click ''test Settings'' to check the settings and finish the installation by pressing ''Ok''
# Open he task window (Window => Tasks) to sniff your code.
# Most time it is a good idea to filter the task (show only in edited file or create an own filter which displays only sniff errors)

=== Eclipse ===
[[Image:eclipse_pti.png|left|thumb|200px|1) Eclipse PTI]]

<div style="clear: both"></div>
Installation is a breeze and follows the usual pattern:
# <tt>Help => Install new Software...</tt>
# <tt>Work with:</tt> Fill in one of the update site URLs found here: http://www.phpsrc.org/eclipse/pti/
# Select the desired tools
# Restart Eclipse.

[[Image:eclipse_pti_settings.png|right|thumb|150px|2) Eclipse PTI settings]]
You are now able to sniff for code violations against common standards like PEAR or Zend etc.

To sniff against your own standards, all you have to do is specify their location and activate them (see screen shot 2)

# <tt>Window => Preferences</tt>
# <tt>PHP Tools => PHP CodeSniffer</tt>

Happy sniffing

=== PHPStorm ===

==== PHPStorm ====
[[Image:PhpStorm4CodeSniffer.png|left|thumb|200px|1) PHPStorm 4.x CodeSniffer]]
<div style="clear: both"></div>

CodeSniffer is supported out of the box in PHPStorm, just go to settings, and under "Inspections" you will see the list of Sniff you have installed.

See: the [http://www.jetbrains.com/phpstorm/webhelp/using-php-code-sniffer-tool.html JetBrains documentation page for setting the Code Sniffer] and also [http://blog.jetbrains.com/webide/2012/03/checking-your-code-with-php-code-sniffer-in-phpstorm-4-0/ phpStorm Blog])

For users on ubuntu using phpStorm. Don't listen instructions at http://www.jetbrains.com/phpstorm/webhelp/using-php-code-sniffer-tool.html#d59626e1126 because there is no working bat (windows file) on linux system. To validate your CodeSniffer choose /usr/bin/phpcs launcher.

Under Settings->Inspections when you choose joomla profile, in the tree below, search for PHP and open it and than make sure that PHP Code Sniffer validation checkbox is checked. Otherwise PHP Code Sniffer won't sniff your code.

On ubuntu you install code standards with:
cd /usr/share/php/PHP/CodeSniffer/Standards
sudo git clone http://github.com/joomla/coding-standards.git Joomla
===== Installing Joomla Sniff =====

# get the sniffers from the [https://github.com/joomla/coding-standards coding standards repo]
# unpack Joomla CodeSniffer rules under:
## If you are using XAMPP ''\xampp\php\PEAR\PHP\CodeSniffer\Standards\Joomla''
## If not maybe you should check here: ''/usr/share/php/PHP/CodeSniffer/Standards''
# Go to Settings (CTRL-ALT-S) and search for "PHP Code Sniffer Validation", click the button Validate to force reload of rules from disk
# Joomla should be now available in the list. See following image:

[[Image:PhpStorm6CodeSniffer.png|left|thumb|200px|1) PHPStorm 6.x CodeSniffer]]
<div style="clear: both"></div>

==== PHP PSR-0, PSR-1 and PSR-2 ====
* https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-0.md
* https://github.com/pmjones/fig-standards/blob/psr-1-style-guide/proposed/PSR-1-basic.md
* https://github.com/pmjones/fig-standards/blob/psr-1-style-guide/proposed/PSR-2-advanced.md

===== Installing PHP PSR-0, PSR-1 and PSR-2 Sniff =====

A CodeSniffer sniff to check against the PSR-x Coding Standard

Download files at
* https://github.com/squizlabs/PHP_CodeSniffer/tree/master/CodeSniffer/Standards

if you are using Xampp,
# unpack PSR-1 CodeSniffer rules under \xampp\php\PEAR\PHP\CodeSniffer\Standards\PSR (SPR or any directory will work)
# Go to Settings (CTRL-ALT-S) and search for "PHP Code Sniffer Validation", click the button Validate to force reload of rules from disk
# PSR is available in the list

==== PHPStorm 3.x / Alternative method ====
'''NOTE''': This method is outdated, but it might be useful if you are looking for a different integration. It also demonstrates the use of external tools in PHPStorm - so it shouldn't be deleted.

<del>There is currently no plugin available</del> The CodeSniffer can also be integrated easily as an external tool. PHPStorm will display the output in the console, including clickable links containing line and column numbers to the files that contain errors.

* Click on "Settings" and search for "External tools"
* Click "Add..."
* Choose a "name", "Group" and "Description".
* Click "Output Filters"
** Click "Add...", Choose a name and enter under "Regular expression to match output" the value: <tt>$FILE_PATH$:$LINE$:$COLUMN$</tt>
* "Program": Search for the phpcs executable on your system. You have to set the path to the ''phpcs.bat'' from the installed PHP_CodeSniffer PEAR package
** for Unix based systems the path is something like /usr/bin/phpcs
** in XAMPP (windows) you can find the file in the php root folder (e.g. C:\xampp\php\phpcs.bat)
* "Paramaters":
** <tt>--standard=<path/to/joomla-platform>/build/phpcs/Joomla</tt> The path to the Joomla! coding standards.
** <tt>--report=emacs</tt> The will generate a simple list containing links to the error files
** Optional you may want to specify <tt>-p</tt> for "progress" or <tt>-n</tt> for "errors only".
** The last parameter has to be <tt>$FilePath$</tt> specifying the file or folder you want to sniff.

A typical "Parameters" line on a Linux system might look like this:
<pre>-np --standard=/home/elkuku/libs/joomla/build/phpcs/Joomla --report=emacs $FilePath$</pre>

You may now right click any file or folder and choose the sniffer from the context menu or add a new toolbar button with a nice Joomla! logo [[File:icon-16-joomla.png]].

=== References ===
* http://www.phpsrc.org/ PTI - PHP tools integration for Eclipse
* http://sourceforge.net/projects/phpmdnb/ Netbeans plugin
* http://hakre.wordpress.com/2010/03/06/php-code-sniffer-eclipse-and-wordpress/ - Excellent article. Just change "Wordpress" for "Joomla!" ;)

[[Category:Development]][[Category:Bug Squad]]

Joomla CodeSniffer

2013-06-20T14:17:55Z

B.nisevic:

{{page|needs technical review|This page needs expanded installation instructions, especially for Windows-based systems}}

== A Nose For Joomla ==

This is a custom coding standard for the PHP CodeSniffer that attempts to codify and enforce the Joomla coding standards.

==Why?==

- Coherent and consisting coding practice makes the files look more professional. Conflicting styles in the same project (or worse, the same file) not only look sloppy, they encourage further sloppiness.

- When all code complies with the same standard, bad code is easier for everyone to spot.

- It makes it easier for someone new to a particular file in the project to find and fix errors, or extend functionality.

- If there is no consistent standard maintained, the sometimes developers will reformat the code to suit themselves. This causes a wide range of changes in the code repository, and if there is a later problem, a significant change could be lost in the chaff produced by a diff.

==Installation==

First of all you have to install the [http://pear.php.net/package/PHP_CodeSniffer/ PHP CodeSniffer]. This set of files is intended to work with phpcs version 1.4, so behavior with any other version is undefined. One way to do this is to start the console (cmd.exe in windows environments) and type:

<code>pear install PHP_CodeSniffer</code>

To specify a specific version of the PHP CodeSniffer, type:

<code>pear install PHP_CodeSniffer-1.4.x</code> (specify a number for x, versions 1.4.0 through 1.4.5 are available)

Pear will handle the whole installation by itself.

Then download and unzip the [https://github.com/joomla/coding-standards Joomla! CodeSniffer] and copy the contents of it into /path/to/PHP_CodeSniffer/Standards/Joomla.

In Unix systems this path is usually /usr/lib/php/PHP/PHP_CodeSniffer/Standards/Joomla but this varies from system to system. In Xubuntu 12.04, the path is /usr/share/php/PHP/CodeSniffer/Standards/Joomla.
Windows based system with XAMPP have the following path: PATH_TO_XAMMP\php\PEAR\PHP\CodeSniffer\Standards (for example: C:\xampp\php\PEAR\PHP\CodeSniffer\Standards)

Use

<code>pear config-get php_dir</code>

to find out where the PEAR directory is on your system, then add "/PHP/PHP_CodeSniffer/Standards" to it.

== Usage ==

You invoke the custom standard by

<code>phpcs --standard=Joomla file/to/sniff</code>

To test a platform file using the provided platform coding standards use

<code>phpcs --standard=build/phpcs/Joomla path/to/file/or/folder</code>

Further documentation on the use of phpcs can be found at: [http://pear.php.net/package/PHP_CodeSniffer/docs]

==IDE integration==

While everybody loves the console as it is with no doubt the most effective way to do whatever you need to do.. sometimes even linux gurus need a little bit of comfort.

Fortunately there is a plugin available for eclipse and netbeans that integrates the CodeSniffer in our favorite IDE, so any coding standard violations are shown like "normal" errors.

=== Netbeans ===

For netbeans you have to install the sniffer plugin first. You can download the plugin [http://sourceforge.net/projects/phpmdnb/files/nbm/ here].

# Start your netbeans IDE
# Open Tools => Plugins => Downloaded and press ''Add Plugin''
# Choose the loaded nbm file and confirm the installation
# Now there is a new tab in Tools => Options => PHP called "PHPCodeSniffer"
# You have to set the path to the ''phpcs.bat'' from the installed PHP_CodeSniffer PEAR package
#* for Unix based systems the path is something like /usr/bin/phpcs
#* in XAMPP (windows) you can find the file in the php root folder (e.g. C:\xampp\php\phpcs.bat)
# As "standard" type "Joomla" to use the Joomla! standard
# now you can click ''test Settings'' to check the settings and finish the installation by pressing ''Ok''
# Open he task window (Window => Tasks) to sniff your code.
# Most time it is a good idea to filter the task (show only in edited file or create an own filter which displays only sniff errors)

=== Eclipse ===
[[Image:eclipse_pti.png|left|thumb|200px|1) Eclipse PTI]]

<div style="clear: both"></div>
Installation is a breeze and follows the usual pattern:
# <tt>Help => Install new Software...</tt>
# <tt>Work with:</tt> Fill in one of the update site URLs found here: http://www.phpsrc.org/eclipse/pti/
# Select the desired tools
# Restart Eclipse.

[[Image:eclipse_pti_settings.png|right|thumb|150px|2) Eclipse PTI settings]]
You are now able to sniff for code violations against common standards like PEAR or Zend etc.

To sniff against your own standards, all you have to do is specify their location and activate them (see screen shot 2)

# <tt>Window => Preferences</tt>
# <tt>PHP Tools => PHP CodeSniffer</tt>

Happy sniffing

=== PHPStorm ===

==== PHPStorm ====
[[Image:PhpStorm4CodeSniffer.png|left|thumb|200px|1) PHPStorm 4.x CodeSniffer]]
<div style="clear: both"></div>

CodeSniffer is supported out of the box in PHPStorm, just go to settings, and under "Inspections" you will see the list of Sniff you have installed.

See: the [http://www.jetbrains.com/phpstorm/webhelp/using-php-code-sniffer-tool.html JetBrains documentation page for setting the Code Sniffer] and also [http://blog.jetbrains.com/webide/2012/03/checking-your-code-with-php-code-sniffer-in-phpstorm-4-0/ phpStorm Blog])

For users on ubuntu using phpStorm. Don't listen instructions at http://www.jetbrains.com/phpstorm/webhelp/using-php-code-sniffer-tool.html#d59626e1126 because there is no working bat (windows file) on linux system. To validate your CodeSniffer choose /usr/bin/phpcs launcher.

===== Installing Joomla Sniff =====

# get the sniffers from the [https://github.com/joomla/coding-standards coding standards repo]
# unpack Joomla CodeSniffer rules under:
## If you are using XAMPP ''\xampp\php\PEAR\PHP\CodeSniffer\Standards\Joomla''
## If not maybe you should check here: ''/usr/share/php/PHP/CodeSniffer/Standards''
# Go to Settings (CTRL-ALT-S) and search for "PHP Code Sniffer Validation", click the button Validate to force reload of rules from disk
# Joomla should be now available in the list. See following image:

[[Image:PhpStorm6CodeSniffer.png|left|thumb|200px|1) PHPStorm 6.x CodeSniffer]]
<div style="clear: both"></div>

==== PHP PSR-0, PSR-1 and PSR-2 ====
* https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-0.md
* https://github.com/pmjones/fig-standards/blob/psr-1-style-guide/proposed/PSR-1-basic.md
* https://github.com/pmjones/fig-standards/blob/psr-1-style-guide/proposed/PSR-2-advanced.md

===== Installing PHP PSR-0, PSR-1 and PSR-2 Sniff =====

A CodeSniffer sniff to check against the PSR-x Coding Standard

Download files at
* https://github.com/squizlabs/PHP_CodeSniffer/tree/master/CodeSniffer/Standards

if you are using Xampp,
# unpack PSR-1 CodeSniffer rules under \xampp\php\PEAR\PHP\CodeSniffer\Standards\PSR (SPR or any directory will work)
# Go to Settings (CTRL-ALT-S) and search for "PHP Code Sniffer Validation", click the button Validate to force reload of rules from disk
# PSR is available in the list

==== PHPStorm 3.x / Alternative method ====
'''NOTE''': This method is outdated, but it might be useful if you are looking for a different integration. It also demonstrates the use of external tools in PHPStorm - so it shouldn't be deleted.

<del>There is currently no plugin available</del> The CodeSniffer can also be integrated easily as an external tool. PHPStorm will display the output in the console, including clickable links containing line and column numbers to the files that contain errors.

* Click on "Settings" and search for "External tools"
* Click "Add..."
* Choose a "name", "Group" and "Description".
* Click "Output Filters"
** Click "Add...", Choose a name and enter under "Regular expression to match output" the value: <tt>$FILE_PATH$:$LINE$:$COLUMN$</tt>
* "Program": Search for the phpcs executable on your system. You have to set the path to the ''phpcs.bat'' from the installed PHP_CodeSniffer PEAR package
** for Unix based systems the path is something like /usr/bin/phpcs
** in XAMPP (windows) you can find the file in the php root folder (e.g. C:\xampp\php\phpcs.bat)
* "Paramaters":
** <tt>--standard=<path/to/joomla-platform>/build/phpcs/Joomla</tt> The path to the Joomla! coding standards.
** <tt>--report=emacs</tt> The will generate a simple list containing links to the error files
** Optional you may want to specify <tt>-p</tt> for "progress" or <tt>-n</tt> for "errors only".
** The last parameter has to be <tt>$FilePath$</tt> specifying the file or folder you want to sniff.

A typical "Parameters" line on a Linux system might look like this:
<pre>-np --standard=/home/elkuku/libs/joomla/build/phpcs/Joomla --report=emacs $FilePath$</pre>

You may now right click any file or folder and choose the sniffer from the context menu or add a new toolbar button with a nice Joomla! logo [[File:icon-16-joomla.png]].

=== References ===
* http://www.phpsrc.org/ PTI - PHP tools integration for Eclipse
* http://sourceforge.net/projects/phpmdnb/ Netbeans plugin
* http://hakre.wordpress.com/2010/03/06/php-code-sniffer-eclipse-and-wordpress/ - Excellent article. Just change "Wordpress" for "Joomla!" ;)

[[Category:Development]][[Category:Bug Squad]]

J1.5:Using the JPane classes in a component

2013-04-01T17:18:45Z

B.nisevic:

{{deprecated|when=1.5|from=1.6|link=Using_the_JHtmlTabs_class_in_a_component|old=JPane|new=JHtmlTabs}}
JPane class types include 'Tabs' and 'Sliders'.

Sliders implement the mootools accordian effect. Examples are the Joomla Admin parameters settings.
Tabs also implement mootools (but in which degree?)

startPane and endPane() require a string identifier.

JPanes contain Panels

startPanel() and endPanel() require name and ID parameters.

You can set some options in the getInstance method.
== JPane options ==
'''startOffset''': The default tab/slider to start with (zero based index).<br/>
'''allowAllClose''': Can we close all sliders (=true) or may always have one open (=false).<br/>
'''opacityTransition''': show a fading Transition (=true or =false) when opening or closing the slider/tab.<br/>
'''duration''': Time duration to display or close the slider/tab in milliseconds (default : 300).<br/>
<br/>
'''onActive''': Another function to use when making a tab active (??)<br/>
'''onBackground''': Another function to use when making a tab dissapear (??)<br/>

== Example ==
<source lang="php">
jimport('joomla.html.pane');
//1st Parameter: Specify 'tabs' or 'sliders' as appearance
//2nd Parameter: Array with 4 parameters (optionnal)
// - 'startOffset' : Starting with third tab(=2) as the default (zero based index)
// - 'allowAllClose' : Determine if all tabs or sliders can be closed (=true) or if there must always be almost one tab/slider opened (=false)
// - 'opacityTransition' : Specify if a fade Transition must be use when opening or closing the slider/tab (true or false)
// - 'duration' : Time duration to display or close the slider/tab in milliseconds (default : 300)
$pane =& JPane::getInstance('tabs', array('startOffset'=>2, 'allowAllClose'=>true, 'opacityTransition'=>true, 'duration'=>600));
echo $pane->startPane( 'pane' );
echo $pane->startPanel( 'Example Panel 1', 'panel1' );
echo "This is panel1";
echo $pane->endPanel();
echo $pane->startPanel( '<h3>Example Panel 2</h3>', 'panel2' );
echo "This is panel2 with an header3 tag";
echo $pane->endPanel();
echo $pane->startPanel( 'Example Panel 3', 'panel3' );
echo "This is panel3";
echo $pane->endPanel();
echo $pane->endPane();
</source>

''Don't forget the echo's!! Thanks to tcp for this post: [http://forum.joomla.org/viewtopic.php?f=231&t=135641#p664869 FYI - Change in usage of JPane]
Also notice that the useCookies in the comments in the code or on the api, do NOT seem to be implemented''

== Adding onClick to Tab ==
Looking in JTabs source, you will found that there are two more options can be set; onActive and onBackground event. This is easy to add if you familiar with PHP and JavaScript. But I will show you how to do in an easy way (but may not a best practic). Look back to JPane->startPanel(..,...), for the first parameter you can add tag to it instead of normal text. So, I just add span tag to the tab title and set onClick to do something.
<source lang="php">
$pane = & JPane::getInstance('Tabs');
echo $pane->startPane('doc') ;
echo $pane->startPanel('<span onclick="document.adminForm.job_id.value=0;">Summary</span>','doc-summary') ;
echo $this->loadTemplate('summary');
echo $pane->endPanel();
foreach($this->jobs as $job)
{
$this->job = $job;
if ($this->doc->type_id == CP_CLEARING_REQ)
{
$this->refJob = null;
foreach ($this->refJobs as $refJob) {
if ( ($refJob->project_no==$job->project_no) && ($refJob->subproject_code==$job->subproject_code) )
{
$this->refJob = $refJob;
break;
}
}
}
echo $pane->startPanel('<span onclick="document.adminForm.job_id.value='.$job->id.';">'.$job->project_no.'/'
.$job->subproject_code."</span>", 'job-'.$job->id);
echo $this->loadTemplate('job');
echo $pane->endPanel();
}
echo $pane->endPane() ;

</source>
[[Category:Development]]

Archived:Learn more about patch files

2013-03-22T14:10:10Z

B.nisevic: /* Other Important Articles About Patch Files */

[[Category:Bug Squad]]

Test this patch, make a patch, are things you hear when you report an issue or when you're working on bugs. What exactly is a patch?

A patch is a file that indicates which exact lines in which exact files should be changed.

Here's a recent patch from issue 11354 which corrected a simple typo.

<code>
Index: plugins/authentication/gmail.php
===================================================================
--- plugins/authentication/gmail.php (revision 10386)
+++ plugins/authentication/gmail.php (working copy)
@@ -87,7 +87,7 @@
}
}
else {
- $message = 'curl isn\'t insalled';
+ $message = 'curl isn\'t installed';
}
if ($success)

</code>
Looking more closely, we see that the patch always starts with the name of the changed file relative to the Joomla! root. In this case it is the file gmail.php in the plugins/authenticaion folder.

Next we see the file named again in two lines. The number in the first line represents the version of the code base or build on which the patch was created, The working copy is the copy that is changed. What do I mean by build? Every time a change is made to the codebase, that creates a new revision or build. You can find your build number in the changelog.php file in your joomla! root.

Next comes @@ -87,7 +87,7 @@ which tells us that the change will start on line 87 of the file.

Finally we see the code. The old line 87 has a – in front of it and the new line 87 has a +.

The new version of the line will replace the old line in the file.

Of course most patches are much more complex than this, but they really just are repeated instances of this structure.

So if you saw this patch file and wanted to fix your version of Joomla! all you would need to do is find line 87 of gmail.php and make that change. So if someone tells you “There's a patch on the tracker” what they are saying is that you can go download the patch and apply it to your version of Joomla!. However one thing to keep in mind is that if your version does not match the version in the code repository it is possible that that patch will not work because it depends on or impacts other parts of the code.

Now, if you're contributing a bug fix as opposed to just reporting an issue, the ideal is to submit a patch file that you have tested. However, if you can't do that, at least give this information:

* The complete names and paths of any files changed
* The line numbers of the changes
* The old and new versions of the changed lines

However, making a patch file is even better and is not complicated if you install a subversion client such as Tortoise or the Subclipse plugin for Eclipse. For information on how to install the Eclipse IDE, see [[Setting_up_your_workstation_for_Joomla!_development | Setting up your workstation for Joomla! development]].

==Patch Files and UTF-8 Characters==
Most patch files are for PHP files that contain simple text. However, patch files can also be used to patch language INI files, and these can often contain UTF-8 characters. There is a known problem when you try to apply a patch with UTF-8 characters using Eclipse. The patch file may show errors when you try to apply it. One possible work-around to this problem is to copy the file to your clipboard and then in the Patch Input Specification in Eclipse, select Clipboard instead of File. Note that the preview for the patched files may show question marks for the UTF-8 characters, but the patch will apply correctly.

You can check that the patch did apply correctly by using the Compare With→Base Revision feature in Eclipse.

==Other Important Articles About Patch Files==
[http://docs.joomla.org/Git_for_Testers_and_Trackers#Important_Notes_About_Patch_File_Format Important Notes About Patch File Format]<br/>
[http://docs.joomla.org/Git_for_Testers_and_Trackers#Apply_Patches_and_Pull_Requests_Without_Branches Apply Patches and Pull Requests Without Branches]<br/>
[http://docs.joomla.org/Git_for_Testers_and_Trackers#Apply_Patches_and_Pull_Requests_Using_Branches Apply Patches and Pull Requests Using Branches]<br/>

Archived:Learn more about patch files

2013-03-22T14:07:12Z

B.nisevic:

[[Category:Bug Squad]]

Test this patch, make a patch, are things you hear when you report an issue or when you're working on bugs. What exactly is a patch?

A patch is a file that indicates which exact lines in which exact files should be changed.

Here's a recent patch from issue 11354 which corrected a simple typo.

<code>
Index: plugins/authentication/gmail.php
===================================================================
--- plugins/authentication/gmail.php (revision 10386)
+++ plugins/authentication/gmail.php (working copy)
@@ -87,7 +87,7 @@
}
}
else {
- $message = 'curl isn\'t insalled';
+ $message = 'curl isn\'t installed';
}
if ($success)

</code>
Looking more closely, we see that the patch always starts with the name of the changed file relative to the Joomla! root. In this case it is the file gmail.php in the plugins/authenticaion folder.

Next we see the file named again in two lines. The number in the first line represents the version of the code base or build on which the patch was created, The working copy is the copy that is changed. What do I mean by build? Every time a change is made to the codebase, that creates a new revision or build. You can find your build number in the changelog.php file in your joomla! root.

Next comes @@ -87,7 +87,7 @@ which tells us that the change will start on line 87 of the file.

Finally we see the code. The old line 87 has a – in front of it and the new line 87 has a +.

The new version of the line will replace the old line in the file.

Of course most patches are much more complex than this, but they really just are repeated instances of this structure.

So if you saw this patch file and wanted to fix your version of Joomla! all you would need to do is find line 87 of gmail.php and make that change. So if someone tells you “There's a patch on the tracker” what they are saying is that you can go download the patch and apply it to your version of Joomla!. However one thing to keep in mind is that if your version does not match the version in the code repository it is possible that that patch will not work because it depends on or impacts other parts of the code.

Now, if you're contributing a bug fix as opposed to just reporting an issue, the ideal is to submit a patch file that you have tested. However, if you can't do that, at least give this information:

* The complete names and paths of any files changed
* The line numbers of the changes
* The old and new versions of the changed lines

However, making a patch file is even better and is not complicated if you install a subversion client such as Tortoise or the Subclipse plugin for Eclipse. For information on how to install the Eclipse IDE, see [[Setting_up_your_workstation_for_Joomla!_development | Setting up your workstation for Joomla! development]].

==Patch Files and UTF-8 Characters==
Most patch files are for PHP files that contain simple text. However, patch files can also be used to patch language INI files, and these can often contain UTF-8 characters. There is a known problem when you try to apply a patch with UTF-8 characters using Eclipse. The patch file may show errors when you try to apply it. One possible work-around to this problem is to copy the file to your clipboard and then in the Patch Input Specification in Eclipse, select Clipboard instead of File. Note that the preview for the patched files may show question marks for the UTF-8 characters, but the patch will apply correctly.

You can check that the patch did apply correctly by using the Compare With→Base Revision feature in Eclipse.

==Other Important Articles About Patch Files==
[http://docs.joomla.org/Git_for_Testers_and_Trackers#Important_Notes_About_Patch_File_Format | Important Notes About Patch File Format]
[http://docs.joomla.org/Git_for_Testers_and_Trackers#Apply_Patches_and_Pull_Requests_Without_Branches | Apply Patches and Pull Requests Without Branches]
[http://docs.joomla.org/Git_for_Testers_and_Trackers#Apply_Patches_and_Pull_Requests_Using_Branches | Apply Patches and Pull Requests Using Branches]

Testing Checklists

2013-03-22T13:13:04Z

B.nisevic:

This article is designed to help Joomla! Bug Squad members as they test Open issues and Pending issues.

=== Testing Open Issues ===
The "Open" status indicates that no JBS member has evaluated this issue. So the goal is to learn enough about the issue to be able to change the status to one of the following: Unable to Confirm, Known Issue, Duplicate Report, Not Joomla! Core, Confirmed, or Information Required. See [[Bug Tracking Process#Resolving Issues | Bug Tracking Process]] for details about these status codes.

Here is a checklist for testing Open issues:
* Did you carefully read the whole description and any other comments?
* Is there enough information provided? If not, add a comment and change to Information Required.
* Did you search the tracker to see if this issue has already been reported? If so, add a comment and change to Duplicate Report.
* Does the issue relate to a Joomla! core program? If not, change status to Not Joomla! Core.
* Is the issue a known issue or limitation? If so, change status to Known Issue.
* Is the issue an enhancement request? If so, change status to Not a Bug.
* Before testing, did you update your local GIT repository to get the latest GIT Joomla! version? (see [[Git for Testers and Trackers]])
* If you couldn't duplicate the problem with the latest GIT version, did you test using the latest production version?
* If the issue is still unconfirmed, try to to reproduce the issue with different cache settings.
* Try to localize the problem by changing your cache settings.
* If you changed the issue to Confirmed, did you make sure there is a detailed test plan in the comments to allow someone who is not familiar with the issue to understand and test the issue?

=== Testing Pending Issues ===
A Pending issue is one that (a) has been confirmed, (b) has a detailed test plan, and (c) has a proposed patch to be tested ([[Learn more about patch files]]). Here is a checklist for testing Pending issues:
* Is there a test plan for the issue shown in the Test Instructions field? If not, post a comment and change status to Information Required.
* Before testing, did you update your local GIT repository to get the latest GIT Joomla! version?
* Did you test the issue ''before'' applying the patch to make sure you can duplicate the problem?
* Did you test the issue after applying the patch to make sure the problem is fixed?
* Are there any other test cases that should be considered? Examples might include:
** template override files (especially beez template)
** testing with SEF or mod_rewrite enabled and disabled
** language file issues (test with Debug Language set to Yes).
** PHP warnings (test with Error Reporting set to Maximum).
* In your comment before you report the test results (positive or negative) add @test to the comment on a separate line (this is used for stats).
* If your test is successful and you are the first tester, indicate in your comment that a second test is needed. If you are the second tester, change the status to Ready to Commit.
* Check the "Monitor Item" link on the left side if you want to receive an email when someone changes this tracker issue.
* Remember to revert the changes made by the patch after you are done testing.

=== Testing Code Snippets ===
Sometimes to test a patch you will need to test PHP code snippets. One very simple way to do this is as follows:
# Create a new folder called "com_test" under the components folder.
# Create a new file called "test.php" under this folder.
# Put your PHP code snippet in this file.
# To run the file, just enter the URL <your domain>/index.php?option=com_test. For example, <nowiki>http://localhost/joomla_development/index.php?option=com_test</nowiki>.

This will run the code snippet inside the Joomla! framework. This way, when you are done, you can just remove the com_test folder and no other files have been changed. (Sam, thanks for this tip!)

=== General Tips & Tricks ===
* If you have the cache enabled (Global Configuration → System → Cache Settings), you will need to clean the cache each time you make a change to the code or parameters. Otherwise, you might be seeing the older cached version of the page. For this reason, unless you are specifically testing the cache feature, test with the Cache set to "No".

* When working it is best to set error reporting to maximum and turn on all debugging options (these are set in Global Configuration).

[[Category:Bug Squad]]

Testing Checklists

2013-03-22T10:05:41Z

B.nisevic:

This article is designed to help Joomla! Bug Squad members as they test Open issues and Pending issues.

=== Testing Open Issues ===
The "Open" status indicates that no JBS member has evaluated this issue. So the goal is to learn enough about the issue to be able to change the status to one of the following: Unable to Confirm, Known Issue, Duplicate Report, Not Joomla! Core, Confirmed, or Information Required. See [[Bug Tracking Process#Resolving Issues | Bug Tracking Process]] for details about these status codes.

Here is a checklist for testing Open issues:
* Did you carefully read the whole description and any other comments?
* Is there enough information provided? If not, add a comment and change to Information Required.
* Did you search the tracker to see if this issue has already been reported? If so, add a comment and change to Duplicate Report.
* Does the issue relate to a Joomla! core program? If not, change status to Not Joomla! Core.
* Is the issue a known issue or limitation? If so, change status to Known Issue.
* Is the issue an enhancement request? If so, change status to Not a Bug.
* Before testing, did you update your local GIT repository to get the latest GIT Joomla! version? (see [[Git for Testers and Trackers]])
* If you couldn't duplicate the problem with the latest GIT version, did you test using the latest production version?
* If the issue is still unconfirmed, try to to reproduce the issue with different cache settings.
* Try to localize the problem by changing your cache settings.
* If you changed the issue to Confirmed, did you make sure there is a detailed test plan in the comments to allow someone who is not familiar with the issue to understand and test the issue?

=== Testing Pending Issues ===
A Pending issue is one that (a) has been confirmed, (b) has a detailed test plan, and (c) has a proposed patch to be tested ([[Learn more about patch files]]). Here is a checklist for testing Pending issues:
* Is there a test plan for the issue shown in the Test Instructions field? If not, post a comment and change status to Information Required.
* Before testing, did you update your local SVN repository to get the latest SVN Joomla! version?
* Did you test the issue ''before'' applying the patch to make sure you can duplicate the problem?
* Did you test the issue after applying the patch to make sure the problem is fixed?
* Are there any other test cases that should be considered? Examples might include:
** template override files (especially beez template)
** testing with SEF or mod_rewrite enabled and disabled
** language file issues (test with Debug Language set to Yes).
** PHP warnings (test with Error Reporting set to Maximum).
* In your comment before you report the test results (positive or negative) add @test to the comment on a separate line (this is used for stats).
* If your test is successful and you are the first tester, indicate in your comment that a second test is needed. If you are the second tester, change the status to Ready to Commit.
* Check the "Monitor Item" link on the left side if you want to receive an email when someone changes this tracker issue.
* Remember to revert the changes made by the patch after you are done testing.

=== Testing Code Snippets ===
Sometimes to test a patch you will need to test PHP code snippets. One very simple way to do this is as follows:
# Create a new folder called "com_test" under the components folder.
# Create a new file called "test.php" under this folder.
# Put your PHP code snippet in this file.
# To run the file, just enter the URL <your domain>/index.php?option=com_test. For example, <nowiki>http://localhost/joomla_development/index.php?option=com_test</nowiki>.

This will run the code snippet inside the Joomla! framework. This way, when you are done, you can just remove the com_test folder and no other files have been changed. (Sam, thanks for this tip!)

=== General Tips & Tricks ===
* If you have the cache enabled (Global Configuration → System → Cache Settings), you will need to clean the cache each time you make a change to the code or parameters. Otherwise, you might be seeing the older cached version of the page. For this reason, unless you are specifically testing the cache feature, test with the Cache set to "No".

* When working it is best to set error reporting to maximum and turn on all debugging options (these are set in Global Configuration).

[[Category:Bug Squad]]