doc/Developer-How-To-Move-Classes-to-src.md

   1 How To Move Classes to `src`
   2 ==============
   3
   4 * [Home](help)
   5   * [Developer Intro](help/Developers-Intro)
   6
   7 Friendica uses [Composer](help/Composer) to manage autoloading.
   8 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.
   9 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.
  10
  11 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.
  12
  13 ## Decide the namespace
  14
  15 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.
  16 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.
  17
  18 A few pointers though:
  19 * `Friendica` is the base namespace for all classes in the `src` folder
  20 * 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`.
  21 * Namespaces can help group classes with a similar purpose or relevant to a particular feature
  22
  23 When you're done deciding the namespace, it's time to use it.
  24 Let's say we choose `Friendica\Core` for the `Config` class.
  25
  26 ## Use the namespace
  27
  28 To declare the namespace, the file `src/Core/Config.php` must start with the following statement:
  29
  30 ````php
  31 namespace Friendica\Core;
  32 ````
  33
  34 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`.
  35 Thankfully, PHP provides namespace shortcuts through `use`.
  36
  37 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.
  38 Here are the different ways you can use `use`:
  39
  40 ````php
  41 // No use
  42 $config = new Friendica\Core\Config();
  43 ````
  44 ````php
  45 // Namespace shortcut
  46 use Friendica\Core;
  47
  48 $config = new Core\Config();
  49 ````
  50 ````php
  51 // Class name shortcut
  52 use Friendica\Core\Config;
  53
  54 $config = new Config();
  55 ````
  56 ````php
  57 // Aliasing
  58 use Friendica\Core\Config as Cfg;
  59
  60 $config = new Cfg();
  61 ````
  62
  63 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.
  64
  65 ## Escape non-namespace classes
  66
  67 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.
  68 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.
  69
  70 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.
  71 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.
  72
  73 ````php
  74 namespace Friendica\Core;
  75 ...
  76 if (\DBM::is_result($r)) {
  77     ...
  78 }
  79 ````
  80 ````php
  81 namespace Friendica\Core;
  82
  83 use Friendica\Database\DBM;
  84
  85 if (DBM::is_result($r)) {
  86     ...
  87 }
  88 ````
  89
  90 ## Remove any useless `require`
  91
  92 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.
  93 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.
  94
  95 ## Miscellaneous tips
  96
  97 When you are done with moving the class, please run `php bin/console.php typo` from the Friendica base directory to check for obvious mistakes.
  98 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.
  99
 100 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.
 101
 102 Check the class file for any magic constant `__FILE__` or `__DIR__`, as their value changed since you moved the class in the file tree.
 103 Most of the time it's used for debugging purposes but there can be instances where it's used to create cache folders for example.
 104
 105 ## Related
 106
 107 * [Class autoloading](help/autoloader)
 108 * [Using Composer](help/Composer)