-- Kevin Schroeder <[EMAIL PROTECTED]> wrote
(on Thursday, 07 February 2008, 12:34 PM -0600):
> > > example, in Zend_Cache_Core we currently have:
> >
> > In the Zend_Form components, I followed this rule
> >
> > * Any set*() method is available as a config option and is normalized
> > to ucfirst():
> >
> > setAction() => action or Action
> > setMethod() => method or Method
> > setLegend() => legend or Legend
> >
> > * All methods are documented in the end-user docs, and the above rule
> > is explained (along with any exceptions)
>
> That may be the case for Zend_Form, but it is not the case for
> Zend_Cache_Core (and subsequent classes), or Zend_Mail_Transport_Smtp or
> Zend_Auth_Adapter_Http to pick a few at random. With those you need to look
> at the Framework code to find out what the options are. While something
> like Zend_Auth_Adapter_Http has them documented in the constructor you still
> need to look at the docs for the constructor to find out what the options
> are. By giving an IDE class constants that you use as configuration keys
> you don't have to look around to find out what the keys are.
No arguments there -- I was simply showing another possibility, as
implemented in a newer component. I'm well aware that not all components
follow these "rules" or conventions. :-)
> > However, that does *not* address IDE completion, as you note. However,
> > you could potentially eschew configuration via array in such a case and
> > simply use the accessors (which is what setConfig() and setOptions() end
> > up doing anyways).
> >
> > <snip - Zend_Config example from current code>
> >
> > > Would have this added
> > >
> > > class Zend_Cache_Core
> > > {
> > > /**
> > > * Sets the lifetime of the cache
> > > */
> > > const CONFIG_LIFETIME = 'lifetime';
> > > const CONFIG_CACHING = 'caching;
> > > const CONFIG_LOGGING = 'logging';
> >
> > No. no. no. Configuration constants should be easy to use, and their
>
> This isn't easy and doesn't correspond to existing keys?
By not having the constant value corresponding to the constant name,
it's more difficult to guess what the key should be called. And what if
there are constants that use the same suffix -- e.g. CORE_LIFETIME; how
do you refer to that?
With configuration options, you cannot assume that the only place you
will be referencing them is in PHP code, and hence, IDEs -- people may
be building config files, and will need to know the keys. If they are
not easily predictable from the constant names, they're going to have
the same problems you outlined already.
For instance, I use VIM, and utilize ctags extensively, which gives me
tab completion for most PHP datatypes -- classes, methods, constants,
class members, etc. I might be able to find the constant name easily
with tab completion, which would then let me write my config file. So, I
might receive Zend_Config::CONFIG_LIFETIME from completion; the question
is, how do I then translate that to a config key? My initial guesses
would be either 'CONFIG_LIFETIME' or 'configLifetime' -- but I'd never
expect it to be simply 'lifetime'.
So, the change I'm suggesting is two-fold:
* Adding the constants
* Standardizing the relationship between constant names and values
That way I don't even have to guess -- I know *exactly* what the config
key would then be, based on the constants available.
> $options = array(
> Zend_Cache_Core::CONFIG_LIFETIME => 60
> );
>
> I'm also not sure how this is a BC break because the constants would only be
> representing the existing configuration keys.
The BC break I referred to is if we added new constants with values that
differ from existing config keys -- which could potentially happen if we
need to namespace config constants from other class constants, as noted
above.
> It would not change them. It would merely expose them in a manner
> that makes it easy for an IDE to discover them for people who are not
> intimately familiar with ZF's source code.
>
> > names should correspond pretty much one-to-one to what they represent.
> > We need to standardize this; in some classes, we have the constant equal
> > to its literal string (e.g., Zend_View_Helper placeholders, Zend_Form),
> > in others we have it equal to a camel-cased version of itself (e.g.,
> > Zend_Validate, Zend_Filter). Whichever way we choose, it should be
> > consistent between all classes -- though this could potentially be a BC
> > break, and should be reserved for a major revision.
> >
> > Another thing to note, though: in many cases (Zend_Form is one), we
> > don't use constants at this point, and there are *so* many configuration
> > keys that creating the constants is going to be a pretty time consuming
> > and painful task -- and a moving target.
>
>
> I agree that there would be places where it may not be worth it, but in
> places where it could be it would only be a moving target if the
> configuration options themselves change.
Or new ones are added. :-)
> > Otherwise, I agree with you -- this *would* improve IDE awareness as
> > well as provide nice documentation of configurable items for developers.
> > :-)
--
Matthew Weier O'Phinney
PHP Developer | [EMAIL PROTECTED]
Zend - The PHP Company | http://www.zend.com/
