Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
144 lines (95 loc) · 3.54 KB

CONTRIBUTING.md

File metadata and controls

144 lines (95 loc) · 3.54 KB

Contributing to graphql-php

Workflow

If your contribution requires significant or breaking changes, or if you plan to propose a major new feature, we recommend you to create an issue with a brief proposal and discuss it with us first.

For smaller contributions just use this workflow:

  • Fork the project.
  • Add your features and or bug fixes.
  • Add tests to ensure your changes work and will continue working.
  • Check your changes using composer check.
  • Add an entry to the Changelog's Unreleased section.
  • Send a pull request.

Setup

git clone <your-fork-url>
cd graphql-php
composer install

Testing

We ensure the code works and continues to work as expected with PHPUnit.

Run unit tests:

composer test

Some tests have an annotation such as @see it('<description>'). It references a matching test in the graphql-js implementation.

When porting tests that utilize the dedent() test utility from graphql-js, we instead use the PHP native nowdoc syntax. If the string contents are in a specific grammar, use an appropriate tag such as GRAPHQL, PHP or JSON:

self::assertSomePrintedOutputExactlyMatches(
    <<<'GRAPHQL'
    type Foo {
      bar: Baz
    }

    GRAPHQL,
    $output
);

Coding Standard

We format the code automatically with php-cs-fixer.

Apply automatic code style fixes:

composer fix

Multiline Ternary Expressions

Ternary expressions must be spread across multiple lines.

$foo = $cond
    ? 1
    : 2;

Extensibility

We cannot foresee every possible use case in advance, extending the code should remain possible.

protected over private

Always use class member visibility protected over private.

Late Static Binding

Always use static:: over self:: for method calls to enable overriding of static class methods.

final classes

Prefer final classes in tests, but never use them in src.

Static Analysis

We validate code correctness with PHPStan.

Run static analysis:

composer stan

Regenerate the PHPStan baseline:

composer baseline

Type Assertions

When control flow or native types are insufficient to convince the IDE or PHPStan that a value is of a certain type, but you know it must be due to some invariant, you may assert its type. Prefer assert() for simple types and only use @var for complex types:

function identity($value) { return $value; }

$mustBeInt = identity(1);
assert(is_int($mustBeInt));

/** @var array<string, int> $mustBeArrayOfStrings */
$mustBeArrayOfStringsToInts = identity(['foo' => 42]);

Running Benchmarks

We benchmark performance critical code with PHPBench.

Check performance:

composer bench

Documentation

We document this library by rendering the Markdown files in docs with MkDocs.

You may propose changes to the docs via merge requests against the master branch. Do not edit the generated HTML files in the gh-pages branch directly, they are automatically generated.

Generate the class reference docs:

composer docs