ElggEntity::addRelationship() might be backwards

[brettp]

ElggEntity::addRelationship($guid, $relationship) claims you should read the relationship as "$guid is a $relationship of this entity" but it calls add_entity_relationship($this->guid, $relationship, $guid) which says to read the relationship as "$guid_one is a $relationship of $guid_two."

Which is it? I lean toward add_entity_relationship()'s description as feeling more natural.

For what it's worth, addRelationship() isn't called anywhere in core. (And yes, I'm aware I wrote the docs for both of these functions...)

[cash]

We should take our cue from the semantic web people:

guid1   relationship guid2
subject predicate    object

Maybe the documentation should encourage people to read this by inserting the verb 'is' or 'has' before the relationship string like they do with RDF:

Joe hasFriend Bob
Joe isMember Jugglers

And changing the table and functions to use subject_guid and object_guid would be great.

[brettp]

All of those would be good steps to making this less confusing. I think the start of the confusion was putting "of" in the relationship itself (or the original docs): "member_of_site," "friend_of"

Using subject_guid and object_guid would clear things up immediately. This is frustrating, but as 1.8 is already saturated and this would be more than a documentation change, unless there's a compelling reason I'm pushing this to 1.9.

[brettp]

Unless we rewrite the relationships to actually include the verb, simply reading the relationship with "has" or "is" still presents the same problem because you don't know which to use:

• Joe (has|is)friend Bob
• Joe (has|is)member Jugglers

If we don't rewrite the relationships, we'd need to pick a verb and stick with it.

[ewinslow]

I'm definitely in favor of rewriting the relationships to include the verb.

Joe isMemberOf Jugglers

or

Jugglers hasMember Joe

are both much clearer to me than the current. I'd rather not try to pick an implied, because 1) it's not necessarily clear to new people, 2) that means we'd have to document it and explain it to these new people, 3) we may end up having to come up with an awkward name for a future relationship in order to fit our convention.