Contributing Code

Before Reporting

• Check the documentation to make sure it's not a misuse of the framework;
• Ask on the #support channel of the Symfony Slack if you're not sure it's a bug.

Writing a Good Bug Report

Report the bug on the official issue tracker following these rules:

• Use the title to clearly describe the issue;
• Describe the steps to reproduce the bug with short code examples (a failing unit test is best);
• Give as much detail as possible about your environment (OS, PHP version, Symfony version, enabled extensions);
• If an exception was thrown, include its stack trace as plain text (never a screenshot, so search engines can index it). Redact any sensitive information first;
• If the bug is complex or spans several layers, add a reproducer.

Reproducing the Bug

A bug reproducer is the minimum amount of code needed to trigger the bug. It makes the difference between a bug that's fixed quickly and one that can't be understood.

For a component used outside the framework, a small PHP script is enough:

1
2
3
4
5
6
7
8
9
10
11

// first, run "composer require symfony/validator"
require_once __DIR__.'/vendor/autoload.php';

use Symfony\Component\Validator\Constraints;

$wrongUrl = 'http://example.com/exploit.html?<script>alert(1);</script>';
$urlValidator = new Constraints\UrlValidator();
$urlConstraint = new Constraints\Url();

// this should display an error, but it displays "null" instead
var_dump($urlValidator->validate($wrongUrl, $urlConstraint));

For a bug in the framework, create a minimal project, push it to a new GitHub repository and link it in your issue:

1

$ composer create-project symfony/skeleton bug_app

The key is to add only the code needed to reproduce the bug: don't copy your whole application. Start from the feature you suspect (a route, a service, an event listener...), add the smallest possible code that shows the bug, and use the Symfony CLI (symfony server:start) to check it. Keep adding small changes until the bug appears.

Getting a Stack Trace

A stack trace shows the trail of function calls that led to an exception. When reporting an exception, always include the plain text stack trace.

In your Web Browser

Symfony's exception page provides the Stack Trace in plain text, ready to paste into a bug report (remember to remove sensitive data):

1

$ php bin/console --verbose your:command

1
2
3

$ curl --head http://localhost:8000/api/posts/1
…
X-Debug-Token-Link: http://localhost:8000/_profiler/110e1e

Get the Source Code

1. Create a GitHub account and sign in.
2. Fork the Symfony repository (click the "Fork" button). This creates your own copy of Symfony where you can push your changes.

3. Clone your fork locally (this creates a symfony/ directory):

   1

   $ git clone git@github.com:YOUR_USERNAME/symfony.git

4. Add the original repository as a remote called upstream. You'll use it to keep your fork up to date:

   1
   2

   $ cd symfony/
   $ git remote add upstream https://github.com/symfony/symfony.git

Now check that everything works by running the test suite.

Test your Changes in a Real Project

To try your Symfony changes inside an existing project, use the link script included in the repository. It replaces the Symfony packages in your project's vendor/ directory with symbolic links to your local Symfony clone:

1
2

$ cd symfony/
$ php link /path/to/your/project

Make sure the project's dependencies are installed (composer install) before running it. Use --copy if your environment can't resolve symlinks, and --rollback to restore the original dependencies when you're done.

Choose the Branch

Create a topic branch off the branch you chose. Use a descriptive name (fix_XXX, where XXX is the issue number, is a good convention for bug fixes):

1
2

$ git fetch upstream
$ git checkout -b fix_XXX upstream/6.4

Make your Change

Work on the code and commit as much as you want, keeping these rules in mind:

• Follow the coding standards and conventions (run PHP CS Fixer to fix code style automatically);
• Add tests that prove the bug is fixed or the feature works;
• Never break backward compatibility (see the BC promise);
• Don't edit files unrelated to your change (e.g. to fix coding standards) because it makes the review harder.

Write good commit messages. Start with a short subject line: the affected component, bridge or bundle in square brackets, then a capitalized, imperative sentence with no trailing period. Add a blank line and a longer description if needed. For example:

1

[HttpClient] Add support for streaming large responses

If your change is a new feature or changes existing behavior, also update:

• the relevant CHANGELOG.md file(s) (prefix the entry with [BC BREAK] or [DEPRECATION] when relevant);
• the relevant UPGRADE-*.md file(s) if you break backward compatibility or deprecate something.

Submit your Pull Request

Update your branch with the latest changes from upstream and resolve any conflict (replace 6.4 with the branch you chose):

1
2

$ git fetch upstream
$ git rebase upstream/6.4

Then push your branch to your fork:

1

$ git push origin fix_XXX

Now open a pull request on the symfony/symfony repository, targeting the branch you chose (e.g. 6.4). The PR description contains a table you must fill in; some answers add requirements:

• Bug fix? Reference the related issue(s), if any.
• BC breaks / Deprecations? Update the relevant CHANGELOG.md and UPGRADE-*.md files.

Give as much detail as possible in the description: it helps the review and becomes part of the permanent record when the PR is merged. If the code isn't finished yet, open the PR as a draft so reviewers know it's still in progress.

Receiving Feedback

We ask all contributors to follow some review best practices to keep feedback constructive. The core team decides which PRs get merged, so their feedback is the most relevant. Don't feel pressured to apply every suggestion immediately. If you receive feedback you find abusive, contact the CARE team.

1
2

$ git rebase upstream/6.4
$ git push --force origin fix_XXX

Before Running the Tests

To run the Symfony test suite, install the external dependencies used during the tests, such as Doctrine, Twig and Monolog. To do so, install Composer and execute the following:

1

$ composer update

1

$ COMPOSER_ROOT_VERSION=7.4.x-dev composer update

Running the Tests

Then, run the test suite from the Symfony root directory with the following command:

1

$ php ./phpunit symfony

The output should display OK. If not, read the reported errors to figure out what's going on and if the tests are broken because of the new code.

1

$ php ./phpunit src/Symfony/Component/Finder/

Testing Generated Code

Some tests generate code on the fly and verify that it matches the expected output stored in a file. To regenerate those files, run the tests with the environment variable TEST_GENERATE_FIXTURES set to 1:

1

$ TEST_GENERATE_FIXTURES=1 php ./phpunit src/Symfony/Component/Config/Tests/Builder/GeneratedConfigTest.php