Development guidelines

Issues and pull requests

When opening new issues, please correctly tag the version where you're experiencing the problem (if it is indeed about a problem) or indicate how urgently you need a new feature (if it is about a feature). Please use GitHub's issue tags accordingly. If possible, indicate where in the codebase the issue is present and, if possible, propose a fix.

To submit your fix or a new feature implementation, please fork the repo and open a pull request. Any CI builds must pass (or not be broken further if they're already broken) when you submit your pull request.

Coding Standards

Intro

This section is derived from Symfony's coding standards recommendations.

When contributing code to lxHive, you must follow its coding standards.

Remember that the main advantage of standards is that every piece of code looks and feels familiar.

lxHive follows the standards defined in the

• PSR-0,
• PSR-1 and
• PSR-2 documents.

Some code is worth a thousand words. Here is a short example containing most features described below:

<?php

/*
 * This file is part of lxHive LRS - http://lxhive.org/
 *
 * Copyright (C) 2018 G3 International
 *
 * This program is free software: you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with lxHive. If not, see <http://www.gnu.org/licenses/>.
 *
 * For authorship information, please view the AUTHORS
 * file that was distributed with this source code.
 */

namespace Acme;

/**
 * Coding standards demonstration.
 */
class FooBar
{
    const SOME_CONST = 42;

    private $fooBar;

    /**
     * @param string $dummy Some argument description
     */
    public function __construct($dummy)
    {
        $this->fooBar = $this->transformText($dummy);
    }

    /**
     * @param string $dummy Some argument description
     * @param array  $options
     *
     * @return string|null Transformed input
     *
     * @throws \RuntimeException
     */
    private function transformText($dummy, array $options = array())
    {
        $mergedOptions = array_merge(
            array(
                'some_default' => 'values',
                'another_default' => 'more values',
            ),
            $options
        );

        if (true === $dummy) {
            return;
        }

        if ('string' === $dummy) {
            if ('values' === $mergedOptions['some_default']) {
                return substr($dummy, 0, 5);
            }

            return ucwords($dummy);
        }

        throw new \RuntimeException(sprintf('Unrecognized dummy option "%s"', $dummy));
    }

    private function reverseBoolean($value = null, $theSwitch = false)
    {
        if (!$theSwitch) {
            return;
        }

        return !$value;
    }
}

Project structure

• We strictly follow a MVCS (Model-View-Controller-Service) pattern.

Models in this case are the Collections and Document namespaces, Views are in the View namespace, the Controllers are in the Resources namespace and the Services are in the Service namespace.

• Follow the SOLID principles of object-oriented design.

File structure

• Add a single space after each comma delimiter;
• Add a single space around binary operators (==, &&, ...), with the exception of the concatenation (.) operator;
• Place unary operators (!, --, ...) adjacent to the affected variable;
• Add a comma after each array item in a multi-line array, even after the last one;
• Add a blank line before return statements, unless the return is alone inside a statement-group (like an if statement);
• Use braces to indicate control structure body regardless of the number of statements it contains;
• Define one class per file - this does not apply to private helper classes that are not intended to be instantiated from the outside and thus are not concerned by the PSR-0 standard;
• Declare class properties before methods;
• Declare public methods first, then protected ones and finally private ones. The exceptions to this rule are the class constructor and the setUp and tearDown methods of PHPUnit tests, which should always be the first methods to increase readability;
• Use parentheses when instantiating classes regardless of the number of arguments the constructor has;
• Exception message strings should be concatenated using sprintf.

Naming Conventions

• Use camelCase, not underscores, for variable, function and method names, arguments;
• Use underscores for option names and parameter names;
• Use namespaces for all classes;
• Prefix abstract classes with Abstract.
• Suffix interfaces with Interface;
• Suffix traits with Trait;
• Suffix exceptions with Exception;
• Use alphanumeric characters and underscores for file names;
• For type-hinting in PHPDocs and casting, use bool (instead of boolean or Boolean), int (instead of integer), float (instead of double or real);
• Don't forget to look at the more verbose conventions document for more subjective naming considerations.

Documentation

• Add PHPDoc blocks for all classes, methods, and functions;
• Omit the @return tag if the method does not return anything;
• The @package and @subpackage annotations are not used.

License

lxHive is released under the GPLv3 license. The license block has to be present at the top of every PHP file, before the namespace.