Add parameters details for Heroku

[weaverryan]

Hey guys!

A friend of mine was using Heroku with Symfony and got it all working nicely, except for handling parameters.yml. I realized that how parameters should be handled is not covered in our document. I believe that environment variables should be used.

[stof]

Indeed, environment variables are the best way to handle it (which is why the ParameterHandler supports mapping environment variables to parameters btw)

[bicpi]

Hi,
I was doing some stuff on Heroku the last weeks and I would like to help. Several other topics came along my way. As it is difficult to figure out where to put things in the docs, I would like to know your thoughts before I start writing.

There may be two possible sections for these things:

1. Existing Heroku cookbook: http://symfony.com/doc/current/cookbook/deployment/heroku.html
2. A currently missing section/cookbook about parameters.yml/parameters.yml.dist and the ParameterHandler

The env-map feature of the ParameterHandler is not Heroku specific topic so it may be explained in another context and then we can link to it from the Heroku cookbook?

Some more issues/tipps with Heroku:

• If you follow the Symfony cookbook or the Heroku docs, your first deployment with Symfony 2.5+ currently fails with an Exception saying that the SensioGeneratorBundle cannot be found. It's because this bundle dep has move to require-dev in composer.json and Heroku executes Composer with the --no-dev flag. @dzuelke recommended to move the dep to the require section to solve this. Seems a bit odd because you then have a dev dep installed on your stage/prod machine but I don't know of it's better/easier to recommend not to push a dev env or to create a new local environment and change the Kernel code a bit. Makes things complicated.
• You can use the SYMFONY_ENV environment variable to set a default environment for CLI commands
• Beside the env-map feature there also an approach using a parameters.php file, see http://www.christophh.net/2013/10/19/sylius-on-heroku. Should we only suggest the env-map approach?
• What about recommending the https://github.com/CHH/heroku-buildpack-php from @CHH with Symfony support instead of the default one?

Last point allows answering questions like "What should be the best practice to properly execute things like installing Assetic assets during the build?" (environment comes from SYMFONY_ENV):

"extra": {
    …
    "heroku": {
        "compile": [
            "php app/console assetic:dump"
        ]
    }
}

Please let me know.

[stof]

The env-map feature of the ParameterHandler is not Heroku specific topic so it may be explained in another context and then we can link to it from the Heroku cookbook?

Well, it is explained in the documentation of the ParameterHandler for people susing it in other contexts. The symfony documentation is not the main documentation of the library.

What about recommending the https://github.com/CHH/heroku-buildpack-php from @CHH with Symfony support instead of the default one?

We should at least mention it, as some things are indeed better using it currently (even though the goal would be that the official buildpack reaches parity on such support so that we can deprecate the CHH buildpack)

[javiereguiluz]

Let's recap the things to do in this PR:

1. Use SYMFONY_ENV parameters (done in [Hackday] Update Heroku doc with SYMFONY_ENV param #4545 and Instructions for setting SYMFONY_ENV on Heroku #4591)
2. Explain the env-map feature (won't fix because it's documented in the ParameterHandler)
3. How to do things like compiling Assetic assets during deploy (compile option of the heroku option in the extra section of composer.json)
4. Solve the problems caused by required dev dependencies (such as SensioGeneratorBundle) ([Cookbook] Custom compile steps on Heroku #5088)
5. Explain parameters.yml parameters.yml.dist` (done in [DX] Quick entry about parameters.yml and parameters.yml.dist #4174)

In my opinion, we just have to tackle 3 and 4 in /cookbook/deployment/heroku. @bicpi are you still interested (and motivated) to work on this? Thanks.

[dzuelke]

How to do things like compiling Assetic assets during deploy (compile option of the heroku option in the extra section of composer.json)

That's specific to @CHH's now unmaintained buildpack. For the official Heroku buildpack, just use a compile script in composer.json, see https://devcenter.heroku.com/articles/php-support#custom-compile-step

[dzuelke]

Solve the problems caused by required dev dependencies (such as SensioGeneratorBundle)

That should never be a problem because your code shouldn't use it with the right environment set. You just need to make sure you heroku config:set SYMFONY_ENV=prod. That's also @fabpot's officially sanctioned way of doing it.

[bicpi]

@javiereguiluz Yes, still interested and motivated. Heroku's PHP support has improved a lot in the last few months so I'm going to check the open items.

[bicpi]

Solve the problems caused by required dev dependencies (such as SensioGeneratorBundle)

@javiereguiluz Mh, this is not an issue any more if you follow the best practice to use Heroku with a non-dev environment, e.g. if you set the prod environment as default. As Heroku uses composer install --no-dev it is not possible to run a dev environment without changes to the composer.json if the dev environment makes use of dev dependencies. Is there a use case to run a dev environment on Heroku, does it makes sense?

[dzuelke]

The only open item for asset compiles is described here: https://devcenter.heroku.com/articles/php-support#build-behavior

[bicpi]

@dzuelke Thanks, already discovered it.

I'll add a note about this and a short one about --no-dev implications and then this ticket can be closed. Hope that sounds good.

[weaverryan]

Closing this - all the todos are "completed" - either have PR's or have open issues.

Thanks!