[Proposal] Recommend using multi-stage build to use composer

[stof]

See https://medium.com/@othillo/adding-composer-to-php-docker-images-using-multi-stage-builds-2a10967ae6c1 for the explanation about this feature.

A common issue with people using this image is that they run composer inside the container generated by this image, which may have different platform packages than their actual runtime. Here are some issues they may face:

• the install fails if they are missing extensions in the composer image (while they are available in their runtime image, which is where the code will be used)
• the install does not fail for missing extensions in the runtime image (for extensions being part of the container image), leading to broken runtime
• the update selects packages for the wrong platform, leading people to stop relying on platform requirements in composer updates (and then asking package maintainers to treat a bump of the min PHP version as a BC break requiring a major version)

[alcohol]

Just to clarify, you're suggesting to add this to the readme/docs that are presented on the Docker hub?

[stof]

There is one drawback though: Composer needs the Zip extension at runtime, and may need VCS tools (if you install from source). When using a multi-stage builds, these are needed in your own image.

[stof]

@alcohol yes, this proposal is about documentation

[alcohol]

Alright, I'm in favor of documenting this 👍 .

But indeed, word of caution should also be added regarding possibly required tooling/extensions.

[alcohol]

Docs can be adjusted by forking https://github.com/docker-library/docs and then changing the files inside the composer directory. Not sure if just anyone can fork and submit though, or if I have to submit it from my fork.

[t3easy]

The multistage build can be used to build the app inside the composer container and copy over the app to the final image. The new --chown flag for COPY (docker 17.09) will take care of the permissions. (Changing permissions in the final image would lead to an additional layer with the size of all changed files).
This way you don't need any vcs tools inside the final image.

[stof]

@t3easy but you have the same drawback than the current usage of a separate container to use Composer: platform packages are based on the PHP runtime added in the composer image, not on your actual PHP runtime, impacting the dependency resolution.
Plus, your solution works only if you use composer only at build time (which is not the case when you want to run composer update or composer require btw). for development tools, you need to be able to have a shell with composer available (which is the case with the current approach using a composer container, and also when copying composer to your own container)

[alcohol]

Does docker-library/docs#1017 suffice for now?