Merge pull request #140 from Xymph/140-document-composer

Rewrite installation and invocation instructions using Composer

CHANGELOG.md

@@ -19,6 +19,7 @@ and [Keep a Changelog](http://keepachangelog.com/).
 
 - Centralized API communication checks in `WikiPage::request()` ([#136])
 - Centralized debug logging of API requests/responses in `WikiPage::request()` ([#139])
+- Rewrote installation and invocation instructions using Composer ([#140])
 - Added additional context to `README.md` ([#127])
 - Added semi-linear merge recommendation to `GOVERNANCE.md` ([#130])
 
@@ -36,6 +37,7 @@ and may require changes in applications that invoke these methods:_
 ### Removed
 
 - Method `Wikimate::debugCurlConfig()`, deprecated since v0.10.0 ([#128])
+- File `globals.php`, replaced by expanded Composer instructions ([#140])
 
 ## Version 0.15.0 - 2021-08-26
 
@@ -213,3 +215,4 @@ and may require changes in applications that invoke these methods:_
 [#136]: https://github.com/hamstar/Wikimate/pull/136
 [#138]: https://github.com/hamstar/Wikimate/pull/138
 [#139]: https://github.com/hamstar/Wikimate/pull/139
+[#140]: https://github.com/hamstar/Wikimate/pull/140

GOVERNANCE.md

@@ -36,7 +36,7 @@ make sure their contents follow the [contribution guidelines](CONTRIBUTING.md).
 ## Process for releasing a new version of Wikimate
 
 Create a PR with all relevant changes to update the repository for the upcoming release.
-(See [#81](https://github.com/hamstar/Wikimate/pull/81) for an example.)
+(See [#126](https://github.com/hamstar/Wikimate/pull/126) for an example.)
 It should apply the following actions:
 
 1. Change the "Upcoming version" heading in the `CHANGELOG.md` file

README.md

@@ -23,27 +23,46 @@ you will need to have PHP installed to run it.
 Install it with your preferred package management tool
 (for example, on Ubuntu Linux you can run: `sudo apt-get install php`)
 
+The recommended way to install this library is with Composer.
+Composer is a dependency management tool for PHP
+that allows you to declare the dependencies your project needs
+and installs them into your project.
+
 Install Composer by following the instructions [here](https://getcomposer.org/doc/00-intro.md).
 
-Then, download Wikimate, and initialise it by running `composer install`
-(or `composer.bat install` if you're on Windows).
+Then, run the following command in your project's folder
+to download Wikimate and initialise it:
+
+```sh
+composer require hamstar/Wikimate
+```
+
+(or `composer.bat require hamstar/Wikimate` if you're on Windows).
 
-To use Wikimate within another project, you can add it as a composer dependency
-by adding the following to your `composer.json` file:
+To use Wikimate within another project, you can add it as a Composer dependency
+by adding the following to your existing `composer.json` file:
 
 ```json
-"hamstar/Wikimate": "0.15.0"
+{
+    "require": {
+        "hamstar/Wikimate": "^0.15"
+    }
+}
 ```
 
+You can find out more on how to install Composer,
+configure autoloading, and other best-practices for defining dependencies
+at [getcomposer.org](https://getcomposer.org).
+
 ## Usage
 
-In your script file (e.g. `index.php`), include Wikimate's `globals.php` file,
+In your script file (e.g. `index.php`), include the project's `autoload.php` file,
 and create a new `Wikimate` object with the target wiki's API address.
 Then provide a username and password to Wikimate's `login` method,
 to log in to that wiki.
 
 ```php
-include 'globals.php';
+require __DIR__.'/vendor/autoload.php';
 
 $api_url = 'http://example.com/api.php';
 $username = 'bot';

USAGE.md

@@ -19,13 +19,13 @@
 
 ## Introduction
 
-In your script file (e.g. `index.php`), include Wikimate's `globals.php` file,
+In your script file (e.g. `index.php`), include the project's `autoload.php` file,
 and create a new `Wikimate` object with the target wiki's API address.
 Then provide a username and password to Wikimate's `login` method,
 to log in to that wiki.
 
 ```php
-include 'globals.php';
+require __DIR__.'/vendor/autoload.php';
 
 $api_url = 'http://example.com/api.php';
 $username = 'bot';

composer.json

@@ -10,6 +10,10 @@
             "email": "[email protected]",
             "homepage": "https://github.com/hamstar"
         },
+        {
+            "name": "Frans P. de Vries",
+            "homepage": "https://github.com/xymph"
+        },
         {
             "name"      : "Contributors",
             "homepage"  : "https://github.com/hamstar/Wikimate/graphs/contributors"