Contributing to the Joomla! Framework

As of June 2017, the individual repositories in the Joomla! Framework GitHub organization are generally structured the same.


Most repositories have two branches representing the two major Framework versions; 1.x and 2.0.

File Structure

Joomla! Framework packages are PSR-4 compliant and follow a common filesystem structure.

NOTE The Crypt and Form 1.x branches are still structured for PSR-0 support due to backward compatibility implications with migrating to PSR-4 and as such those branches have a slightly different repository structure. Additionally, the Session package's 1.x branch was not migrated to PSR-4 and still follows the PSR-0 structure.

Issue tracking and pull requests are managed via GitHub in each package's repository. All of the Framework's packages are listed under the Joomla! Framework organization. You can find the documentation about how to fork a repository and start contributing to the Joomla! Framework at

All contributions are welcome to be submitted for review for inclusion in the Framework, but before they will be accepted, we ask that you follow these simple guidelines:

Please be patient as not all items will be tested or reviewed immediately by a Framework maintainer. Also be receptive to feedback about your changes to the Framework. The maintainer team and other community members may make suggestions or ask questions about your change. This is part of the review process, and helps everyone to understand what is happening, why it is happening, and potentially optimize your code.

Security Issues

Security issues should be reported to the Joomla! Security Strike Team by either filling out the contact form or emailing

Ideally, everybody who contributes to the Framework, or any other Open Source Matters (OSM) supported project for that matter, should sign the Joomla! Contributor Agreement (JCA). But, we are aware that some contributors will not want to take the extra effort, especially for one-time contributors of modest amounts of code. As a compromise, the Joomla! Project requires a JCA from anybody who makes a significant contribution to Joomla! or any other OSM project. "Significant" is, of course, a judgment call. As a general guideline, if you as an individual have contributed or intend to contribute over 100 lines of code to the Joomla! Framework, we will ask for you to sign the JCA. If you are contributing as an employee of a company (that is, the work you are contributing was done on company time) then we need a JCA with your company's signature no matter how small the contribution is.

When you add new classes, properties or methods, please use __DEPLOY_VERSION__ in the @since tags in Docblocks. We'll replace that marker with the actual version the changes are deployed in.

All submitted code must be compliant with the Joomla! Coding Standards. This standard is documented at There is a tool called PHP_CodeSniffer that allows you to validate your code against the Joomla! Coding Standards.

Install & Use

The Framework repositories are using version 2.x of the Joomla! Coding Standards which is based on the 2.x branch of PHP_CodeSniffer. PHP_CodeSniffer is installed as part of a composer install, helpful when you are cloning a package's git repository. Please see for more documentation on PHP_CodeSniffer.

Once PHP_CodeSniffer is installed and the Joomla! Coding Standards are downloaded, you can now check your code against the standard. The exact command to be run will vary based on whether the repository uses the base definition or has a custom ruleset due to rule exemptions for that package, therefore we suggest copying the command from the package's .travis.yml file.

IDE Support

Some editors support PHP_CodeSniffer as a plugin or a built in feature. It will allow you to see if your code matches the Joomla! standard directly in your editor. You can find configuration files for many editors from this repository: Download the repository content via the Zip button and import the appropriate .xml file into your editor.

Whether your pull request is a bug fix or introduces new classes or methods to the Framework, we ask that you include unit tests for your changes. We understand that not all users submitting pull requests will be proficient with PHPUnit. The maintainers and community as a whole are a helpful group and can help you with writing tests. PHPUnit, and any additional testing dependencies, is installed as part of a composer install, helpful when you are cloning a package's git repository. Please see for the full PHPUnit documentation.

For Framework 1.x releases, documentation for each package can be found in the file in the root of the repository. As of 2.0, each repository will have a dedicated docs directory.

The docs directory structure at a minimum uses the following format:

The documentation files use GitHub Flavored Markdown. When contributing new features to existing packages, please add notes about the new features to the existing file in the packages you change or add new files to the docs directory (depending on the branch you are submitting the change to). When submitting new packages, documentation in the form of a file will be required with your pull request. The package documentation should explain how a developer should should be able to get started using the code in the package. The documentation should give an explanation of the classes, interfaces, and/or traits, and provide several simple examples.