From 1c276b5cd5e9789d71f55581aa571757e9621294 Mon Sep 17 00:00:00 2001
From: Hypolite Petovan <mrpetovan@gmail.com>
Date: Sat, 1 Apr 2017 17:58:21 -0400
Subject: [PATCH] Add Composer documentation

---
 doc/Composer.md         |  98 ++++++++++++++++
 doc/Developers-Intro.md |  12 +-
 doc/Home.md             |   1 +
 doc/autoloader.md       | 251 +++++++++++++++++++---------------------
 4 files changed, 226 insertions(+), 136 deletions(-)
 create mode 100644 doc/Composer.md

diff --git a/doc/Composer.md b/doc/Composer.md
new file mode 100644
index 0000000000..d0e930e343
--- /dev/null
+++ b/doc/Composer.md
@@ -0,0 +1,98 @@
+Using Composer
+==============
+
+* [Home](help)
+  * [Developer Intro](help/Developers-Intro)
+
+Friendica uses [Composer](https://getcomposer.org) to manage dependencies libraries and the class autoloader both for libraries and namespaced Friendica classes.
+
+It's a command-line tool that downloads required libraries into the `vendor` folder and makes any namespaced class in `src` available through the whole application through `boot.php`.
+
+* [Class autoloading](help/autoloader)
+
+## How to use Composer
+
+If you don't have Composer installed on your system, Friendica ships with a copy of it at `util/composer.phar`.
+For the purpose of this help, all examples will use this path to run Composer commands, however feel free to replace them with your own way of calling Composer.
+Composer requires PHP CLI and the following examples assume it's available system-wide.
+
+### Installing/Updating Friendica
+
+#### From Archive
+
+If you just unpacked a Friendica release archive, you don't have to use Commposer at all, all the required libraries are already bundled in the archive.
+
+#### Installing with Git
+
+If you prefer to use `git`, you will have to run Composer to fetch the required libraries and build the autoloader before you can run Friendica.
+Here are the typical commands you will have to run to do so:
+
+````
+~> git clone https://github.com/friendica/friendica.git friendica
+~/friendica> cd friendica
+~/friendica> util/composer.phar install
+````
+
+That's it! Composer will take care of fetching all the required libraries in the `vendor` folder and build the autoloader to make those libraries available to Friendica.
+
+#### Updating with Git
+
+Updating Friendica to the current stable or the latest develop version is easy with Git, just remember to run Composer after every branch pull.
+
+````
+~> cd friendica
+~/friendica> git pull
+~/friendica> util/composer.phar install
+````
+
+And that's it. If any library used by Friendica has been upgraded, Composer will fetch the version currently used by Friendica and refresh the autoloader to ensure the best performances.
+
+### Developing Friendica
+
+First of all, thanks for contributing to Friendica!
+Composer is meant to be used by developers to maintain third-party libraries required by Friendica.
+If you don't need to use any third-party library, then you don't need to use Composer beyond what is above to install/update Friendica.
+
+#### Adding a third-party library to Friendica
+
+Does your shiny new [Plugin](help/Plugins) need to rely on a third-party library not required by Friendica yet?
+First of all, this library should be available on [Packagist](https://packagist.org) so that Composer knows how to fetch it directly just by mentioning its name in `composer.json`.
+
+This file is the configuration of Friendica for Composer. It lists details about the Friendica project, but also a list of required dependencies and their target version.
+Here's a simplified version of the one we currently use on Friendica:
+
+````json
+{
+	"name": "friendica/friendica",
+	"description": "A decentralized social network part of The Federation",
+	"type": "project",
+	...
+	"require": {
+		"ezyang/htmlpurifier": "~4.7.0",
+		"mobiledetect/mobiledetectlib": "2.8.*"
+	},
+	...
+}
+````
+
+The important part is under the `require` key, this is a list of all the libraries Friendica may need to run.
+As you can see, at the moment we only require two, HTMLPurifier and MobileDetect.
+Each library has a different target version, and [per Composer documentation about version constraints](https://getcomposer.org/doc/articles/versions.md#writing-basic-version-constraints), this means that:
+
+* We will update HTMLPurifier up to version 4.8.0 excluded
+* We will update MobileDetect up to version 2.9.0 excluded
+
+There are other operators you can use to allow Composer to update the package up to the next major version excluded.
+Or you can specify the exact version of the library if you code requires it, and Composer will never update it although it isn't recommended.
+
+To add a library, just add its Packagist identifier to the `require` list and set a target version string.
+
+Then you should run `util/composer.phar update` to add it to your local `vendor` folder and update the `composer.lock` file that specifies the current versions of the dependencies.
+
+#### Updating an existing dependency
+
+If a package needs to be updated, whether to the next minor version or to the next major version provided you changed the adequate code in Friendica, simply edit `composer.json` to update the target version string of the relevant library.
+
+Then you should run `util/composer.phar update` to update it in your local `vendor` folder and update the `composer.lock` file that specifies the current versions of the dependencies.
+
+Please note that you should commit both `composer.json` and `composer.lock` with your work every time you make a change to the former.
\ No newline at end of file
diff --git a/doc/Developers-Intro.md b/doc/Developers-Intro.md
index 61b300b0cc..5568afeb5d 100644
--- a/doc/Developers-Intro.md
+++ b/doc/Developers-Intro.md
@@ -6,8 +6,7 @@ Where to get started to help improve Friendica?
 Do you want to help us improve Friendica?
 Here we have compiled some hints on how to get started and some tasks to help you choose.
 A project like Friendica is the sum of many different contributions.
-**Very different skills are required to make good software.
-Some of them involve coding, others do not.**
+**Very different skills are required to make good software, not all of them involve coding!**
 We are looking for helpers in all areas, whether you write text or code, whether you spread the word to convince people or design new icons.
 Whether you feel like an expert or like a newbie - join us with your ideas!
 
@@ -47,6 +46,14 @@ We can't promise we have the right skills in the group but we'll try.
 Programming
 ---
 
+### Composer
+
+Friendica uses [Composer](https://getcomposer.org) to manage dependencies libraries and the class autoloader both for libraries and namespaced Friendica classes.
+
+It's a command-line tool that downloads required libraries into the `vendor` folder and makes any namespaced class in `src` available through the whole application through `boot.php`.
+
+* [Using Composer](help/Composer)
+
 ###Coding standards
 
 For the sake of consistency between contribution and general code readability, Friendica follows the widespread [PSR-2 coding standards](http://www.php-fig.org/psr/psr-2/) to the exception of a few rules.
@@ -120,6 +127,7 @@ Ask us to find out whom to talk to about their experiences.
 Do not worry about cross-posting.
 
 ###Client software
+
 As Friendica is using a [Twitter/GNU Social compatible API](help/api) any of the clients for those platforms should work with Friendica as well.
 Furthermore there are several client projects, especially for use with Friendica.
 If you are interested in improving those clients, please contact the developers of the clients directly.
diff --git a/doc/Home.md b/doc/Home.md
index b4b389921a..5490d171f8 100644
--- a/doc/Home.md
+++ b/doc/Home.md
@@ -47,6 +47,7 @@ Friendica Documentation and Resources
 * [Protocol Documentation](help/Protocol)
 * [Database schema documantation](help/database)
 * [Class Autoloading](help/autoloader)
+* [Using Composer](help/Composer)
 * [Code - Reference(Doxygen generated - sets cookies)](doc/html/)
 * [Twitter/GNU Social API Functions](help/api)
 
diff --git a/doc/autoloader.md b/doc/autoloader.md
index 69c62451cd..83f1010440 100644
--- a/doc/autoloader.md
+++ b/doc/autoloader.md
@@ -1,209 +1,192 @@
-Autoloader
+Autoloader with Composer
 ==========
 
 * [Home](help)
+  * [Developer Intro](help/Developers-Intro)
 
-There is some initial support to class autoloading in Friendica core.
+Friendica uses [Composer](https://getcomposer.org) to manage dependencies libraries and the class autoloader both for libraries and namespaced Friendica classes.
 
-The autoloader code is in `include/autoloader.php`.
-It's derived from composer autoloader code.
+It's a command-line tool that downloads required libraries into the `vendor` folder and makes any namespaced class in `src` available through the whole application through `boot.php`.
 
-Namespaces and Classes are mapped to folders and files in `library/`,
-and the map must be updated by hand, because we don't use composer yet.
-The mapping is defined by files in `include/autoloader/` folder.
+* [Using Composer](help/Composer)
 
-Currently, only HTMLPurifier library is loaded using autoloader.
+## A quick introduction to class autoloading
 
+The autoloader dynamically includes the file defining a class when it is first referenced, either by instantiating an object or simply making sure that it is available, without the need to explicitly use "require_once".
 
-## A quick introdution to class autoloading
+Once it is set up you don't have to directly use it, you can directly use any class that is covered by the autoloader (currently `vendor` and `src`)
 
-The autoloader it's a way for php to automagically include the file that define a class when the class is first used, without the need to use "require_once" every time.
+Under the hood, Composer registers a callback with [`spl_autoload_register()`](http://php.net/manual/en/function.spl-autoload-register.php) that receives a class name as an argument and includes the corresponding class definition file.
+For more info about PHP autoloading, please refer to the [official PHP documentation](http://php.net/manual/en/language.oop5.autoload.php).
 
-Once is setup you don't have to use it in any way. You need a class? you use the class.
+### Example
 
-At his basic is a function passed to the "spl_autoload_register()" function, which receive as argument the class name the script want and is it job to include the correct php file where that class is defined.
-The best source for documentation is [php site](http://php.net/manual/en/language.oop5.autoload.php).
+Let's say you have a PHP file in `src/` that define a very useful class:
 
-One example, based on fictional friendica code.
+```php
+	// src/ItemsManager.php
+	<?php
+	namespace \Friendica;
 
-Let's say you have a php file in "include/" that define a very useful class:
-
-```
-    file: include/ItemsManager.php
-    <?php
-    namespace \Friendica;
-
-    class ItemsManager {
-       public function getAll() { ... }
-       public function getByID($id) { ... }
-    }
-```
-
-The class "ItemsManager" has been declared in "Friendica" namespace.
-Namespaces are useful to keep things separated and avoid names clash (could be that a library you want to use defines a class named "ItemsManager", but as long as is in another namespace, you don't have any problem)
-
-If we were using composer, we had configured it with path where to find the classes of "Friendica" namespace, and then the composer script will generate the autoloader machinery for us.
-As we don't use composer, we need check that the autoloader knows the Friendica namespace.
-So in "include/autoloader/autoload_psr4.php" there should be something like
-
-```
-    $vendorDir = dirname(dirname(dirname(__FILE__)))."/library";
-    $baseDir = dirname($vendorDir);
-    return array(
-       "Friendica" => array($baseDir."/include");
-    );
+	class ItemsManager {
+		public function getAll() { ... }
+		public function getByID($id) { ... }
+	}
 ```
 
+The class `ItemsManager` has been declared in the `Friendica` namespace.
+Namespaces are useful to keep classes separated and avoid names conflicts (could be that a library you want to use also defines a class named `ItemsManager`, but as long as it is in another namespace, you don't have any problem)
 
-That tells the autoloader code to look for files that defines classes in "Friendica" namespace under "include/" folder. (And btw, that's why the file has the same name as the class it defines.)
-
-*note*: The structure of files in "include/autoloader/" has been copied from the code generated by composer, to ease the work of enable autoloader for external libraries under "library/"
-
-Let's say now that you need to load some items in a view, maybe in a fictional "mod/network.php".
-Somewere at the start of the scripts, the autoloader was initialized. In Friendica is done at the top of "boot.php", with "require_once('include/autoloader.php');".
+Let's say now that you need to load some items in a view, maybe in a fictional `mod/network.php`.
+In order for the Composer autoloader to work, it must first be included. In Friendica this is already done at the top of `boot.php`, with `require_once('vendor/autoload.php');`.
 
 The code will be something like:
 
-```
-    file: mod/network.php
-    <?php
+```php
+	// mod/network.php
+	<?php
 
-    function network_content(App $a) {
-       $itemsmanager = new \Friendica\ItemsManager();
-       $items = $itemsmanager->getAll();
+	function network_content(App $a) {
+		$itemsmanager = new \Friendica\ItemsManager();
+		$items = $itemsmanager->getAll();
 
-       // pass $items to template
-       // return result
-    }
+		// pass $items to template
+		// return result
+	}
 ```
 
-That's a quite simple example, but look: no "require()"!
-You need to use a class, you use the class and you don't need to do anything more.
+That's a quite simple example, but look: no `require()`!
+If you need to use a class, you can simply use it and you don't need to do anything else.
 
-Going further: now we have a bunch of "*Manager" classes that cause some code duplication, let's define a BaseManager class, where to move all code in common between all managers:
+Going further: now we have a bunch of `*Manager` classes that cause some code duplication, let's define a `BaseManager` class, where we move all common code between all managers:
 
-```
-    file: include/BaseManager.php
-    <?php
-    namespace \Friendica;
+```php
+	// src/BaseManager.php
+	<?php
+	namespace \Friendica;
 
-    class BaseManager {
-      public function thatFunctionEveryManagerUses() { ... }
-    }
+	class BaseManager {
+		public function thatFunctionEveryManagerUses() { ... }
+	}
 ```
 
 and then let's change the ItemsManager class to use this code
 
-```
-    file: include/ItemsManager.php
-    <?php
-    namespace \Friendica;
+```php
+	// src/ItemsManager.php
+	<?php
+	namespace \Friendica;
 
-    class ItemsManager extends BaseManager {
-       public function getAll() { ... }
-       public function getByID($id) { ... }
-    }
+	class ItemsManager extends BaseManager {
+		public function getAll() { ... }
+		public function getByID($id) { ... }
+	}
 ```
 
-The autoloader don't mind what you need the class for. You need a class, you get the class.
-It works with the "BaseManager" example here, it works when we need to call static methods on a class:
+Even though we didn't explicitly include the `src/BaseManager.php` file, the autoloader will when this class is first defined, because it is referenced as a parent class.
+It works with the "BaseManager" example here and it works when we need to call static methods:
 
-```
-    file: include/dfrn.php
-    <?php
-    namespace \Friendica;
+```php
+	// src/Dfrn.php
+	<?php
+	namespace \Friendica;
 
-    class dfrn {
-      public static function  mail($item, $owner) { ... }
-    }
+	class Dfrn {
+		public static function  mail($item, $owner) { ... }
+	}
 ```
 
-```
-    file: mod/mail.php
-    <?php
+```php
+	// mod/mail.php
+	<?php
 
-    mail_post($a){
-     ...
-     \Friendica\dfrn::mail($item, $owner);
-     ...
-    }
+	mail_post($a){
+		...
+		\Friendica\dfrn::mail($item, $owner);
+		...
+	}
 ```
 
 If your code is in same namespace as the class you need, you don't need to prepend it:
 
-```
-    file: include/delivery.php
-    <?php
-
-    namespace \Friendica;
+```php
+	// include/delivery.php
+	<?php
 
-    // this is the same content of current include/delivery.php,
-    // but has been declared to be in "Friendica" namespace
+	namespace \Friendica;
 
-    [...]
-    switch($contact['network']) {
+	// this is the same content of current include/delivery.php,
+	// but has been declared to be in "Friendica" namespace
 
-        case NETWORK_DFRN:
-            if ($mail) {
-                $item['body'] = ...
-                $atom = dfrn::mail($item, $owner);
-            } elseif ($fsuggest) {
-                $atom = dfrn::fsuggest($item, $owner);
-                q("DELETE FROM `fsuggest` WHERE `id` = %d LIMIT 1", intval($item['id']));
-            } elseif ($relocate)
-                $atom = dfrn::relocate($owner, $uid);
-    [...]
+	[...]
+	switch($contact['network']) {
+		case NETWORK_DFRN:
+			if ($mail) {
+				$item['body'] = ...
+				$atom = Dfrn::mail($item, $owner);
+			} elseif ($fsuggest) {
+				$atom = Dfrn::fsuggest($item, $owner);
+				q("DELETE FROM `fsuggest` WHERE `id` = %d LIMIT 1", intval($item['id']));
+			} elseif ($relocate)
+				$atom = Dfrn::relocate($owner, $uid);
+	[...]
 ```
 
-This is real "include/delivery.php" unchanged, but as the code is declared to be in "Friendica" namespace, you don't need to write it when you need to use the "dfrn" class.
+This is the current code of `include/delivery.php`, and since the code is declared to be in the "Friendica" namespace, you don't need to write it when you need to use the "Dfrn" class.
 But if you want to use classes from another library, you need to use the full namespace, e.g.
 
-```
-    <?php
-    namespace \Friendica;
+```php
+	// src/Diaspora.php
+	<?php
 
-    class Diaspora {
-      public function md2bbcode() {
-        $html = \Michelf\MarkdownExtra::defaultTransform($text);
-      }
-    }
+	namespace \Friendica;
+
+	class Diaspora {
+		public function md2bbcode() {
+			$html = \Michelf\MarkdownExtra::defaultTransform($text);
+		}
+	}
 ```
 
-if you use that class in many places of the code and you don't want to write the full path to the class everytime, you can use the "use" php keyword
+if you use that class in many places of the code and you don't want to write the full path to the class every time, you can use the "use" PHP keyword
 
-```
-    <?php
-    namespace \Friendica;
+```php
+	// src/Diaspora.php
+	<?php
+	namespace \Friendica;
 
-    use \Michelf\MarkdownExtra;
+	use \Michelf\MarkdownExtra;
 
-    class Diaspora {
-      public function md2bbcode() {
-        $html = MarkdownExtra::defaultTransform($text);
-      }
-    }
+	class Diaspora {
+		public function md2bbcode() {
+			$html = MarkdownExtra::defaultTransform($text);
+		}
+	}
 ```
 
 Note that namespaces are like paths in filesystem, separated by "\", with the first "\" being the global scope.
-You can go more deep if you want to, like:
+You can go deeper if you want to, like:
 
 ```
+	// src/Network/Dfrn.php
     <?php
     namespace \Friendica\Network;
 
-    class DFRN {
+    class Dfrn {
     }
 ```
 
+Please note that the location of the file defining the class must be placed in the appropriate sub-folders of `src` if the namespace isn't plain `\Friendica`.
+
 or
 
 ```
+	// src/Dba/Mysql
     <?php
-    namespace \Friendica\DBA;
+    namespace \Friendica\Dba;
 
-    class MySQL {
+    class Mysql {
     }
 ```
 
-So you can think of namespaces as folders in a unix filesystem, with global scope as the root ("\").
-
+So you can think of namespaces as folders in a Unix file system, with global scope as the root ("\").
-- 
2.39.5