Aura for PHP

Contributing

As an open-source project, Aura depends on your skills and talent to help make it better for everyone. Do you want to contribute some code or documentation to Aura? Here's how!

Prerequisites

  1. Install Git and have a Github account. If you are new to Git and Github, this setup guide will help you.

  2. Install PHPUnit for unit tests.

Library Packages

  1. Create a fork of the repository to which you want to contribute.

  2. Clone that fork to your development workstation.

    git clone git@github.com:{$YOUR_USER_NAME}/{$AURA_REPO}.git
cd {$REPO}

  3. From the 2.x branch, create and check out a branch for your new work, then push it to Github:

    git checkout 2.x
git branch {$WORKING_BRANCH}
git checkout {$WORKING_BRANCH}
git push --set-upstream origin {$WORKING_BRANCH}

  4. Add the original Aura repository as a remote.

    git remote add upstream https://github.com/auraphp/{$AURA_REPO}.git

  5. Do your work, fixing bugs or adding features.

    • Honor the Aura standards for code

    • Maintain 100% test coverage, adding new tests as needed. (Be wary of making changes to existing tests.)

    • Push your changes early and often.

    • To fetch upstream changes from the original Aura repository and merge them into your working branch:

      git fetch upstream
git merge upstream/2.x

    You may need to resolve conflicts in your working branch after merging.

  6. When all the tests pass and your final push is ready for review, make a pull request from your working branch to the original Aura repository. Be prepared for extensive discussion and revision, and a waiting period before your pull request is merged.

Standards

These are the major standards for code contributions.

  1. Conform to PSR-1 for basic coding standards.

  2. Conform to PSR-2 for coding style, with the following additions that are unspecified by PSR-2:

    1. Variables, properties, array keys, and the like should be in $snake_case and not $camelCase.

    2. Default to the use of the Solar vocabulary for method names.

    3. Do not use public properties on user-defined classes. (Magic __get(), __set(), and so on are allowed to present the appearance of public properties.)

    4. Do not use globals or superglobals (e.g., $_SERVER). Inject them as needed via constructor or method parameters.

    5. The ! operator must be followed by a space; for example, ! isset() instead of !isset().

  3. Conform to PSR-4 for autoloading.

  4. Do not introduce dependencies on any other package.

  5. Maintain 100% test coverage.

  6. Adhere to semantic versioning. Do not introduce backwards compatibility breaks.

  7. A class should either create objects or operate on those objects, never both. This means the new keyword should be used only in Factories and Builders. (The built-in PHP classes, as well as all exceptions, are exempt from this rule)

  8. Prefer explicit configuration over implicit convention.

  9. Default to Dependency Injection instead of Service Locator. If a Service Locator is actually needed, it should locate only one type of object.

  10. Compose functionality through dependency injection, rather than through inheritance and base classes.

  11. Make effective and reasonable use of closures and callable objects, especially for object creation factories.

  12. Keep the README updated with any new or changed features.

Some of those rules may sound crazy to you; to other developers, they might sound like good sense. So if you have questions ...

Questions?

Please feel free to contact the Aura community of developers about the contribution guidelines, or anything else Aura-related. And thanks!