joomla / joomla-framework

[READ-ONLY] This repo is no longer in active development. Please see https://github.com/joomla-framework for the individual Framework packages.

Joomla! Framework

What is the Joomla! Framework ?

The Joomla! Framework is a platform for writing web and command line applications in PHP. It is free and open source software, distributed under the GNU General Public License version 2 or later.

It is composed of code originally developed for the Joomla Content Management System (CMS). For more information about the Joomla CMS visit http://www.joomla.org/about-joomla.html.

For news and information about developing with Joomla, please visit http://developer.joomla.org.

View the Joomla Framework API Documentation at http://api.joomla.org and is powered by phpDocumentor 2.

You can discuss Joomla Framework development by joining the mailing list at http://groups.google.com/group/joomla-dev-framework.

Requirements

• PHP 5.3.10
• Each package has their own requirements as well. Ex: The Image package requires the PHP GD extension. Please see the composer.json in each package repository for these requirements.
• Applications implementing the Joomla Framework must implement the 'JPATH_ROOT' constant which should be the root path of the application.

Installation

The simplest way to get up and running with the Joomla Framework is to use composer. Basic installation for composer can be found below, for additional information on installing composer, read the documentation.

curl -sS https://getcomposer.org/installer | php

Full Installation Via Composer

Composer has the ability to download the full stack framework (including all our packages) as a project starter using the "create-project" command. In the example below, "myAwesomeApp" is the folder where you want to create the project. It should not be created yet.

php composer.phar create-project --prefer-dist joomla/framework myAwesomeApp

If you are interested in working with the development code (in the master branch), and not a tagged stable distribution, then pass in the --stability="dev" command after --prefer-dist.

Package Installation Via Composer

There are two ways to add our packages to your existing composer powered application.

Adding packages manually to the require option in your composer.json.

{
    "require": {
        "joomla/PACKAGENAME": "VERSION"
    }
}

and then run install (or update).

php composer.phar install

Adding packages using composer require

php composer.phar require joomla/packagename:version

Full Installation Via Git

git clone git://github.com/joomla/joomla-framework.git

Documentation

General documentation about the Joomla Framework can be found under the /docs folder of this repository. In addition, each package has documentation in a README.md file.

Reporting Bugs and Issue

Bugs and issues found in the Joomla Framework code can be reported on the Issues list. Even for distributed packages where the code is in another repo, please submit issues to this issue tracker.

Contributing

All kind of contributions are welcome. Please read about how to contribute here.

You may find tasks you can do on the Issues list by filtering on labels and milestones.

joomla-framework's Issues

Update docs/analysis.md

This file needs a review in terms of how to run tests on the Framework. Note there are two ways.

1. Tests can be run from root just like in the old platform.
2. Tests can be run from the root of each Package as if they were installed by Composer.

Tag 1.0 Final

Write documentation for Application package

Extensive developer documention is required to teach developers how to start building the various types of applications.

• Cli
• Web
• Daemon
• Web Client
• Web Router Base
• Web Router Rest

Update /README.markdown

Text needs to be changed from referring to "Platform" to refer to "Framework".

Text needs to be reviewed in general as being appropriate for the "home" page of the repositories instructions.

Remove @subpackage

The @subpackage tag is deprecated so we need to remove it from all files.

Also remove the extra new line after it in the file header DocBlock. In that case, the final result should look something like:

<?php
/**
 * @package    Joomla\Framework
 * @copyright  Copyright (C) 2005 - 2013 Open Source Matters, Inc. All rights reserved.
 * @license    GNU General Public License version 2 or later; see LICENSE
 */

Note that you will need to adjust the alignment of other tags after you remove @subpackage. This affects file header and class docblocks. Please run the code sniffer after you change the files.

Update documentation for the Log package

Examples in the Log package README need to be converted to namespace style.

Refactor usage of TestReflection

We need to change all the usage of TestReflection. In a file where this is used, you will need to add:

use Joomla\Test\Helper;

TestReflection::setValue should be changed to Helper::setValue.

TestReflection::getValue should be changed to Helper::getValue.

TestReflection::invoke should be changed to Helper::invoke.

Write documentation for Archive package

Developer documentation for the Archive class and examples for all the available adapters is needed.

• Archive
• Bzip2
• Gzip
• Tar
• Zip

Freshen documentation for the Input package

The documentation for the input package needs to be converted completely to namespace style.

Remove coupling to JFactory

We need to remove the coupling to the old JFactory, now \Joomla\Factory.

• Application
• Archive
• Client
• Controller
• Filesystem
• Filter
• Form
• Http
• Language
• Log
• Model
• OAuth1
• OAuth2
• Session

Update documentation for Keychain package

The documentation for the Keychain package needs to be converted to namespace style.

Update CONTRIBUTING.markdown

We just need to freshen this document and mark sure it is accurate and easy for people to follow.

Improve documentation for Github package

More complete developer documentation and examples are required for the Github package to cover all available options.

• Account
• Commits
• Forks
• Gists
• Hooks
• Http
• Issues
• Milestones
• Object
• Pulls
• Refs
• Statuses

Write unit tests for Joomla\Profiler\Profiler

Unit tests are needed for this class.

Get tests running in the respective packages, independently

See the Date package for a good example.

• phpunit.xml.dist needs to be copied from the Date package into each package and test the running of tests.
• bootstrap.php needs to be copied fromDate\Tests` to the corresponding package you are working on.
• Each test file needs to be namepaced, for example, for the Date package, the namespace is \Joomla\Date\Tests.

Complete:

• Application
• Archive
• Cache
• Controller
• Crypt
• Data
• Database
• Date
• DI
• Event
• Facebook
• Filesystem
• Filter
• Form
• Github
• Google
• Http
• Image
• Input
• Keychain
• Language
• Ldap
• Linkedin
• Log
• Model
• Oauth1
• Oauth2
• Profiler
• Registry
• Router
• Session
• String
• Twitter
• Uri
• Utilities
• View

Make sure composer.json files are accurate with their required dependencies

Decoupled JText where possible

We need to get JText out of the Framework as much as possible (the Form package is one exception in a few places). The exceptions or errors just need to be converted to natural language strings.

Write documentation for the Client package

• Buffer
• Ftp
• Helper
• Ldap

Decouple the rendering of Joomla\Profiler

We need to take the rendering elements out of Profiler, or at least decouple it somehow. We should be storing the raw data internally and should be able to return that raw data.

Update @since to version 1.0

We are reseting the entire Framework to version 1.0 so all @since tags need to be reset to 1.0. For example:

    /**
     * An instance of the class to test.
     *
     * @var    Joomla\Date\Date
     * @since  1.0
     */
    private $instance;

Clean all deprecated code

Any code marked with @deprecated needs to be removed. We are not supporting any deprecated code in the new Framework.

Update documentation for View package

The documentation for the View package needs to be converted to namespace style.

Write documentation for the Language package

Developer documentation and examples are required for the Language package.

• Language
• Helper
• Stemmer
• Text
• Transliterate

Improve documentation for Crypt package

The Crypt package currently has minimal developer documentation.

• Crypt
• Cipher
• Cipher 3DES
• Cipher Blowfish
• Cipher MCrypt
• Cipher Rijndael256
• Cipher Simple
• Key
• Password
• Password Simple

Update documentation for Model package

The documentation for the Model package needs to be converted to namespace style.

[Database] Driver date format

I saw JDate::toSql has been removed which is good, but I don't see a replacement yet

We should have a method like :

public function formatDate(DateTime $date);

in the drivers.

Improve documentation for Http package

Parts of the documentation for the Http package are missing. It also needs to be converted to namespace style.

Write documentation for the Date package

Developer documentation and examples are required for the Data package.

Set up travis for each repo

Set up automatic subsplit when there's a merge to master

Which PHP version to use?

I saw composer.json specified PHP version 5.3.10 as a minimum requirement for Joomla Framework. Why is this the exact version? Why not 5.3.9 or 5.3.11? Why not go all the way and use 5.4.x, which was released right after 5.3.10?

See also #36

Installation Instructions in each package README

We need a new doc to explain how people can install packages using Composer. This one is really important to get right and the instructions need to be clear and simple.

Tests for new Cache package

We've brought in the new Cache package that Louis Landry did a while back. Unfortunately it has not tests so these need to be done.

Update docs/introduction.md

This document needs a lot of work as a result of the Composer changes. Please ask about how you can help improve it.

Write documentation for the Filter package

Developer documentation and examples are required for the Filter package.

• Input
• Output

Write documentation for the Cache package

Developer documentation is required for the Cache package and the available caching handlers.

• General documentation for Cache
• Apc
• File
• Memcached
• None
• Wincache
• XCache

Refactor logging in Database package

The database package is tightly coupled to the Joomla Log package at the moment. We need to change this to inject a PSR-3 logger.

Tasks:

1. Add a public setLogger(\Psr\Log\LoggerInterface $logger) method that sets a protected logger property.
2. Add a protected log($level, $message, array $context = array()) method to Driver that checks if a logger has been set, and if so logs the message.
3. Refactor the usage of Log to use the log method.
4. Update unit tests.

Change @package

We need to change the @Package tag to Joomla\Framework for core class files and Joomla\Framework\Test for unit test files. For example:

<?php
/**
 * @package    Joomla\Framework
 */

Tag a 1.0b1 and test that all packages update in their repos and on packagist

Improve documentation for Google package

More complete developer documentation and examples are required for the Google package.

Copy mocks into local test folders

We need to copy all the mocks (and probably refactor them) to all the local test folders. See examples in the Database (Driver and Query) and Model (Model) packages.

Update documentation for Controller package

The documentation for the Controller package needs to be converted to namespace style.

Write documentation for the Database package

Extensive developer documentation an examples are required for the Database package.

• Drivers
• Queries
• Exporters
• Importers
• Iterators

Write documentation for the File package

Developer documentation and examples are required for the File package.

• File
• Folder
• Helper
• Patcher
• Path
• Stream

Update documentation for Data package

The documentation for the Data package needs to be converted to namespace style.

Document ArrayHelper

The ArrayHelper class needs to be documented.

Tasks:

1. Add a brief example of how to use each method in the ArrayHelper class.

References:
https://github.com/joomla/joomla-framework/blob/master/vendor/Joomla/Utilities/README.md

Update docs/testing.md

This is a short doc to help you write unit tests for the Framework. It needs freshening and maybe expanding to be more helpful and informative.

Write documentation for the Form package

Developer documentation and examples are required for the Form package.

• Forms
• Fields
• Rules
• Helper

Write documentation for the Compat package

We just need some simple notes about the Compat package. It currently provides for the JsonSerialize interface that is only available in PHP 5.4.

Ensure travis completes unit tests after the first push.