From dfd4c8528ece203a27ff8c718614423fbb04d8d9 Mon Sep 17 00:00:00 2001
From: Hypolite Petovan <mrpetovan@gmail.com>
Date: Sun, 30 Apr 2017 17:34:23 -0400
Subject: [PATCH] Add new documentation page about moving classes to src

---
 doc/Composer.md                             |   5 +
 doc/Developer-How-To-Move-Classes-to-src.md | 105 ++++++++++++
 doc/Developers-Intro.md                     |   2 +
 doc/Home.md                                 |  34 ++--
 doc/autoloader.md                           | 173 ++++++++++----------
 mod/help.php                                |   2 +-
 view/theme/frio/css/style.css               |   2 +-
 7 files changed, 222 insertions(+), 101 deletions(-)
 create mode 100644 doc/Developer-How-To-Move-Classes-to-src.md

diff --git a/doc/Composer.md b/doc/Composer.md
index 8310baf3f0..02ce61639c 100644
--- a/doc/Composer.md
+++ b/doc/Composer.md
@@ -113,3 +113,8 @@ For Composer, this would be:
 ````
 $> COMPOSER_HOME=/var/tmp/composer sudo -u [web user] util/composer.phar [mode]
 ````
+
+## Related
+
+* [Class autoloading](help/autoloader)
+* [How To Move Classes to `src`](help/Developer-How-To-Move-Classes-to-src)
diff --git a/doc/Developer-How-To-Move-Classes-to-src.md b/doc/Developer-How-To-Move-Classes-to-src.md
new file mode 100644
index 0000000000..d502e863c3
--- /dev/null
+++ b/doc/Developer-How-To-Move-Classes-to-src.md
@@ -0,0 +1,105 @@
+How To Move Classes to `src`
+==============
+
+* [Home](help)
+  * [Developer Intro](help/Developers-Intro)
+
+Since April 2017, Friendica uses [Composer](help/Composer) to manage autoloading.
+This means that all the PHP class files moved to the `src` folder will be [automatically included](help/autoloader) when the class it defines is first used in the flow.
+This is an improvement over the current `require` usage since files will be included on an actual usage basis instead of the presence of a `require` call.
+
+However, there are a significant number of items to check when moving a class file from the `include` folder to the `src` folder, and this page is there to list them.
+
+## Decide the namespace
+
+This isn't the most technical decision of them all, but it has long lasting consequences as it will be the name that will be used to refer to this class from now on.
+There is [a shared Ethercalc sheet](https://ethercalc.org/friendica_classes) to suggest namespace/class names that lists all the already moved class files for inspiration.
+
+A few pointers though:
+* `Friendica` is the base namespace for all classes in the `src` folder
+* Namespaces match the directory structure, with `Friendica` namespace being the base `src` directory. The `Config` class set in the `Friendica\Core` namespace is expected to be found at `src/Core/Config.php`.
+* Namespaces can help group classes with a similar purpose or relevant to a particular feature
+
+When you're done deciding the namespace, it's time to use it.
+Let's say we choose `Friendica\Core` for the `Config` class.
+
+## Use the namespace
+
+To declare the namespace, the file `src/Core/Config.php` must start with the following statement:
+
+````php
+namespace Friendica\Core;
+````
+
+From now on, the `Config` class can be referred to as `Friendica\Core\Config`, however it isn't very practical, especially when the class was previously used as `Config`.
+Thankfully, PHP provides namespace shortcuts through `use`.
+
+This language construct just provides a different naming scheme for a namespace or a class, but doesn't trigger the autoload mechanism on its own.
+Here are the different ways you can use `use`:
+
+````php
+// No use
+$config = new Friendica\Core\Config();
+````
+````php
+// Namespace shortcut
+use Friendica\Core;
+
+$config = new Core\Config();
+````
+````php
+// Class name shortcut
+use Friendica\Core\Config;
+
+$config = new Config();
+````
+````php
+// Aliasing
+use Friendica\Core\Config as Cfg;
+
+$config = new Cfg();
+````
+
+Whatever the style chosen, a repository-wide search has to be done to find all the class name usage and either use the fully-qualified class name (including the namespace) or add a `use` statement at the start of each relevant file.
+
+## Escape non-namespace classes
+
+The class file you just moved is now in the `Friendica` namespace, but it probably isn't the case for all the classes referenced in this file.
+Since we added a `namespace Friendica\Core;` to the file, all the class names still declared in `include` will be implicitly understood as `Friendica\Core\ClassName`, which is rarely what we expect.
+
+To avoid `Class Friendica\Core\ClassName not found` errors, all the `include`-declared class names have to be prepended with a `\`, it tells the autoloader not to look for the class in the namespace but in the global space where non-namespaced classes are set.
+If there are only a handful of references to a single non-namespaced class, just prepending `\` is enough. However, if there are many instance, we can use `use` again.
+
+````php
+namespace Friendica\Core;
+...
+if (\dbm::is_result($r)) {
+    ...
+}
+````
+````php
+namespace Friendica\Core;
+
+use \dbm;
+
+if (dbm::is_result($r)) {
+    ...
+}
+````
+
+## Remove any useless `require`
+
+Now that you successfully moved your class to the autoloaded `src` folder, there's no need to include this file anywhere in the app ever again.
+Please remove all the `require_once` mentions of the former file, as they will provoke a Fatal Error even if the class isn't used.
+
+## Miscellaneous tips
+
+When you are done with moving the class, please run `php util/typo.php` from the Friendica base directory to check for obvious mistakes.
+Howevever, this tool isn't bullet-proof, and a staging install of Friendica is recommended to test your class move without impairing your production server if you host one.
+
+Most of Friendica processes are run in the background, so make sure to turn on your debug log to check for errors that wouldn't show up while simply browsing Friendica.
+
+## Related
+
+* [Class autoloading](help/autoloader)
+* [Using Composer](help/Composer)
\ No newline at end of file
diff --git a/doc/Developers-Intro.md b/doc/Developers-Intro.md
index 5568afeb5d..3cda8ab466 100644
--- a/doc/Developers-Intro.md
+++ b/doc/Developers-Intro.md
@@ -52,7 +52,9 @@ Friendica uses [Composer](https://getcomposer.org) to manage dependencies librar
 
 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)
 * [Using Composer](help/Composer)
+* [How To Move Classes to `src`](help/Developer-How-To-Move-Classes-to-src)
 
 ###Coding standards
 
diff --git a/doc/Home.md b/doc/Home.md
index 5490d171f8..4cecec44e3 100644
--- a/doc/Home.md
+++ b/doc/Home.md
@@ -36,21 +36,25 @@ Friendica Documentation and Resources
 
 **Developer Manual**
 
-* [Where to get started?](help/Developers-Intro)
-* [Help on Github](help/Github)
-* [Help on Vagrant](help/Vagrant)
-* [How to translate Friendica](help/translations)
-* [Bugs and Issues](help/Bugs-and-Issues)
-* [Plugin Development](help/Plugins)
-* [Theme Development](help/themes)
-* [Smarty 3 Templates](help/smarty3-templates)
-* [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)
-
+* [Get started](help/Developers-Intro)
+* Set up development environment
+	* [Help on Github](help/Github)
+	* [Help on Vagrant](help/Vagrant)
+	* [Bugs and Issues](help/Bugs-and-Issues)
+* Code structure
+	* [Plugin Development](help/Plugins)
+	* [Theme Development](help/themes)
+	* [Smarty 3 Templates](help/smarty3-templates)
+* How To
+	* [Translate Friendica](help/translations)
+	* [Use Composer](help/Composer)
+	* [Move classes to `src`](help/Developer-How-To-Move-Classes-to-src)
+* Reference
+	* [Twitter/GNU Social API Functions](help/api)
+	* [Code (Doxygen generated - sets cookies)](doc/html/)
+	* [Protocol Documentation](help/Protocol)
+	* [Database schema documantation](help/database)
+	* [Class Autoloading](help/autoloader)
 
 **External Resources**
 
diff --git a/doc/autoloader.md b/doc/autoloader.md
index 83f1010440..af76cf3299 100644
--- a/doc/autoloader.md
+++ b/doc/autoloader.md
@@ -24,14 +24,14 @@ For more info about PHP autoloading, please refer to the [official PHP documenta
 Let's say you have a PHP file in `src/` that define a very useful class:
 
 ```php
-	// src/ItemsManager.php
-	<?php
-	namespace \Friendica;
+// src/ItemsManager.php
+<?php
+namespace Friendica;
 
-	class ItemsManager {
-		public function getAll() { ... }
-		public function getByID($id) { ... }
-	}
+class ItemsManager {
+	public function getAll() { ... }
+	public function getByID($id) { ... }
+}
 ```
 
 The class `ItemsManager` has been declared in the `Friendica` namespace.
@@ -43,16 +43,16 @@ In order for the Composer autoloader to work, it must first be included. In Frie
 The code will be something like:
 
 ```php
-	// mod/network.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()`!
@@ -61,132 +61,137 @@ If you need to use a class, you can simply use it and you don't need to do anyth
 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:
 
 ```php
-	// src/BaseManager.php
-	<?php
-	namespace \Friendica;
+// 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
 
 ```php
-	// src/ItemsManager.php
-	<?php
-	namespace \Friendica;
+// 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) { ... }
+}
 ```
 
 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:
 
 ```php
-	// src/Dfrn.php
-	<?php
-	namespace \Friendica;
+// src/Dfrn.php
+<?php
+namespace Friendica;
 
-	class Dfrn {
-		public static function  mail($item, $owner) { ... }
-	}
+class Dfrn {
+	public static function  mail($item, $owner) { ... }
+}
 ```
 
 ```php
-	// mod/mail.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:
 
 ```php
-	// include/delivery.php
-	<?php
+// include/delivery.php
+<?php
 
-	namespace \Friendica;
+namespace Friendica;
 
-	// this is the same content of current include/delivery.php,
-	// but has been declared to be in "Friendica" namespace
+// this is the same content of current include/delivery.php,
+// but has been declared to be in "Friendica" namespace
 
-	[...]
-	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);
-	[...]
+[...]
+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 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
-	// src/Diaspora.php
-	<?php
+// src/Diaspora.php
+<?php
 
-	namespace \Friendica;
+namespace Friendica;
 
-	class Diaspora {
-		public function md2bbcode() {
-			$html = \Michelf\MarkdownExtra::defaultTransform($text);
-		}
+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 every time, you can use the "use" PHP keyword
 
 ```php
-	// src/Diaspora.php
-	<?php
-	namespace \Friendica;
+// 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 deeper if you want to, like:
 
 ```
-	// src/Network/Dfrn.php
-    <?php
-    namespace \Friendica\Network;
+// 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`.
+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;
+// src/Dba/Mysql
+<?php
+namespace Friendica\Dba;
 
-    class Mysql {
-    }
+class Mysql {
+}
 ```
 
 So you can think of namespaces as folders in a Unix file system, with global scope as the root ("\").
+
+## Related
+
+* [Using Composer](help/Composer)
+* [How To Move Classes to `src`](help/Developer-How-To-Move-Classes-to-src)
\ No newline at end of file
diff --git a/mod/help.php b/mod/help.php
index 61387753bf..1d5c831ef4 100644
--- a/mod/help.php
+++ b/mod/help.php
@@ -90,7 +90,7 @@ function help_content(App $a) {
 		for($k=0;$k<$lastlevel; $k++) $toc.="</ul>";
 		$html = implode("\n",$lines);
 
-		$a->page['aside'] = $toc.$a->page['aside'];
+		$a->page['aside'] = '<section class="help-aside-wrapper">' . $toc . $a->page['aside'] . '</section>';
 	}
 
 	$html = "
diff --git a/view/theme/frio/css/style.css b/view/theme/frio/css/style.css
index 91b01e950a..01cab105bc 100644
--- a/view/theme/frio/css/style.css
+++ b/view/theme/frio/css/style.css
@@ -98,7 +98,7 @@ blockquote {
 code {
     white-space: pre-wrap;
 }
-.help-content-wrapper code {display: inline}
+.help-content-wrapper code, .help-aside-wrapper code {display: inline}
 
 /*
 * standard page elements