php-coding-standards.markdown

@@ -141,6 +141,35 @@ count()
 keys()
 ```
 
+The usage of these methods are only allowed when it is clear that there is a main relation:
+
+- a CookieJar has many Cookie objects;
+- a Service Container has many services and many parameters (as services is the main relation, the naming convention is used for this relation);
+- a Console Input has many arguments and many options. There is no "main" relation, and so the naming convention does not apply.
+
+
+For many relations where the convention does not apply, the following methods must be used instead (where XXX is the name of the related thing):
+
+| Main Relation | Other Relations |
+| ----- | ----- |
+|get()	|getXXX()|
+|set()	|setXXX()|
+|n/a	|replaceXXX()|
+|has()	|hasXXX()|
+|all()	|getXXXs()|
+|replace()	|setXXXs()|
+|remove()	|removeXXX()|
+|clear()	|clearXXX()|
+|isEmpty()	|isEmptyXXX()|
+|add()	|addXXX()|
+|register()	|registerXXX()|
+|count()	|countXXX()|
+|keys()	|n/a|
+
+
+While "setXXX" and "replaceXXX" are very similar, there is one notable difference: "setXXX" may replace, or add new elements to the relation. "replaceXXX", on the other hand, cannot add new elements. If an unrecognized key as passed to "replaceXXX" it must throw an exception.
+
+
 ### Documentation
 
 * Add PHPDoc blocks for all classes, methods, and functions;