Proposal for Standards & Interface Repository

[arborint]

All of these are possible, but the last I'm against. Changing the behavior of an object via magic methods is ok, but changing the behavior of an internal type leads down a road that I think has a lot of boogie men waying to jump out and beat you up. Seriously, what's next, IntObject in which you can treat an object as an int? You can already sort of do with __toString() and echo'able objects, but I still don't know if its right.

I agree with being against using an object as some other type. It seems like a conversion method would be clearer in the cases that it is needed. But since I don't have that need perhaps people looking for that capablity can explain where it is necessary.

All this said, I would be for 1 or 3. I like 1 because it is easily backwards compatible. It's only problem is that you loose the ability do $properties->array[3]->value->names[4].

Well us path guys would say $properties->get('array/3/value/names/4') but then we get in REST/Xpath arguments.

This example brings up another point: should it be assumed that if an array is set within a Properties value that it is itself a nested Properties?

I think we want to specify an interface, not an implementation. If what this thing does is give and get things from an object using Keys then it doesn't matter what the things are.

Ok - where are we on name? Marcus' Keyed is sort of growing on me. Nice, short, and simply answers "this Container is Keyed" - "this Container is Properties" makes since too, but Keyed does describe exactly what you should expect.

I have no opinion as to the diction, but "Key" and "Keyed" are short and uncommon which are good things. The "Keyed" naming is growing on me with the notion of "I'm using a Keyed interface for my Car class"

One quick note... I do like the idea of having a series of classes that define generic behaviors, such as URL, URI, File, Directory, SymLink, etc., etc. At that point, we're starting to move to direct competition with PEAR. Maybe that's a good thing, but that's not what I had in mind with this.

I'm not anti-PEAR, but I also don't use it. So my interest in on creating something that I will use and that is probably a common feeling.

If that's the general concensus, maybe we do need to relook at what we're doing here and start with a code repository of basic objects. I would still like to see them done as interfaces first, then everybody can create their own implementation based off of the File, URL, and such interface. I think I said it earlier, but a possible outgrowth of this interface repository would be a code repository of what's considered "best practices" for each of the interfaces. After all, there are only so many ways you can implement File.

I think that the interfaces are the most important thing we can do for PHP. If everyone can still do their own implementation yet have interoperablity we will get more uptake.

[Travis S]

Howdy all...

I'm going to take the weekend's quiteness for something of a concensus here. Over the weekend I put together what I believe is the final interface. The last posts we had here seemed to lean toward naming it Keyed, so that's what I've gone with. Short, and shouldn't class with any object names.

Here is the highlight reel:

interface Keyed {
    public function __get($key);
    public function __set($key, $value);
    public function __isset($key);
    public function __unset($key);
}

// attempt a __get('key') when __isset('key')  == false
class NotFoundException extends RuntimeException { }

// attempt __set()/__unset() when not a allowed
class ReadOnlyException extends RuntimeException { }

// attempt any method, but generally __unset(), when not allowed
class IllegalOperationException extends RuntimeException{ } 

This gives us all of the magic methods, and expected exceptions to throw whenever the object we want to implement doesn't allow the behaviors that have been mentioned here. Thoughts, comments? If there aren't any, I'll put together a package and upload it to SF over the next day or so.

To view the current code, and the file structure I'm using, you can look at the repository at: https://svn.opensir.org/svn/trunk/src/

Finally, here is the full interface, comments and all:

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

/**
 * Setup OpenSIR environment variables.
 */
require_once dirname(__FILE__) . '/opensir.library.php';

/**
 * Provides an interface for storing and retrieving any number of "Keyed" 
 * properties via PHP's {@link http://us2.php.net/manual/en/language.oop5.magic.php magic 
 * methods}.
 *
 * This interfaces is meant to be used by any object that should expose values
 * to match a given key.  Specific implementations are left up to the developer,
 * but they must provide for catching the requests to get or set via the magic
 * method __get()/__set().  In addition, __isset() is specified.  In PHP 5.1,
 * this is used by the internal isset() to insure that a property is set.  The
 * code would determine if a property is set in PHP >= 5.1 is 
 * <i>isset($keyed->key)</i>, in PHP < 5.1, however, it would be 
 * <i>$keyed->__isset('key')</i>.  Both function identically, but only the 
 * latter is compatible with versions of PHP 5.0.5 and lower.
 *
 * Present in this specification are {@link __set()} and {@link __unset()}.
 * When implementing Keyed in a read-only environment, it is acceptable to throw
 * a {@link ReadOnlyException} for both of these methods.  In an environment 
 * where {@link __set()} can be called, but a value can not be completely 
 * removed via {@link __unset()}, it is acceptable to throw a
 * {@link IllegalOperationException}.
 *
 * @license http://www.gnu.org/copyleft/lesser.html LGPL
 * @author Collectively authored via 
 *     {@link http://www.sitepoint.com/forums/showthread.php?t=298611}.
 */
interface Keyed
{
    /**
     * Retrieves a mixed value from this container by its given <i>$key</i>.
     *
     * Should throw {@link NotFoundException} if <i>__isset($key) == FALSE</i>. 
     *
     * @param string
     * @return mixed
     */
    public function __get($key);
    
    
    /**
     * Sets the property of a given <i>$key</i> to a given <i>$value</i>.
     *
     * May throw {@link ReadOnlyException} if this object is read-only.
     *
     * @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 __isset($key);
    
    
    /**
     * Removes a given value at <i>$key</i> from this object
     *
     * May throw {@link ReadOnlyException} if this object is read-only or
     * {@link IllegalOperationException} if the <i>$key</i> can not be removed.
     *
     * @param string
     */
    public function __unset($key);
}

[jayboots]

FWIW, it looks good to me, Travis.

[illusina]

Looks good -- sorry I can't reply further at the moment, registering at my university

[lastcraft]

Hi.

A good design is reached not when there is nothing to add, but when there is nothing you can take away. What can you take away?

For me, defining exceptions is needless. There is a trap of ending up with a bigger exception hierachy than your code (I can see SPL going this way). There really is nothing wrong with implementors coming up with there own exceptions. They probably have some in their library already. I would leave it.

I still don't see why __unset() is needed. Actually I still think it's incorrect. It is much more applicable to a more complicated structure and will cause people to write extra code when they don't need it (probably 75%+ of the time). This adds nothing to interoperability, but adds work to implementors. I still say dump it. I think it's nasty.

What's left is nice .

yours, Marcus

[Selkirk]

Could someone explain what value I would get out of using a framework that implemented these interfaces? Or what value a framework gets from implementing these interfaces? Sorry if this was covered, but this isnt immediately obvious to me.

There are many cases where a framework needs to work with an object defined by the user of the framework. Lets call that object a component. The framework needs a standardized interface or at least a convention in order to know how to access the properties of that component. Should it do a $component->property, or $component->get('property'), or $component->getProperty()?

For example, lets say you define a Customer object with Propel and want to pass it to the template layer of WACT for output. If both packages can agree on a standard property access model, then using them together is much easier. One can always use adapters, but its much much easier not to.

I think that -> and thus __get/__set is the natural and native choices for property access.

Note that the Properties interface that a component exposes to external users may not be the same one that it uses internally. As I think I showed with my prior example, by choosing __get and __set, we almost guarantee that it won't be.

That also doesn't mean that a component can't implement more than one style. I think what we are saying here is that for interoperability purposes, we are agreeing to implement the -> style as a required minimum.

Also, that doesn't mean that we have to necessarily use typehinting to require the Properties interface to be implemented. As long as one does not do so, any old PHP object can be used as a component. Thats lightweight.

[Selkirk]

So typical usage is like this...

class Request implements Properties { ... }
class Row implements Properties { ... }
class Configuration implements Properties { ... }
class Session implements Properties { ... } 

Lets not forget

class Customer implements Properties { ... }
class SalesOrder implements Properties { ... } 

[Selkirk]

Ok - where are we on name? Marcus' Keyed is sort of growing on me. Nice, short, and simply answers "this Container is Keyed" - "this Container is Properties" makes since too, but Keyed does describe exactly what you should expect.

Properties makes more sense to me because thats what they are. read it this way:

class Customer implements Keyed {}
vs.
class Customer implements Properties {} 

I don't think it makes sense to say a Customer is a Keyed in the same sense that one says a Square is a Rectangle. On the other hand, Customer implements Properties makes perfect sense to me.

[jayboots]

A good design is reached not when there is nothing to add, but when there is nothing you can take away. What can you take away?

There are more constraints than that. The design must still lend itself to usability and interop. If we take away the things you suggest then where is the standard aspect? Take the exceptions for example -- first, comparing with SPL is not productive because that is a much more complex beast than we are aiming at and has decidedly different goals. Further, there is nothing wrong with implementers coming up with their own exceptions but for the sake of interop, they should throw a standardized exception. Actually, I'm surprised you would say otherwise.

I continue to believe that your thinking on __unset is flawed or at least provides less flexibility than one might like. __unset maps to the unset keyword so we should always be willing to capture that because whether we specificy it or not, it is always "virtually" available. There is a difference between not including "unset()" and not including "__unset()". As far as extra code, is function __unset() {} really bloat?


Best regards.

[jayboots]

Properties makes more sense to me because thats what they are. read it this way:

class Customer implements Keyed {}
  vs.
  class Customer implements Properties {} 

I don't think it makes sense to say a Customer is a Keyed in the same sense that one says a Square is a Rectangle. On the other hand, Customer implements Properties makes perfect sense to me.

This is where things get interesting. Should Customer implement Keyed or should it have a member that implements Keyed (with its local "keyed" interface vectored to the member)? It is difficult to answer, I think, because I think it is odd to say that implements necessarily implies "is a".

[arborint]

I am starting to think that the interface defined here is Properties and not Keyed because it really only allows access to object properties. Using __get()/__set() means that you can't do things like $customer->division/group = 'Lion Tamers'; so it's not really keyed or abstracted in any way. You'd need get()/set() for that. It seems that this interface is really all about adding and standardizing exception handling for getting / setting properties.

[Selkirk]

I just wanted to make it explicit that what we are describing here is a portion of a component API. This is the PHP equivalent of a Java Bean. Or at least one facet.

Individual Java Beans will vary in the functionality they support, but the typical unifying features that distinguish a Java Bean are:

• Support for “introspection” so that a builder tool can analyze how a bean works
• Support for “customization” so that when using an application builder a user can customize the appearance and behaviour of a bean.
• Support for “events” as a simple communication metaphor than can be used to connect up beans.
• Support for “properties”, both for customization and for programmatic use.
• Support for persistence, so that a bean can be customized in an application builder and then have its customized state saved away and reloaded later.

A bean is not required to inherit from any particular base class or interface. ... Note that while beans are primarily targeted at builder tools they are also entirely usable by human programmers. All the key APIs such as events, properties, and persistence, have been designed to work well both for human programmers and for builder tools.

Ever wonder why PHP has a hundred frameworks and a hundred template engines but hardly any of them work together? Its because there is no standard component API in PHP.

I'm not trying to say that we should immediately flesh out the other Component API facets. I'm Just trying to put this discussion in context.

[DougBTX]

Ever wonder why PHP has a hundred frameworks and a hundred template engines but hardly any of them work together?

Because it is so easy in PHP that people write them by accident

[Travis S]

A good design is reached not when there is nothing to add, but when there is nothing you can take away. What can you take away?
...snip...
I still don't see why __unset() is needed. Actually I still think it's incorrect. It is much more applicable to a more complicated structure and will cause people to write extra code when they don't need it (probably 75%+ of the time).

I thought you were moving? Here I was thinking I could slip this in without you saying we should drop __unset() again, and you've still got Internet access. Well, if we drop __unset() and want to go completely lean, then we need to drop __set() and create MutableKeyed for read/write access.

I do see your point that it adds extra bloat, but since we've defined 75% of the magic methods as requirements, I think we'd be remiss if we didn't include the last one since it does have some bearing. If I use unset($keyed->key), and then I switch out to yours and I don't get anything, or an undefined index error, that's no good. For these to be interchangable and read/write, I think we need to keep __unset() there. If it isn't needed, you can implement it to return null, or better yet, through an InvalidOperationException. Which brings me to...

For me, defining exceptions is needless. There is a trap of ending up with a bigger exception hierachy than your code (I can see SPL going this way). There really is nothing wrong with implementors coming up with there own exceptions. They probably have some in their library already. I would leave it.

I think one of the more important things here is a standard way of returning an error. Say the read-only example using __set(). I might return null, you might return false, someone else might throw an exception, and still another might trigger an error. By coming up with generic exceptions that people can extend off of if they want to have their own exception handling, we provide a standard means for telling the application what has happened. Maybe just expecting a plain exception is the way to go, but personally I feel you loose some of the effectiveness of the exception if you have to fill your catch() block with a bunch of if() { } else {} statements of a case statement.

This actually gets back to what was mentioned earlier about Java having a standard set of classes. The more I think about, the more I think you're correct in that PHP needs that. As part of that set of standard objects I think we need a few common Exceptions. I was going to save this discussion for my next thread about standard classes, so maybe we should push of defining specific exceptions to be thrown until we get to that point. I'm fine with that, but I do think we need to have a standard failure mechanism. If I'm relying on d51ReadOnlyException and switch over to your interface, I would have to change all of my exceptions to read lcReadOnlyException. If we both share ReadOnlyException as the superclass, that's a non-issue.

Re: discussion of Keyed vs. Properties. I'm fine either way. There was movement toward Keyed when I put the code together over the weekend, so that's what I went with. It does make sense, maybe not when read in every case as "Object implements Keyed", but when translated into English as "Object is Keyed" it works fine. I do like the fact that it would be much less likely to be in conflict with someone elses "Properties" iterator. One final thing in favor of Keyed, "StoreItem is Keyed" implies that it has the behavior of a Keyed object, while "StoreItem is Properties" implies that the StoreItem is just properties. Basically, Keyed implies a state of being while Properties implies being something.

[dagfinn]

There is a trap of ending up with a bigger exception hierachy than your code (I can see SPL going this way). There really is nothing wrong with implementors coming up with there own exceptions. They probably have some in their library already. I would leave it.

I agree that there is a trap, and defining three different exception classes for this one interface seems to carry an imminent risk of falling into that trap.

To put that in perspective, here's a quote from Object Design by Rebecca Wirfs-Brock and Alan McKean:

Deep exception class hierarchies and wide exception class hierarchies are seldom a good idea...Most programmers can remember and distinguish 5-7 clearly different exception classes, but if you give them 20-30 exception classes with similar names and subtle distinctions, they will never be able to remember them all and will have to continually refer to the system documentation.

On the other hand, some middle ground might be the best place to go. At least recommending exceptions rather than some other, less flexible mechanism.

[Dr Livingston]

Using the Standard PHP Library as an example is a valid point. To me, the Standard PHP Library is a prime example of getting it wrong... They made a complete and utter a*** out of it in my view.

Now we're stuck with it

[kyberfabrikken]

If I'm relying on d51ReadOnlyException and switch over to your interface, I would have to change all of my exceptions to read lcReadOnlyException. If we both share ReadOnlyException as the superclass, that's a non-issue.

You're implicitly assuming that implemjentors will use exceptions as their errorhandling mechanism. There are however other ways to handle errors in php, such as trigger_error and simply returning FALSE. I can appreciate that exceptions are a superior way to deal with errors now we got them, but simply ignoring a feature of the language is dangerous to say it the least. Remember the really annoying error-object of PEAR ?

If we're sticking to exceptions as the default errorhandling mechanism (which is fine as long as we agree to it explicitly) I tend to agree with dagfinn's last post. It's often not that important exactly what kind of exception you recieved. Normally you can recieve only one anyway, so most of the time you just end up catching the toplevel exception anyway.

[dagfinn]

I loathed SPL to begin with, too. But now I'm going to come out of the closet and admit that--after overcoming my initial revulsion and using it in practice--I rather like the SPL iterator concept. The fact of having a standardized interface (hmmm...isn't that what we're trying to do in this thread ) and being able to use an iterator in a foreach statement now tastes pretty good to me.

It may be excessive to have to implement six (seven?) methods when the standard Java iterator has only three, but I find that the advantages outweigh the problems. As for the rest of the SPL stuff, I just pretend it doesn't exist.

And I think that's very relevant to this thread. A standardized interface doesn't have to be perfect to be useful.

[dbevfat]

I am just an observer here, but I want to bring back the __get/get('property')/getProperty() issue.

The basic idea of an interface is to ... well, be an interface, which is to introduce public methods to an interface user (= user of a class that implements the interface). So, strictly speaking, in that perspective, by defining __get/__set in an interface, you are telling the interface users to use __get and __set, since no other public method were introduced.

Then magic behind __get+__set is being called automatically when there is an access to an inexistent public property. Shouldn't the choice for this be on the implementer's side? I don't feel comfortable with interface forcing me to use this kind of magic, unless I would explicitly want to. I could imagine using the Keyed/Properties interface for a class and have that magic in the same class for some other purpose. The point I'm trying to make is that using such magic is definitely a thing of implementation, not an interface, and must as such not be forced via an interface.

Also, as was stated before, by using methods it would be easier to use more complex structures (paths) for variables.

Regards

[lastcraft]

Hi.

My point was the same as Dagfinns. Specify that the error mechanism is an exception and then only specify that it should have the interface Exception. The exception is likely to be highly context sensitive anyway. For example, say we are using a DB row. Failing on an operation here is likely to trigger a very specific exception that has nothing to do with our interface. If you make the DB exceptions implement our exception interface (we even specified classes above for an interface library ) then our interface is spreading outward like some kind of disease.

Regarding a Person implementing Properties, I doubt this will ever be the case. More likely there is a higher level interface that handles one-to-many relationships, but that also extends Keyed/Properties.

Regarding unset(), why not wait. If there is a clamour for it, then add it later. It's much easier to add stuff than remove it.

Regarding the SPL, the iterator stuff (should have been Foreachable ) is great. The trouble is here is another classic example of people puttling in a load of methods that everyone ignores and a load of extra classes that no one understands. The interface is acting as a rough coding standard, not a true interface atht anyone can truly rely on.

Regarding my net connection, I am writing these on an occasional basis from work. My home development is still stuffed. You don't get rid of me that easily...

yours, Marcus

[mx2k]

Also, as was stated before, by using methods it would be easier to use more complex structures (paths) for variables.

wouldn't you then be forcing people to still have to parse those paths in order to obtain access or at least use the methods names get() and set() to get a property, so how is this any different from forcing __set() and __get() ?



however could you interface two different applications doing the following?

$t = $object->property-property;

// and the other is doing

$t = $object->get('object/property/propery'); 

I continue to believe that your thinking on __unset is flawed or at least provides less flexibility than one might like. __unset maps to the unset keyword so we should always be willing to capture that because whether we specificy it or not, it is always "virtually" available. There is a difference between not including "unset()" and not including "__unset()". As far as extra code, is function __unset() {} really bloat?

then doesn't this concept also imply that we should use __call() just because it's virtually is available? I think this sort of thinking is flawed. Use the bare minimum of what is required and if you need more, just extend as necessary for your own needs.

however i don't see why you would want to remove a property with __unset(). the below makes more sense than including everything in one interface forcing things if they are not needed. i would hate to have to put a blank method in a class just for the sake of use an interface that has more than what the common needs maybe.

interface IExtendedProperties
extends Properites
{
        public function __isset();
        public function __unset();
} 

exceptions should not be required with any interface. let the developer decide on their own error handling. this helps with providing flexible standards that can be extended.

[Travis S]

Regarding unset(), why not wait. If there is a clamour for it, then add it later. It's much easier to add stuff than remove it.

While I disagree with whether or not unset() is needed, I do agree with this statement. With that in mind, I would say let's pull __unset() and the specific exceptions and give this a go with the plan of revisiting it the end of October.

[jayboots]

then doesn't this concept also imply that we should use __call() just because it's virtually is available? I think this sort of thinking is flawed. Use the bare minimum of what is required and if you need more, just extend as necessary for your own needs.

It may indeed be required for a different interface but not for properties. This is the main point I want to emphasize: when you are dealing with generics and you get a standard interface, you don't want to switch to see which "version" of the interface you need to handle. When it comes to a property interface, a generic handler should always be able to rely on its subject handling in a consistent way any property call including __unset. If we don't account for generic usage I think the whole point of having interfaces is moot. What I'm saying is, a property container should do the things that a generic property container is assumed to do: add, remove, exists and of course valueOf. This isn't defining a property -- it is defining a property container. Othewise we are going to have a plethora of interfaces each defining a single method to satisfy everyone's idea of "slim".

exceptions should not be required with any interface. let the developer decide on their own error handling. this helps with providing flexible standards that can be extended.

Although I have a soft-spot for that idea, I think it is more appropriate to let developers decide if they want to use specific interfaces or not. If they decide they want standards compliance then let us define what that means so as to make everyone's life less complicated. That doesn't mean it should be exceptions necessarily, but it should be *something*. There is a difference between generic and willy-nilly

[mx2k]

Although I have a soft-spot for that idea, I think it is more appropriate to let developers decide if they want to use specific interfaces or not. If they decide they want standards compliance then let us define what that means so as to make everyone's life less complicated. That doesn't mean it should be exceptions necessarily, but it should be *something*. There is a difference between generic and willy-nilly

well this is the kicker part. sigh. (and yes i'm too lazy to go back and read page one of this thread), but the idea of this whole deal, is to provide a library of interfaces that would provide common ground between applications

now yes, if i am designing for my own purposes i can do wacked out things for myself, and i can leave things out or add them in, but wait, now i need to interface an existing guestbook & blog with the current application, that developer x in a different company or just even different department has designed...

and with exceptions, Exception is part of the SPL and SPL, to my knowledge (though very limited), can be turned off.

Errorhandling is like wearing a seatbelt, you can choose to wear it tight, or loose, or not at all. And we know what happens when you choose to not wear it all and and then something bad happens, but the law shouldn't enforce common sense, because it makes things more complicated and troublesome on some people than its worth.

stick to the core, bare bones essentials and that in itself should expand to the appeal of a decent degree of developers and even though you are setting some standards that might irk some developers to some degree, it won't kill the concept totally and them leave breathing room, without forcing them to abandon the idea totally.

annoying naming i can live with.

excess amount of work to adhere to standards.....not cool. Its bad enough i have to do it with W3c and then put in hacks cause of IE and misc browsers do not all impliment those standards.

[Dr Livingston]

Off Topic:

And we know what happens when you choose to not wear it all and and then something bad happens,

Sod the law, what happens is that you go through the windscreen. Head first

That has got to hurt...