Coding Standards #1
Description
ObjectivePHP RFC:
- Version: 2.0.0
- Date: 2017-01-09
- Author: Gauthier Delamarre gauthier@objective-php.org
- Status: Draft
Summary
As the second version of ObjectivePHP should be focused on cleaning the existing code base and normalizing components, I suggest to write down coding recommendations regarding style and naming to help making components more consistent across the framework.
Proposal
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD",
"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be
interpreted as described in RFC 2119.
Code style
Every file MUST be formatted according to PSR-2. Once (and if) it is released, PSR-12 MUST be used in place.
Note: as PSR-2 implementations may vary in different checkers/fixers, we suggest to rely on php-cs ruleset as reference. Thus, it is highly recommended to contributors to setup their development tools to check or fix code styles using php-cs or php-cs-fixer before committing.
Files naming
When not specified in PSR, files SHOULD be named using lowercase letters, multiple words being separated using a dash (-).
Namespaces
The root namespace of core components MUST be ObjectivePHP.
Third-party components MUST NOT use this namespace.
The first subnamespace SHOULD reflect the component name as close as possible. Example:
<?php
// Services Factory component
namespace ObjectivePHP\ServicesFactory;Packages
Official Packages MUST be located in ObjectivePHP\Package namespace.
Obviously, third-party packages MUST NOT be located in this namespace.
Also, a package class MUST be located in its root namespace, and end with the word 'Package'. Example:
<?php
// Phinx package - src/PhinxPackage.php
namespace ObjectivePHP\Package\Phinx;
class PhinxPackage
{
}Exceptions
All exception classes SHOULD be located under RootNamespace\Exception namespace.
Exception classes MUST NOT be named Exception. They all MUST be named in a descriptive way and SHOULD end by Exception.
Every components MUST provide a root exception class, named after the component itself. This root exception class MAY or MAY NOT extend another exception from ObjectivePHP.
Other exceptions provided by the component MUST extend the components root exception.
Example:
<?php
namespace ObjectivePHP\Router\Exception;
class RouterException extends \Exception
{
}
class RouteNotFoundException extends RouterException
{
}Events
It's highly recommended to trigger events. If you do so, you SHOULD provide an Interface to expose the triggered events.
Example:
<?php
namespace ObjectivePHP\Cli;
/**
* Interface CliEvent
* @package ObjectivePHP\Cli
*/
interface CliEvent
{
const BEFORE_RUN_ACTION = 'cli.action.run.before';
const AFTER_RUN_ACTION = 'cli.action.run.after';
}Tests
Test suites SHOULD rely under Test\ObjectivePHP namespace.
Test MUST use Codeception framework
Codeception must be required as "dev" dependency
Backward Incompatible Changes
Applying these changes, mostly the "Exceptions" part, will largely break compatibility.
Proposed Objective PHP Version(s)
Targeted framework (and components) version to strictly apply these standards is 2.0.0.
RFC Impact
To Components
Describe the impact to the core components.
To Packages
Describe the impact to the packages.
To Workflow
Describe any new workflow steps and/or steps modifications required by this proposal (if applies), so they can be accurately and comprehensively explained in the framework documentation.
To Configuration
No impact
Future Scope
This sections details areas where the feature might be improved in future, but that are not currently proposed in this RFC.
Proposed Voting Choices
As all changes are bundled in one vote it require a 2/3 majority.