From 3e63ebf7fe3494961423f8d37123c78a1e23cba8 Mon Sep 17 00:00:00 2001
From: Sander Marechal <s.marechal@jejik.com>
Date: Wed, 3 Oct 2012 20:32:00 +0200
Subject: [PATCH] Add stream context options documetation

---
 doc/04-schema.md                              | 15 ++++++-
 doc/05-repositories.md                        |  7 ++++
 .../handling-private-packages-with-satis.md   | 40 +++++++++++++++++++
 3 files changed, 60 insertions(+), 2 deletions(-)

diff --git a/doc/04-schema.md b/doc/04-schema.md
index 5ba680bd8..8f619ee3a 100644
--- a/doc/04-schema.md
+++ b/doc/04-schema.md
@@ -504,8 +504,10 @@ ignored.
 The following repository types are supported:
 
 * **composer:** A composer repository is simply a `packages.json` file served
-  via HTTP, that contains a list of `composer.json` objects with additional
-  `dist` and/or `source` information.
+  via the network (HTTP, FTP, SSH), that contains a list of `composer.json`
+  objects with additional `dist` and/or `source` information. The `packages.json`
+  file is loaded using a PHP stream. You can set extra options on that stream
+  using the `options` parameter.
 * **vcs:** The version control system repository can fetch packages from git,
   svn and hg repositories.
 * **pear:** With this you can import any pear repository into your composer
@@ -524,6 +526,15 @@ Example:
                 "type": "composer",
                 "url": "http://packages.example.com"
             },
+            {
+                "type": "composer",
+                "url": "https://packages.example.com",
+                "options": {
+                    "ssl": {
+                        "verify_peer": "true"
+                    }
+                }
+            },
             {
                 "type": "vcs",
                 "url": "https://github.com/Seldaek/monolog"
diff --git a/doc/05-repositories.md b/doc/05-repositories.md
index c0f70c1e5..a675ab47c 100644
--- a/doc/05-repositories.md
+++ b/doc/05-repositories.md
@@ -148,6 +148,13 @@ hash changed.
 This field is optional. You probably don't need it for your own custom
 repository.
 
+#### stream options
+
+The `packages.json` file is loaded using a PHP stream. You can set extra options
+on that stream using the `options` parameter. You can set any valid PHP stream
+context option. See [Context options and parameters](http://nl3.php.net/manual/en/context.php)
+for more information.
+
 ### VCS
 
 VCS stands for version control system. This includes versioning systems like
diff --git a/doc/articles/handling-private-packages-with-satis.md b/doc/articles/handling-private-packages-with-satis.md
index 722a497ad..e7fa23509 100644
--- a/doc/articles/handling-private-packages-with-satis.md
+++ b/doc/articles/handling-private-packages-with-satis.md
@@ -85,3 +85,43 @@ itself.
             "company/package3": "dev-master"
         }
     }
+
+### Security
+
+To secure your private repository you can host it over SSH or SSL using a client
+certificate. In your project you can use the `options` parameter to specify the
+connection options for the server.
+
+Example using a custom repository using SSH (requires the SSH2 PECL extension):
+
+    {
+        "repositories": [
+            {
+                "type": "composer",
+                "url": "ssh2.sftp://example.org",
+                "options": {
+                    "ssh2": {
+                        "username": "composer",
+                        "pubkey_file": "/home/composer/.ssh/id_rsa.pub",
+                        "privkey_file": "/home/composer/.ssh/id_rsa"
+                    }
+                }
+            }
+        ]
+    }
+
+Example using HTTP over SSL using a client certificate:
+
+    {
+        "repositories": [
+            {
+                "type": "composer",
+                "url": "https://example.org",
+                "options": {
+                    "ssl": {
+                        "cert_file": "/home/composer/.ssl/composer.pem",
+                    }
+                }
+            }
+        ]
+    }