feature(composer): Fully support installing Elgg as a composer depend…

…ency

Can register views, translations, and start.php from the root dir now

I left out "classes" intentionally to encourage composer autoloader usage.

Fixes #8431

.gitignore

@@ -1,5 +1,6 @@
 # ignore Elgg configuration
 /engine/settings.php
+/settings.php
 /.htaccess
 /mod/*
 /composer.lock

autoloader.php

@@ -31,4 +31,4 @@
 echo "You must set up the project dependencies. Run the following commands:\n" .
 	"curl -s http://getcomposer.org/installer | php\n" .
 	"php composer.phar install";
-exit;
+exit;

docs/admin/backup-restore.rst

@@ -206,7 +206,7 @@ Bringing it all together
 
 The restored elgg installation knows **nothing** about the new database name, database username, directory structure, etc. That's what we're going to address here.
 
-Edit ``/public_html/engine/settings.php`` on the new hosting provider to reflect the database information for the database that you just created.
+Edit ``/public_html/settings.php`` on the new hosting provider to reflect the database information for the database that you just created.
 
 .. code:: php
 

docs/guides/dont-modify-core.rst

@@ -3,34 +3,58 @@ Don't Modify Core
 
 .. warning:: 
 
-   Don't modify any non-config files that come with Elgg. 
+    In general, you shouldn't modify non-config files that come with third-party software like Elgg.
 
-Instead, create a :doc:`custom plugin<plugins>` and alter behavior through the rich Elgg plugin API.
+The best way to customize the behavior of Elgg is to :doc:`install Elgg as a composer dependency</intro/install>`
+and use the root directory to store modifications specific to your application,
+and alter behavior through the rich Elgg plugin API.
 
-Here are the main reasons not to modify the core of Elgg, or of any other third party software that offers better extensibility routes through plugins.
+If you'd like to share customizations between sites or even publish your changes
+as a reusable package for the community, create a :doc:`plugin<plugins>`
+using the same plugin APIs and file structure.
 
 It makes it hard to get help
 ----------------------------
 
-When you don't share the same codebase as everyone else, it's impossible for others to know what is going on in your system and whether your changes are to blame. This can frustrate those who offer help because it can add considerable noise to the support process.
+When you don't share the same codebase as everyone else,
+it's impossible for others to know what is going on in your system
+and whether your changes are to blame. This can frustrate those who offer help
+because it can add considerable noise to the support process.
 
 It makes upgrading tricky and potentially disastrous
 ----------------------------------------------------
 
-You will certainly want or need to upgrade Elgg to take advantage of security patches, new features, new plugin APIs, new stability and performance improvements. If you've modified core files, then you must be very careful when upgrading that your changes are not overwritten and that they are compatible with the new Elgg code. If your changes are lost or incompatible, then the upgrade may remove features you've added or even completely break your site.
+You will certainly want or need to upgrade Elgg to take advantage of
 
-This can also be a slippery slope. Lots of modifications can lead you to an upgrade process so complex that it's practically impossible. There are lots of sites stuck running old versions software due to taking this path.
+ * security patches
+ * new features
+ * new plugin APIs
+ * new stability improvements
+ * performance improvements
+
+If you've modified core files, then you must be very careful when upgrading that
+your changes are not overwritten and that they are compatible with the new Elgg code.
+If your changes are lost or incompatible, then the upgrade may remove features 
+you've added and even completely break your site.
+
+This can also be a slippery slope. Lots of modifications can lead you to an
+upgrade process so complex that it's practically impossible.
+There are lots of sites stuck running old versions software due to taking this path.
 
 It may break plugins
 --------------------
 
-You may not realize until much later that your "quick fix" broke seemingly unrelated functionality that plugins depended on.
+You may not realize until much later that your "quick fix" broke
+seemingly unrelated functionality that plugins depended on.
 
 Summary
 -------
 
 - Resist the temptation
-   Editing existing files is quick and easy, but doing so heavily risks the maintainability, security, and stability of your site.
-- When receiving advice, consider if the person telling you to modify core will be around to rescue you if you run into trouble later!
+   Editing existing files is quick and easy, but doing so heavily risks the
+   maintainability, security, and stability of your site.
+- When receiving advice, consider if the person telling you to modify core will
+  be around to rescue you if you run into trouble later!
 - Apply these principle to software in general. 
-   If you can avoid it, don't modify third party plugins either, for many of the same reasons: Plugin authors release new versions, too, and you will want those updates.
+   If you can avoid it, don't modify third party plugins either, for the same reasons:
+   Plugin authors release new versions, too, and you will want those updates.

docs/guides/guidelines.rst

@@ -1,7 +1,9 @@
 Plugin coding guidelines
 ========================
 
-In addition to the Elgg Coding Standards, these are guidelines for creating plugins. Core plugins are being updated to this format and all plugin authors should follow these guidelines in their own plugins.
+In addition to the Elgg Coding Standards, these are guidelines for creating plugins.
+Core plugins are being updated to this format and all plugin authors should follow
+these guidelines in their own plugins.
 
 .. seealso::
 

docs/guides/upgrading.rst

@@ -12,6 +12,64 @@ See the administrator guides for :doc:`how to upgrade a live site </admin/upgrad
 From 1.x to 2.0
 ===============
 
+Elgg can be now installed as a composer dependency instead of at document root
+------------------------------------------------------------------------------
+
+That means an Elgg site can look something like this:
+
+.. code::
+
+    settings.php
+    vendor/
+      elgg/
+        elgg/
+          engine/
+            start.php
+          _graphics/
+            elgg_sprites.png
+    mod/
+      blog
+      bookmarks
+      ...
+
+``elgg_get_root_path`` and ``$CONFIG->path`` will return the path to the application
+root directory (the one containing ``settings.php``), which is not necessarily the
+same as Elgg core's root directory (which in this case is ``vendor/elgg/elgg/``).
+
+Do not attempt to access the core Elgg from your plugin directly, since you cannot
+rely on its location on the filesystem.
+
+In particular, don't try load ``engine/start.php``.
+
+.. code:: php
+
+    // Don't do this!
+    dirname(__DIR__) . "/engine/start.php";
+    
+To boot Elgg manually, you can use the class ``Elgg\Application``.
+
+.. code:: php
+
+    // boot Elgg in mod/myplugin/foo.php
+    require_once dirname(dirname(__DIR__)) . '/vendor/autoload.php';
+    \Elgg\Application::start();
+
+However, use this approach sparingly. Prefer :doc:`routing` instead whenever possible
+as that keeps your public URLs and your filesystem layout decoupled.
+
+Also, don't try to access the ``_graphics`` files directly.
+
+.. code:: php
+
+    readfile(elgg_get_root_path() . "_graphics/elgg_sprites.png");
+    
+Use :doc:`views` instead:
+
+.. code:: php
+
+    echo elgg_view('elgg_sprites.png');
+    
+
 Cacheable views must have a file extension in their names
 ---------------------------------------------------------
 
@@ -29,7 +87,6 @@ which can result in conflicts between cacheable views that don't have file exten
 to disambiguate files from directories.
 
 
-
 Dropped ``jquery-migrate`` and upgraded ``jquery`` to ^2.1.4
 ------------------------------------------------------------
 
@@ -284,16 +341,6 @@ If your code uses one of the following functions, read below.
 If you provide a callable ``$handler`` to be called with the results, your handler will now receive a
 ``\Doctrine\DBAL\Driver\Statement`` object. Formerly this was an ext/mysql ``result`` resource.
 
-engine/start.php is deprecated
-------------------------------
-
-Plugins should use the class ``Elgg\Application`` to boot Elgg. Typical usage:
-
-.. code:: php
-
-    // boot Elgg in mod/myplugin/foo.php
-    require_once dirname(dirname(__DIR__)) . '/autoloader.php';
-    (new \Elgg\Application)->bootCore();
 
 Event/Hook calling order may change
 -----------------------------------

docs/intro/install.rst

@@ -69,20 +69,23 @@ Overview
 Upload Elgg
 -----------
 
--  Download the `latest version of Elgg`_
--  Upload the ZIP file with an FTP client to your server
--  Unzip the files in your domain's document root (/home/username/www).
-
-.. _latest version of Elgg: http://elgg.org/download.php
-
-Elgg also supports installing from source with Composer:
+With Composer (recommended if comfortable with CLI):
 
 .. code:: shell
 
     cd /path/to/wwwroot/
     composer self-update
     composer global require "fxp/composer-asset-plugin:~1.0"
-    composer create-project Elgg/Elgg:~2.0 .
+    composer create-project elgg/starter-project:dev-master .
+
+From pre-packaged zip (recommended if not comfortable with CLI):
+
+-  Download the `latest version of Elgg`_
+-  Upload the ZIP file with an FTP client to your server
+-  Unzip the files in your domain's document root.
+
+.. _latest version of Elgg: https://elgg.org/download.php
+
 
 Create a data folder
 --------------------
@@ -145,8 +148,7 @@ A note on settings.php and .htaccess
 
 The Elgg installer will try to create two files for you:
 
--  engine/settings.php, which contains the database settings for your
-   installation
+-  settings.php, which contains local environment configuration for your installation
 -  .htaccess, which allows Elgg to generate dynamic URLs
 
 If these files can't be automatically generated, for example because the