Proposal for Standards & Interface Repository

[kyberfabrikken]

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 like to think that the returntype is part of a methods signature - Even if php, being loosly typed, doesn't explicitly state a returntype. Furthermore, I'd say that any exceptions a method might throw is too part of the signature. If you have a look at a strongly typed language such as java, you'll notice that methods of classes aswell as interfaces state which exceptions they might throw.

[datune]

@kyberfabrikken

I would like to refer you to my previous post, where i quote Bruce Eckel, and I take it he knows his stuff

[kyberfabrikken]

@kyberfabrikken
I would like to refer you to my previous post, where i quote Bruce Eckel, and I take it he knows his stuff

And I'd like to refer you to ahundiaks previous post, where he states :

(...) interfaces are contracts and not specifying what a method is supposed to do kind of makes the contract worthless.

[Dr Livingston]

[datune]

Ok..erm...kyberfabrikken...it seems thay you don't know your stuff either. I am going to be bold here and just ask you to first look your stuff up, I'm not the person to repeat myself over and over again.
So please, read my previous post again, so that you too know what an interface is. (obviously you don't)

Not sure what your point is trying to refer me to ahundiak's post...

[ahundiak]

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

Hmmm. Didn't mean to start a flame war. But Bruce Eckel also said:

The interface keyword takes the abstract concept one step further. You could think of it as a “pure” abstract class. It allows the creator to establish the form for a class: method names, argument lists, and return types, but no method bodies. An interface can also contain fields, but these are implicitly static and final. An interface provides only a form, but no implementation.

So indicating what (if anything) a method should return seems to part of designing an interface.

[jayboots]

Refreshing.

As an addendum, we might also remember that the class names and method names carry semantic weight. Interfaces are not merely arbitrary names with methods m(0)..m(n). We may implement them in any way we choose, but there is a spirit that their names (and documentation) carry which denotes a style of purpose for the interface. That does not imply what exactly each method will do, but it does suggest a minimal conceptual expectation for each method call. Again, there is no way -- or need -- to enforce behaviour at this point. This should simply provide the syntax for semantic hooks which are used to later build-up concrete behaviours.

As to method return types -- there is no way to enforce such a thing in PHP so it too must remain a thing of documentation.

[arborint]

I think your all right. I would like to focus on what we want it to be.

I should reply to datune's first response to my interface proposal to say that I just copied the comments (and reduced them) from what Travis_S posted because I was addressing his post. I think most of the comments can go if you like, it's the method names that I care about.

As for exceptions, I think of Keyed as the object form of a PHP associative array. That's because we are talking about PHP here. In another language it be different. But my point is that I wouldn't want accessing an undefined array element to cause an exception (I think a few here might) and the same goes for Keyed. It should return NULL if the key does not exist. We provide a method to check if the key exists. If you want to cause an exception at a higher level then you can. If you want to implement an exception if a key doesn't exist, do so as appropriate. But the return value for get('name') should behave, in general, like $value = $data['name'] because that's what PHP programmers will expect.

[ahundiak]

But the return value for get('name') should behave, in general, like $value = $data['name'] because that's what PHP programmers will expect.

Well, $value = $data['name'] can result in a:
Notice: Undefined index: name in ...
so I really don't think it's a good analogy.

I myself would like to see an exception thrown if an unknown property is requested. As I see it there is always a chance that an expected property will not be found regardless of the use case. And the programmer needs to deal with it.

Consider the Request object containing a list of posted values. We know what values to expect so there is really not much point in checking each and every value to see if it exists. In other words our code should look like:
$address = $request->get('address');
Instead of
if ($request->has('address')) $address = $request->get('address');
else $address = 'Deal with this very rare condition';
or
$address = $request->get('address');
if ($address === NULL) // deal with it

On the other hand, it is possible that the submission got corrupted or hacked or some sort of programming error results in a unknown field. Throwing exceptions allows one to write clean code using method 1 while at the same time dealing with the rare missing data cases.

Of course there are also time when it's ok for data to be missing. In which case one could run the has method before attempting to use get to avoid an exception.

So it's really a question of which use case is more common. In my own (admittedly limited) experience, the case in which missing data should be treated exceptionally is the norm.

[lastcraft]

Hi.

Guys, cool off a little .

An interface can be specified by documentation. It's not even a concept that is well defined. Obviously we want to use the interface keyword if we can in PHP5, but there is much more to an interface than that. At one extreme we just have a method name and at the other we have Eiffel contracts. One aspect of our problem is to define the depth of imposition.

My inclination is to start as weak as possible, move on to another interface and then revisit. So the methods $value = get($key), set($key, $value), boolean has($key) say, and move on. Here I am implying that the $value you get out is the one that you put in earlier. To me that is part of the interface, but I know of no way to enforce this except as a description of intent.

The concept of interface is one of a minimal level of cooperation. Like all things with computers, that is a human problem.

yours, Marcus

[arborint]

So the methods $value = get($key), set($key, $value), boolean has($key) say, and move on.

I agree on the methods and I agree even more on moving on. Any last objections to these methods?

If not, what would be the next basic interface that would be useful to define?

[mx2k]

I agree on the methods and I agree even more on moving on. Any last objections to these methods?

If not, what would be the next basic interface that would be useful to define?

of couse i have to object =) after some thought, it we are are doing to much with to generic an interface, the interface is supposed to be properties, but different developers have different ideas of properties. so lets break this all down

i don't care for the idea that get()/set() = __get()/__set() because you can't do $x->Property->anotherProperty and inside the class have get() access __get(), thats why __get() is magic. and in a framework like prado, __get(), __set() come in handy

depending on how you implement properties, you might not need exists() or has(), which leads to bloat.

IKeyed sounds like it is more for a hashtable, collection, dictionary, or what have you.

so we shouldn't have a properties interface.

interface IKeyed {
      public function setKey($key, $value);
      public function getKey($key);
      public function keyExists($key);
}

interface IGenericAccessors {
      public function get($x);  // $x could be a key, a function, a file path..etc
      public function set($x, $value);
}

interface IMagicAccessors  {
      public function __get($property);
      public function __set($property, $value);
} 

As to method return types -- there is no way to enforce such a thing in PHP so it too must remain a thing of documentation.

i whole heartedly agree. php doesn't have void and functions, it just has functions which can return mixed types. thus php interfaces do not and can not enforce a return type right now, then you would really need to implement overloading in php, then your changing the dynamic of the language.

@ahundiak, if you're looking for exceptions and and return types, then you are looking more for a framework, than an interface repository. interfaces are there to (not to point out the profound) interface.

you can have completely two different systems who do totally two different things with the data passed, but all you have to know is that this class implements this interface, so it must have this method to do whatever its got to do with the data you are passing to it.

your class doesn't have to know what it does, just that it has that certain method(s).

[arborint]

i don't care for the idea that get()/set() = __get()/__set() because you can't do $x->Property->anotherProperty and inside the class have get() access __get(), thats why __get() is magic. and in a framework like prado, __get(), __set() come in handy

Actually if __get()/__set() call get()/set() then every combination should work fine in PHP5.

$foo->get('one')->get('two');
$foo->get('one')->two;
$foo->one->get('two');
$foo->one->two; 

I'd say simpler would be:

interface IKeyed {
      public function set($key, $value);
      public function get($key);
      public function has($key);
}

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

[mx2k]

Actually if __get()/__set() call get()/set() then every combination should work fine in PHP5.

$foo->get('one')->get('two');
$foo->get('one')->two;
$foo->one->get('two');
$foo->one->two; 

I'd say simpler would be:

interface IKeyed {
      public function set($key, $value);
      public function get($key);
      public function has($key);
}

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

here are some of the reasons i seperated the above.

IKeyed hints as something being keyed into a storage container, get()/set() are too generic to be tucked into IKeyed and have an enforced has(). you might be forcing to put a has() where it isn't needed.

getKeyed(); setKeyed(); hasKey(), is a little more descriptive and implies this interface to be used with such a container.

where as get()/set() , which are commonly known as accessor methods can get properties, or files, or whatever the developer wants you to have limited access to. Php is dynamic and people have been known to do all sorts of stuff with get()/set(), not just properties.
has() and __isset() in a properties class, is just extra weight to push for in all circumstances.

most well developed interfaces are small and the methods are specficially named (ie. public function postDataHandler($postData) , rarely are they generic (except in cases likes ICountable), and classes will use sometimes 3 or four interfaces. depending on the needs. so no need to try to do everything with one interface....

leave get()/set() into another interface, where i'm sure it won't be used as muc, hopefully (which is a good thing since i'm sure many people already use this in various ways in their code). and __get()/__set() in another interface (which I am thinking the interface would also be used rarely. as well)

which means to people who have complained about being locked in, in using these methods, you will only be locked in, when you are interfacing your code with another person's code and those interfaces are needed for interloping. which could be never. or just in certain circumstances.

however i think people's minds are thinking more of a framework than interface repository.


by requiring less in these interfaces, you are keeping it simple in the long run. and keep in mind the wider audience you want, the less code you want to break or add to another developers work load.

my conclusion after much thought. there should not be a properties interface. and there are not too many cases where i see IGenericAccessors and IMagicAccessors being used to help interloping code as far as logic goes, more so, its there to help interloping a certain coding style. (i.e. a framework or code library ). which might not be a very positive thing to push for when building a repository for such a diverse group of programmers., at least not here at the beginning.

i do see IKeyed being handy in alot of hashtables, collections, dictionary classes, etc. but in order not to use up the key functions get()/set(), that are widely used for more than just properties in php, it would be smarter to use getKeyed()/setKeyed/hasKey(). or some alternative...

• to not break current code,
  
• to reinforce the idea that you're using this interface for keyed values in a storage container
  
• to not cripple or scare of people with certain coding styles who might want to use get()/set() __get()/__set() for something else & who do not want to be tied to a has() or isset() when using generic accessors,

if you wish for enforce a has or isset(), implement another interface that will enforce that method. or add one to your personal library/framework =) and dont forget to document it.

::trips and falls off soap box and breaks both legs::

[kyberfabrikken]

if you're looking for exceptions and and return types, then you are looking more for a framework, than an interface repository.

I can't say that I don't follow you on that distinction, but it's just not very precise, and thus could cause trouble ahead. Framework is a very fuzzy term, so you'll have to concretize exactly which elements you think belongs in the project, and which don't. An more important - why.

i whole heartedly agree. php doesn't have void and functions, it just has functions which can return mixed types. thus php interfaces do not and can not enforce a return type right now

php4 doesn't have the keyword interface, but it doesn't mean that one can't operate with the concept. Have a look at WACT DataSource interface for an example of that.
I hate to repeat myself, but I insist that returntype is part of an interface, even if php doesn't support this on an implementation-level.
We could decide that only features which are supported on a language-level should be used. I think it's rather radical stand, but there may be some sort of logic to it. More importantly, I really think we should decide on which route to take before proceeding, or we're bound to fail.

::trips and falls off soap box and breaks both legs::

Nah, they don't have an animated gif for that yet.

[siteartwork]

I hate to repeat myself, but I insist that returntype is part of an interface, even if php doesn't support this on an implementation-level.

Check out the Low Level interface Serializable. The method serialize() requests a return parameter, which should either be NULL or a string. Thus, it could be possible to check the return type during runtime and trigger an error - assumed that you implemenent the interface in C/C++....

[mx2k]

I can't say that I don't follow you on that distinction, but it's just not very precise, and thus could cause trouble ahead. Framework is a very fuzzy term, so you'll have to concretize exactly which elements you think belongs in the project, and which don't. An more important - why.

an interface does not enforce the logic inside the method. just that the method exists, has a signature, and in strongly typed languages, a return type.

Exceptions, unless for some reason, type hinted in the signature of a method, is logic that is in some place in the class.....or inside the method and since interfaces don't care what logic is inside a method why are we trying to decide for someone what goes inside that method(s)?

you're assuming that this will be the case for every use of this interface for everyone, and until its proven, why add it?


when you add things like exceptions, you are adding complexity, bulk, and trying to enforce a standard, that has yet to be proven in php(this is php, not java or any other language, what might be good for them in compiled languages, might be death to php). to get people to use standardized interfaces should be your first baby step,

do not be another pear. =)

by using exceptions are you assuming that SPL is turned on, which might not always be the case.

I can see where interfaces can help standardization accross many platforms as talked about earlier,

but i do not see where adding exceptions, or any other reusable classes is going to help win over a diverse group of people who use various coding styles/libraries and as people have personal preferences and etc. You have your hands full with just getting an interface repository together, why kill a project before it has even really begun?

those sort of things should be put in either a seperate standardized code library, after much testing and refactoring, or built into a collabrative framework (a standardized reusable layered code base that is interwined and suited for Rapid Development, much where you would make use of things like IGenericAccessor, at a base object level, or IDatabinder, etc. )

i could just as easy use throw new exception(' certain message', 30); using a code opposed using a new class every 5 seconds. new myNewExceptionForEveryLittleKeyComponent('message');

yes, i'm throwing out stuff here, but i'm doing so after shifting through much php code, reading forums, books and all other things php and seeing how picky people are to using their own way of doing things.

php4 doesn't have the keyword interface, but it doesn't mean that one can't operate with the concept. Have a look at WACT DataSource interface for an example of that.
I hate to repeat myself, but I insist that returntype is part of an interface, even if php doesn't support this on an implementation-level.
We could decide that only features which are supported on a language-level should be used. I think it's rather radical stand, but there may be some sort of logic to it. More importantly, I really think we should decide on which route to take before proceeding, or we're bound to fail.

alot of return types could be mixed in php. you have to be really careful as we don't have true overloading in php. some well known methods, you really don't even have to think about the return type. IsBlah()...HasBlah(), most likely will be boolean.

set, doesn't have to have a return type, but it could (boolean, null, etc),

get could be mixed. or if its used in a collection of certain types of objects, it return just one certain object type or null, or throw an exception, or an outOfRangeException (vs. a PropertyWriteOnlyException, if used in a different context) if a certain key or index isn't found, depending on how get() is being used.

however because the language is dynamic in nature, you should leave it to the person using the interface to document what is being returned rather than totally narrowing the scope of the interface to a certain type now, possible cutting off the use of these interfaces all together.

you could also ask nicely for the developer to add an @throw or @exception to their documentation as well. =)

Nah, they don't have an animated gif for that yet.

but we should

[kyberfabrikken]

some well known methods, you really don't even have to think about the return type. IsBlah()...HasBlah(), most likely will be boolean.

The reason why you don't have to think, is because there is a de-facto standard prescribing that thoose methods returns a boolean. That's an implicit part of the interface. It's no different from stating it in a @returns comment.

set, doesn't have to have a return type, but it could (boolean, null, etc)

If you don't specify the returntype, you loose the ability to switch implementations of the same interface.

Class A implements interface I. Class C uses class A. Class B also implements I.
If A returns true on success, and B doesn't, and class C expects A's behaviour, it will fail when you switch A with B. That kind of makes the interface pointless in the first place.

(...) and since interfaces don't care what logic is inside a method why are we trying to decide for someone what goes inside that method(s)?

That seems to be a common misconception. An interface states an expected behaviour - not how it's implemented. That doesn't mean that there isn't some expected result of a call to an interfaces method.

by using exceptions are you assuming that SPL is turned on, which might not always be the case.

?

when you add things like exceptions, you are adding complexity

It sounds to me like you simply don't like exceptions as an errorhandling-mechanism. Is that the case ?

[mx2k]

The reason why you don't have to think, is because there is a de-facto standard prescribing that thoose methods returns a boolean. That's an implicit part of the interface. It's no different from stating it in a @returns comment.

right, which are common. the @returns should be left up to the developer using the interface to prescribe whats is being returned. not the repository because php is a dynamic loosely typed language.

mixed is not an exact type, yet its most likely what a lot of methods will return in php, because, again, we do not have true overloading.

so unless you want to something like some strongly typed languages and have getString(), getInteger, getNumeric, getBoolean(), which can add to bloat, or having a ton of interfaces with the same methods that have different return different types (which i would see as pointless in php), could just get really messy, really quick,

should be left the developer who is using the interface to put the @returns in his/her code.

If you don't specify the returntype, you loose the ability to switch implementations of the same interface.

this again, should be left up to the individual developer to place

Class A implements interface I. Class C uses class A. Class B also implements I. If A returns true on success, and B doesn't, and class C expects A's behaviour, it will fail when you switch A with B. That kind of makes the interface pointless in the first place.

unless b has a zero, false, or another equilvant to false, the type can easily be changed in php to evaluate a boolean value. again this should be left up to the developer, unless its cases where there consistency like Has or Is.

I do see what you are saying, but that should be the developer's responsibility, when using an interface in php, to specify the expected return value, because php is dynamic and a scripting language.

if there is a common repository in php, it should reflect php's ability to adapt to various needs and be short and simple.

That seems to be a common misconception. An interface states an expected behaviour - not how it's implemented. That doesn't mean that there isn't some expected result of a call to an interfaces method.

depending on the frame of reference. method/routine, is obviously going to do something. however, when using an interface, yes sometimes, there is a expected result and in those cases, the developer needs to specify it in a language like php through documentation, so that you can comply with those specs.

in other times, you don't need to know what a method does exactly, other than that class just has that method and you pass it certain parameters, especially if you are interacting with another person's code/system.

because it might not return anything.

It sounds to me like you simply don't like exceptions as an errorhandling-mechanism. Is that the case ?

i do actually, but i believe in flexibility and i don't want to create a new one, unless i really have a need to trap that exception by its type. simply not worth the overhead in a scripting language to go overboard with different exception types in alot of cases. most people do not even let them bubble up properly.

nor is it rationale to enforce a certain style of error traping at this point....

SPL is the standard php library....which houses the exception class, but can be turned off in the .ini file or when compiled.

[lastcraft]

Hi.

One of the main values of a Keyed interface is the interop aspect. I would like to take a database row from an author, see that it follows the Keyed interface and drop it straight into a display widget that accepts Keyed. Even if this is from a different author.

The same with dropping a request object into a form.

The same with dropping a configuration object into a database connector.

The decison to have has() needs to be informed by this. The definition of an "interface" needs to be informed by this. The decision to use fancy overloading tricks needs to be informed by this.

yours, Marcus

[dagfinn]

i do actually, but i believe in flexibility and i don't want to create a new one, unless i really have a need to trap that exception by its type. simply not worth the overhead in a scripting language to go overboard with different exception types in alot of cases. most people do not even let them bubble up properly.

This has been discussed earlier in this thread. What a lot of people agreed on--I think--was that it's reasonable to specify that exceptions should be used rather than some other error handling mechanism, but not to demand specific or additional exception classes.

[arborint]

One of the main values of a Keyed interface is the interop aspect. I would like to take a database row from an author, see that it follows the Keyed interface and drop it straight into a display widget that accepts Keyed. Even if this is from a different author.

The same with dropping a request object into a form.

The same with dropping a configuration object into a database connector.

We really should not underestimate the powerful benefits of this. I have been meaning to itemize this list that lastcraft rolls out naturally. If your Request, Config, DB Row, Template, and Response all use the same container interface then many things are simplified and interesting possibilities occur. They are core objects in most PHP apps and comprise the main data flow from request to response. Once you get interop between them (and then interop between different applications/frameworks) then many interesting things start to happen.

The decison to have has() needs to be informed by this. The definition of an "interface" needs to be informed by this. The decision to use fancy overloading tricks needs to be informed by this.

Unfortunatiely several groups here seemed to be informed differently. It feels like we are moving forward but don't have a quorum. mx2k not happy about specifying the return values and the Java contingent disappeared into the woodwork once we became un-esoteric.

[dagfinn]

Hi.

One of the main values of a Keyed interface is the interop aspect.

Yes. We're trying to satisfy real-world requirements, not theoretical ones.

I would like to take a database row from an author, see that it follows the Keyed interface and drop it straight into a display widget that accepts Keyed. Even if this is from a different author.

The same with dropping a request object into a form.

Yes. Yes.

The same with dropping a configuration object into a database connector.

How? Wouldn't the database connector need something more specific, like database name and password? How could a non-specific Keyed interface ensure that it would get that specific information?

[arborint]

How? Wouldn't the database connector need something more specific, like database name and password? How could a non-specific Keyed interface ensure that it would get that specific information?

All your DB Connector cares about is that $config->get('DBName'), etc. exist. It's all about the interface.

Even better, something like:

$config = $locator->get('Config');     // Locator implements Keyed too
$db = new DBConnector($config); 

Now if I change what my DBConnector needs, all I need to change is what's in Config. All my code is oblivious to that contract so need not worry about it.

[mx2k]

This has been discussed earlier in this thread. What a lot of people agreed on--I think--was that it's reasonable to specify that exceptions should be used rather than some other error handling mechanism, but not to demand specific or additional exception classes.

::sigh:: brought by again by adhundiak. see earlier post, previous page,

besides i found it documented in prado and in other places, that throwing exceptions inside of magic methods can cause the server to crash.

not happy about specifying the return values

 interface IKeyed {
      public function set($key, $value); //mixed
      public function get($key); //mixed
      public function has($key); //boolean, or at least it should be
} 

in instances like get() 'mixed' is not a 'type'. in php, where you can use a generic accessor in an interface, like above, and the value differs upon what the developer, has keyed in, how can you specify a return value for get() in the repository?

again "mixed" is not a type. and in cases likes Exists(), Has(), or IsSomething, boolean is implied, you don't really need to specify it, unless you really want it documented.

the developer implementing the interface should specify this, not us or the repository....sigh. and if you're developing code for other people to use, you should already be documenting this kind of stuff or at least the make the code self documenting.

in most cases you would benefit from being more specifc if you wish for a return type, HasControl($control), HasProperty($property), etc. getString(), if you want specify a type, but that doesn't mean php can enforce the type coming from that method if a developer implements that interface incorrectly.


as far as IKeyed

request object // has items items/array/stack $_REQUEST
configuration object // has items items/array/stack $cfgvalues
data row // has items/array/stack $row
CustomerProfileCollection // has CustomerProfile items

CustomerProfile // object has real properties, no virtual properties, no items or stack/array

IKeyed is great for the first 4, but i don't see it being used for object CustomerProfile, nor the need for it to impliment any kind of properties/accessor interface that includes Has()/ __Isset().

if($cfg->has('dbconnection')
 $conn = $cfg->get('dbconnection');

class CustomerProfile
implements IGenericAccessor
 {
   
    private $_age = 0;
    private $_aim = '';
    private $_phone = '';

    public function set($x, $value){}
    public function get($x){}
    // don't really see a need for has
    // at least i don't need it. 
}