doc/autoloader.md

   1 Autoloader\r
   2 ==========\r
   3 \r
   4 * [Home](help)\r
   5 \r
   6 There is some initial support to class autoloading in Friendica core.\r
   7 \r
   8 The autoloader code is in `include/autoloader.php`.\r
   9 It's derived from composer autoloader code.\r
  10 \r
  11 Namespaces and Classes are mapped to folders and files in `library/`,\r
  12 and the map must be updated by hand, because we don't use composer yet.\r
  13 The mapping is defined by files in `include/autoloader/` folder.\r
  14 \r
  15 Currently, only HTMLPurifier library is loaded using autoloader.\r
  16 \r
  17 \r
  18 ## A quick introdution to class autoloading\r
  19 \r
  20 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.\r
  21 \r
  22 Once is setup you don't have to use it in any way. You need a class? you use the class.\r
  23 \r
  24 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.\r
  25 The best source for documentation is [php site](http://php.net/manual/en/language.oop5.autoload.php).\r
  26 \r
  27 One example, based on fictional friendica code.\r
  28 \r
  29 Let's say you have a php file in "include/" that define a very useful class:\r
  30 \r
  31 ```\r
  32     file: include/ItemsManager.php\r
  33     <?php\r
  34     namespace \Friendica;\r
  35 \r
  36     class ItemsManager {\r
  37        public function getAll() { ... }\r
  38        public function getByID($id) { ... }\r
  39     }\r
  40 ```\r
  41 \r
  42 The class "ItemsManager" has been declared in "Friendica" namespace.\r
  43 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)\r
  44 \r
  45 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.\r
  46 As we don't use composer, we need check that the autoloader knows the Friendica namespace.\r
  47 So in "include/autoloader/autoload_psr4.php" there should be something like\r
  48 \r
  49 ```\r
  50     $vendorDir = dirname(dirname(dirname(__FILE__)))."/library";\r
  51     $baseDir = dirname($vendorDir);\r
  52     return array(\r
  53        "Friendica" => array($baseDir."/include");\r
  54     );\r
  55 ```\r
  56 \r
  57 \r
  58 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.)\r
  59 \r
  60 *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/"\r
  61 \r
  62 Let's say now that you need to load some items in a view, maybe in a fictional "mod/network.php".\r
  63 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');".\r
  64 \r
  65 The code will be something like:\r
  66 \r
  67 ```\r
  68     file: mod/network.php\r
  69     <?php\r
  70 \r
  71     function network_content(App $a) {\r
  72        $itemsmanager = new \Friendica\ItemsManager();\r
  73        $items = $itemsmanager->getAll();\r
  74 \r
  75        // pass $items to template\r
  76        // return result\r
  77     }\r
  78 ```\r
  79 \r
  80 That's a quite simple example, but look: no "require()"!\r
  81 You need to use a class, you use the class and you don't need to do anything more.\r
  82 \r
  83 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:\r
  84 \r
  85 ```\r
  86     file: include/BaseManager.php\r
  87     <?php\r
  88     namespace \Friendica;\r
  89 \r
  90     class BaseManager {\r
  91       public function thatFunctionEveryManagerUses() { ... }\r
  92     }\r
  93 ```\r
  94 \r
  95 and then let's change the ItemsManager class to use this code\r
  96 \r
  97 ```\r
  98     file: include/ItemsManager.php\r
  99     <?php\r
 100     namespace \Friendica;\r
 101 \r
 102     class ItemsManager extends BaseManager {\r
 103        public function getAll() { ... }\r
 104        public function getByID($id) { ... }\r
 105     }\r
 106 ```\r
 107 \r
 108 The autoloader don't mind what you need the class for. You need a class, you get the class.\r
 109 It works with the "BaseManager" example here, it works when we need to call static methods on a class:\r
 110 \r
 111 ```\r
 112     file: include/dfrn.php\r
 113     <?php\r
 114     namespace \Friendica;\r
 115 \r
 116     class dfrn {\r
 117       public static function  mail($item, $owner) { ... }\r
 118     }\r
 119 ```\r
 120 \r
 121 ```\r
 122     file: mod/mail.php\r
 123     <?php\r
 124 \r
 125     mail_post($a){\r
 126      ...\r
 127      \Friendica\dfrn::mail($item, $owner);\r
 128      ...\r
 129     }\r
 130 ```\r
 131 \r
 132 If your code is in same namespace as the class you need, you don't need to prepend it:\r
 133 \r
 134 ```\r
 135     file: include/delivery.php\r
 136     <?php\r
 137 \r
 138     namespace \Friendica;\r
 139 \r
 140     // this is the same content of current include/delivery.php,\r
 141     // but has been declared to be in "Friendica" namespace\r
 142 \r
 143     [...]\r
 144     switch($contact['network']) {\r
 145 \r
 146         case NETWORK_DFRN:\r
 147             if ($mail) {\r
 148                 $item['body'] = ...\r
 149                 $atom = dfrn::mail($item, $owner);\r
 150             } elseif ($fsuggest) {\r
 151                 $atom = dfrn::fsuggest($item, $owner);\r
 152                 q("DELETE FROM `fsuggest` WHERE `id` = %d LIMIT 1", intval($item['id']));\r
 153             } elseif ($relocate)\r
 154                 $atom = dfrn::relocate($owner, $uid);\r
 155     [...]\r
 156 ```\r
 157 \r
 158 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.\r
 159 But if you want to use classes from another library, you need to use the full namespace, e.g.\r
 160 \r
 161 ```\r
 162     <?php\r
 163     namespace \Friendica;\r
 164 \r
 165     class Diaspora {\r
 166       public function md2bbcode() {\r
 167         $html = \Michelf\MarkdownExtra::defaultTransform($text);\r
 168       }\r
 169     }\r
 170 ```\r
 171 \r
 172 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\r
 173 \r
 174 ```\r
 175     <?php\r
 176     namespace \Friendica;\r
 177 \r
 178     use \Michelf\MarkdownExtra;\r
 179 \r
 180     class Diaspora {\r
 181       public function md2bbcode() {\r
 182         $html = MarkdownExtra::defaultTransform($text);\r
 183       }\r
 184     }\r
 185 ```\r
 186 \r
 187 Note that namespaces are like paths in filesystem, separated by "\", with the first "\" being the global scope.\r
 188 You can go more deep if you want to, like:\r
 189 \r
 190 ```\r
 191     <?php\r
 192     namespace \Friendica\Network;\r
 193 \r
 194     class DFRN {\r
 195     }\r
 196 ```\r
 197 \r
 198 or\r
 199 \r
 200 ```\r
 201     <?php\r
 202     namespace \Friendica\DBA;\r
 203 \r
 204     class MySQL {\r
 205     }\r
 206 ```\r
 207 \r
 208 So you can think of namespaces as folders in a unix filesystem, with global scope as the root ("\").\r
 209 \r