Merge pull request #264 from defuse/phar-create

Phar Building

.gitignore

@@ -1 +1,11 @@
-test/unit/File/big-generated-file
+*~
+/test/unit/File/big-generated-file
+/composer.lock
+/vendor
+defuse-crypto.phar
+defuse-crypto.phar.sig
+composer.phar
+box.phar
+phpunit.phar
+phpunit.phar.asc
+test/unit/File/tmp

.travis.yml

@@ -10,4 +10,13 @@ sudo: false
 matrix:
     fast_finish: true
 
-script: ./test.sh
+install:
+    - composer install
+    - curl -LSs https://box-project.github.io/box2/installer.php | php
+    - mkdir ~/box
+    - mv box.phar ~/box/box
+
+script:
+    - ./test.sh
+    - PATH=$PATH:~/box/ make -C dist/ build-phar
+    - ./test.sh dist/defuse-crypto.phar

composer.json

@@ -7,15 +7,22 @@
     "authors": [
         {
             "name": "Taylor Hornby",
-            "email": "havoc@defuse.ca"
+            "email": "taylor@defuse.ca",
+            "homepage": "https://defuse.ca/"
+        },
+        {
+            "name": "Scott Arciszewski",
+            "email": "info@paragonie.com",
+            "homepage": "https://paragonie.com"
         }
     ],
     "autoload": {
-        "files": ["autoload.php"]
+        "classmap": ["src"]
     },
     "require": {
-        "php":  ">=5.4.0",
-        "ext-openssl": "*"
+        "paragonie/random_compat": "~2.0",
+        "ext-openssl": "*",
+        "php":  ">=5.4.0"
     },
     "require-dev": {
         "nikic/php-parser": "^2.0"

dist/Makefile

@@ -0,0 +1,37 @@
+# This builds defuse-crypto.phar. To run this Makefile, `box` and `composer`
+# must be installed and in your $PATH. Run it from inside the dist/ directory.
+
+box := $(shell which box)
+composer := "composer"
+
+.PHONY: all
+all: sign-phar
+
+.PHONY: sign-phar
+sign-phar: build-phar
+	gpg -u 7B4B2D98 --armor --output defuse-crypto.phar.sig --detach-sig defuse-crypto.phar
+
+# ensure we run in clean tree. export git tree and run there.
+.PHONY: build-phar
+build-phar:
+	@echo "Creating .phar from revision $(shell git rev-parse HEAD)."
+	rm -rf worktree
+	install -d worktree
+	(cd $(CURDIR)/..; git archive HEAD) | tar -x -C worktree
+	$(MAKE) -f $(CURDIR)/Makefile -C worktree defuse-crypto.phar
+	mv worktree/*.phar .
+	rm -rf worktree
+
+.PHONY: clean
+clean:
+	rm -vf defuse-crypto.phar defuse-crypto.phar.sig
+
+# Inside workdir/:
+
+defuse-crypto.phar: dist/box.json composer.lock
+	cp dist/box.json .
+	php -d phar.readonly=0 $(box) build -c box.json -v
+
+composer.lock:
+	$(composer) install --no-dev
+

dist/box.json

@@ -0,0 +1,24 @@
+{
+    "chmod": "0755",
+    "finder": [
+        {
+            "in": "src",
+            "name": "*.php"
+        },
+        {
+            "in": "vendor/composer",
+            "name": "*.php"
+        },
+        {
+            "in": "vendor/paragonie",
+            "name": "*.php",
+            "exclude": "other"
+        }
+    ],
+    "compactors": [
+        "Herrera\\Box\\Compactor\\Php"
+    ],
+    "main": "vendor/autoload.php",
+    "output": "defuse-crypto.phar",
+    "stub": true
+}

docs/InstallingAndVerifying.md

@@ -4,7 +4,7 @@ Getting The Code
 There are two ways to use this library in your applications. You can either:
 
 1. Use [Composer](https://getcomposer.org/), or
-2. `require_once()` a single `.phar` file in your application.
+2. `require_once` a single `.phar` file in your application.
 
 Option 1: Using Composer
 -------------------------
@@ -23,16 +23,20 @@ Option 2: Including a PHAR
 ----------------------------
 
 The `.phar` option lets you include this library into your project simply by
-calling `require_once()` on a single file. Simply check out the tag with the
-version you want, for example for version 2.0.0 you would do:
-
-```
-git checkout v2.0.0
-```
+calling `require_once` on a single file. Download `defuse-crypto.phar` and
+`defuse-crypto.phar.sig` from this project's
+[releases](https://github.com/defuse/php-encryption/releases) page.
+
+You should verify the integrity of the `.phar`. The `defuse-crypto.phar.sig`
+contains the signature of `defuse-crypto.phar`. It is signed with Taylor
+Hornby's PGP key. You can find Taylor's public key in `dist/signingkey.asc`. You
+can verify the public key's fingerprint against the Taylor Hornby's [contact
+page](https://defuse.ca/contact.htm) and
+[twitter](https://twitter.com/DefuseSec/status/723741424253059074).
 
-You'll find the `.phar` file for that release in `dist/defuse-crypto.phar`.
-Install it to somewhere on your filesystem, e.g.
-`/var/www/lib/defuse-crypto.phar`. You can now use it in your code like this:
+Once you have verified the signature, it is safe to use the `.phar`. Place it
+somewhere in your file system, e.g. `/var/www/lib/defuse-crypto.phar`, and then
+pass that path to `require_once`.
 
 ```php
 <?php
@@ -45,10 +49,3 @@ Install it to somewhere on your filesystem, e.g.
     // ...
 ```
 
-You should verify the integrity of the `.phar`. It is signed with Taylor
-Hornby's PGP key. The signature file is `dist/defuse-crypto.phar.sig`. You can
-find Taylor's public key in `other/signingkey.asc.
-
-You can verify the public key's fingerprint against the Taylor Hornby's [contact
-page](https://defuse.ca/contact.htm) and
-[twitter](https://twitter.com/DefuseSec/status/723741424253059074).

docs/InternalDeveloperDocs.md

@@ -16,12 +16,14 @@ following tools installed:
 
 - `php` (with OpenSSL enabled, if you're compiling from source).
 - `gpg`
+- `composer`
 
 Running the Tests
 ------------------
 
-Simply run `./test.sh`. This will download a PHPUnit PHAR, verify its
-cryptographic signatures, and then use it to run the tests in `test/unit`.
+First do `composer install` and then you can run the tests by running
+`./test.sh`. This will download a PHPUnit PHAR, verify its cryptographic
+signatures, and then use it to run the tests in `test/unit`.
 
 Reporting Bugs
 ---------------
@@ -72,6 +74,14 @@ This library is developed around several core values:
 Publishing Releases
 --------------------
 
+To make a release, you will need to install [composer](https://getcomposer.org/)
+and [box](https://github.com/box-project/box2) on your system. They will need to
+be available in your `$PATH` so that running the commands `composer` and `box`
+in your terminal run them, respectively. You will also need the private key for
+signing (ID: 7B4B2D98) available.
+
+Once you have those tools installed and the key available follow these steps:
+
 Make a fresh clone of the repository:
 
 ```
@@ -84,11 +94,23 @@ Check out the branch you want to release:
 git checkout <branchname>
 ```
 
-Run the sign-release script (note this will make a commit on your current
-branch):
+Generate and sign the `.phar`:
 
 ```
-./other/sign-release.sh <tagname> <tagmessage>
+cd dist
+make
 ```
 
-Push the branch and tag up to GitHub.
+Tag the release:
+
+```
+git -c user.signingkey=7B4B2D98 tag -s "<TAG NAME>" -m "<TAG MESSAGE>"
+```
+
+`<TAG NAME>` should be in the format `v2.0.0` and `<TAG MESSAGE>` should look
+like "Release of v2.0.0."
+
+Push the tag to github, then use the
+[releases](https://github.com/defuse/php-encryption/releases) page to draft
+a new release for that tag. Upload the `.phar` and the `.phar.sig` file to be
+included as part of that release.