doc/autoloader.md

   1 Autoloader with Composer
   2 ==========
   3
   4 * [Home](help)
   5   * [Developer Intro](help/Developers-Intro)
   6
   7 Friendica uses [Composer](https://getcomposer.org) to manage dependencies libraries and the class autoloader both for libraries and namespaced Friendica classes.
   8
   9 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`.
  10
  11 * [Using Composer](help/Composer)
  12
  13 ## A quick introduction to class autoloading
  14
  15 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".
  16
  17 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`)
  18
  19 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.
  20 For more info about PHP autoloading, please refer to the [official PHP documentation](http://php.net/manual/en/language.oop5.autoload.php).
  21
  22 ### Example
  23
  24 Let's say you have a PHP file in `src/` that define a very useful class:
  25
  26 ```php
  27 // src/ItemsManager.php
  28 <?php
  29 namespace Friendica;
  30
  31 class ItemsManager {
  32         public function getAll() { ... }
  33         public function getByID($id) { ... }
  34 }
  35 ```
  36
  37 The class `ItemsManager` has been declared in the `Friendica` namespace.
  38 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)
  39
  40 Let's say now that you need to load some items in a view, maybe in a fictional `mod/network.php`.
  41 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');`.
  42
  43 The code will be something like:
  44
  45 ```php
  46 // mod/network.php
  47 <?php
  48
  49 function network_content(App $a) {
  50         $itemsmanager = new Friendica\ItemsManager();
  51         $items = $itemsmanager->getAll();
  52
  53         // pass $items to template
  54         // return result
  55 }
  56 ```
  57
  58 That's a quite simple example, but look: no `require()`!
  59 If you need to use a class, you can simply use it and you don't need to do anything else.
  60
  61 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:
  62
  63 ```php
  64 // src/BaseManager.php
  65 <?php
  66 namespace Friendica;
  67
  68 class BaseManager {
  69         public function thatFunctionEveryManagerUses() { ... }
  70 }
  71 ```
  72
  73 and then let's change the ItemsManager class to use this code
  74
  75 ```php
  76 // src/ItemsManager.php
  77 <?php
  78 namespace Friendica;
  79
  80 class ItemsManager extends BaseManager {
  81         public function getAll() { ... }
  82         public function getByID($id) { ... }
  83 }
  84 ```
  85
  86 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.
  87 It works with the "BaseManager" example here and it works when we need to call static methods:
  88
  89 ```php
  90 // src/Dfrn.php
  91 <?php
  92 namespace Friendica;
  93
  94 class Dfrn {
  95         public static function  mail($item, $owner) { ... }
  96 }
  97 ```
  98
  99 ```php
 100 // mod/mail.php
 101 <?php
 102
 103 mail_post($a){
 104         ...
 105         Friendica\dfrn::mail($item, $owner);
 106         ...
 107 }
 108 ```
 109
 110 If your code is in same namespace as the class you need, you don't need to prepend it:
 111
 112 ```php
 113 // include/delivery.php
 114 <?php
 115
 116 namespace Friendica;
 117
 118 // this is the same content of current include/delivery.php,
 119 // but has been declared to be in "Friendica" namespace
 120
 121 [...]
 122 switch($contact['network']) {
 123         case NETWORK_DFRN:
 124                 if ($mail) {
 125                         $item['body'] = ...
 126                         $atom = Dfrn::mail($item, $owner);
 127                 } elseif ($fsuggest) {
 128                         $atom = Dfrn::fsuggest($item, $owner);
 129                         q("DELETE FROM `fsuggest` WHERE `id` = %d LIMIT 1", intval($item['id']));
 130                 } elseif ($relocate)
 131                         $atom = Dfrn::relocate($owner, $uid);
 132 [...]
 133 ```
 134
 135 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.
 136 But if you want to use classes from another library, you need to use the full namespace, e.g.
 137
 138 ```php
 139 // src/Diaspora.php
 140 <?php
 141
 142 namespace Friendica;
 143
 144 class Diaspora {
 145         public function md2bbcode() {
 146                 $html = \Michelf\MarkdownExtra::defaultTransform($text);
 147         }
 148 }
 149 ```
 150
 151 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
 152
 153 ```php
 154 // src/Diaspora.php
 155 <?php
 156 namespace Friendica;
 157
 158 use \Michelf\MarkdownExtra;
 159
 160 class Diaspora {
 161         public function md2bbcode() {
 162                 $html = MarkdownExtra::defaultTransform($text);
 163         }
 164 }
 165 ```
 166
 167 Note that namespaces are like paths in filesystem, separated by "\", with the first "\" being the global scope.
 168 You can go deeper if you want to, like:
 169
 170 ```
 171 // src/Network/Dfrn.php
 172 <?php
 173 namespace Friendica\Network;
 174
 175 class Dfrn {
 176 }
 177 ```
 178
 179 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`.
 180
 181 or
 182
 183 ```
 184 // src/Dba/Mysql
 185 <?php
 186 namespace Friendica\Dba;
 187
 188 class Mysql {
 189 }
 190 ```
 191
 192 So you can think of namespaces as folders in a Unix file system, with global scope as the root ("\").
 193
 194 ## Related
 195
 196 * [Using Composer](help/Composer)
 197 * [How To Move Classes to `src`](help/Developer-How-To-Move-Classes-to-src)