Contributing

Table of Contents

1. Bugs
   1. Reporting a Bug
   2. Fixing a Bug
2. Features
3. Security Vulnerabilities
4. Coding Style
   1. PHPDoc
5. Naming Conventions
   1. Variables
   2. Functions/Methods
   3. Constants
   4. Namespaces
   5. Classes
   6. Abstract Classes
   7. Interfaces
   8. Traits

Bugs

Before you attempt to write a bug fix, first read the documentation to see if you're perhaps using Opulence incorrectly.

Reporting a Bug

To report a bug, create a new issue with a descriptive title, steps to reproduce the bug (eg a failing PHPUnit test), and information about your environment.

Fixing a Bug

To fix a bug, create a pull request on the latest stable branch (1.2) of the main Opulence repository with the fix and relevant PHPUnit tests.

Features

We always appreciate when you want to add a new feature to Opulence. For minor, backwards-compatible features, create a pull request on the latest stable branch (1.2) of the main Opulence repository. Do not submit pull requests to individual libraries' repositories. For major, possibly backwards-incompatible features, create a pull request on the develop branch. All new features should come with PHPUnit tests proving their functionality. Pull requests should never be sent to the master branch.

Opulence strives to not create any unnecessary library dependencies. This even includes having dependencies on other Opulence libraries. If your change will introduce a new dependency to a library, create an issue and ask about it before implementing it. If your feature is a useful combination of multiple Opulence libraries, it's possible it'll be recommended to go into the Opulence\Framework library.

Security Vulnerabilities

Opulence takes security seriously. If you find a security vulnerability, please email us at bugs@opulencephp.com.

Coding Style

Opulence follows PSR-1 and PSR-2 coding standards and uses PSR-4 autoloading. It uses StyleCI to automatically enforce code style, so you don't have to worry about that. If you'd like to run the formatter locally, a config for the PHP CS Fixer is bundled with Opulence.

PHPDoc

Use PHPDoc to document all class properties, methods, and functions. Constructors only need to document the parameters. Method/function PHPDoc must include one blank line between the description and the following tag. Here's an example:

class Book
{
    /** @var string The title of the book */
    private $title;

    /**
     * @param string $title The title of the book
     */
    public function __construct(string $title)
    {
        $this->setTitle($title);
    }

    /**
     * Gets the title of the book
     *
     * @return string The title of the book
     */
    public function getTitle() : string
    {
        return $this->title;
    }

    /**
     * Sets the title of the book
     *
     * @param string $title The title of the book
     * @return $this For object chaining
     */
    public function setTitle(string $title) : self
    {
        $this->title = $title;

        return $this;
    }
}

Naming Conventions

Inspired by Code Complete, Opulence uses a straightforward approach to naming things.

Variables

All variable names:

• Must be lower camel case, eg $emailAddress
• Must NOT use Hungarian Notation

Functions/Methods

All function/method names:

• Must be succinct
  • Your method name should describe exactly what it does, nothing more, and nothing less
  • If you are having trouble naming a method, that's probably a sign that it is doing too much and should be refactored
• Must be lower camel case, eg compileList()
  • Acronyms in function/method names ≤ 2 characters long, capitalize each character, eg startIO()
  • "Id" is an abbreviation (not an acronym) for "Identifier", so it should be capitalized Id
• Must answer a question if returning a boolean variable, eg hasAccess() or userIsValid()
  • Always think about how your function/method will be read aloud in an if statement. if (userIsValid()) reads better than if (isUserValid()).
• Must use getXXX() and setXXX() for functions/methods that get and set properties, respectively
  • Don't name a method that returns a username username(). Name it getUsername() so that its purpose is unambiguous.

Constants

All class constants' names:

• Must be upper snake case, eg TYPE_SUBSCRIBER

Namespaces

All namespaces:

• Must be Pascal case, eg Opulence\QueryBuilders
  • For namespace acronyms ≤ 2 characters long, capitalize each character, eg IO

Classes

All class names:

• Must be succinct
  • Your class name should describe exactly what it does, nothing more, and nothing less
  • If you are having trouble naming a class, that's probably a sign that it is doing too much and should be refactored
• Must be Pascal case, eg ListCompiler
  • For class name acronyms ≤ 2 characters long, capitalize each character, eg IO
  • Class filenames should simply be the class name with .php appended, eg ListCompiler.php

Class properties should appear before any methods. The following is the preferred ordering of class properties and methods:

Properties

1. Constants
2. Public static properties
3. Public properties
4. Protected static properties
5. Protected properties
6. Private static properties
7. Private properties

Methods

1. Magic methods
2. Public static methods
3. Public abstract methods
4. Public methods
5. Protected static methods
6. Protected abstract methods
7. Protected methods
8. Private static methods
9. Private methods

Note: Methods of the same visibility should be ordered alphabetically.

Abstract Classes

All abstract class names:

• Must be Pascal case, eg ConnectionPool
• Must NOT use Abstract, Base, or any other word in the name that implies it is an abstract class

Interfaces

All interface names:

• Must be preceded by an I, eg IUser

Traits

All trait names:

• Must be Pascal case, eg ListValidator
• Must be NOT use T, Trait, or any other word in the name that implies it is a trait