Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:36775
Mailing-List: contact internals-help@lists.php.net; run by ezmlm
Received-SPF: pass (pb1.pair.com: domain zend.com designates 212.25.124.162 as permitted sender)
Message-ID: <47F463F0.4030407@zend.com>
Date: Wed, 02 Apr 2008 21:58:24 -0700
Organization: Zend Technologies
User-Agent: Thunderbird 2.0.0.12 (Windows/20080213)
MIME-Version: 1.0
To: 'PHP Internals' <internals@lists.php.net>
Content-Type: text/plain; charset=ISO-8859-1; format=flowed
Content-Transfer-Encoding: 7bit
Subject: intl naming
From: stas@zend.com (Stanislav Malyshev)

Hi!

I wanted to ask the people here for opinions on the subject of functions 
naming in pecl/intl (hopefully soon to be ext/intl ;) module. Current 
state can be seen at http://docs.php.net/manual/en/book.intl.php

First, a bit of background.
Intl extension project was created with the purpose to bring 
internationalization capabilities of the ICU library to PHP 5, 
specifically 5.2.x and 5.3.x branches. We felt that as PHP gets more and 
more enterprise adoption, it needs to start supporting internationalized 
development much sooner than PHP 6 roadmap would allow us to. Thus, the 
goals of the project were chosen as follows:
1. Provide dual OO/procedural API for all functions
2. Provide same PHP API for both PHP 5 and PHP 6, to allow easy 
migration in the future
3. Keep same codebase in 5.x versions and keep codebases between 5 and 6 
as close as possible
4. Have separate functional modules for each functionality piece (number 
formatter, locale handling, collator, normalization, etc.) with intend 
to add more modules as we go, while keeping single extension as an 
umbrella for them.

As a consequence, we arrived at the naming scheme we have now in 
pecl/intl, i.e. classes named as NumberFormatter, MessageFormatter, 
DateFormatter, Collator, etc. and functions named as numfmt_*, msgfmt_*, 
collator_*, datefmt_*. The latter were chosed in accordance to the 
guidelines stated at http://www.php.net/reST/php-src/CODING_STANDARDS, 
saying:

If they [function names - SM] are part of a "parent set" of functions, 
that parent should be included in the user function name, and should be 
clearly related to the parent program or function family. This should be 
in the form of parent_*.

Recently, concerns were raised specifically about the name 
DateFormatter, which can potentially infringe on ext/date namespace, and 
in general about all the names. There were proposals to prefix all class 
and function names with Intl and intl_ respectively. While I feel that 
would make the API unnecessarily cluttered (since each module will have 
to keep its prefix anyway, we'd have stuff like 
intl_numfmt_parse_currency which IMO looks much uglier than 
numfmt_parse_currency, same goes for IntlCollator vs. Collator, etc.)
However, technically it is possible to do such change, and I believe if 
it has to be done it has to be done now, when we have first phase of the 
development feature-complete and ready (up to bugfixes here and there) 
to announce the module as 1.0 version for everybody to use.

So, I propose people to consider all the above and the following options:
1. Leave it as is.
Pro: we have it now and it works, and it looks nice.
Contra: see above

2. Rename only problematic one - DateFormatter to IntlDateFormatter
Pro: minimal change, nice names stay and can be used in PHP 6 API too.
Contra: one piece starts with Intl, others don't - API looks weird as a 
whole

3. Rename all classes to Intl* while leaving functions as is
Pro: All classes in the extension look the same, functions still have 
nice names
Contra: All classes get ugly names, and they are going to stay in PHP 6 
where those will be recommended system classes (so not Locale but 
IntlLocale, not Collator but IntlCollator).

4. Rename both classes and functions.
Pro: All API looks the same, purists are happy
Contra: API looks ugly, too many prefixes for functions.

So, please comment. If you have more ideas on the topic, please feel 
welcome to propose. We want to make this decision ASAP, so that we could 
move forward with the extension release.
-- 
Stanislav Malyshev, Zend Software Architect
stas@zend.com   http://www.zend.com/
(408)253-8829   MSN: stas@zend.com