PEPr: Latest proposals with status Proposed

PEPr Proposal [574]: Web Services::Services_oEmbed

2008-09-26T20:15:30-05:00

Proposed package: Web Services::Services_oEmbed

Proposer: Joe Stump [Wishlist]

Services_oEmbed is a package for fetching meta data about URI's from oEmbed providers. It currently supports the entire draft specification, including auto-discovery.

oEmbed (http://www.oembed.com) is an open specification for discovering more information about URI's. oEmbed services return structure meta-data about a URI (e.g. type of object, title, author information, thumbnail details, etc.).

PEPr Proposal [573]: Database::MDB2_TableBrowser

2008-09-26T19:08:56-05:00

Proposed package: Database::MDB2_TableBrowser

Proposer: Isaac Tewolde

Database table abstraction library

Use this library to construct table browsing objects out of your database table. These objects allow your code to handle any database table in an abstract way. By freeing your code from the database details it is possible for you to build generic data reporting or manipulation functions that can work with any table.

Put another way, if you really hate using sql in your code, having to piece together bits of sql to make queries...this library gives you an alternative. Currently only the single table browser is implemented. If you need to work with data that spans multiple tables, you can build a table view as this library works with them as well.

CHANGES:

This library has been completely rewritten and is more modular now. The package is now redone as an MDB2 module and the new architechture offers new possibilities.

PEPr Proposal [572]: PEAR::Exception2

2008-09-19T05:55:41-05:00

Proposed package: PEAR::Exception2

Proposer: Till Klampaeckel [Wishlist]

PEAR_Exception2 aims to provide an Exception class for PHP5-compatible PEAR(1) packages to extend from. In contrast to PEAR_Exception, this package provides are more lightweight dependency than the entire PEAR package.

This would be my proposal, I'm open for suggestions:

http://www.friendpaste.com/H7ULHnvJ

PEPr Proposal [564]: Web Services::ContactsWindows

2008-06-29T15:12:23-05:00

Proposed package: Web Services::ContactsWindows

Proposer: Jonathan Street

Interacts with the Windows Live Contacts API (http://dev.live.com/contacts/).

Currently supports obtaining the address book in both the full format and the invite format. It does not currently support adding, updating or deleting contacts. I plan on adding this later. Hopefully obtaining contact information will meet most needs.

PEPr Proposal [563]: Web Services::WindowsDelegatedAuthentication

2008-06-29T15:03:45-05:00

Proposed package: Web Services::WindowsDelegatedAuthentication

Proposer: Jonathan Street

Windows Live ID Delegated Authentication enables third party developers to request access to a users Windows Live ID account. Essentially it is a proprietary version of OAuth.

This package supports the main aspects of Windows Live ID Delegated Authentication. It can be used to generate the url to which a user should be directed to grant you access. It can then process the returned variables so that a developer can access the users data.

It does not currently support refreshing the delegation token. I don't currently expect many (if any) people to have need for this but if I'm wrong I'll add it later.

To use the service developers will need to register their application.

PEPr Proposal [550]: Web Services::Services_GeoNames

2008-04-10T02:57:03-05:00

Proposed package: Web Services::Services_GeoNames

Proposer: David Jean Louis

Services_GeoNames is a PHP interface to the various webservices offered by the GeoNames project.

You will find all the details at the project home

PEPr Proposal [547]: Database::SimpleDAO

2008-04-02T19:24:59-05:00

Proposed package: Database::SimpleDAO

Proposer: Huilen Abed Moure

SimpleDAO is a Data Access Object generator for PHP 5 and MySQL applications.

PEPr Proposal [538]: RFC::Coding standard enhancements

2008-03-07T11:34:53-05:00

Proposed package: RFC::Coding standard enhancements

Proposer: Christian Weiske

Table of Contents

Introduction

Split function definitions onto several lines

Split function call on several lines

Split long assigments onto several lines

Split long if statements onto several lines

Ternary operators

Alignment of function parameters

Alignment of assignments

Array formatting

Recommendation: Readability of code blocks.

Return early

Notes

Introduction

This RFC defines changes and enhancements to the current Coding Standards (CS) in PEAR. They are neccessary because the standards are not clear in some cases. With applications like PHP_CodeSniffer being used, is is important that those issues are worked out and tools can deliver reliable warnings and CS errors.

Most of the issues we currently have deal with long lines and how they should be split. General rule of thumb is that when splitting a line, the originating lines are indented by 4 spaces.

Futher, the format shall allow it to easily comment out those lines - be it for debugging or development reasons. This implies that closing braces are to be put on a line on its own, and commas at the end of a line.

While it might seem archaic to some, the 75-80 line rule is still important. Please see http://paul-m-jones.com/?p=276 for an in-depth discussion on the topic.

Split function definitions onto several lines

Functions with many parameters need to be split onto several lines to keep the 80 chars/line limit.

The first parameters may be put onto the same line as the function name if there is enough space.

Subsequent parameters on following lines are to be indented 4 spaces. The closing parenthesis and the opening brace are to be put onto the next line, on the same indentation level as the "function" keyword.

Example:



<?php



function someFunctionWithAVeryLongName($firstParameter = 'something', $secondParameter = 'booooo',

    $third = null, $fourthParameter = false, $fifthParameter = 123.12,

    $sixthParam = true

) {

    //....

?>

Split function call on several lines

The CS require lines to have a maximum length of 80 chars.

Calling functions or methods with many parameters while adhering to CS is impossible in that cases. It should be allowed to split parameters in function calls onto several lines.

Example:



<?php



$this->someObject->subObject->callThisFunctionWithALongName(

    $parameterOne, $parameterTwo,

    $aVeryLongParameterThree

);

?>

Several parameters per line should be allowed. Parameters need to be indented 4 spaces compared to the level of the function call. The opening parenthesis is to be put at the end of the function call line, the closing parenthesis gets its own line at the end of the parameters. This shows a visual end to the parameter indentations and follows the opening/closing brace rules for functions and conditionals. (See bug #11562)

The same applies not only for parameter variables, but also for nested function calls and for arrays.

Example:



<?php



$this->someObject->subObject->callThisFunctionWithALongName(

    $this->someOtherFunc(

        $this->someEvenOtherFunc(

            'Help me!',

            array(

                'foo'  => 'bar',

                'spam' => 'eggs',

            ),

            23

        ),

        $this->someEvenOtherFunc()

    ),

    $this->wowowowowow(12)

);

?>

Nesting those function parameters is allowed if it helps to make the code more readable, not only when it is necessary when the characters per line limit is reached.

Using fluent application programming interfaces often leads to many concatenated function calls. Those calls may be split onto several lines. When doing this, all subsequent lines are indented by 4 spaces and begin with the "->" arrow.

Example:



<?php



$someObject->someFunction("some", "parameter")

    ->someOtherFunc(23, 42)

    ->andAThirdFunction();

?>

Split long assigments onto several lines

Assigments may be split onto several lines when the character/line limit would be exceeded. The equal sign has to be positioned onto the following line, and indented by 4 characters.

Example:



<?php



$GLOBALS['TSFE']->additionalHeaderData[$this->strApplicationName]

    = $this->xajax->getJavascript(t3lib_extMgm::siteRelPath('nr_xajax'));

?>

Split long if statements onto several lines

Long if statements may be split onto several lines when the character/line limit would be exceeded. The conditions have to be positioned onto the following line, and indented 4 characters. The logical operators (&&, ||, etc.) should be at the beginning of the line to make it easier to comment (and exclude) the condition. The closing parenthesis and opening brace get their own line at the end of the conditions.

Keeping the operators at the beginning of the line has two advantages: It is trivial to comment out a particular line during development while keeping syntactically correct code (except of course the first line). Further is the logic kept at the front where it's not forgotten. Scanning such conditions is very easy since they are aligned below each other.

Example:



<?php



if (($condition1

    || $condition2)

    && $condition3

    && $condition4

) {

    //code here

} 

?>

The first condition may be aligned to the others.

Example:



<?php



if (   $condition1

    || $condition2

    || $condition3

) {

    //code here

}

?>

The best case is of course when the line does not need to be split. When the if clause is really long enough to be split, it might be better to simplify it. In such cases, you could express conditions as variables an compare them in the if() condition. This has the benefit of "naming" and splitting the condition sets into smaller, better understandable chunks:



<?php



$is_foo = ($condition1 || $condition2);

$is_bar = ($condition3 && $condtion4);

if ($is_foo && $is_bar) {

    // ....

}

?>

Note: There were suggestions to indent the parantheses "groups" by 1 space for each grouping. This is too hard to achieve in your coding flow, since your tab key always produces 4 spaces. Indenting the if clauses would take too much finetuning.

Ternary operators

The same rule as for if clauses also applies for the ternary operator: It may be split onto several lines, keeping the question mark and the colon at the front.



<?php



$a = $condition1 && $condition2

    ? $foo : $bar;



$b = $condition3 && $condition4

    ? $foo_man_this_is_too_long_what_should_i_do

    : $bar;

?>

Alignment of function parameters

To support readability, parameters in subsequent calls to the same function/method may be aligned by parameter name:



<?php



$this->callSomeFunction('param1',     'second',        true);

$this->callSomeFunction('parameter2', 'third',         false);

$this->callSomeFunction('3',          'verrrrrrylong', true);

?>

Alignment of assignments

To support readability, the equal signs may be aligned in block-related assignments:



<?php



$short  = foo($bar);

$longer = foo($baz);

?>

The rule can be broken when the length of the variable name is at least 8 characters longer/shorter than the previous one:



<?php



$short = foo($bar);

$thisVariableNameIsVeeeeeeeeeeryLong = foo($baz);

?>

Array formatting

Assignments in arrays may be aligned. When splitting array definitions onto several lines, the last value may also have a trailing comma. This is valid PHP syntax and helps to keep code diffs minimal:



<?php



$some_array = array(

    'foo'  => 'bar',

    'spam' => 'ham',

);

?>

Recommendation: Readability of code blocks.

Related lines of code should be grouped into blocks, seperated from each other to keep readability as high as possible. The definition of "related" depends on the code :)

For example:



<?php



if ($foo) {

    $bar = 1;

}

if ($spam) {

    $ham = 1;

}

if ($pinky) {

    $brain = 1;

}

?>

is a lot easier to read when seperated:



<?php



if ($foo) {

    $bar = 1;

}



if ($spam) {

    $ham = 1;

}



if ($pinky) {

    $brain = 1;

}

?>

Return early

To keep readability in functions and methods, it is wise to return early if simple conditions apply that can be checked at the beginning of a method:



<?php



function foo($bar, $baz)

{

    if ($foo) {

        //assume

        //that

        //here

        //is

        //the

        //whole

        //logic

        //of

        //this

        //method

        return $calculated_value;

    } else {

        return null;

    }

}

?>

It's better to return early, keeping indentation and brain power needed to follow the code low.



<?php



function foo($bar, $baz)

{

    if (!$foo) {

        return null;

    }



    //assume

    //that

    //here

    //is

    //the

    //whole

    //logic

    //of

    //this

    //method

    return $calculated_value;

}

?>

Notes

We should keep to the 4 space indentation rule. Allowing 6, 8 or any other number for "personal preference" is an absurd line in a "standard".

Of course, the best rule is keeping your code easy and clean, avoing dozens of parameters to a function ("code smell" for long parameter lists). But sometimes there is no way to avoid functions with 6 parameters, and having default values for them does not simplfy the situation. The rules here are exactly for that code lines.

PEPr Proposal [534]: HTML::HTML_Form_Error

2008-03-02T04:14:55-05:00

Proposed package: HTML::HTML_Form_Error

Proposer: Jacopo Andrea Nuzzi

With this application you can easily validate fields of your form.

This class could also be used to validate query strings.

You can use HTML_Form_Error with several languages:

* English

* Italian

If you are interested to implement/improve or add a new translation feel free to send an email to jacoz@php.net

PEPr Proposal [532]: Validate::Validate_IT

2008-02-23T09:36:16-05:00

Proposed package: Validate::Validate_IT

Proposer: Jacopo Andrea Nuzzi

Validation class for Italy.

This class provides methods to validate:

Postal code (CAP)
Telephone number (and prefix)
Mobile number (and prefix)
Regions (and regions code)
Cities (and cities code)
Fiscal code