Skip to end of metadata
Go to start of metadata

<ac:macro ac:name="unmigrated-inline-wiki-markup"><ac:plain-text-body><![CDATA[

<ac:macro ac:name="unmigrated-inline-wiki-markup"><ac:plain-text-body><![CDATA[

Zend Framework: Naming conventions for 2.0 - Matthew Ratzloff Component Proposal

Proposed Component Name Naming conventions for 2.0 - Matthew Ratzloff
Developer Notes http://framework.zend.com/wiki/display/ZFDEV/Naming conventions for 2.0 - Matthew Ratzloff
Proposers Matthew Ratzloff
Zend Liaison TBD
Revision 1.0 - May 25, 2008: Incomplete initial draft (wiki revision: 12)

Table of Contents

1. Overview

To do: Zend_Search, methods, Boolean accessors

Since the initial preview in March 2006, there hasn't really been much in the way of direction given on naming standards for classes in Zend Framework. This lack of consistency is what has yielded two nomenclatures for CLI components ("Zend_Console" vs. "Zend_Controller_Response_Cli"), differing terms for similar concepts ("Zend_Json_Decoder" vs. "Zend_Mime_Decode"), both nouns and verbs in equal measure ("Zend_Loader" but not "Zend_Translator"; alternately, "Zend_Translate" but not "Zend_Load"), and so on.

I first brought this issue up in February 2007 and concluded, "Consistency means predictability, which means being able to recall names without having to check the manual every time. It's why most people can't use PHP's date or string functions without looking at the documentation, for example." Beyond this there are also intangible benefits, such as presenting a more professional appearance. Because many skilled PHP developers contribute to this project, the Zend Framework community also has an opportunity to lead the general PHP community by example.

There was a lot of agreement from the community (and a couple Zenders) but no movement because the framework was preparing for 1.0. At the time I was told, "There is life after 0.9.0," and so as we prepare for 2.0, I think it's the perfect time to revisit this.

Note: Because this is a non-traditional proposal, the bulk of the proposal will be in the first three sections.

2. References

3. Component Requirements, Constraints, and Acceptance Criteria

Class Names

There are currently 1074 classes that comprise Zend Framework. With few exceptions, these all follow similar standards found in other languages and frameworks. For example, that Java Naming Conventions state,

Class names should be nouns, in mixed case with the first letter of each internal word capitalized. Try to keep your class names simple and descriptive. Use whole words-avoid acronyms and abbreviations (unless the abbreviation is much more widely used than the long form, such as URL or HTML).

The .NET Guidelines for Names state the following:

In general, type names should be noun phrases, where the noun is the entity represented by the type. For example, Button, Stack, and File each have names that identify the entity represented by the type. Choose names that identify the entity from the developer's perspective; names should reflect usage scenarios.

ActionScript Naming Conventions are similar:

Class names are usually nouns or qualified nouns. (...) Don't use nouns that also might be interpreted as verbs. For example, Running, or Gardening. Using these nouns might lead to confusion with methods, states, or other application activities.

Therefore, I propose the Zend Framework Coding Standard section B.3 be modified to include language similar to the following:

Class names must be nouns, noun phrases, or proper nouns (i.e., protocols, formats, algorithms, PHP extensions, or products), with two exceptions.

In cases of classes that represent implementation strategies, an unambiguous adjective is permitted. For example, Zend\Controller\Router\Rewrite is acceptable (it should be interpreted as "RewriteRouter"), but Zend\Loader\Plugin is not, as it is unclear whether the class represents a Zend::Loader plugin or a generic plugin loader. (In this case it is the latter; the class is actually named Zend\Loader\PluginLoader.)

Gerunds (verbs in noun form ending in "-ing") are permitted when a suitable noun cannot be found. The Zend\Measure\Cooking namespace is an example of this.

Verbs, adverbs, and prepositions are not permitted.

Abstract Classes and Interfaces

As Matthew Weier O'Phinney notes, there are issues with PHP 5.3's namespace implementation and the framework's pre-2.0 standard of interface names in the form of Zend_Example_Interface and quasi-standard of abstract class names in the form of Zend_Example_Abstract. As such, I propose the following:

Abstract classes and interfaces are special cases and therefore are treated as such. Abstract classes must be named in the form of Zend\Example\AbstractExample, while interfaces are named in the form of Zend\Example\ExampleInterface.

Abbreviations

Abbreviations are acceptable, so long as they are universally understood and unambiguous, and the unabbreviated word is sufficiently long. Examples include "db", "config", and "info". "Auth" is acceptable so long a disambiguation note is included in the documentation. Examples of out-of-conformance words include "str".

I'd like some community input here. Which abbreviations are unacceptable? What are some examples of common abbreviations that aren't acceptable?

Our Lexicon

A consistent set of names for common concepts is important for the framework to feel like a cohesive whole. To that end, we have standardized on certain words: Alphabetic not Alpha or Text, Alphanumeric not Alnum or TextNum, Directory not Dir, Integer not Int, and Utilities not Util or Utils.

These specific word choices are of course debatable and community input is welcome. Naturally, this is also related to the above section.

Specific class name change recommendations

These are specific name change recommendations.

Old class name New class name Notes
Zend_Acl_Assert Zend\Acl\Assertion  
Zend_Filter_Alnum Zend\Filter\Alphanumeric 1
Zend_Filter_Alpha Zend\Filter\Alphabetic 1
Zend_Filter_Dir Zend\Filter\Directory 1
Zend_Filter_Int Zend\Filter\Integer 1
Zend_Controller_Action Zend\Controller\AbstractAction  
Zend_Controller_Response_Cli Zend\Controller\Response\Console  
Zend_Db_Statement_Oracle* Zend\Db\Statement\Oci*  
Zend_Db_Table_Rowset Zend\Db\Table\RowSet 2
Zend_Gdata_App_Util Zend\Gdata\App\Utilities 1
Zend_Gdata_Calendar_Extension_Timezone Zend\Gdata\Calendar\Extension\TimeZone 2
Zend_Gdata_Exif_Extension_FStop Zend\Gdata\Exif\Extension\Fstop 2
Zend_Log_Filter_Suppress Zend\Log\Filter???  
Zend_Mime_Decode Zend\Mime\Decoder  
Zend_Service_Amazon* Zend\Service\Amazon\Associates* 4
Zend_Service_StrikeIron_USAddressVerification Zend\Service\StrikeIron\UsAddressVerification 2
Zend_Service_Technorati_Utils Zend\Service\Technorati\Utilities 1
Zend_Translate Zend\Translator  
Zend_Validate* Zend\Validator*  
Zend_Validate_Alnum Zend\Validator\Alphanumeric 1
Zend_Validate_Alpha Zend\Validator\Alphabetic 1
Zend_Validate_Ccnum Zend\Validator\CreditCard 3
Zend_Validate_Int Zend\Validator\Integer 1
Zend_Validate_Ip Zend\Validator\IpAddress 3

1 Subject to community input about abbreviations and/or lexicon
2 Does not follow existing naming standard
3 For reasons of clarity
4 This must be namespaced to allow for EC2, S3, etc.

4. Dependencies on Other Framework Components

5. Theory of Operation

6. Milestones / Tasks

7. Class Index

8. Use Cases

9. Class Skeletons

]]></ac:plain-text-body></ac:macro>

]]></ac:plain-text-body></ac:macro>

Labels:
None
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.
  1. May 26, 2008

    <p>I like it, use as few abbreviations as possible, in favor of unambiguous names.</p>

  2. Jun 02, 2008

    <p>I am also in favor of this... This would break BC but in a good way I think.</p>

  3. Jun 02, 2008

    <p>Also, wouldn't be a better name Zend_Logger for Zend_Log?</p>

    1. Oct 14, 2008

      <p>Both Logger and Log are nouns, and both make sense. I see no reason to rename in this example.</p>

  4. Jun 02, 2008

    <p>This is a definite must-have for ZF 2.0 in my opinion.</p>

  5. Jun 13, 2008

    <p>I agree totally with you.<br />
    Every respectable framework needs order and a consistent name convention.</p>

  6. Jul 15, 2008

    <p>Would it also be an idea to use the new PHP Namespaces feature? It'll probably break compatibility with earlier PHP versions (< 5.3), but it'll get rid of classnames like Zend_Controller_Blah_Blah. Instead, you define your Blah class to belong to the Controller namespace, and the Controller in the Zend namespace. </p>

    <p>Using the Action class, for example, would change from class SomeController extends Zend_Controller_Action to</p>

    <p><?php<br />
    use Zend::Controller;<br />
    class SomeController extends Action</p>

    <p>Would, from my point of view, be a lot neater - no need to 'fake' namespaces by prefixing classnames with Zend_Something anymore. But that's perhaps not directly related to naming conventions. That, and it breaks pre-PHP 5.3 compatibility.</p>

    1. Jul 24, 2008

      <p>This proposal will take into account PHP 5.3. The current naming convention is at odds with namespaces in PHP 5.3, so that will have to be addressed. For example, one can't have Zend_Example_Interface or Zend_Example_Abstract because if you say new Interface() or new Abstract() an exception will be thrown. It's possible that the developers of PHP will fix this before the final release, but I doubt it. We may ultimately have to go the route of Zend_Example_ExampleInterface or Zend_Example_IExample.</p>

  7. Jul 17, 2008

    <p>+1</p>

  8. Jul 18, 2008

    <p>No arguments here +1</p>

  9. Jul 23, 2008

    <p>Is there any reason why it's called Zend_Gdata, when all other similar components are grouped under Zend_Service?</p>

    <p>Would it not make sense to rename it Zend_Service_Gdata or even Zend_Service_Google to make room for other APIs from Google?</p>

    1. Jul 24, 2008

      <p>The development of a PHP GData API was part of a deal between Zend and Google, and as part of the deal Google allowed Zend to include the component in Zend Framework (it must also be available separately--see <a class="external-link" href="http://framework.zend.com/download/webservices">http://framework.zend.com/download/webservices</a>). While Zend_Service_Google (for example) would make more sense in the context of the framework, the name must stay as it is.</p>

      <p>Same story for Zend_InfoCard.</p>

      1. Oct 14, 2008

        <p>Actually, that's an oversimplification. Google abbreviates its own "Google Data API" to "GData". In this case, GData is an appropriate component name. It, and Zend_InfoCard, have top-level namespaces not just because they were developed by partners, but because they provide rich functionality that falls outside the scope of other top-level components. Zend_GData, while a web service, provides much more functionality than most other web services for which we have APIs, and because of its scope does not follow the same design guidelines of other Zend_Service components; Zend_InfoCard relates to identity, authentication, and resource management (falling under multiple top-level components).</p>

        <p>Additionally, I'd like to caution against the idea that a nested, hierarchical structure is best for the framework. While it makes sense in some areas, many other areas it does not. One particular pain point of a nested hierarchy is in the documentation: how does a user find the appropriate component, browsing through the manual? For instance, many feel pagination is something that works on data sets, and thus should be under Zend_Data_Paginator – but if all that is in the TOC is "Zend_Data", and you're looking for pagination, how do you find it? In such a case, a flattened hierarchy with at most 2 - 3 levels of depth would aid tremendously.</p>

        <p>There are arguments for both styles of organization. I think we need to be careful of renaming for the sake of renaming, and be cognizant of the many requirements of ZF users.</p>

        1. Oct 14, 2008

          <p>I can see both sides with GData, but I wouldn't change it anyway. By the way, did you realize that you were using <a href="http://framework.zend.com/wiki/pages/viewpage.action?pageId=43560&focusedCommentId=3867817#comment-3867817">my own argument</a> from a few months ago against me? Maybe it was intentional, in which case I laughed. <ac:emoticon ac:name="wink" /></p>

          <p>Agreed about restraining the desire to "rename for the sake of renaming". On the other hand, this will be the single largest renaming effort the framework will ever undergo, so it's important to get it right.</p>

  10. Aug 31, 2008

    fc

    <p>+1</p>

    <p>When would this be happening? Is there an estimate date for the release of version 2.0?</p>

    1. Sep 01, 2008

      <p>No, but it will almost certainly be a little while after the release of PHP 5.3.</p>

      1. Oct 14, 2008

        <p>I'm thinking it will be 6 - 12 months after 5.3.0. This will give enough time for a bugfix release on the PHP 5.3 branch, and some time for distributions to begin adopting it. Additionally, we'll need time to perform our changes; utilization of namespaces will not be a trivial undertaking, and we also want to identify other areas where new language functionality may help simplify our implementations.</p>

  11. Oct 14, 2008

    <p>I'm not sure I agree with the "AbstractSomething" and "SomethingInterface" naming convention at this point, even though I'm the one who originally put the idea (or a similar one) forward.</p>

    <p>Why? Two reasons: it smacks of Hungarian Notation, and because it's better to use plain language.</p>

    <p>As an example, which makes more sense from a language perspective: Zend_Foobar_Adapter, or Zend_Foobar_AdapterInterface? Sure, the latter clearly denotes that it's an interface, but now consider actual usage:</p>
    <ac:macro ac:name="code"><ac:default-parameter>php</ac:default-parameter><ac:plain-text-body><![CDATA[
    namespace Zend::Foobar;
    // ...

    if ($foo instanceof AdapterInterface)

    // vs:

    if ($foo instanceof Adapter)
    ]]></ac:plain-text-body></ac:macro>
    <p>The latter in this case clearly notes an IS-A type of relation, as well as gives a better semantic: $foo IS-A adapter. It's not an <em>interface</em>, it's an <em>adapter</em>.</p>

    <p>A similar argument may be made for abstract classes: what particular base functionality is provided? Which of the following makes more sense from a natural language perspective:</p>
    <ac:macro ac:name="code"><ac:default-parameter>php</ac:default-parameter><ac:plain-text-body><![CDATA[
    use Zend::Controller::Request
    class Http extends AbstractRequest
    {
    }

    // vs:

    class Http extends Base
    {
    }
    ]]></ac:plain-text-body></ac:macro>

    <p>In the latter, it's clear that the new class is inheriting some <em>base</em> functionality; in the former, it's less clear what the AbstractRequest provides.</p>

    <p>If we're going to get all gung-ho about naming, let's use <em>meaningful</em> names, not type-driven names.</p>

    1. Oct 14, 2008

      <blockquote>
      <p>I'm not sure I agree with the "AbstractSomething" and "SomethingInterface" naming convention at this point, even though I'm the one who originally put the idea (or a similar one) forward.</p>

      <p>Why? Two reasons: it smacks of Hungarian Notation, and because it's better to use plain language.</p></blockquote>

      <p>I can see how it would seem similar to Hungarian notation, but it's really not that bad. Seems something like "IAdapter" would fit that criticism better. Hungarian notation relies on a shared shorthand, which the full word "Interface" is not.</p>

      <p>I go back to first principles in these cases, and one of mine (and, I think, Zend Framework's) is "explicit is always better than implicit". Saying <code>$foo instanceof AdapterInterface</code> is more explicit than <code>$foo instanceof Adapter</code>. For me, explicitly specifying "abstract" communicates more clearly than "base". Base doesn't imply abstract to me.</p>

      <p>For that matter, if we're talking about meaningful names, using Zend::Controller::Router::Route::Routable instead of Zend::Controller::Router::Route::Interface could be interpreted as more meaningful. I still like having the word "interface" in the class name in some way, however.</p>

      <p>Of course, this proposal is to get people talking, so hopefully we get more feedback. <ac:emoticon ac:name="smile" /></p>

      1. Oct 15, 2008

        <p>I think that generic names fit in most cases.<br />
        Adapter for example... we use Adapter almost over the whole framework.<br />
        Having the classes additionally named Interface and Abstract is in this case irrelevant in my opinion. A Translate_Adapter is always an adapter.</p>

        <p>Anyhow the decission itself will be made there is one other point.<br />
        WHEN we name it AdapterInterface we should also name it AdapterAbstract or visa versa all types in front and then the class... InterfaceAdapter... AbstractAdapter...</p>

        <p>I see no reason, except english grammar, why to have the type in two different places depending on the type. InterfaceAdapter would simply read as InterfaceForAdapter. <ac:emoticon ac:name="smile" /></p>

      2. Oct 15, 2008

        <p>I'm with Matthew! Explicity rules (for me).</p>

        <p>You could state that you can differentiate naming a class and naming an interface (e.g. interfaces get the pre- or suffix Interface) since those are different language constructs but that doesn't apply to abstract classes of course...</p>

        1. Oct 15, 2008

          <p><em>Which</em> Matthew are you with? there are two of us, on opposite sides of the issue. <ac:emoticon ac:name="cheeky" /></p>

          1. Oct 15, 2008

            <p>Sorry Matthew, the other Matthew. <ac:emoticon ac:name="wink" /></p>

      3. Oct 15, 2008

        <p>Actually, using Abstract or Interface in the name <strong>is</strong> Hungarian Notation. HN is simply the practice of naming a variable such that the name "indicates its type or intended use" (see the Wikipedia entry). <strong>Typically</strong> it starts with a three letter annotation, but it's not restricted to this style. The point, though, is that using the names "Abstract" and "Interface" in the names is not particularly helpful – doing so merely hints to the underlying language level implementation. API documentation, user documentation, and the class/interface declarations themselves are the appropriate places to give those details.</p>

        <p>Saying "instanceof AdapterInterface" explicitly says... what? That it implements an interface? That's implicit in the "instanceof" operator, which will only evaluate true if the class implements or extends the right side item. It doesn't matter if the right side item is an interface, an abstract class, or another defined class; what matters is simply that the left side item somehow adheres to the contract (API) it defines.</p>

        <p>My "Base" example is definitely a poor one. Here's a better one:</p>

        <ac:macro ac:name="code"><ac:default-parameter>php</ac:default-parameter><ac:plain-text-body><![CDATA[
        use Zend::Controller;

        class FooController extends Controller::Action
        {
        }
        ]]></ac:plain-text-body></ac:macro>

        <p>In the above case, we know that we're extending the action controller. Does it matter that it's an abstract class? No. What matters is that we are aware that we're <em>extending</em> something, and that the name states what it is we're <em>extending</em> (an action controller). A class does not need to be abstract to be extended.</p>

        <p>Here's another one:</p>

        <ac:macro ac:name="code"><ac:default-parameter>php</ac:default-parameter><ac:plain-text-body><![CDATA[
        use Zend::Controller;

        class CheckAuthentication implements Controller::Plugin
        {
        }

        // or

        class CheckAuthentication extends Controller::Plugin::AllHooks
        {
        }
        ]]></ac:plain-text-body></ac:macro>

        <p>In the above examples, the first indicates that we're defining a controller plugin. In the second, we indicate we're extending a plugin that defines all hooks. These are good, clear, explicit names. Again, how would adding the words "Interface" or "Abstract" make these any clearer? What if at a later date we decided to make AllHooks concrete (maybe it could provide some functionality on its own for managing plugins)? Usage would be the same, but with the rules proposed, we'd need to rename the class!</p>

        <p>PHP will tell you if you try to instantiate an abstract class or interface, and will barf up tons of messages as it merrily shuts itself down. Good API documentation and end-user documentation can help alleviate the need for the user to find this information out "the hard way". There's really no need for the implementation information to be present in the class/interface names themselves.</p>

        <p>Finally, one of the goals of namespacing is to help <em>shorten</em> names. Including the class types in the names is completely counterintuitive in this regard. Let's stick with sensible names.</p>

        1. Oct 15, 2008

          <p>In practice, I've never promoted an abstract class to be concrete. I've made interfaces abstracts, and vice versa, but that would necessitate a change in usage anyway.</p>

          <p>Let's come from the other side. Say you have an abstract class, Zend::Example. Now you realize that it would be really handy to have a concrete class in its place (for example, for static configuration methods). You'd have to rename the existing class. Now any userland code that extends Zend::Example must likewise change to point to the abstract class.</p>

          <p>By explicitly calling it Zend::Example::AbstractExample, you are free to create a concrete class Zend::Example without impacting anything. Examples of this exist in the framework today: Captcha, Measure, Request, and Server, for example.</p>

          <p>Let's take another situation. How do you port the following?</p>

          <ac:macro ac:name="code"><ac:plain-text-body><![CDATA[abstract class Zend_View_Abstract implements Zend_View_Interface]]></ac:plain-text-body></ac:macro>

          <p>In this case, Zend_View already exists.</p>

          <p><code>$foo instanceof Adapter</code> may be self-explanatory, but the real issue is if you are looking at the directory tree, can you instantly pick out if there is an abstract class or an interface?</p>

        2. Nov 17, 2008

          <p>I absolutely agree with your point of view! With one exception. Class names Plugin or Adapter may be confusing if there is a lot of classes with the same name in different namespaces. Especially when they are (frequently) used in one peace of user code. Namespaces should aviod name collisions. But not only in parse/compile level, but in developer-mind-level too.</p>

          <p>This is particular problem of classes *Exception.</p>

  12. Jan 20, 2009

    <p>If you're going to interCap/camelCap everything (such as CreditCard), then I suggest you also change Alphanumeric to AlphaNumeric. Alphabetic can stay as-is, because it's not a compound word, or combination of words.</p>

    1. Jan 20, 2009

      <p><a class="external-link" href="http://en.wikipedia.org/wiki/Alphanumeric">http://en.wikipedia.org/wiki/Alphanumeric</a></p>

  13. Jan 31, 2009

    <p>I don't see a reason why to rename Ip to IpAddress</p>

  14. Feb 06, 2009

    <p>I agree with most of what's said so far. I have a few thoughts, though.</p>

    <blockquote>
    <p>Abbreviations are acceptable, so long as they are universally understood and unambiguous, and the unabbreviated word is sufficiently long. Examples include "db", "config", and "info". "Auth" is acceptable so long a disambiguation note is included in the documentation. Examples of out-of-conformance words include "str".</p></blockquote>

    <p>I'd like to chip in and say that "Auth" is ambiguous. It can be both "Authorization" or "Authentication", which are not the same.</p>

    <blockquote>
    <p>Both Logger and Log are nouns, and both make sense. I see no reason to rename in this example.</p></blockquote>

    <p>The classes in this case don't deal with being a "Logger" alone, nor do the represent a single "Log". They all deal with the concept of "Logging", hence this component should be called Logging*. While we're at it, let's move it to zend\util\logging* (see more below).</p>

    <blockquote>
    <p>Additionally, I'd like to caution against the idea that a nested, hierarchical structure is best for the framework. While it makes sense in some areas, many other areas it does not. One particular pain point of a nested hierarchy is in the documentation: how does a user find the appropriate component, browsing through the manual? For instance, many feel pagination is something that works on data sets, and thus should be under Zend_Data_Paginator - but if all that is in the TOC is "Zend_Data", and you're looking for pagination, how do you find it? In such a case, a flattened hierarchy with at most 2 - 3 levels of depth would aid tremendously.</p></blockquote>

    <p>I agree with that argument to a certain extent, which I'm afraid we've passed now. At the time of this writing, there are 86 entries (50 directories and 36 top level classes) in the standard trunk, and both numbers are expected to grow. I find it harder to find the functionality I'm after when there is no (or little) grouping of components. Many top-level namespaces/classes can be combined. For example, if I'm looking for classes related to authentication and ACL, they're both related to security. Why not use a tagging/grouping namespace for gathering those classes; zend\security\acl* and zend\security\authentication* (man I hate the backslash for separating namespaces). Also note that I wrote the namespaces in all lowercase. The reason for is to make it easier to distinguish namespaces from actual classes. I know it might be hard to swallow at first, but think about it, and consider how we will use namespaced classes when PHP 5.3/6.0 is out.</p>

    <p>It won't be hard to represent this in the documentation either, because you can show all namespaces at once. I.e. you don't have to limit the class/namespace list to only show zend\security, you can list all; zend\security, zend\security\acl, zend\security\authentication, etc. To see an example of what I mean, look to the Java API docs: <a class="external-link" href="http://java.sun.com/javase/6/docs/api/">http://java.sun.com/javase/6/docs/api/</a> (look at the "Packages" table). Granted those are API docs, but the same concept can be applied to the ZF Reference Guide. In addition to being more readble and easier to traverse manually, it will probably make searching easier too.</p>

    <blockquote>
    <p><fuzz about <sub>Abstract</sub>/<sub>Interface</sub>/*></p></blockquote>

    <p>I agree that this kind of hungarian notation shouldn't be necessary in the naming conventions, but I do like the single "I" prefix for interfaces, or even using adjective naming, such as "Runnable" or "IRunnable". The reason I like it is because you clearly see that you're dealing with an interface. And let's face it, interfaces and abstract classes are not the same thing. They are not interchangebly compatible with each other (you can't make an interface into an abstract class <ac:link><ri:page ri:content-title="or vice versa" /></ac:link> without refactoring user-land code. Abstract classes however should not have prefixes/suffixes - unless absolutely necessary to distinguish from concrete implementations - simply because other languages don't use prefixes/suffixes. In the case of abstract/concrete conflict, the abstract class should indicate that it's a "base" class (or parent class, if you like), by prefixing the class with "Base" or "Basic". The only example i can think of is Zend_View; zend\mvc\view\IView, zend\mvc\view\BasicView, zend\mvc\view\View. In most cases, however, there is no need for prefixes. Earlier I've heard people say "using a prefix makes it easier to quickly determine which classes are abstract if you browse the entire class tree", or "it's easier to search for and find all abstract classes when using prefixes". Those use cases are contrived, and don't relate to everyday coding at all. The only drawback is that you <em>might</em> try to instantiate an abstract class thinking it's a concrete class, but this will only happen once, and you'll remember it for the rest of your life.</p>

    <p>Regarding Zend_Controller_Action, it's my opinion that this class should be named zend\mvc\controller\ActionController. At least it shouldn't be called *\controller\Action, because the class itself is not an action - it contains <em>several</em> actions.</p>

    <p>(okay it might be a bit over the top with the extra "mvc" namespace i threw in there, but it's a good idea)</p>

    <blockquote>
    <p><fuzz about adapters></p></blockquote>

    <p>As this discussion shows, adapters are heavily used throughout ZF. This is why the classes should not be called just <namespace>\Adapter. The class name "Adapter" is not descriptive, as it does not imply what it is an adapter <em>for</em>. Is it a database adapter, or is it a translation storage adapter? Just say so in the class name, and it will be easier to read and immediately understand what it is. It also avoids confusion if you ever were to use two different type of adapters in the same class.</p>

    <p>Last, but not least, I'd like to propose a totally new namespace: zend\util\. This namespace could in fact contain logging, validators, filters, compression stuff, and more.</p>

    <p>Conclusion:<br />
    +1 from me, but I want to take it to the next level and make a narrow and deep codebase.</p>

  15. Feb 23, 2009

    <p>One thing that's always bothered me about the PEAR naming convention (no fault of its own, just the application of it) is that it promotes completely useless class names. For example lets say I was creating a Zend_Form instance for creating an event:<br />
    I would put this in the "namespace" My_Form_Event. Now that PHP will have namespace support this becomes \My\Form\Event. The problem, however, is that My_Form is not the part of the name of the class...it's just the "namespace". The class name is "Event", and after importing the namespace, you would be doing something like this: $form = new Event(). This is totally unclear. It would be much better to call this class My_Form_EventForm or in 5.3 \My\Form\EventForm.</p>

    <p>If this were Java, the class would be something like org.my.form.EventForm, not org.my.form.Event.</p>

    <p>I think a similar thing should be done with the Zend classes. For example \Zend\Filter\Alnum. It does not make sense to instantiate an new Alnum()...what is an Alnum anyway? new AlnumFilter would make a lot more sense.</p>

    <p>Also, something has to be done with things like Zend_Search_Lucene_Index_SegmentWriter_DocumentWriter...<br />
    I believe (someone can correct me if i'm wrong) that in Java APIs packages rarely run more than two or three levels deep. I think a class like this should be in the \Zend\Search\Lucene\Index Namespace with the class name being something like DocumentSegmentWriter.</p>

    1. Feb 23, 2009

      <p>I can see your point... but when using PHP namespaces, you are either specifically in a given namespace, or importing another namespace into the current scope. When you import namespaces, you still have to use the alias when referring to classes:</p>
      <ac:macro ac:name="code"><ac:plain-text-body><![CDATA[
      import Zend\Filter;
      import Zend\Validate;

      $f = new Filter\Alnum();
      $v = new Validate\Alnum();
      ]]></ac:plain-text-body></ac:macro>

      <p>Seems pretty clear what you're creating here – a filter and a validator.</p>

      <p>Now, let's say you're using the My\Form namespace:</p>
      <ac:macro ac:name="code"><ac:plain-text-body><![CDATA[
      namespace My\Form;

      class Event
      {
      }
      ]]></ac:plain-text-body></ac:macro>

      <p>In this particular case, you're creating a new class, Event. But you're in the My\Form namespace – so it should, again, be contextually evident what type of class it is.</p>

      <p>I think the difference here is that ZF is acting as a component library in this regard, and the namespace is actually indicative of the context of the classes it contains.</p>

      <p>I can definitely see benefit to the idea of having the namespaces be no more than a few levels deep, and think it warrants discussion.</p>

    2. Feb 23, 2009

      <p>I absolutely agree with your opinion (see <a class="external-link" href="http://weierophinney.net/matthew/archives/181-Migrating-OOP-Libraries-and-Frameworks-to-PHP-5.3.html#c22769">http://weierophinney.net/matthew/archives/181-Migrating-OOP-Libraries-and-Frameworks-to-PHP-5.3.html#c22769</a>). Class names should be understandable nouns. As they are in Java or .Net (<a class="external-link" href="http://msdn.microsoft.com/en-us/library/system.net.aspx">http://msdn.microsoft.com/en-us/library/system.net.aspx</a>)</p>

  16. Jul 16, 2009

    <p>Yes, away with "Abstract" and "Interface" suffixes please. They have always bothered me tbh. </p>

    <p>As for Zend_View, it is just not aptly named. As are many of these abstract classes. For example, Zend_CodeGenerator_Php_Abstract. What does that tell me? That it is an abstract class class in the Zend_CodeGenerator_Php package, but that is not what I want to know... Zend_CodeGenerator_Php_Entity would be better.</p>

    1. Jul 16, 2009

      <p>In conjunction with a number of other frameworks, we have decided to retain the "Abstract" and "Interface" suffixes on abstract classes and interfaces, though with one important change: the leading underscore will not only not be required, it will be forbidden.</p>

      <p>The rationale for retaining them hinges on several important things, primarily in regards to non-native English speakers. First, it provides a quick visual cue when scanning the directory or class tree as to which classes are interfaces, and which may provide base functionality to extend. Second, for non-native English speakers, coming up with good, abstract names can be quite difficult, and in some cases non-obvious: e.g., is a person interface "Personable" (not necessarily, but they may be Humanoid). Third, predictability: you know both when developing and using the framework what to name classes.</p>

      <p>Yes, I would have preferred dropping the Hungarian Notation, but I think it's justified.</p>

  17. Sep 03, 2009

    <p>Something that's been bugging me while attempting to set up a modular directory structure:</p>

    <p> If you add a resource type to Zend_Loader_Autoloader_Resource, you are mapping a directory (e.g., "models") to a class prefix (e.g., "Module_Model_").</p>

    <p>But controllers, which seem intended to act like "resources" (i.e., live in a "controllers" directory rather than a "Controller_" namespace directory), have a suffix rather than a prefix (e.g., "Module_DefaultController" rather than "Module_Controller_Default").</p>

    <p> This seems inconsistent.  On the one hand, it makes sense to support suffixes in the resource autoloader, especially with namespaces.  "\Module\Model\User" implies that the thing IS A "User", when really it is a "User Model" or "User Table", which would be better indicated by "\Module\UserModel" or even "\Module\Model\UserModel".  On the other hand, suffixes in general disrupt a narrow & deep namespace philosophy, and smell of Hungarian Notation.</p>

    <p> Anyway, I don't have a solution, but this seems worth talking about.  Not exactly the issue at hand, since it does not affect the naming of Zend classes themselves, so if this belongs somewhere else, let me know (I'm new around here).</p>

    <p>Related: Shouldn't Zend_Controller_Action be Zend_ControllerAbstract?  A controller IS A Controller, not an Action.</p>

    1. Sep 03, 2009

      <p>Zend_Controller predates most of the framework by a fair bit; people were using Zend_Controller_Action before Zend_Db ever existed. As such the conventions for naming controllers using a suffix is pretty set in stone right now, and changing the schema even in 2.0 (when BC breaks are allowed) would be a major migration issue. However, changes we will be making in 2.0 will make it easier to facilitate alternate naming conventions should you so desire. </p>

      <p>As for Zend_Controller_Action naming – there are two points you're overlooking:</p>
      <ul>
      <li>First, we have two types of controllers in ZF: the <em>front</em> controller and <em>action</em> controllers (which are dispatched by the front controller); there needs to be a differentiation in names. The controllers developers write are <em>action</em> controllers, and hence the name.</li>
      <li>Second, until recent revisions to the naming conventions, we had no rule for naming abstract classes; there was no imperative to include the keyword "Abstract" in their names. (I actually find it funny that you find this form of Hungarian Notation okay, but not with controllers <ac:emoticon ac:name="wink" /></li>
      </ul>

      1. Sep 05, 2009

        <p>Well, you had mentioned above that it had already been decided abstract classes would contain the "Abstract" suffix, so I was just trying to fall in line <ac:emoticon ac:name="smile" />. The other point makes sense; for some reason in my head the "Front Controller" is the "Dispatcher" and the "Action Controller" is just the "Controller," probably due to experience with other (lesser) frameworks.</p>

        <p>"However, changes we will be making in 2.0 will make it easier to facilitate alternate naming conventions should you so desire."</p>

        <p>That is good to hear, and likely will address my concerns.</p>

        <p>Thanks!</p>

  18. Dec 29, 2009

    <p>I definitely give this proposal a huge +1. I'll keep looking through it and adding input, but for right now, I will say that I don't think the credit card validator should change to Zend\Validator\CreditCard. That particular validator does not determine the validity of a credit card itself – it doesn't check against a payment gateway to see if a credit card actually exists. All it does is check to make sure that the specific credit card <em>number</em> is of a valid format.</p>

    <p>I think Zend\Validator\CreditCardNumber is a more accurate name for what the validator does.</p>

    1. Dec 30, 2009

      <p>You should take a better look.<br />
      Zend_Validate_CreditCard DOES also allow to check against payment gateways.</p>

      1. Dec 30, 2009

        <p>I apologize; I did not thoroughly review the changes that will be released with 1.10. Consider my objection revoked.</p>

  19. Mar 23, 2010

    <p>What about lowercasing all namespaces java like to make it easier to seperate them from class names?<br />
    I think it it would support readability of code.</p>

    <p>So people would know that \zend\db\adapter\pdo\Mysql is the class Mysql and \zend\db\adapter\pdo\mysql is the namespace mysql.</p>

    <p>I would also suggest to keep the underscore as first character for public/private members and methods.</p>

    1. Mar 23, 2010

      <p>This was originally discussed in the PHP Framework Interoperability Group meeting, and later in our on-list discussions, and rejected for a variety of reasons. Some of these include:</p>
      <ul>
      <li>It's typically bad-form to have a namespace and a class of the same name, even when they differ in case. It's too easy to misinterpret which is which, and to introduce errors simply through typos.</li>
      <li>Difficulty migrating from existing Vendor_Prefixed code. You no longer get a 1:1 map from the original code to the final code. This will be true both for migrating ZF code, as well as migrating end-user code to consume a namespaced ZF as well as to utilize namespaces itself.</li>
      <li>The namespace separator makes it trivially easy to determine what is the namespace, and what is the class name – everything preceding the final namespace separator is the namespace.</li>
      <li>MixedCase allows for more natural naming or for names that are CompoundNames. Were we to go all lowercase, this would require introducing underscores or dots for components with such names.<br />
      As such, we will continue using MixedCase in namespace names.</li>
      </ul>

      1. Mar 23, 2010

        <p>Hi Matthew,</p>

        <p>thanks for your response. I did not know that you've already considered and discussed this.<br />
        From a migration poit of view it's also helpful to keep the MixedCase format for namespaces and makes it easier to switch from 1.x to 2.x in existing applications. I completely agree, just wanted to throw in the idea. <ac:emoticon ac:name="wink" /></p>

        <p>Is there a preview release or svn where I could take a look on ZF 2?<br />
        I am currently using 1.10 and PHP 5.3 and like to switch to ZF2 when it is released.</p>

        <p>What about the declare(ENCODING = charset) statement? In the FLOW3 releases I saw that they're using it in every file - too much overhead in my opinion. In my codes I follow the rule everything is UTF-8 and only differend charsets must specify declare(ENCODING = charset). I guess ZF2 would be UTF-8 and there will be no declare statements at all? Has this been mentoined or discussed yet?</p>

        1. Mar 24, 2010

          <p>We just started work on ZF2 a few weeks ago, and are still working on what we call "foundation" tasks:</p>
          <ul>
          <li>Stripping require_once calls (done)</li>
          <li>Converting to namespaces (in process; finalizing a tool to help automate the process)</li>
          <li>Refactoring exception support</li>
          <li>Removing deprecated components<br />
          Once the above are done, we'll likely provide a snapshot for folks to get a feel for the "flavor" of ZF. However, the work will still be some ways from being completed, as we then will start work on refactoring the various plugin systems to be consistent across the framework, as well as working on various rewrites (with the help of the community). </li>
          </ul>

          <p>There will be periodic updates on the status, but I don't expect ZF2 to be usable in any meaningful way for at last a couple more months.</p>

          <p>Regarding your encoding statement, the assumption is and will continue to be that the files are UTF-8 encoded.</p>

  20. Feb 05, 2011

    <p>Archiving this proposal, feel free to recover it when you want to work on it again. For more details see <a href="http://framework.zend.com/wiki/display/ZFDEV/Archiving+of+abandoned+proposals+(Feb+5+2011)">this email</a>.</p>