gauthier commented 6 years ago

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.

Links to external references, discussions, issues or RFCs

fanshan commented 6 years ago

Could we change the namespace for tests to Tests\ObjectivePHP\* ?

rflavien commented 6 years ago

@fanshan why should this namespace be plural and not the others ? For consistency I think it's better to name it Test\ObjectivePHP\* as we already have ObjectivePHP\Service\*, ObjectivePHP\Action\*, ObjectivePHP\Middleware\*, ...