Browse Source

Elaborated on importance of PHP extension dependencies

@Seldaek: As discussed yesterday here addition to the docs re PHP extensions. I have put it as a note as it appears emphasized for users to notice easily.
vbashkirtsev 8 years ago
parent
commit
eb494e5464
1 changed files with 19 additions and 1 deletions
  1. 19 1
      doc/04-schema.md

+ 19 - 1
doc/04-schema.md

@@ -328,7 +328,9 @@ a constraint that it otherwise would not. For more information [see the
 aliases article](articles/aliases.md).
 
 `require` and `require-dev` also support references to specific PHP versions
-and PHP extensions your project needs to run successfully.
+and PHP extensions your project needs to run successfully. If PHP extension
+is not strictly required by your project but may improve its performance/functionality
+it is recommended to list such PHP extension in `suggest`.
 
 Example:
 
@@ -337,10 +339,26 @@ Example:
     "require" : {
         "php" : "^5.5 || ^7.0",
         "ext-mbstring": "*"
+    },
+    "suggest" : {
+        "ext-XCache": "Opcode cache to improve performance"
     }
 }
 ```
 
+> **Note:** It is important to list PHP extensions your project uses,
+> especially when your project targeted at wider audience. Not all PHP
+> installations are created equal: some may miss extensions you may consider
+> as standard (such as `ext-mysqli` which is not installed by default in
+> Fedora/CentOS minimal installation systems). Failure to list used PHP
+> extension may lead to bad user experience: composer will install your
+> project without any errors just for your project to fail at run-time.
+> `composer show --platform` command lists all PHP extensions available on
+> your system. You may use it to help you to compile the list of extensions to
+> be included in composer.json. Alternatively you may use third party tools
+> to analyze your project for the list of extensions used.
+
+
 #### require
 
 Lists packages required by this package. The package will not be installed