RFC - Class Naming Conventions

<ac:macro ac:name="note"><ac:parameter ac:name="title">Work in Progress</ac:parameter><ac:rich-text-body>
<p>This page is work in progress. Please discuss and feel free to edit, rephrase, extend with more cases and examples.</p></ac:rich-text-body></ac:macro>

<p>This RFC contains a proposal for several additions to current <a href="http://framework.zend.com/wiki/x/yQCvAg">ZF2 Coding Standards</a> regarding class naming and class file location.</p>

<p>Conventions of this document:</p>
<ul>
<li><code>ComponentX</code> - component of ZF2, top level class</li>
<li><code>SubcomponentX</code> - subcomponent ComponentX</li>
<li><code>PluginX</code> - loadable plugin for component or subcomponent (Adapter, Reader, Writer etc)</li>
</ul>

<h2>Requirements</h2>
<p>This section proposes standards to be marked as <strong>MUST</strong>, <strong>MUST NOT</strong>, <strong>SHOULD</strong> and <strong>SHOULD NOT</strong> in CS docs. But after discussion some requirements could become recommendations. </p>

<h3>Options</h3>
<p>Options <code>extends Stdlib\Options</code> class should be prefixed with instance it configures (<code>AdapterOptions</code>) and should live in same namespace as instance class. </p>
<ac:macro ac:name="code"><ac:default-parameter>php</ac:default-parameter><ac:plain-text-body><![CDATA[
namespace ComponentX;

// file ComponentX/ComponentX.php
class ComponentX
{}

// file ComponentX/ComponentXOptions.php
class ComponentXOptions
{}

]]></ac:plain-text-body></ac:macro>

<p>There should be no class named <code>Config</code> to avoid confusion with <code>Options</code>. If "config" is a valid term in component's knowledge domain, class name should be prefixed with some word expressing purpose of the config class. </p>

<h3>Exceptions</h3>
<p>Exception classes including ExceptionInterface live in Exception subnamespace of the component (<code>ComponentX\Exception\ExceptionInterface</code>). </p>

<p>Subcomponents that define their own exceptions follow same rule. Exceptions for the subcomponents should extend main cimponent's exceptions</p>

<ac:macro ac:name="code"><ac:default-parameter>php</ac:default-parameter><ac:plain-text-body><![CDATA[
namespace ComponentX\Exceptions;

interface ExceptionInterface
{}
]]></ac:plain-text-body></ac:macro>

<ac:macro ac:name="code"><ac:default-parameter>php</ac:default-parameter><ac:plain-text-body><![CDATA[
namespace ComponentX\SubcomponentY\Exceptions;

use ComponentX\Exceptions\ExceptionInterface as ComponentXExceptionInterface

interface ExceptionInterface extends ComponentXExceptionInterface
{}
]]></ac:plain-text-body></ac:macro>

<h3>Pugin Boker and Loader</h3>
<p>Plugin loading related classes ( <code>PluginBroker</code>, <code>PluginLoader</code> ) should leave one namespace above Plugin class.</p>
<ac:macro ac:name="code"><ac:default-parameter>php</ac:default-parameter><ac:plain-text-body><![CDATA[
namespace ComponentsX\Adapter

class FileAdapter
{}

namespace ComponentsX\Adapter;

class FileAdapter
{}

namespace ComponentsX;

class FileAdapterBroker extends PluginBroker
{}

class FileAdapterLoader extends PluginLoader
{}
]]></ac:plain-text-body></ac:macro>

<h2>Recommendations</h2>
<p>This sections proposes recommendations to be marked as <strong>MAY</strong> in CS docs.</p>

<h3>Factories</h3>
<ul>
<li>Factory class that creates only one type of instance may be prefixed with instance name.
<ac:macro ac:name="code"><ac:default-parameter>php</ac:default-parameter><ac:plain-text-body><![CDATA[
namespace ComponentsX;

class ComponentsXFactory
{
public static function create()
{}
}
]]></ac:plain-text-body></ac:macro></li>
</ul>

<ul>
<li>class that creates several types of instances should be not prefixed
<ac:macro ac:name="code"><ac:default-parameter>php</ac:default-parameter><ac:plain-text-body><![CDATA[
namespace ComponentsX;

class ComponentsXFactory
{
public static function createComponentX()
{}

public static function createAdapter()
{}
}
]]></ac:plain-text-body></ac:macro></li>
</ul>