Best practices

[liuggio]

Overloading is not so used in the php community, is it mandatory?

This is a public library and you'd follow best practices and coding standard, giving importance to the code readability.

Finally this library has tags but it's bad practice modifying tags adding commits into the same tag and introducing BC in the same tag.
Tag should be like screen shot, if you have a BC is better to create another major version.

You are providing a library all the BC should be planned and should go through a deprecated step.

You are providing a library so public and protected methods are important, those are like interfaces for us.

This is not a rant is a pray, so please think about us when you'll modify this library.

related to #211

[jamiehannaford]

@liuggio Hey Giulio, thanks for your feedback. To answer to your points:

1.) In terms of method overloading - it's really an issue of object encapsulation. I'm faced with two choices: allowing resource models to be accessed and mutated through direct access to its properties; or to enforce a public API through getter/setter methods - regardless of whether they're defined concretely or through overloading. I believe encapsulation is one of the most important patterns to enforce when you're dealing with dozens of objects that contain business logic.

Say you go with the first option, because you're unfamiliar with overloading and magic methods. Throughout your library, which contains thousands of lines of code, you're communicating with objects through their raw properties. Now imagine there's an API change and you have to update a property name. Now you have to find every single instance where sibling classes reference the original and do a pain-staking find and replace.

Setter/getter methods get away from this problem by providing a consistent object interface. So really, the choice is whether to have hundreds - and I mean hundreds - of setter/getter methods in your codebase. The majority of which are doing a basic operation - identical to every other getter/setter in that object. So it's a decision between dynamically loading these methods, or having thousands of lines of repetitive code. Perhaps it's not a permanent solution - we're always looking towards better ones - but it's the best compromise with the current state of the SDK.

2.) Please define "best practices" and "coding standards". Or at least provide a reference. The truth is, these things are not set in stone - they're subjective and prone to ruthless debate. With a SDK that has so much usage and is therefore privy to so much public scrutiny, you cannot always please everyone. But I hope to at least communicate the reasoning behind certain decisions.

3.) In terms of the tag issue - I completely agree. When we released v1.7.0, I updated the name of an existing tag release. For some reason this operation also updated the commit hash - so 1.6.0 pointed to the current version. I'm talking with Github and hopefully we'll be able to fix this issue soon. I can keep you updated if you want.

[jamiehannaford]

@liuggio V1.6.0 is back to its original commit hash - so you can rollback to that version in Composer.

[liuggio]

Thanks for your reply,

1. Yes I understand your point of view, for us explicit is better than implicit,
   For the external classes(the one'd be tagged as @api) I think is better to have all the explicit functions,
   Using Interface as contract, this is another cons for overloading.
2. thanks a lot.

Thanks a lot I saw a lot of improvement on this library.