Improve readme, prepare 2.2.4

CHANGELOG.md

@@ -2,9 +2,14 @@
 
 See README.md for info about version numbering. Follows https://keepachangelog.com/en/1.0.0/
 
+## 2.2.4 - 2018-09-24
+### Added
+- bug fixes for LocationMessage: after conversations with Threema support staff
+- improved README.md
+
 ## 2.2.3 - 2018-08-15
 ### Added
-- unofficial support for LocationMessage: reverse engineered from the message format. Not documented by Threema
+- unofficial support for receiving LocationMessage: reverse engineered from the message format. Not documented by Threema
 
 ## 2.2.2 - 2018-08-15
 ### Changed

README.md

@@ -7,17 +7,29 @@ You have four other alternatives
 * Use the official Threema github repo https://github.com/threema-ch/threema-msgapi-sdk-php. No longer maintained (Oct 2015)
 * Download the .zip file version from https://gateway.threema.ch/. Currently v1.1.7 Oct 2016. Missing the Bulk Lookup api.
 * Use an unofficial version which stays close to the official version, occasionally has patches accepted by Threema https://github.com/rugk/threema-msgapi-sdk-php. It has an [`official`](https://github.com/rugk/threema-msgapi-sdk-php/tree/official) branch which mirrors the official version. Rugk has done a ton of great work to move the package forward into the modern ecosystem while maintaining as much backwards compatibility as possible.
-* Use https://github.com/chillerlan/php-threema which is a separate implementation (Jun 2017) and missing some functionality. The API is cleaner / more logical in some places 
+* Use https://github.com/chillerlan/php-threema which is a separate implementation (Jun 2017) and missing some functionality. The API is cleaner / more logical in some places than the above alternatives. 
 
 Why build another one?
 
-* PHP7.2 has libsodium compiled in. If we target 7.2 as the minimum version, a whole lot of complicated code from the official version is no longer needed. We can delete the older PECL sodium drivers and the driver selection code. The Salt git submodule is no longer needed.
+* PHP7.2 has **libsodium** compiled in. If we target 7.2 as the minimum version, a whole lot of complicated code from the official version is no longer needed. We can delete the older PECL sodium drivers and the driver selection code. The Salt git submodule is no longer needed.
 * Composer means that we can delete the phar command line runner, delete the two autoloaders that `require` a lot of files and do static initialisation for every page load (even if Threema is not being used) 
 * Fix some of the problems caused by the above, plus some broken type hints (for phpStorm), and split the (small number of) unit tests out to a separate `/tests` directory so they do not clutter an authoritative classmap
-* Add the missing bulk lookup function (not implemented in PHP, hard to add by subclassing one of the alternatives because some important methods on the Connection class are private)
-* In general, try to adhere to modern php package standards so that it is more comfortable to use this in other projects. 
-* Fix some of the architectural issues so it is easier to test and allows for dependency injection. 
-* Working towards a [botman](https://github.com/botman/botman) integration / plugin 
+* Add the missing **bulk lookup** function (hard to add by subclassing one of the alternatives)
+* Add support for additional undocumented message types eg Location.
+* In general, try to adhere to modern **php package conventions** so that it is more comfortable to use this in other projects. 
+* Fix some of the architectural issues so it is easier to test and allows for dependency injection.
+* Make the api more consistent: eg it was hard to know when to pass a binary value or a hex encoded value.
+* Simplify the api: remove or wrap helper classes to reduce complexity
+
+In summary, what is new
+
+* PHP7.2+ only (libsodium)
+* Simple package following modern conventions
+* Composer support: clean autoloader
+* Dependencies injected
+* Symfony Console commands for familiar use and easier integration within a bigger app
+* Supports Bulk Lookup API call
+* Supports receiving Location message type (not publicly documented)
 
 Versioning
 
@@ -28,16 +40,17 @@ The contributors of this repository are not affiliated with Threema or the Three
 ## Installation
 
 ```
-composer install lss\threema-gateway
+composer install lss/threema-gateway
 ```
 
 If you want to check whether your server meets the requirements and everything is configured properly, run `vendor/bin/threema-gateway` without any parameters on the console. It should show a list of commands if it is working, or an error message if not. 
 
 ## SDK usage
 
+* Follow the documentation below to create a new key pair. Save these carefully and keep them secret. Do not make them accessible via the web. 
 * Go to https://gateway.threema.ch/ and create an account.
-* Follow the documentation there to create a new key pair. Save these carefully and keep them secret. Do not make them accessible via the web.
-* You will choose your Threema ID, which starts with a * and is a total of 8 characters long eg *MYKEY12
+* You will choose your Threema ID, which starts with a * and is a total of 8 characters long eg *MYKEY12.
+* Upload your public key.
 * Your API Secret is shown by your account name: a 16 character alphanumeric string.
 
 ### Creating a connection
@@ -108,24 +121,25 @@ tl;dr: expect to see and use hex
 
 Run 
 ```
-vendor\bin\threema-gateway
+vendor/bin/threema-gateway
 ``` 
 for a list of commands and their options. 
 
 Store your api secret, public and private keys in a file called `default.key` in the current working directory. See
-`default.key.sample` for a template.
+`default.key.sample` for a template. This will save you a lot of typing and keep your secrets off the command line.
+Do _not_ check your default.key file into version control.
 
-A good smoke test to see if everything is working right is 
+To generate a new key pair,
 ```
-vendor\bin\threema-gateway credits
+vendor/bin/threema-gateway key:create-pair
 ```
-which should show you the number of credits remaining in your account or an error message on failure.
+which will print the keys to the console. Copy and paste those to your `default.key` file. You also need this to register your ID on Threema Gateway.
 
-To generate a new key pair,
+A good smoke test to see if everything is working right is 
 ```
-vendor\bin\threema-gateway key:create-pair
+vendor/bin/threema-gateway credits
 ```
-which will print the keys to the console. Copy and paste those to your `default.key` file.
+which should show you the number of credits remaining in your account or an error message on failure.
 
 ## Contributing
 
@@ -150,7 +164,6 @@ composer phpstan
 
 * ReceiveMessageResult assumes you want to store file attachments on the local filesystem. This may not be true eg if using Amazon infrastructure. Refactor to allow for FileAcceptors(?) which can be overloaded to use Flysystem, local file system, or a null object pattern that ignores the file
 * Url class is probably not needed
-* AssocArray class is probably not needed 
 * Wait for PSR-18 to be approved, then migrate HttpDriver to use it (then we can drop direct cUrl support ourselves and rely on third parties to do a better job)
 
 ## Other platforms (Java and Python)