Contributing

Bugs

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

Reporting a Bug

To report a bug, create a new issue for the appropriate library 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.0) of the library's repository with the fix and relevant PHPUnit tests.

Features

We always appreciate when you want to add a new feature to Aphiria. For minor, backwards-compatible features, create a pull request on the latest stable branch (master) of the library's 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.

Aphiria strives to not create any unnecessary library dependencies. This even includes having dependencies on other Aphiria libraries. If your change will introduce a new dependency to a library, create an issue and ask about it before implementing it.

Security Vulnerabilities

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

Coding Style

Aphiria follows PSR-1 and PSR-2 coding standards and uses PSR-4 autoloading. It uses PHP CS Fixer to enforce code style (available by running composer run-script lint-fix from the terminal).

All PHP files should specify declare(strict_types=1);. Additionally, unless a class is specifically meant to be extended, declare them as final to encourage composition instead of inheritance.

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:

final class Book
{
    /** @var string The title of the book */
    private string $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, Aphiria uses a straightforward approach to naming things.

Variables

All variable names:

Functions/Methods

All function/method names:

Constants

All class constants' names:

Namespaces

All namespaces:

Classes

All class names:

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:

Interfaces

All interface names:

Traits

All trait names: