When developing an API, one point you have to consider is whether you want to provide an implicit or an explicit API.
An explicit API is usually quite self-explanatory, the method name tells you what the method does (at least, if it has a good name). Some examples from the core of CakePHP:
Model::findAll($conditions = null, $fields = null, $order = null, $limit = null, $page = 1, $recursive = null) // deprecated Model::findCount($conditions = null, $recursive = 0) // deprecated FormHelper::checkbox($fieldName, $options = array()) FormHelper::submit($caption = null, $options = array())
On the other hand, an implicit API doesn’t tell you what the method does (respectively it does it on a more abstract level):
Model::find($type, $options = array()) // new syntax FormHelper::input($fieldName, $options = array())
In the first example, the $type parameter determines what the method does, and in the second example it depends either on the data type of the respective database field or on the value of the “type” option.
For you as a developer, implementing an implicit API means a) you have to write more code and b) you have to write more documentation (because you also have to explain what the method does)… On the other hand, an implicit API allows you to provide a unified API (e.g. Model::find(‘all’), Model::find(‘count’), and Model::find(‘list’) vs. Model::findAll(), Model::findCount(), and Model::generateList()).
For a user, an implicit API is probably more difficult to use than an explicit API, at least in the beginning. For example, if you want to get the number of some records, you first look for a method with “count” in its name. With an explicit API you will find the Model::findCount() method, but with an implicit API you probably won’t discover that Model::find() supports a “count” type…
Anyway, in the end it is up to you to decide which approach better fits to your specific situation. Both approaches have their advantages and disadvantages.