11. Contributing

11.1. Submitting bugs and feature requests

Bugs and feature requests are tracked on GitHub.

11.2. Coding Standards

When contributing to SmartyBundle you should follow the standards defined in the PSR-0, PSR-1 and PSR-2. documents.

Here’s a short example:

<?php
/**
* This file is part of NoiseLabs-SmartyBundle
*
* NoiseLabs-SmartyBundle is free software; you can redistribute it
* and/or modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation; either
* version 3 of the License, or (at your option) any later version.
*
* NoiseLabs-SmartyBundle 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
* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
* License along with NoiseLabs-SmartyBundle; if not, see
* <http://www.gnu.org/licenses/>.
*
* Copyright (C) 2011-2013 Vítor Brandão
*
* @category    NoiseLabs
* @package     SmartyBundle
* @author      Vítor Brandão <vitor@noiselabs.org>
* @copyright   (C) 2011-2013 Vítor Brandão <vitor@noiselabs.org>
* @license     http://www.gnu.org/licenses/lgpl-3.0-standalone.html LGPL-3
* @link        http://www.noiselabs.org
*/

namespace NoiseLabs\Bundle\SmartyBundle;

/**
 * This class provides X.
 *
 * @author John Doe <john@example.com>
 */
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
     * @return string|null Transformed input
     */
    private function transformText($dummy, $options = array())
    {
        $mergedOptions = array_merge($options, array(
            'some_default' => 'values',
        ));

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

        return $dummy;
    }
}

11.2.1. Structure

  • Add a single space after each comma delimiter;
  • Add a single space around operators (==, &&, ...);
  • 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.

11.2.1.1. Naming Conventions

  • Use camelCase, not underscores, for variable, function and method names, arguments;
  • Use underscores for option, parameter names;
  • Use namespaces for all classes;
  • Suffix interfaces with Interface;
  • Use alphanumeric characters and underscores for file names;

11.2.1.2. Documentation

  • Add PHPDoc blocks for all classes, methods, and functions;
  • Omit the @return tag if the method does not return anything;

11.2.1.3. License

  • SmartyBundle is released under the LGPL-3 license, and the license block has to be present at the top of every PHP file, before the namespace.

11.3. Authors

Vítor Brandão - vitor@noiselabs.org ~ twitter.com/noiselabs ~ blog.noiselabs.org

See also the list of contributors who participated in this project.