doc/Composer.md

   1 Using 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 * [Class autoloading](help/autoloader)
  12
  13 ## How to use Composer
  14
  15 If you don't have Composer installed on your system, Friendica ships with a copy of it at `bin/composer.phar`.
  16 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.
  17 Composer requires PHP CLI and the following examples assume it's available system-wide.
  18
  19 ### Installing/Updating Friendica
  20
  21 #### From Archive
  22
  23 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.
  24
  25 #### Installing with Git
  26
  27 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.
  28 Here are the typical commands you will have to run to do so:
  29
  30 ````
  31 ~> git clone https://github.com/friendica/friendica.git friendica
  32 ~/friendica> cd friendica
  33 ~/friendica> bin/composer.phar install
  34 ````
  35
  36 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.
  37
  38 #### Updating with Git
  39
  40 Updating Friendica to the current stable or the latest develop version is easy with Git, just remember to run Composer after every branch pull.
  41
  42 ````
  43 ~> cd friendica
  44 ~/friendica> git pull
  45 ~/friendica> bin/composer.phar install
  46 ````
  47
  48 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.
  49
  50 ### Developing Friendica
  51
  52 First of all, thanks for contributing to Friendica!
  53 Composer is meant to be used by developers to maintain third-party libraries required by Friendica.
  54 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.
  55
  56 #### Adding a third-party library to Friendica
  57
  58 Does your shiny new [Addon](help/Addons) need to rely on a third-party library not required by Friendica yet?
  59 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`.
  60
  61 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.
  62 Here's a simplified version of the one we currently use on Friendica:
  63
  64 ````json
  65 {
  66         "name": "friendica/friendica",
  67         "description": "A decentralized social network part of The Federation",
  68         "type": "project",
  69         ...
  70         "require": {
  71                 "ezyang/htmlpurifier": "~4.7.0",
  72                 "mobiledetect/mobiledetectlib": "2.8.*"
  73         },
  74         ...
  75 }
  76 ````
  77
  78 The important part is under the `require` key, this is a list of all the libraries Friendica may need to run.
  79 As you can see, at the moment we only require two, HTMLPurifier and MobileDetect.
  80 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:
  81
  82 * We will update HTMLPurifier up to version 4.8.0 excluded
  83 * We will update MobileDetect up to version 2.9.0 excluded
  84
  85 There are other operators you can use to allow Composer to update the package up to the next major version excluded.
  86 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.
  87
  88 To add a library, just add its Packagist identifier to the `require` list and set a target version string.
  89
  90 Then you should run `bin/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.
  91
  92 #### Updating an existing dependency
  93
  94 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.
  95
  96 Then you should run `bin/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.
  97
  98 Please note that you should commit both `composer.json` and `composer.lock` with your work every time you make a change to the former.
  99
 100 ## Composer FAQ
 101
 102 ### I used the `composer` command and got a warning about not to run it as root.
 103
 104 See [https://getcomposer.org/root]().
 105 Composer should be run as the web server user, usually `www-data` with Apache or `http` with nginx.
 106 If you can't switch to the web server user using `su - [web user]`, you can directly run the Composer command with `sudo -u [web user]`.
 107
 108 ### Running Composer with `sudo` complains about not being able to create the composer cache directory in `/root/.composer`
 109
 110 This is because `sudo` doesn't always change the `HOME` environment variable, which means that the command is run as the web server user but the system still uses `root` home directory.
 111 However, you can temporarily change environment variable for the execution of a single command.
 112 For Composer, this would be:
 113 ````
 114 $> COMPOSER_HOME=/var/tmp/composer sudo -u [web user] bin/composer.phar [mode]
 115 ````
 116
 117 ## Related
 118
 119 * [Class autoloading](help/autoloader)
 120 * [How To Move Classes to `src`](help/Developer-How-To-Move-Classes-to-src)