Proposal for Standards & Interface Repository

[jayboots]

Here in a few hours I'll have an RC Last week was hectic for me followed by five days out of town. I'm just getting caught up on this thread.

Jay - regarding unset(), I see your points, but I think we're going down the right path by not including it... at least at first. I justify this by asking a simple question: will the interface absolutely not work if we don't included __unset()? My answer is no, because all Keyed needs to do is be able to have values. To do that, you need to be able to set(), get(), and check to see if something isset(). unset() is an extra. In your use, it would be a necessary extra, but in a more broad sense, I believe it's a plain extra. As far as this being a "patch" if we add it in later, I don't think so. As Marcus has said here and many times before, we can add more later if we need it, it's harder to pull it out.

Good stuff, Travis! To be honest (and FWIW!), I'm much appeased with the interface being called Keyed as lastcraft suggested rather than Properties. I think lastcraft was right to question the naming: it certainly helps change my view on the direction of the interface; however, I still think it should be prefixed by the project name.

As a personal aside, despite the fact that I agree that it is better to start small and grow, I am a little leary of the blanket "it is harder to pull it out" metaphor. After all, we are still in the very start of the design stage and I would expect that no one is seriously going to depend on any of this work for quite some time. At any rate, I don't think it should be used as a stick to beat away ideas or discussions. I am not suggesting that is the case, but I can imagine it happening as progress mounts and we get into even more complicated and challenging areas.

Best regards to all.

[jayboots]

A case could be made for that, however, as opensir grows it will need a uniform way for files to locate other opensir files internally so it can satisfy dependencies. One big thing I have against PEAR is it's requirement that code be placed inside the include_path. To keep from requiring that, we have to define a constant and we'll need one central location to store it - thus opensir.library.php.

I named it library, as it provides an entry point for the library from the outside world. As the docs mention, it's entirely optional. You're more than welcome to call "include '/path/to/Keyed.interface.php';", which will go ahead and call the file to insure it knows how to communicate internally.

I don't really want to advance this part of the discussion too much at this point, but can we agree to rather rely on autoloading techniques? We can use spl_autoload_register() [which will one day allow for methods but currently only allows for functions] so as to not step on __autoload(). Even if we can't define this now, can we agree not to rely on a path constant as a long-term solution?

[JaredWhite]

Hey folks, I hope I'm not butting in, but I breezed through some of the posts here recently and wanted to say that I really like the idea of having a standard PHP interface repository. The PHP project I'm currently working on will be used by the public (developers, that is), so I'm using a lot of interfaces so my classes are loosely coupled. Some of these interfaces are basic and could easily be "standardized" based on the functionality.

Here's one I'd like to tackle right away: value filtering. I think it'd be great if there were a couple of interfaces to define how to find and execute filters on values (values being either native PHP types or value objects). Here's my idea of what they are:

1. FilterRegistry -- you could request a filter based on name, and you could get a list of filters that would apply to the supplied value. FilterRegistry is a singleton.
2. Filter -- a filter would take an input value and return an output value. In addition, it would have a way to specify filter options (either ahead of time or as part of the filtering method call itself). (Implementation note: it would raise some kind of exception if the value supplied is not supported by the filter.)

What do you think? Maybe if people like the idea we should talk in a different thread? I don't want to interrupt you folks' thought processes on the Keyed/Properties/Whatever interface (good stuff!).

Jared

[arborint]

A case could be made for that, however, as opensir grows it will need a uniform way for files to locate other opensir files internally so it can satisfy dependencies.

I think YAGNI applies here. You have stated a potential future need, but not a present need.

One big thing I have against PEAR is it's requirement that code be placed inside the include_path. To keep from requiring that, we have to define a constant and we'll need one central location to store it - thus opensir.library.php.

I agree about the inlcude_path, but you are simply replacing something you don't like with something you do, not meeting a need.

I named it library, as it provides an entry point for the library from the outside world. As the docs mention, it's entirely optional. You're more than welcome to call "include '/path/to/Keyed.interface.php';", which will go ahead and call the file to insure it knows how to communicate internally.

I have to agree with kyberfabrikken. I don't see a problem with having opensir.library.php or jayboots autoloader available for people to choose. You don't need to include opensir.library.php in Keyed.interface.php to use it, but by putting it in you are forcing people to use it. Remove it for now and let it be shown to be needed.

[dbevfat]

About the naming:

I feel that Keyed is a name that more suits an object that reads/writes values in (key, value) pairs:
$obj->get('key')

And name Properties feel more like accessing the object's properties:
$obj->property

It's that an object has a property, but holds a value for a key. Which might just as well mean the same thing. Maybe I'm totally off, I'm not a native English speaker, but it feels so.

Just thought I'd mention it.

Regards

PS. Still not happy with __get/__set, because I still think using any magical overloading should be considered as an implementation detail. An interface user should have an option to use magical overloading or not. I do believe I have a point here.

[arborint]

PS. Still not happy with __get/__set, because I still think using any magical overloading should be considered as an implementation detail. An interface user should have an option to use magical overloading or not. I do believe I have a point here.

I agree. I have not heard anything but esoteric reasons to use __get()/__set() rather than get()/set(). And you can implement __get()/__set() by calling get()/set(). So:

class KeyedAssignable implements Keyed {
function __get($key) {
    return self::get($key);
}

function __set($key, $value) {
    self::set($key, $value);
}
} 

I can think of several reasons not to use __get()/__set(), the main one being that it does not allowed you to intercept all properties you want to set, only those that are not defined. This leads to propertyless classes that cannot be inspected.

[datune]

I really really don't see the point of overloading in an interface like this one.
As said before, this is an implementation detail.

[lastcraft]

Hi.

Another problem with overload in PHP4.4 is that it makes the current crop of reference problems ten times worse. Looks like the reference "fixes" have not caught up with __get() and __set() usage.

yours, Marcus

[arborint]

So what about the very basic:

<?php
/**
 * This file contains {@link Keyed}. 
 *
 * @package OpenSIR
 */

/**
 * Provides an interface for storing and retrieving any number of "Keyed" 
 * properties 
 *
 * This interfaces is meant to be used by any object that should expose values
 * to match a given key.  
 *
 * @package OpenSIR
 * @author Travis Swicegood <development@domain51.com>
 * @author Collectively authored via 
 *     {@link http://www.sitepoint.com/forums/showthread.php?t=298611}.
 * @license http://www.gnu.org/copyleft/lesser.html LGPL
 */
interface Keyed
{
    /**
     * Retrieves a mixed value from this container by its given <i>$key</i>.
     *
     * If <i>exists($key) == FALSE</i> the value of NULL is returned. 
     *
     * @param string
     * @return mixed
     */
    public function get($key);
    
    
    /**
     * Sets the property of a given <i>$key</i> to a given <i>$value</i>.
     *
     * @param string
     * @param mixed
     */
    public function set($key, $value);
    
    
    /**
     * Returns <i>TRUE</i> if a given property is set, <i>FALSE</i> otherwise.
     *
     * @param string
     * @return boolean
     */
    public function exists($key);   // or hasKey() or keyExists() ??
}
?>

[Travis S]

Now I think I know how some of the PEAR guys feels...

Ok - if I remember correctly, I originally stated that I liked the idea of get()/set() versus __get()/__set() and having two interfaces such as Keyed and MagicalKeyed. If I remember correctly, at the time the concensus was using __get()/__set() seemed to make the most sense as it took advantage of one of the new PHP features to make things easier. There are still a hundred different ways to store the values once you get to __set() - defining that you must use __set() is no more of an implementation detail imo than defining set().

Marcus - as far as PHP 4.x, this isn't being considered for use in PHP 4 other than directly calling __get() instead of using the overloading. I've heard of nothing but problems with that whole feature.

Re: opensir.library.php - you're right to an extent arborint. We're not going to need it... yet. I'm fine with pull it out of the next release I tag until we get to the point we need it like I've done with Exceptions

[kyberfabrikken]

defining that you must use __set() is no more of an implementation detail imo than defining set()

Good point.

Marcus - as far as PHP 4.x, this isn't being considered for use in PHP 4 other than directly calling __get() instead of using the overloading. I've heard of nothing but problems with that whole feature.

Isn't that an argument for going get() rather than __get() ?

Re: opensir.library.php - you're right to an extent arborint. We're not going to need it... yet. I'm fine with pull it out of the next release I tag until we get to the point we need it like I've done with Exceptions

+1 vote there.

[33degrees]

Why not simply implement both get()/set() and _get()/_set() ?

[Ezku]

So what about the very basic:

    public function exists($key);   // or hasKey() or keyExists() ?? 

I side with has($key): If $set has $key, then... Plus it's shorter.

[arborint]

Now I think I know how some of the PEAR guys feels...

Actully threads like this make me feel good. It is my experience that when these guys care about something it is important.

Ok - if I remember correctly, I originally stated that I liked the idea of get()/set() versus __get()/__set() and having two interfaces such as Keyed and MagicalKeyed.

If we have circled it is time for a Scrum.

If I remember correctly, at the time the concensus was using __get()/__set() seemed to make the most sense as it took advantage of one of the new PHP features to make things easier.

No there wasn't a concensus and there still doesn't seem to be one. As I recall, Selkirk was the one strongly for __get()/__set().

There are still a hundred different ways to store the values once you get to __set() - defining that you must use __set() is no more of an implementation detail imo than defining set().

Actually, in this case it is THE implementation detail.

[arborint]

I side with has($key): If $set has $key, then... Plus it's shorter.

I like names best when they are decided. Perhaps we should start a poll? :'(

[Selkirk]

-> is the standard property access notation for PHP. When PHP gets native support for accessor methods, they will work with ->. Notice that I say when. I'm optimistic about this one, but forward compatibility guessing is dicey at best.

Some implementation experiments have me thinking that it might be a bad idea to allow direct calls of the magic methods. Ala $obj->__get(). It may be best to leave it to the engine to make these calls.

Not to mention that the benefit of being lightweight enough not to have to declare a specific interface or parent class.

I think its best to define how the client might expect to access the properties of the object, rather than to define how the object might like its clients to access it. I hope that the difference in perspective is clear.

I'm pretty much at a standstill on this. I need to do tons of research and try out implementations before I can comment much further, but don't have the time right now.

[Selkirk]

Here is one direction for research.

zend_object_handler.c has a function that looks like this:

zval *zend_std_read_property(zval *object, zval *member, int type TSRMLS_DC)
{
    zend_object *zobj;
    zval *tmp_member = NULL;
    zval **retval;
    zval *rv = NULL;
    zend_property_info *property_info;
    int silent;
    zend_bool use_get;

    silent = (type == BP_VAR_IS);
    zobj = Z_OBJ_P(object);
    use_get = (zobj->ce->__get && !zobj->in_get);

...

    /* make zend_get_property_info silent if we have getter - we may want to use it */
    property_info = zend_get_property_info(zobj->ce, member, use_get TSRMLS_CC);

    if (!property_info || zend_hash_quick_find(zobj->properties, property_info->name, property_info->name_length+1, property_info->h, (void **) &retval) == FAILURE) {
        if (use_get) {
            /* have getter - try with it! */
            zobj->in_get = 1; /* prevent circular getting */
            rv = zend_std_call_getter(object, member TSRMLS_CC);
            zobj->in_get = 0;

            if (rv) {
                retval = &rv;
            } else {
                retval = &EG(uninitialized_zval_ptr);    
            }
        } else {
            if (!silent) {
                zend_error(E_NOTICE,"Undefined property:  %s::$%s", zobj->ce->name, Z_STRVAL_P(member));
            }
            retval = &EG(uninitialized_zval_ptr);
        }
    }
...
    return *retval;
} 

Not hard to see where the re-entry problem comes from, huh? There is also a structure like this:

typedef struct _zend_property_info {
    zend_uint flags;
    char *name;
    int name_length;
    ulong h;
    char *doc_comment;
    int doc_comment_len;
} zend_property_info; 

Now lets imagine adding two more members to this structure:

char *getter;
char *setter; 

And modifying the compiler so that the following PHP class was legal and the proper zend_property_info structures were created:

class myClass {
    private $myX;
    public property $x read getX write setX;
    private function getX() {
        return $this->myX;
    }
    private function setX($x) {
        $this->myX = $x;
    }
} 

Notice the new property keyword. The syntax is unwieldy. Perhaps there are better options?

My question is what does the logic in zend_std_read_property have to look like to support this? Some pseudo code like:

if (!property_info) {
    // call __get
} else if (property_info->getter) {
    // call getter method
} else {
    // call zend_hash_quick_find
        // if not found call __get
} 

Perhaps I'm naive, but i'm not really seeing any big performance barriers here in an extra boolean check?

Am I the only one who thinks that native accessor methods would be a good thing?

Does this help explain why I favor ->?

[arborint]

It's a little hard to know how to respond to this, but I think it needs responding to. I will try to stretch my toes and see if I can touch the ground.

-> is the standard property access notation for PHP. When PHP gets native support for accessor methods, they will work with ->. Notice that I say when. I'm optimistic about this one, but forward compatibility guessing is dicey at best.

I understand that -> is the standard property access notation, but the question is: are we trying to extend POPOs (entschuldigung mein Deutsch ) or create a standard interface for simple keyed containers. As objects are already containers of a sort, I don't think it makes sense to keep returning to them for keyed containers. I think I may want my classes that implement the Keyed interface to still have regular properties and also have separate keyed access. I don't think I want to loose anything; I want to gain a simple container standard.

Some implementation experiments have me thinking that it might be a bad idea to allow direct calls of the magic methods. Ala $obj->__get(). It may be best to leave it to the engine to make these calls.

Calling $obj->__get() directly just sounds like a recipe for trouble down the road.

Not to mention that the benefit of being lightweight enough not to have to declare a specific interface or parent class.

Objects are currently lightweight enough for this. I really get the sense that you are looking for an extended standard to object behavior and not a container interface.

I think its best to define how the client might expect to access the properties of the object, rather than to define how the object might like its clients to access it. I hope that the difference in perspective is clear.

We have had many examples and I think many have looked at this from that perspective. Lastcraft kicked it off and many other examples followed.

I'm pretty much at a standstill on this. I need to do tons of research and try out implementations before I can comment much further, but don't have the time right now.

You are searching for expanded object behavior for PHP5. That's fine. But that is very different that a minimal keyed container interface for PHP5 that is also useful PHP4.

I would suggest that we split the discussions of an expanded object behavior for PHP5 and a minimal keyed container, because that is what is causing the circling here. Then those interested in expanded object behavior for PHP5 can see if it is possible and those interested a minimal keyed container can see if it is worthwhile.

[jayboots]

As objects are already containers of a sort, I don't think it makes sense to keep returning to them for keyed containers. I think I may want my classes that implement the Keyed interface to still have regular properties and also have separate keyed access. I don't think I want to loose anything; I want to gain a simple container standard.

Personally I find this idea very java like which wants everything to be accessible via a method call. It is not the only way to see this problem. Furthermore, I don't think it is will be good practice to mix access styles. I'm certainly not convinced as to its necessity.

You are searching for expanded object behavior for PHP5. That's fine. But that is very different that a minimal keyed container interface for PHP5 that is also useful PHP4.

I think it is a delusion to think that PHP4 can be supported -- it doesn't even support interfaces and IMO it is not a suitable yardstick to gauge which tools ought be employed for this sort of standards work.

[arborint]

Personally I find this idea very java like which wants everything to be accessible via a method call. It is not the only way to see this problem. Furthermore, I don't think it is will be good practice to mix access styles. I'm certainly not convinced as to its necessity.

Well if you don't "mix access styles" then the methods within a class would be forced to access properties through __get()/__set() as well. I'm not sure what good practice is, or what java like is in this case, but I don't want to limit myself if I don't need to.

I think it is a delusion to think that PHP4 can be supported -- it doesn't even support interfaces and IMO it is not a suitable yardstick to gauge which tools ought be employed for this sort of standards work.

Just because PHP4 does not have interfaces does not mean that you could not implement classes adhering to the standard. That's most of the battle. The real reason you need "implements Keyed" is if something like a DI system needs the interface for internal reasons.

[Dr Livingston]

I cannot see any benifit of supporting PHP4 and it has nothing to do with Interfaces. In fact there would be several factors to consider first, such as that PHP4 uses references for example. How does that effect the design... In regards for example, if someone uses a PHP4 library with PHP5, based on what this discussion provides?

That is a BC issue which could (proberly will actually) cloud the wider discussion later. Also consider just how much of use will you get from a PHP4 implementation in regards to how long PHP4 will be continued to be supported?

[datune]

Erm..you guys, stop mixing up DESIGN issues with IMPLEMENTATION issues. An interface does not enforce any implementation details or rules, all it requires is for you to IMPLEMENT the methods layed out in the interface.

I think the interface posted by arborint (here) perfectly demonstrates how NOT to design an interface (comment wise that is).

Otherwise it is just fine. Personally I vote for the name Keyed and to use the methods as outlined in that very post. I also think using exists() serves the most general purpose.

For example one possible usage of Keyed might look like (this example is only for demonstration purposes, I'm not saying this is how it should be implemented!)

<?php 
interface IKeyed 
{ 
    public function get($key);            
    public function set($key, $value);            
    public function exists($key); 
} 
class Keyed implements IKeyed
{
protected $values = array();
 
function __construct($key, $value)
{
$this->set($key, $value);
}
 
function get($key)
{
return $this->values[$key];     
}
 
function set($key, $value)
{
$this->values[$key] = $value;
}
 
function exists($key)
{
return array_key_exists($key, $this->values);
}
}
 
class Tag extends Keyed
{
protected $name;
protected $value;
 
function __construct($name, $value)
{
$this->set('name', $name);
$this->set('value', $value); 
}
 
function render()
{
return $this->get('name') . '="' 
    . $this->get('value') . '"';
}
}
$tag = new Tag('name', 'datune');
if($tag->exists('name')) echo $tag->render();
?>

Now ask yourself, what makes more sense:

To see if a TAG exists or if it has a key (?).

Now let's exchange every single instance of the word Tag with for example a button, or an image list, or a ini like config file etc...

$button->exists('search');
$imageList->exists('smile');
$config->exists('dbName');

Here I think looking at possible implementations helps to find the "most likely best suited" method names.

But as you can see, when DESIGNING an INTERFACE, there is no need to think about WHAT a certain method might return and what not, or whether it should return false or null.

I believe what needs to be focused on is to agree upon a common interface, which will allow us individuals to go nuts and implement a version of Keyed the way we think it should be, and then allows users(=other developers) to pick out of a repository whichever version they prefer.

If there is one thing I would love to see happen within this community then it would be to agree upon a fixed set of interfaces and truly push that forward and try to create a standard. (for starters a standard within this community, don't set out to be the next great thing trying to show pear how it should be, instead start simple, stay simple!)

[arborint]

OK, so we have:

1 vote for changing PHP's internals
1 vote for get/set/has
1 votes for get/set/exists

Well it's a start.

[ahundiak]

Erm..you guys, stop mixing up DESIGN issues with IMPLEMENTATION issues. An interface does not enforce any implementation details or rules, all it requires is for you to IMPLEMENT the methods layed out in the interface.

I think the interface posted by arborint (here) perfectly demonstrates how NOT to design an interface (comment wise that is).
...
But as you can see, when DESIGNING an INTERFACE, there is no need to think about WHAT a certain method might return and what not, or whether it should return false or null.

mx2k has posted similiar opinions (posts #196,#199) suggesting that interfaces should not deal with exceptions/triggering errors or return values.

I'm wondering what the rest of the community thinks? Maybe we need to decide just what a PHP interface should be?

For myself, I just don't understand why you would not want to define boundary conditions. When I do:
$x = $request->get('something');
I really need to know what will happen if 'something' does not exist. Exception? ErrorTrigger? NULL?

The notion that each implementor should decide seem to eliminate any possibility of sharing classes based on interface support.

I actually reread the entire thread trying to figure out what happened to exceptions. There are over 30 posts in which exceptions were pretty much assumed. And then they went away.

It just seems to me that interfaces are contracts and not specifying what a method is supposed to do kind of makes the contract worthless.

[datune]

@ahundiak

Maybe we need to decide just what a PHP interface should be

That's not something that can be decided upon, an interface is an interface is an interface.

It seems that you are not comfortable with the difference of an interface and it's actual body (implementation).

Here, let me help by quoting Bruce from TIJ:

An interface says, “This is what all classes that implement this particular interface will look like.” Thus, any code that uses a particular interface knows what methods might be called for that interface, and that’s all. So the interface is used to establish a “protocol” between classes. (Some object-oriented programming languages have a keyword called protocol to do the same thing.)

AND

To make a class that conforms to a particular interface (or group of interfaces), use the implements keyword, which says, “The interface is what it looks like, but now I’m going to say how it works.”

So you see, the key here is that with a uniform interface library developers can create different versions of a class Keyed, which will also be(or not) behave differently. What you want is a class Keyed which always behaves the same but uses different algorithms to achieve that goal.

For example, you ALWAYS expect get() to return false, HOW it computes it to be false you don't care about. That's what you are looking for, which has nothing to do with designing interfaces.

This hopefully clears things up